Commit 259d3f36 authored by LE GAC Renaud's avatar LE GAC Renaud
Browse files

Use the construct Returns.

parent d2005e90
......@@ -13,7 +13,8 @@ def INHIBIT_DELETE_UNDEF(set):
Args:
set (gluon.dal.Set):
:returns: bool
Returns:
bool:
"""
db, T = current.globalenv['db'], current.T
......@@ -39,7 +40,8 @@ def INHIBIT_UPDATE_UNDEF(set, values):
Args:
set (gluon.dal.Set):
:returns: bool
Returns:
bool:
"""
db, T = current.globalenv['db'], current.T
......
......@@ -64,16 +64,15 @@ def _to_field(field, linkedcombo=True, **kwargs):
``Ext.form.Field`` class. They are applied in the following order:
constructor, modifiers and keyword arguments.
:returns: :class:`.Field`
.. note::
The return configurator is a :class:`.Field`.
However it can be a :class:`.ComboBox`,
a :class:`.FieldDate`,
a :class:`.FieldTextArea`, ...
depending on the ``type`` of the database field.
The association is defined in the dictionary
:const:`FTYPE_TO_XTYPE`.
Returns:
Field:
The return configurator is a :class:`.Field`.
However it can be a :class:`.ComboBox`,
a :class:`.FieldDate`,
a :class:`.FieldTextArea`, ...
depending on the ``type`` of the database field.
The association is defined in the dictionary
:const:`FTYPE_TO_XTYPE`.
.. attention::
It is recommended to used the more general method :meth:`to_field`
......@@ -209,11 +208,10 @@ def to_field(field, composite=True, linkedcombo=True, **kwargs):
class. They are applied in the following order:
constructor, modifiers and keyword arguments.
:returns:
:class:`.Field` or ``None``
Return ``None`` when composite is ``True`` and when
the field is consumed by a ``FieldContainer``.
Returns:
* Field
* ``None`` when the argument composite is ``True`` and when
the field is consumed by a ``FieldContainer``.
"""
table = field.table
......@@ -268,14 +266,13 @@ def to_fields(table):
Args:
table (gluon.dal.Table): database table
:returns:
list
The list elements are :class:`.Field`, but
it can be a :class:`.ComboBox`,
a :class:`.FieldDate`,
a :class:`.FieldTextArea`, ...,
depending on the ``type`` of the database field.
Returns:
list:
The list elements are :class:`.Field`, but
it can be a :class:`.ComboBox`,
a :class:`.FieldDate`,
a :class:`.FieldTextArea`, ...,
depending on the ``type`` of the database field.
"""
li = []
......@@ -355,7 +352,8 @@ def to_formPanel(table, **kwargs):
applied in the following order: constructor, modifiers
and keyword arguments.
:returns: :class:`.FormPanel`
Returns:
FormPanel:
"""
tablename = table._tablename
......@@ -393,7 +391,8 @@ def to_gridColumn(field, **kwargs):
They are applied in the following order: constructor, modifiers
and keyword arguments.
:returns: :class:`.GridColumn`
Returns:
GridColumn:
"""
T = current.T
......@@ -452,7 +451,8 @@ def to_gridColumnModel(table):
Args:
table (gluon.dal.Table): database table
:returns: :class:`.GridColumnModel`
Returns:
GridColumnModel:
"""
delete_columns = []
......@@ -513,11 +513,10 @@ def to_gridFilter(table, **kwargs):
Rules are store in the modifier section ``grid_filters``.
:returns:
:class:`.GridFilter`
Return an empty dictionary if the GridFilter is
not defined in the application model.
Returns:
GridFilter:
Return an empty dictionary if the GridFilter is
not defined in the application model.
"""
......@@ -623,7 +622,8 @@ def to_gridPanel(table, **kwargs):
``App.grid.Panel`` class. They are applied in the following order:
constructor, modifiers, keyword arguments.
:returns: :class:`.GridPanel`
Returns:
GridPanel:
"""
tablename = table._tablename
......@@ -670,7 +670,8 @@ def to_jsonstore(table, **kwargs):
``App.data.DirectStore`` class. They are applied in the following order:
constructor, modifiers, keyword arguments.
:returns: :class:`.DirectStore`
Returns:
DirectStore:
"""
db = table._db
......@@ -754,7 +755,8 @@ def to_model(table):
Args:
table (gluon.dal.Table): database table
:returns: dict
Returns:
dict:
"""
db = table._db
......@@ -816,7 +818,8 @@ def to_panelWithUrlSelector(table, selectorTitle='Select', **kwargs):
any of the Ext JS configuration parameters of the
``App.panel.WithUrlSelector`` class.
:returns: :class:`.PanelWithUrlSelector`
Returns:
PanelWithUrlSelector:
:raise BaseException: when baseUrl is not defined.
......@@ -844,7 +847,8 @@ def to_treeNodes():
The Node structure is defined in the application model using
:class:`.ViewportModifier`.
:returns: list
Returns:
list:
"""
cfg = []
......@@ -869,7 +873,8 @@ def to_viewport(**kwargs):
any of the Ext JS configuration parameters of the
``App.viewport.Viewport`` class.
:returns: dict
Returns:
dict:
"""
cfg = {}
......
......@@ -139,12 +139,11 @@ class DbSvc(BaseSvc):
"[table1.field1] belongs (1, 2, 3)"
"([table1.field1] == [table2.field2]) | ([table1.field2] == [table2.field1])"
:returns:
tuple of gluon.dal.Query
* the first element is the full query with all conditions or an empty string.
* the second element contains only the left join conditions or an empty string.
* the third element contains only the filter conditions or an empty string.
Returns:
tuple of gluon.dal.Query:
* the first element is the full query with all conditions or an empty string.
* the second element contains only the left join conditions or an empty string.
* the third element contains only the filter conditions or an empty string.
.. note::
All elements of the list are ANDED in the web2py query
......@@ -202,10 +201,11 @@ class DbSvc(BaseSvc):
table (gluon.dal.Table): database table
id (int): database record identifier
:returns:
dict -- key, value pairs where each key corresponds
to a field of the table. Foreign keys are resolved.
The key are encoded as ``Table1Field1``.
Returns:
dict:
key, value pairs where each key corresponds
to a field of the table. Foreign keys are resolved.
The key are encoded as ``Table1Field1``.
"""
db = current.globalenv['db']
......@@ -232,7 +232,8 @@ class DbSvc(BaseSvc):
table (gluon.dal.Table): database table
field (gluon.dal.Field): database field
:returns: bool
Returns:
bool:
"""
return field in current.globalenv['db'][table].fields
......@@ -247,10 +248,11 @@ class DbSvc(BaseSvc):
fields (dict): key, value pairs where each key corresponds
to a ``gluon.dal.Field``
:returns:
dict -- key, value pairs for each field with errors.
The key is encoded as ``Table1Field1`` and the value is a string
describing the error message.
Returns:
dict:
key, value pairs for each field with errors.
The key is encoded as ``Table1Field1`` and the value is a string
describing the error message.
"""
di = {}
......@@ -304,21 +306,20 @@ class DbSvc(BaseSvc):
Args:
arg (dict): :ref:`input transaction dictionary <input transaction dictionary>`
:returns:
gluon.storage.Storage
* ``Storage(errors=[], records=[])``
Returns:
gluon.storage.Storage:
* ``Storage(errors=[], records=[])``
* One to one correspondence between the errors
and the records lists
* One to one correspondence between the errors
and the records lists
* ``records`` is a list of dictionaries containing key value pairs
where the key corresponds to a database field.
The keys are encoded as ``Table1Field1``.
* ``records`` is a list of dictionaries containing key value pairs
where the key corresponds to a database field.
The keys are encoded as ``Table1Field1``.
* The ``error`` is ``None`` when the ``record`` is validated.
Otherwise the error is a dictionary
``{Table1Field1: "error message", ...}``
* The ``error`` is ``None`` when the ``record`` is validated.
Otherwise the error is a dictionary
``{Table1Field1: "error message", ...}``
"""
data = Storage(errors=[], records=[])
......@@ -368,15 +369,15 @@ class DbSvc(BaseSvc):
Args:
arg (dict): :ref:`input transaction dictionary <input transaction dictionary>`
:returns:
:ref:`output transaction dictionary <output transaction dictionary>`
The full transaction is aborted when at least one field value
is not validated by the database engine or when the transaction
is killed by the callback ``table._before_insert``.
In that scenario, the ``errors`` key contains either a string,
the error message return by callback, or the dictionary returns
by the validator.
Returns:
dict:
:ref:`output transaction dictionary <output transaction dictionary>`
The full transaction is aborted when at least one field value
is not validated by the database engine or when the transaction
is killed by the callback ``table._before_insert``.
In that scenario, the ``errors`` key contains either a string,
the error message return by callback, or the dictionary returns
by the validator.
"""
self.dbg("Start DbSvc.create")
......@@ -434,17 +435,17 @@ class DbSvc(BaseSvc):
The key ``records`` is the list of ``id`` to be deleted
*e.g.* ``[id1, id2, ... ]``.
:returns:
:ref:`output transaction dictionary <output transaction dictionary>`
Returns:
dict:
:ref:`output transaction dictionary <output transaction dictionary>`
* The key``records`` is a list of dictionary containing the ``id``
of the delete records *e.g.* ``[{TableId:xx}, ..]``.
* The key``records`` is a list of dictionary containing the ``id``
of the delete records *e.g.* ``[{TableId:xx}, ..]``.
* The full transaction is aborted when either one record does
not exist or when the delete operation is rejected by the
callback ``table._before_delete``. The ``errors`` key
contains the error messages return by the callback.
* The full transaction is aborted when either one record does
not exist or when the delete operation is rejected by the
callback ``table._before_delete``. The ``errors`` key
contains the error messages return by the callback.
"""
self.dbg("Start DbSvc.destroy")
......@@ -516,11 +517,11 @@ class DbSvc(BaseSvc):
configuration parameters: ``page``, ``start``, ``limit``,
``sort`` and ``dir``.
:returns:
:ref:`output transaction dictionary <output transaction dictionary>`
The key ``records`` is a list of dictionary containing the key value
pairs for the record found in the database.
Returns:
dict:
:ref:`output transaction dictionary <output transaction dictionary>`
The key ``records`` is a list of dictionary containing the key value
pairs for the record found in the database.
"""
self.dbg("Start DbSvc.read")
......@@ -604,19 +605,20 @@ class DbSvc(BaseSvc):
be updated. Each dictionary contains key, value pairs for fields
to be updated as well as the record ``id``.
:returns:
:ref:`output transaction dictionary <output transaction dictionary>`
Returns:
dict:
:ref:`output transaction dictionary <output transaction dictionary>`
* the key ``records`` is a list of dictionary containing the complete
key, value pairs for the ``record`` updated in the database.
* the key ``records`` is a list of dictionary containing the complete
key, value pairs for the ``record`` updated in the database.
* The full transaction is aborted when either a field value is not
validated by the database engine or when the transaction
is kill by the callback ``table._before_update``.
The *errors* key contains the error message return by callback or
a dictionary returns by the validator (the key is the field
identifier encoded as ``Table1Field1`` while the value is
the error message).
* The full transaction is aborted when either a field value is not
validated by the database engine or when the transaction
is kill by the callback ``table._before_update``.
The *errors* key contains the error message return by callback or
a dictionary returns by the validator (the key is the field
identifier encoded as ``Table1Field1`` while the value is
the error message).
"""
self.dbg("Start DbSvc.update.")
......
......@@ -80,13 +80,11 @@ class DirectSvc(BaseSvc):
"""Check the client request and launch the execution
of the function / method on the server.
:rtype: str
:returns:
str
* the response of the function / method run
on the server side
* the response is encoded as a JSON string.
Returns:
str:
* the response of the function / method run
on the server side
* the response is encoded as a JSON string.
:raise gluon.http.HTTP:
when the request has no arguments
......@@ -136,8 +134,9 @@ class DirectSvc(BaseSvc):
Args:
f (function): reference to a function
:returns:
function -- the input argument
Returns:
function:
the input argument
"""
# a procedure is registered as 'action.method'
......@@ -158,9 +157,10 @@ class DirectSvc(BaseSvc):
"""Route the request to the appropriate function / method,
pass the proper arguments and return the results.
:returns:
str -- the response of the function / method
encoded as a JSON string.
Returns:
str:
the response of the function / method
encoded as a JSON string.
:raise gluon.http.HTTP:
with the code 500 when the execution of the
......
......@@ -12,10 +12,9 @@ def CLEAN_COMMA(value):
Args:
value (str or unicode):
:returns: str or unicode
.. note::
return the value unchanged when it is not a string.
Returns:
str or unicode:
the return the value is unchanged when it is not a string.
"""
if not isinstance(value, (str, unicode)):
......@@ -31,10 +30,9 @@ def CLEAN_SPACES(value):
Args:
value (str or unicode):
:returns: str or unicode
.. note::
return the value unchanged when it is not a string.
Returns:
str or unicode:
the return the value is unchanged when it is not a string.
"""
if not isinstance(value, (str, unicode)):
......
......@@ -32,7 +32,8 @@ def as_list(val):
Args:
val (any): input value
:returns: list
Returns:
list:
"""
if not isinstance(val, (list, tuple)):
......@@ -68,7 +69,8 @@ def decode_field(field):
Args:
field (str): value
:returns: tuple
Returns:
tuple:
"""
li = []
......@@ -95,7 +97,8 @@ def dummy_row(table, value=''):
value (str): value associated to each field either
an empty string of None
:returns: gluon.dal.Row
Returns:
gluon.dal.Row:
"""
db = table._db
......@@ -121,7 +124,8 @@ def encode_field(*args):
"""Encode the string arguments into a CapitalizeWords.
The reverse function is :meth:`decode_field`.
:returns: str
Returns:
str:
.. note::
useful to build database field name like ``TableField``
......@@ -146,9 +150,10 @@ def encode_validator_errors(error):
``TablenameFieldname`` while the value is the
error message return by the validator
:returns:
dict -- error message are translated and should be more friendly
since it contains the field name with its error.
Returns:
dict:
error message are translated and should be more friendly
since it contains the field name with its error.
"""
di = {}
......@@ -165,7 +170,8 @@ def get_all_tables(dal):
Args:
dal (gluon.dal.DAL): the database
:returns: list
Returns:
list:
.. note::
It is recommend to use standard iterator provided by
......@@ -190,7 +196,9 @@ def get_create_id(table, **kwargs):
Args:
table (gluon.dal.Table): database table
:returns: int -- the ``id`` of the record.
Returns:
int:
the ``id`` of the record
"""
id = get_id(table, **kwargs)
......@@ -208,10 +216,11 @@ def get_field_validators(field):
Args:
field (gluon.dal.Field): database field
:returns:
dict -- The keys depend on the validators.
Typical one are ``minValue``, ``maxValue``, ``regex``, ``regexText``,
``maxLength``, ``minLength``, ...
Returns:
dict:
the keys depend on the validators.
Possible values are ``minValue``, ``maxValue``,
``regex``, ``regexText``,``maxLength``, ``minLength``, ...
"""
cfg = {}
......@@ -278,7 +287,9 @@ def get_file_paths(path, ext=None, alpha=True):
alpha (bool): sort the paths in alphabetic order
:returns: list -- local paths for all selected files.
Returns:
list:
local paths for all selected files.
"""
li = []
......@@ -312,22 +323,21 @@ def get_foreign_field(field):
Args:
field (gluon.dal.Field): database field
:returns:
tuple
Returns:
tuple:
* ``(k_tablename, k_fieldname, k_keyname)``
* ``(k_tablename, k_fieldname, k_keyname)``
* ``k_tablename`` is the name of the reference table
* ``k_tablename`` is the name of the reference table
* ``k_fieldname`` is the name of the reference field, *e.g.*
``table.field`` S{->} ``k_table.k_field``
* ``k_fieldname`` is the name of the reference field, *e.g.*
``table.field`` S{->} ``k_table.k_field``
* ``k_keyname`` is the name of the primary key of the reference table.
It is requires by the left join,
``table.field == k_table.k_key``.
In almost all case ``k_key`` is equal to ``id``.
* ``k_keyname`` is the name of the primary key of the reference table.
It is requires by the left join,
``table.field == k_table.k_key``.
In almost all case ``k_key`` is equal to ``id``.
* ``None`` for standard field.
* ``None`` for standard field.
"""
if not is_foreign_field(field):
......@@ -372,7 +382,9 @@ def get_id(table, **kwargs):
Args:
table (gluon.dal.Table): database table
:returns: int or None -- the ``id`` of the record.
Returns:
* int -- the ``id`` of the record
* ``None`` when the record does not exist
"""
query = None
......@@ -395,7 +407,8 @@ def get_language():
"""Get the primary language of the application from the HTML
language code, *e.g.* ``en``, ``fr``, ....
:returns: str
Returns:
str
"""
lg = current.T.accepted_language
......@@ -415,12 +428,11 @@ def get_plugin_path(plugin_name):
Args:
plugin_name (str): name of the plugin, *e.g.* ``plugin_dbui``
:returns:
str
* the path of the first directory starting with ``plugin_name``.
* the local path is relative to the application directory.
* ``None`` if the plugin is not found.
Returns:
str:
* the path of the first directory starting with ``plugin_name``.
* the local path is relative to the application directory.
* ``None`` if the plugin is not found.
"""
server_path, client_path = get_reference_paths()
......@@ -444,7 +456,9 @@ def get_reference_paths():
* The local path is relative to the applications directory.
It is useful on the client-side
:returns: tuple -- ``("applications/myapp", "/myapp")``
Returns:
tuple:
``("applications/myapp", "/myapp")``
"""
server_path = os.path.join('applications', current.request.application)
......@@ -459,7 +473,8 @@ def get_set_field(field):
Args:
field (gluon.dal.Field): database field
:returns: list
Returns:
list:
"""
validators = as_list(field.requires)
......@@ -499,9 +514,10 @@ def get_script_path(plugin):
Args:
plugin (reference): web2py plugin instance
:returns:
str -- the local path of the script file relative to the
application directory.
Returns:
str:
the local path of the script file relative to the
application directory.
"""
server_path, client_path = get_reference_paths()
......@@ -534,7 +550,9 @@ def get_store_id(name):
Args:
name (str):