Commit b47dffe6 authored by LE GAC Renaud's avatar LE GAC Renaud
Browse files

Use the Args construct instead of :param:+:type:.

parent ef33fe47
......@@ -16,6 +16,9 @@ class BaseSvc:
def dbg(self, *args):
"""Print ``args`` if the attribute debug is true.
Args:
args (list): object to be printed
"""
if self.debug:
pprint.pprint(args)
......@@ -10,8 +10,8 @@ from gluon import current
def INHIBIT_DELETE_UNDEF(set):
"""Delete the row containing undefined value is not allowed
:type set: gluon.dal.Set
:param set:
Args:
set (gluon.dal.Set):
:returns: bool
......@@ -36,8 +36,8 @@ def INHIBIT_DELETE_UNDEF(set):
def INHIBIT_UPDATE_UNDEF(set, values):
"""Update the row containing undefined value is not allowed
:type set: gluon.dal.Set
:param set:
Args:
set (gluon.dal.Set):
:returns: bool
......
......@@ -53,13 +53,10 @@ def _to_field(field, linkedcombo=True, **kwargs):
:class:`.FieldsModifier` instructions
but does not handle :class:`.FieldContainer`.
:type field: gluon.dal.Field
:param field:
:type linkedcombo: bool
:param linkedcombo:
``LinkedComboBox`` are ignored when ``False``.
Useful to build grid filter.
Args:
field (gluon.dal.Field):
linkedcombo (bool): ``LinkedComboBox`` are ignored when ``False``.
Useful to build grid filter.
:keyword kwargs:
any Ext JS configuration parameters of the
......@@ -196,18 +193,12 @@ def to_field(field, composite=True, linkedcombo=True, **kwargs):
model using the modifiers
:class:`.FieldsModifier`.
:type field: gluon.dal.Field
:param field:
:type composite: bool
:param composite:
``FieldContainer`` is ignored when ``False``.
Useful to build grid filter.
:type linkedcombo: bool
:param linkedcombo:
``LinkedComboBox`` are ignored when ``False``.
Useful to build grid filter.
Args:
field (gluon.dal.Field);
composite (bool): ``FieldContainer`` is ignored when ``False``.
Useful to build grid filter.
linkedcombo (bool): ``LinkedComboBox`` are ignored when ``False``.
Useful to build grid filter.
:type kwargs: dict
:param kwargs:
......@@ -271,8 +262,8 @@ def to_fields(table):
:class:`.FormModifier` and the
:class:`.FieldsModifier` respectively.
:type table: gluon.dal.Table
:param table:
Args:
table (gluon.dal.Table): database table
:returns:
list
......@@ -351,8 +342,8 @@ def to_formPanel(table, **kwargs):
for the database ``table``. The conversion takes into account the
:class:`.FormModifier` instructions.
:type table: gluon.dal.Table
:param table:
Args:
table (gluon.dal.Table): database table
:type kwargs: dict
:param kwargs:
......@@ -389,8 +380,8 @@ def to_gridColumn(field, **kwargs):
for the database ``field``. The conversion takes into account the
:class:`.GridModifier` instructions.
:type field: gluon.dal.Field
:param field:
Args:
field (gluon.dal.Field): database field
:type kwargs: dict
:param kwargs:
......@@ -455,8 +446,8 @@ def to_gridColumnModel(table):
for the database ``table``. The conversion takes into account the
:class:`.GridModifier` instructions.
:type table: gluon.dal.Table
:param table:
Args:
table (gluon.dal.Table): database table
:returns: :class:`.GridColumnModel`
......@@ -498,8 +489,8 @@ def to_gridFilter(table, **kwargs):
the database ``table``. The ``GridFilter`` is parametrized using the
:class:`.GridModifier`.
:type table: gluon.dal.Table
:param table:
Args:
table (gluon.dal.Table): database table
:type kwargs: dict
:keyword kwargs:
......@@ -620,8 +611,8 @@ def to_gridPanel(table, **kwargs):
the database ``table``. The conversion takes into account the
:class:`.GridModifier` instructions.
:type table: gluon.dal.Table
:param table:
Args:
table (gluon.dal.Table): database table
:type kwargs: dict
:keyword kwargs:
......@@ -667,8 +658,8 @@ def to_jsonstore(table, **kwargs):
the database ``table``. The conversion takes into account the
:class:`.StoreModifier` instructions.
:type table: gluon.dal.Table
:param table:
Args:
table (gluon.dal.Table): database table
:type kwargs: dict
:keyword kwargs:
......@@ -757,8 +748,8 @@ def to_model(table):
"""Build the :class:`.Model` configuration for
the database ``table``.
:type table: gluon.dal.Table
:param table:
Args:
table (gluon.dal.Table): database table
:returns: dict
......@@ -805,20 +796,14 @@ def to_panelWithUrlSelector(table, selectorTitle='Select', **kwargs):
"""Build the :class:`.PanelWithUrlSelector` configuration
where the selector is a form derived from the database ``table``.
:type table: gluon.dal.Table
:param table:
:type selectorTitle: str
:param selectorTitle:
the title of the FieldSet encapsulating
the selector fields.
:type baseUrl: str
:param baseUrl:
The selected values are send to a controller
defined by the baseUrl.
Values are processed and results will be published in the panel.
It is mandatory to specified the baseUrl.
Args:
table (gluon.dal.Table): database table
selectorTitle (str): the title of the FieldSet encapsulating
the selector fields.
baseUrl (str): the selected values are send to a controller
defined by the baseUrl.Values are processed and results
will be published in the panel.
It is mandatory to specified the baseUrl.
:type kwargs: dict
:keyword kwargs:
......
......@@ -102,8 +102,8 @@ class DbSvc(BaseSvc):
"""Check that the transaction data dictionary ``arg``
contains the ``keywords``.
:type arg: dict
:param arg: :ref:`input transaction dictionary <input transaction dictionary>`
Args:
arg (dict): :ref:`input transaction dictionary <input transaction dictionary>`
:type keywords: dict
......@@ -126,19 +126,18 @@ class DbSvc(BaseSvc):
def _encode_query(self, li):
"""Encode the query send by the client to a web2py ``Query``.
:type li: list
:param li:
the query send by the client as a list of string.
The following string are understood by the method::
Args:
li (list): the query send by the client as a list of string.
The following string are understood by the method::
"[table1.field1] == [table2.field2]" or "[table1, field1] == [table2, field2]"
"[table1.field1] > n"
"[table1.field1] like 'm%'"
"[table1.field1] contains 'm%'"
"[table1.field1] startswith 'm%'"
"[table1.field1].lower() like 'm%'"
"[table1.field1] belongs (1, 2, 3)"
"([table1.field1] == [table2.field2]) | ([table1.field2] == [table2.field1])"
"[table1.field1] == [table2.field2]" or "[table1, field1] == [table2, field2]"
"[table1.field1] > n"
"[table1.field1] like 'm%'"
"[table1.field1] contains 'm%'"
"[table1.field1] startswith 'm%'"
"[table1.field1].lower() like 'm%'"
"[table1.field1] belongs (1, 2, 3)"
"([table1.field1] == [table2.field2]) | ([table1.field2] == [table2.field1])"
:returns:
tuple of gluon.dal.Query
......@@ -199,11 +198,9 @@ class DbSvc(BaseSvc):
def _get_record(self, table, id):
"""Get the record ``id`` located in the database ``table``.
:type table: gluon.dal.Table
:param table:
:type id: int
:param id:
Args:
table (gluon.dal.Table): database table
id (int): database record identifier
:returns:
dict -- key, value pairs where each key corresponds
......@@ -231,11 +228,9 @@ class DbSvc(BaseSvc):
def _is_field_in_table(self, table, field):
"""Check that the ``field`` belongs to the ``table``.
:type table: gluon.dal.Table
:param table:
:type field: gluon.dal.Field
:param field:
Args:
table (gluon.dal.Table): database table
field (gluon.dal.Field): database field
:returns: bool
......@@ -247,13 +242,10 @@ class DbSvc(BaseSvc):
"""Check each ``field`` value against its ``validators``.
:type table: gluon.dal.Table
:param table:
:type fields: dict
:param fields:
key, value pairs where each key corresponds
to a ``gluon.dal.Field``
Args:
table (gluon.dal.Table): database table
fields (dict): key, value pairs where each key corresponds
to a ``gluon.dal.Field``
:returns:
dict -- key, value pairs for each field with errors.
......@@ -283,8 +275,8 @@ class DbSvc(BaseSvc):
def _is_table_in_db(self, tablename):
"""Check that the table exists in the database.
:type tablename: str
:param tablename: name of the table
Args:
tablename (str): name of the database table
:raise DbSvcException: when the table does not exists
......@@ -309,8 +301,8 @@ class DbSvc(BaseSvc):
The method also validates each value.
:type arg: dict
:param arg: :ref:`input transaction dictionary <input transaction dictionary>`
Args:
arg (dict): :ref:`input transaction dictionary <input transaction dictionary>`
:returns:
gluon.storage.Storage
......@@ -361,8 +353,8 @@ class DbSvc(BaseSvc):
def count(self, tablename):
"""Count the total number of records in the table
:type tablename: string
:param tablename: name of the table
Args:
tablename (str): name of the database table
"""
db = current.globalenv['db']
......@@ -373,8 +365,8 @@ class DbSvc(BaseSvc):
"""Create new records defined by the transaction data ``arg``.
Several transactions of the same type are processed together.
:type arg: dict
:param arg: :ref:`input transaction dictionary <input transaction dictionary>`
Args:
arg (dict): :ref:`input transaction dictionary <input transaction dictionary>`
:returns:
:ref:`output transaction dictionary <output transaction dictionary>`
......@@ -436,12 +428,11 @@ class DbSvc(BaseSvc):
"""Delete existing records defined by the transaction data ``arg``.
Several transactions of the same type are processed together.
:type arg: dict
:param arg:
:ref:`input transaction dictionary <input transaction dictionary>`
The key ``records`` is the list of ``id`` to be deleted
*e.g.* ``[id1, id2, ... ]``.
Args:
arg (dict):
:ref:`input transaction dictionary <input transaction dictionary>`
The key ``records`` is the list of ``id`` to be deleted
*e.g.* ``[id1, id2, ... ]``.
:returns:
:ref:`output transaction dictionary <output transaction dictionary>`
......@@ -500,8 +491,8 @@ class DbSvc(BaseSvc):
"""Read the content of a table as specified in the transaction data ``arg``.
The ``arg`` dictionary contains the following keys:
:type arg: dict
:param arg:
Args:
arg (dict):
:ref:`input transaction dictionary <input transaction dictionary>`
* The *optional* key ``where`` (optional) is a list of string
......@@ -606,10 +597,9 @@ class DbSvc(BaseSvc):
"""Update records defined by the transaction data ``arg``.
Several transactions of the same type are processed together.
:type arg: dict
:param arg:
Args:
arg (dict):
:ref:`input transaction dictionary <input transaction dictionary>`
the key ``records`` is the list of dictionaries one per record to
be updated. Each dictionary contains key, value pairs for fields
to be updated as well as the record ``id``.
......
......@@ -113,11 +113,9 @@ class DirectSvc(BaseSvc):
def error(self, code, message):
"""Build and raise the gluon.http.HTTP exception
:type code: int
:param code: code of the HTTP error
:type message: str
:param message: explanation for the HTTP error
Args:
code (int): code of the HTTP error
message (str): explanation for the HTTP error
:raise gluon.http.HTTP:
......@@ -135,8 +133,8 @@ class DirectSvc(BaseSvc):
@service.register
def myfunction(a, b):
:type f: function
:param f:
Args:
f (function): reference to a function
:returns:
function -- the input argument
......
......@@ -40,8 +40,8 @@ class FieldsModifier(Modifier):
* There is one to one correspondence between the ``composite_fields.main``
and the ``composite_fields.others`` lists.
:type tablename: str
:param tablename: name of the database table
Args:
tablename (str): name of the database table
"""
Modifier.__init__(self, MODIFIER_FIELDS, tablename)
......@@ -74,10 +74,10 @@ class FieldsModifier(Modifier):
Existing value of the configuration options are replace by those
defined by the keyword arguments.
:type field: str
:param field:
name of the database field.
It should belong to the database table defined in the constructor.
Args:
field (str): name of the database field.
It should belong to the database table defined
in the constructor.
"""
self.data.extjs_fields[field] = kwargs
......
......@@ -9,8 +9,8 @@ def CLEAN_COMMA(value):
"""Remove trailing comma(s).
Search patterns are: ',' or ', ' or ' ,, ' ...
:type value: str or unicode
:param value:
Args:
value (str or unicode):
:returns: str or unicode
......@@ -28,8 +28,8 @@ def CLEAN_SPACES(value):
"""Remove leading as well as trailing spaces and keep a single space
between words.
:type value: str or unicode
:param value:
Args:
value (str or unicode):
:returns: str or unicode
......
......@@ -21,10 +21,10 @@ def configure_forms(db, **extjs):
"""Apply to all form widgets the same configuration options.
Useful to set plugins in one go, for example.
:type db: gluon.dal.DAL or list of table name
:param db:
list of forms to be modified. They are identified by their
associated table name.
Args:
db (gluon.dal.DAL or list):
list of forms to be modified. They are identified by their
associated table name.
.. note::
The keyword arguments define values for the Ext JS configuration
......@@ -77,8 +77,8 @@ class FormModifier(Modifier):
* ``mapper`` (None or function) reference to the function used
to organize the ``FieldSet`` in ``Tabs``, for example.
:type tablename: str
:param tablename: name of the database table
Args:
tablename (str): name of the database table
"""
Modifier.__init__(self, MODIFIER_FORMS, tablename)
......
......@@ -23,10 +23,9 @@ def configure_grids(db, **extjs):
"""Apply to all grid widgets the same configuration options.
Useful to set plugins in one go, for example.
:type db: gluon.dal.DAL or list of table name
:param db:
list of forms to be modified. They are identified by their
associated table name.
Args:
db (gluon.dal.DAL or list): list of forms to be modified.
They are identified by their associated table name.
The keyword arguments contain the configuration options for
the Ext.grid.Panel.
......@@ -82,8 +81,8 @@ class GridModifier(Modifier):
* ``template_columns`` (list
:type tablename: str
:param tablename: name of the database table
Args:
tablename (str): name of the database table
"""
Modifier.__init__(self, MODIFIER_GRIDS, tablename)
......@@ -123,18 +122,18 @@ class GridModifier(Modifier):
located on the right side of the GridPanel.
A filter corresponds to a field in the FieldSet.
:type filter: tuple
:param filter:
A filter is defined by a tuple containing three strings:
Args:
filter (tuple):
A filter is defined by a tuple containing three strings:
* The database field name. The field has to
belong to the database table defined in the constructor.
However, the more elaborate syntax, ``'table2.field1'``,
allows to use foreign field.
* The operator, ``'=='``, ``'contains'``, ...
Valid operator are defined in the method
:meth:`plugin_dbui.dbsvc.DbSvc._encode_query`
* The comment for the tool tip.
* The database field name. The field has to
belong to the database table defined in the constructor.
However, the more elaborate syntax, ``'table2.field1'``,
allows to use foreign field.
* The operator, ``'=='``, ``'contains'``, ...
Valid operator are defined in the method
:meth:`.DbSvc._encode_query`
* The comment for the tool tip.
The keyword argument contains Ext JS configuration options
for the associated Ext.form.Field.
......@@ -150,10 +149,9 @@ class GridModifier(Modifier):
This method is useful to fine tune column width for example.
:type fieldname: str
:param fieldname:
name of a database field.
It has to belong to the table defined in the constructor.
Args:
fieldname (str): name of a database field.
It has to belong to the table defined in the constructor.
The keyword arguments defines the configuration options
for the associated ``Ext.grid.Column`` widget.
......@@ -275,8 +273,8 @@ class GridModifier(Modifier):
By default it is activate for all grids.
:type bool: boolean
:param bool: activate the row numbering when ``True``.
Args:
bool (boolean): activate the row numbering when ``True``.
"""
self.data.row_numbering = bool
......@@ -29,8 +29,8 @@ def as_list(val):
"""Encapsulated ``val`` into a ``list`` when ``val`` is not an
instance of a ``list``.
:type val: any
:param val: input value
Args:
val (any): input value
:returns: list
......@@ -65,8 +65,8 @@ def decode_field(field):
useful to decode database field name:
``TableField`` or ``TableFieldFunction``
:type field: str
:param field:
Args:
field (str): value
:returns: tuple
......@@ -90,11 +90,10 @@ def dummy_row(table, value=''):
empty_row = dummy_row(db.table)
row.records.append(row)
:type table: gluon.dal.Table
:param table:
:type value: string
:param value: value associated to each field either an empty string of None
Args:
table (gluon.dal.Table): database table
value (str): value associated to each field either
an empty string of None
:returns: gluon.dal.Row
......@@ -142,10 +141,10 @@ def encode_field(*args):
def encode_validator_errors(error):
"""Encode and translate the validator errors.
:type error: dict
:param error:
the key is the table field encode as C[TablenameFieldname]
while the value is the error message return by the validator
Args:
error (dict): the key is the table field encode as
``TablenameFieldname`` while the value is the
error message return by the validator
:returns:
dict -- error message are translated and should be more friendly
......@@ -163,8 +162,8 @@ def get_all_tables(dal):
"""Get the list of names for all tables in the database, ``dal``,
including alias table.
:type dal: gluon.dal.DAL
:param dal:
Args:
dal (gluon.dal.DAL): the database
:returns: list
......@@ -188,8 +187,8 @@ def get_create_id(table, **kwargs):
id = get_create_id(db.person, first_name="Joe", last_name="Doe")
:type table: gluon.dal.Table
:param table:
Args:
table (gluon.dal.Table): database table
:returns: int -- the ``id`` of the record.
......@@ -206,8 +205,8 @@ def get_field_validators(field):
"""Get the Ext JS configuration parameters to run
database gluon.dal.Field validators on the client-side.
:type field: gluon.dal.Field
:param field:
Args:
field (gluon.dal.Field): database field
:returns:
dict -- The keys depend on the validators.
......@@ -263,23 +262,21 @@ def get_file_paths(path, ext=None, alpha=True):
The local paths are relative to the application directory.
:type path: None, list or string
:param path:
local path defining the target files:
Args:
path (None, list or str):
local path defining the target files:
* ``None``.
* a ``string`` pointing to one files.
* a ``list`` of strings pointing to several files.
* a ``string`` pointing to a directory.
* a ``list`` of string pointing to files and directory.
* ``None``.
* a ``string`` pointing to one files.
* a ``list`` of strings pointing to several files.
* a ``string`` pointing to a directory.
* a ``list`` of string pointing to files and directory.
:type ext: str