From 7bb893a47c12cca1c100ef3ff7de73308b7812ca Mon Sep 17 00:00:00 2001
From: Renaud Le Gac <legac@cppm.in2p3.fr>
Date: Thu, 4 Apr 2013 16:19:45 +0200
Subject: [PATCH] First pass to remove epydoc error.
---
modules/plugin_dbui/converter.py | 17 +--
modules/plugin_dbui/dbsvc.py | 211 ++++++++++++++--------------
modules/plugin_dbui/directsvc.py | 6 +-
modules/plugin_dbui/formmodifier.py | 80 +++++------
modules/plugin_dbui/helper.py | 32 ++---
modules/plugin_dbui/navtree.py | 35 +++--
modules/plugin_dbui/selector.py | 40 +++---
7 files changed, 206 insertions(+), 215 deletions(-)
diff --git a/modules/plugin_dbui/converter.py b/modules/plugin_dbui/converter.py
index 9ed65508..97bb0987 100644
--- a/modules/plugin_dbui/converter.py
+++ b/modules/plugin_dbui/converter.py
@@ -369,22 +369,19 @@ def to_gridColumnModel(table):
def to_gridFilter(table, **kwargs):
- """Convert a gluon.dal.Table into an ExtJS App.grid.GridFilter.
+ """Convert a L{gluon.dal.Table} into an ExtJS App.grid.GridFilter.
The grid filter is set using the grid modifiers.
Return an empty dictionary if not defined
ExtJS configuration parameters are applied in the following order:
constructor, modifiers, keyword arguments.
- FILTER RULE:
- A tuple of 3 string (field1, operator, comment).
- Field1 is the name of a field belonging to the table.
- Valid operators are defined in Dbsvc._encode_query.
-
- A more elaborate filter rule allows to filter on any foreign field.
- the syntax is (table2.field1, operator, comments).
-
- Rules are store in modifier section grid_filters.
+ @note: A filter rule is a tuple of 3 string C{(field1, operator, comment)}.
+ C{Field1} is the name of a field belonging to the table.
+ Valid operators are defined in Dbsvc._encode_query.
+ A more elaborate filter rule allows to filter on any foreign field.
+ The syntax is C{(table2.field1, operator, comments)}.
+ Rules are store in the modifier section C{grid_filters}.
"""
T = current.T
diff --git a/modules/plugin_dbui/dbsvc.py b/modules/plugin_dbui/dbsvc.py
index 62d85757..ad9c34ef 100644
--- a/modules/plugin_dbui/dbsvc.py
+++ b/modules/plugin_dbui/dbsvc.py
@@ -35,29 +35,25 @@ class DbSvc(BaseSvc):
It relies on the Ext.Direct protocol exposing dbSvc methods on
the client-side.
- Main methods are:
+ Main methods allows to:
- create
- to create a new record in a table.
-
- read
- read the content of a a table
- resolving foreign key.
+ - create a new record in a table.
+
+ - read the content of a a table
+ resolving foreign key.
- update
- update the record of a table.
+ - update the record of a table.
- destroy
- delete the record of a table.
+ - destroy the record of a table.
Each method return a dictionary:
- {success: True, records:{blabla}, msg: 'blalbla'}
+ C{{success: True, records:{blabla}, msg: 'blalbla'}}
- The keyword success is always present. It is mandatory for
+ The keyword C{success} is always present. It is mandatory for
the FormPanel widget of the ExtJS library, but not strictly
required since failure can be propagated through HTTP errors.
- In the records dictionary database field are encode as TableField.
+ In the records dictionary database field are encoded as C{TableField}.
If the action failed an Exception is raised.
The exception can be catch to generate an HTTP error.
@@ -70,21 +66,21 @@ class DbSvc(BaseSvc):
def _check_request(self, arg, keywords=('tableName', 'records')):
- """Helper function to check that the request arg is well formed.
- The dictionary arg contains the following keys:
+ """Helper function to check that the request C{arg} is well formed.
+ The dictionary C{arg} contains the following keys:
- tablename
- the name of the table in the database
+ - C{tablename}
+ the name of the table in the database
- dbFields
- The list of table fields.
+ - C{dbFields}
+ the list of table fields.
- records (optional)
- A dictionary containing the new / update values for field
- as well as the identifier of the record to be create, updated
- or delete.
+ - C{records} (optional)
+ a dictionary containing the new / update values for field
+ as well as the identifier of the record to be create, updated
+ or delete.
- Raise the DbSvcException if a keyword is missing or if the table
+ Raise the C{DbSvcException} if a keyword is missing or if the table
does not exist in the database.
"""
@@ -99,7 +95,7 @@ class DbSvc(BaseSvc):
def _encode_query(self, li):
"""Helper method to encode the list of query send by the client
- as a web2py query.
+ as a web2py query::
"[table1.field1] == [table2.field2]" or "[table1, field1] == [table2, field2]"
"[table1.field1] > n"
@@ -110,9 +106,11 @@ class DbSvc(BaseSvc):
"[table1.field1] belongs (1, 2, 3)"
"([table1.field1] == [table2.field2]) | ([table1.field2] == [table2.field1])"
- all element of the list are ANDED
- operator are ==, !=, <, >, <=, >=
- boolean operator are &, |
+ All elements of the list are ANDED.
+
+ Operators are C{==, !=, <, >, <=, >=}
+
+ Boolean operators are C{&, |}
"""
query = ""
@@ -211,20 +209,20 @@ class DbSvc(BaseSvc):
"""Helper method to prepare the records for their insertion
in the database (create or update).
- The current transaction is defined in the dictionary arg.
- It is associate to one table and can contain several records.
+ The current transaction is defined in the dictionary C{arg}.
+ It is associated to one table and can contain several records.
- tablename
- the name of the table in the database
+ - C{tablename}
+ the name of the table in the database
- dbFields
- The list of table fields.
- It also include pointing field resolving foreign keys.
- [(table1, field1), (table1, field2), (table2, field3), ...]
+ - C{dbFields}
+ The list of table fields.
+ It also include pointing field resolving foreign keys.
+ C{[(table1, field1), (table1, field2), (table2, field3), ...]}
- records (ROOT)
- List of dictionary containing the new / update values for field
- as well as the identifier of the record to be updated (id)
+ - C{records (ROOT)}
+ List of dictionary containing the new / update values for field
+ as well as the identifier of the record to be updated (id)
The method removes fields in the record which do not belong to the
table since the JsonStore send the foreign key and the pointing field.
@@ -232,7 +230,7 @@ class DbSvc(BaseSvc):
The method also validates values.
- Return a Storage:
+ Return a Storage::
{
"errors": [None,...],
@@ -241,7 +239,7 @@ class DbSvc(BaseSvc):
There is one to one correspondence between the errors
and the records lists. Error is None when fields are validated.
- Otherwise the error is a dictionary:
+ Otherwise the error is a dictionary::
{TableField: "error message", ...}
@@ -276,22 +274,22 @@ class DbSvc(BaseSvc):
def create(self, arg):
- """Create new records defined in the transaction arg.
- The dictionary arg contains the following keys:
+ """Create new records defined in the transaction C{arg}.
+ The dictionary C{arg} contains the following keys:
- tableName
- the name of the table in the database
+ - C{tableName}
+ the name of the table in the database
- dbFields
- The list of table fields.
- It also include pointing field resolving foreign keys.
- [(table1, field1), (table1, field2), (table2, field3), ...]
-
- records (ROOT)
- A list of dictionary containing the new values for fields
- as well as the identifier of the record to be updated (id)
+ - C{dbFields}
+ the list of table fields.
+ It also include pointing field resolving foreign keys.
+ C{[(table1, field1), (table1, field2), (table2, field3), ...]}
+
+ - C{records} (ROOT)
+ a list of dictionary containing the new values for fields
+ as well as the identifier of the record to be updated (id)
- Return a dictionary with status, message and the update row:
+ Return a dictionary with C{status}, message and the update row::
{
success: True,
@@ -300,7 +298,7 @@ class DbSvc(BaseSvc):
}
When at least a field value is not validated, abort the full transaction
- and return a dictionary with the error messages for the first bad record:
+ and return a dictionary with the error messages for the first bad record::
{
success: False,
@@ -339,21 +337,22 @@ class DbSvc(BaseSvc):
def destroy(self, arg):
- """Destroy the record defined in the transaction arg.
- The dictionary arg contains the following keys:
+ """Destroy the record defined in the transaction C{arg}.
+ The dictionary C{arg} contains the following keys:
- tableName
- the name of the table in the database
+
+ - C{tableName}
+ the name of the table in the database.
- dbFields
- The list of table fields.
- It also include pointing field resolving foreign keys.
- [(table1, field1), (table1, field2), (table2, field3), ...]
+ - C{dbFields}
+ the list of table fields.
+ It also include pointing field resolving foreign keys.
+ C{[(table1, field1), (table1, field2), (table2, field3), ...]}
- records (ROOT)
- A list with id numbers
+ - C{records} (ROOT)
+ a list with id numbers
- Return a dictionary with status, message and ids of the deleted row:
+ Return a dictionary with C{status}, message and ids of the deleted row::
{
success: True,
@@ -362,7 +361,7 @@ class DbSvc(BaseSvc):
}
When at least one record does not exist, abort the full transaction
- and return a dictionary with the error messages for the first bad record:
+ and return a dictionary with the error messages for the first bad record::
{
success: False,
@@ -398,37 +397,37 @@ class DbSvc(BaseSvc):
def read(self, arg):
- """Read the content of a table as specified in the transaction arg.
- The arg dictionary contains the following keys:
+ """Read the content of a table as specified in the transaction C{arg}.
+ The C{arg} dictionary contains the following keys:
- tableName
- name of the database table
+ - C{tableName}
+ name of the database table
- dbFields
- A list of field to be read.
- It also include pointing field resolving foreign keys.
- [(table1, field1), (table1, field2), (table2, field3), ...]
+ - C{dbFields}
+ a list of field to be read.
+ It also include pointing field resolving foreign keys.
+ C{[(table1, field1), (table1, field2), (table2, field3), ...]}
- where (optional)
- define the inner join when handling foreign key.
- The syntax follows the web2py convention:
- ['db.table1.field1 == db.table2.id'].
- An AND is performed between the different
- elements of the list.
-
- orderby (optional)
- order directive
- A list of fields [(table1, field1, dir), (table2, field3, dir), ...]
- where dir is either ASC or DESC
+ - C{where} (optional)
+ define the inner join when handling foreign key.
+ The syntax follows the web2py convention:
+ C{['db.table1.field1 == db.table2.id']}.
+ An AND is performed between the different
+ elements of the list.
+
+ - C{orderby} (optional)
+ order directive
+ A list of fields C{[(table1, field1, dir), (table2, field3, dir), ...]}
+ where C{dir} is either C{"ASC"} or C{"DESC"}
The dictionary can also contains parameters useful for paging.
- For more detail see Ext.PagingToolbar.
- start
- limit
- sort
- dir
+ For more detail see Ext.PagingToolbar:
+ - start
+ - limit
+ - sort
+ - dir
- The method return a list of records:
+ The method return a list of records::
{
success: True,
@@ -489,22 +488,22 @@ class DbSvc(BaseSvc):
def update(self, arg):
- """Update records defined in the transaction arg.
- The arg dictionary contains the following keys:
+ """Update records defined in the transaction C{arg}.
+ The C{arg} dictionary contains the following keys:
- tableName
- the name of the table in the database
+ - C{tableName}
+ the name of the table in the database
- dbFields
- The list of table fields.
- It also include pointing field resolving foreign keys.
- [(table1, field1), (table1, field2), (table2, field3), ...]
+ - C{dbFields}
+ the list of table fields.
+ It also include pointing field resolving foreign keys.
+ C{[(table1, field1), (table1, field2), (table2, field3), ...]}
- records (ROOT)
- A list of dictionary containing the update values for field
- as well as the identifier of the record to be updated (id)
+ - C{records} (ROOT)
+ a list of dictionary containing the update values for field
+ as well as the identifier of the record to be updated (id)
- Return a dictionary with status, message and the update row:
+ Return a dictionary with status, message and the update row::
{
success: True,
@@ -513,7 +512,7 @@ class DbSvc(BaseSvc):
}
When at least a field value is not validated, abort the full transaction
- and return a dictionary with the error messages for the first bad record:
+ and return a dictionary with the error messages for the first bad record::
{
success: False,
diff --git a/modules/plugin_dbui/directsvc.py b/modules/plugin_dbui/directsvc.py
index 03b832cd..864ea88f 100644
--- a/modules/plugin_dbui/directsvc.py
+++ b/modules/plugin_dbui/directsvc.py
@@ -34,13 +34,13 @@ class MyJsonEncoder(json.JSONEncoder):
class DirectSvc(BaseSvc):
"""Generic service to implement the Ext.Direct protocol on the server side
- Specification: http://www.sencha.com/products/extjs/extdirect/
+ Specification: U{http://www.sencha.com/products/extjs/extdirect/}
This implementation is based on the web2py service:
- http://www.web2py.com/book/default/chapter/09
+ U{http://www.web2py.com/book/default/chapter/09}
It is a simplified version of the class Service in gluon.tools.
- To register functions and make it available remotely use decorator
+ To register functions and make it available remotely use decorator::
service = DirectSvc(globals())
diff --git a/modules/plugin_dbui/formmodifier.py b/modules/plugin_dbui/formmodifier.py
index 88c2041f..39909bf2 100644
--- a/modules/plugin_dbui/formmodifier.py
+++ b/modules/plugin_dbui/formmodifier.py
@@ -62,54 +62,54 @@ class FormModifier(Modifier):
All keyword arguments of this method have to be defined:
- masterName
- field name for the master combobox
+ - C{masterName}
+ field name for the master combobox
- slaveNames
- field name for the master combobox.
- Either a string or a list of string when several
- slaves are linked to a master.
+ - C{slaveNames}
+ field name for the master combobox.
+ Either a string or a list of string when several
+ slaves are linked to a master.
- storeName
- name of the store containing values
- which will be displayed in the master and slave
- combobox. Either mystoreStore for and Ext.data.ArrayStore
- or tableStore for a store linked to a database table.
+ - C{storeName}
+ name of the store containing values
+ which will be displayed in the master and slave
+ combobox. Either mystoreStore for and Ext.data.ArrayStore
+ or tableStore for a store linked to a database table.
- displayFieldMaster
- Name of the field in the store shown in the master combo.
- Either field for Ext.data.ArrayStore or TableField
- for a store linked to a database table.
+ - C{displayFieldMaster}
+ name of the field in the store shown in the master combo.
+ Either field for Ext.data.ArrayStore or TableField
+ for a store linked to a database table.
- valueFieldMaster
- Name of the field in the store return by the master combo.
- Either field for Ext.data.ArrayStore or TableField
- for a store linked to a database table.
+ - C{valueFieldMaster}
+ name of the field in the store return by the master combo.
+ Either field for Ext.data.ArrayStore or TableField
+ for a store linked to a database table.
- displayFieldSlaves
- Name of the field in the store display in the slave combo.
- Either field for Ext.data.ArrayStore or TableField
- for a store linked to a database table.
- Either a string or a list of string when several
- slaves are linked to a master.
+ - C{displayFieldSlaves}
+ name of the field in the store display in the slave combo.
+ Either field for Ext.data.ArrayStore or TableField
+ for a store linked to a database table.
+ Either a string or a list of string when several
+ slaves are linked to a master.
- valueFieldSlaves
- Name of the field in the store return by the slave combo.
- Either field for Ext.data.ArrayStore or TableField
- for a store linked to a database table.
- Either a string or a list of string when several
- slaves are linked to a master.
+ - C{valueFieldSlaves}
+ name of the field in the store return by the slave combo.
+ Either field for Ext.data.ArrayStore or TableField
+ for a store linked to a database table.
+ Either a string or a list of string when several
+ slaves are linked to a master.
- masterExtJS
- configuration parameters dictionary for the master
- Ext.form.Combobox. Might be useful to set the master
- in readOnly mode for example
+ - C{masterExtJS}
+ configuration parameters dictionary for the master
+ Ext.form.Combobox. Might be useful to set the master
+ in readOnly mode for example
- slavesExtJS
- configuration parameters dictionary for the slave
- Ext.form.Combobox. It can also be a list of dictionary
- when running with multi-slaves. Might be useful to set
- the salve in readOnly mode for example.
+ - C{slavesExtJS}
+ configuration parameters dictionary for the slave
+ Ext.form.Combobox. It can also be a list of dictionary
+ when running with multi-slaves. Might be useful to set
+ the salve in readOnly mode for example.
"""
# Multi-slaves case
diff --git a/modules/plugin_dbui/helper.py b/modules/plugin_dbui/helper.py
index 2ee622b7..e0eff964 100644
--- a/modules/plugin_dbui/helper.py
+++ b/modules/plugin_dbui/helper.py
@@ -71,7 +71,7 @@ def get_all_tables(dal):
house by the DAL object. The list includes alias table.
It is recommend to use standard iterator provided by
- the DAL object. However by contruction, they ignore
+ the DAL object. However by construction, they ignore
alias table.
"""
@@ -86,8 +86,7 @@ def get_create_id(table, **kwargs):
If the row does not exits it is created using fields, values pairs.
Return the integer id of the row.
- table
- gluon.dal.Table
+ @type table: gluon.dal.Table
"""
id = get_id(table, **kwargs)
@@ -151,19 +150,19 @@ def get_file_paths(path, ext=None, alpha=True):
The relative path for a file or a directory is relative to the application.
A path can be:
- None.
+ - C{None}.
The method return an empty list.
- A string pointing to one files.
+ - A C{string} pointing to one files.
The method return a list with the local path of the file
- A list of string pointing to several files.
+ - A C{list} of string pointing to several files.
The method return list of local paths for the selected files.
- A string pointing to a directory.
+ - A C{string} pointing to a directory.
The method return a list of files found in the directory.
- A list of string pointing to files and directory.
+ - A C{list} of string pointing to files and directory.
The method return a list with local paths of the selected files
and those located in the selected directory.
@@ -202,19 +201,19 @@ def get_file_paths(path, ext=None, alpha=True):
def get_foreign_field(field):
- """Helper function returning a tuple (k_tablename, k_fieldname, k_keyname)
+ """Helper function returning a tuple C{(k_tablename, k_fieldname, k_keyname)}
where:
- k_tablename is the name of the parent table
+ - C{k_tablename} is the name of the parent table
- k_fieldname is the name of the parent field
- table.field --> k_table.k_field
+ - C{k_fieldname} is the name of the parent field, I{i.e}
+ C{table.field} S{->} C{k_table.k_field}
- k_keyname is the name of the primary key of the parent table
+ - C{k_keyname} is the name of the primary key of the parent table
requires by the left join. In most of the case it is id
- table.field == k_table.k_key
+ C{table.field == k_table.k_key}
- Otherwise return None.
+ Otherwise return C{None}.
"""
if not is_foreign_field(field):
@@ -258,8 +257,7 @@ def get_id(table, **kwargs):
Return the integer id or None if the row does not exist.
- table
- gluon.dal.Table
+ @type table: gluon.dal.Table
"""
query = None
diff --git a/modules/plugin_dbui/navtree.py b/modules/plugin_dbui/navtree.py
index 9b70e582..ef9eb3ae 100644
--- a/modules/plugin_dbui/navtree.py
+++ b/modules/plugin_dbui/navtree.py
@@ -13,8 +13,8 @@ class Node(object):
def __init__(self, text):
"""Constructor of the node
- text
- name of the node appearing in the viewport
+ @param text: name of the node appearing in the viewport
+ @type text: str
"""
self.text = text
@@ -25,13 +25,12 @@ class Node(object):
def add_child(self, text, cfg):
"""Add a child (leaf) to the node.
- text
- the name of the leaf
-
- cfg
- configuration dictionary for the associated
- ExtJS widget
-
+ @param text: the name of the leaf
+ @type text: str
+
+ @param cfg: configuration dictionary for the associated ExtJS widget
+ @type cfg: dict
+
"""
di = {'cfg': cfg, 'leaf': True, 'text': text}
self.children.append(di)
@@ -39,19 +38,17 @@ class Node(object):
def add_children(self, leaves, func=None, hidden=[]):
"""Helper method to add children to the node.
-
- leaves
- a list of string
-
- func
- function to translate the leaf name into
- the configuration dictionary of the associated ExtJS widget
+ Leaf names are translated and sorted by alphabetic order.
- hidden
- List of children to be hidden
+ @param leaves: a list of string
+ @type leaves: list
- Leaf names are translated and sorted by alphabetic order.
+ @param func: function to translate the leaf name into
+ the configuration dictionary of the associated ExtJS widget
+ @param hidden: List of children to be hidden.
+ @type hidden: list
+
"""
# translator
T = current.T
diff --git a/modules/plugin_dbui/selector.py b/modules/plugin_dbui/selector.py
index 0bb90b61..7eb4683d 100644
--- a/modules/plugin_dbui/selector.py
+++ b/modules/plugin_dbui/selector.py
@@ -9,10 +9,11 @@ A database report relies on three main components:
A powerful mechanism is also in place to render the report in different format
like HTML, CSV, .... It relies on the Selector class, on the IFRAME and
-on the view:
+on the view::
selector = Selector(virtdb.myselector, extfield='format')
iframe = selector.download()
+
if iframe:
return iframe
@@ -51,18 +52,20 @@ class Selector(Storage):
"""
def __init__(self, table, exclude_fields=(), extfield='format'):
"""
- table
- the gluon.dal.Table containing the
- definition of the selector
+
+ @param table:
+ the table containing the
+ definition of the selector
+ @type table: gluon.dal.Table
- exclude_fields
- A tuple containing a list of selector field names
- which will be ignored in query and select operations.
+ @param exclude_fields:
+ A tuple containing a list of selector field names
+ which will be ignored in query and select operations.
- extfield
- the name of the selector string defining the format
- of the report. To be used in conjunction with the
- download method.
+ @param extfield:
+ the name of the selector string defining the format
+ of the report. To be used in conjunction with the
+ download method.
"""
@@ -123,8 +126,7 @@ class Selector(Storage):
"""Add constraints which will be used in the database query
and database select operations.
- query
- gluon.dal.Query
+ @type query: gluon.dal.Query
"""
self._extra_queries.append(query)
@@ -204,8 +206,7 @@ class Selector(Storage):
The extfield and fields in the exclude_fields tuple are
not take into account.
- table
- gluon.dal.Table
+ @type table: gluon.dal.Table
"""
db = table._db
@@ -274,12 +275,11 @@ class Selector(Storage):
It returns Rows which contains foreign tables columns.
- table
- gluon.dal.Table
+ @type table: gluon.dal.Table
- kwargs
- The keyword arguments are those of the
- gluon.dal.Set.select method: orderby, groupby, ....
+ @param kwargs:
+ The keyword arguments are those of the
+ gluon.dal.Set.select method: orderby, groupby, ....
"""
db = table._db
--
GitLab