diff --git a/modules/plugin_dbui/converter.py b/modules/plugin_dbui/converter.py
index 9ed655085305782bd634db076a6b3c5234319322..97bb098774a16a2241bc1e72951d2928eb745302 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 62d85757c9954e2a5352ec99e4720401bd868978..ad9c34ef7a4f15bbaf0900ca8acece00263258ec 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 03b832cddc634efb1bad558f6846f9c1f16f5c42..864ea88faf19131050f97dfa8ed61db351cc21b9 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 88c2041fe461fc15542270a07bae007fec9112d5..39909bf298d66d572fe8ba02abac6a9a733b94c4 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 2ee622b776988ea5bbb6236c4b6b9b4c9bfcdd7b..e0eff964e1c48951e5198e4045ab2a30244b0df9 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 9b70e582954b519a08185ba544a9d3e14264f71e..ef9eb3ae7e11e72efe722700792695b214595205 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 0bb90b611e671a2fb98fccc21b988d53fc103305..7eb4683d25fd0c4853f02cb7b88b6cb5017696f3 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