From c37558643c923acc4f792e6e08d8e3c269685f83 Mon Sep 17 00:00:00 2001
From: Renaud Le Gac <legac@cppm.in2p3.fr>
Date: Sun, 7 Apr 2013 11:57:42 +0200
Subject: [PATCH] *review oythoin documentation using epytext.
---
modules/plugin_dbui/basesvc.py | 16 ++-
modules/plugin_dbui/converter.py | 231 +++++++++++++++++++++----------
modules/plugin_dbui/dbsvc.py | 95 ++++++++-----
modules/plugin_dbui/extjs.py | 90 ++++++------
4 files changed, 287 insertions(+), 145 deletions(-)
diff --git a/modules/plugin_dbui/basesvc.py b/modules/plugin_dbui/basesvc.py
index 35ca7623..99436182 100644
--- a/modules/plugin_dbui/basesvc.py
+++ b/modules/plugin_dbui/basesvc.py
@@ -1,4 +1,6 @@
-""" Author: R. Le Gac
+""" base class to build service
+
+@author: R. Le Gac
"""
@@ -7,16 +9,24 @@ import pprint
class BaseSvc:
"""Base class to build service.
- Use the environment attribute to access to db, T, ....
"""
def __init__(self, environment):
+ """
+ @type environment: dict
+
+ @param environment: contains the global variables
+ namely C{db} and C{T}.
+
+ >>> svc = BaseSvc(globals())
+
+ """
self.debug = False
self.environment = environment
def dbg(self, *args):
- """Print args if the attribute debug is true.
+ """Print C{args} if the attribute debug is true.
"""
if self.debug:
diff --git a/modules/plugin_dbui/converter.py b/modules/plugin_dbui/converter.py
index 97bb0987..f7a73d3c 100644
--- a/modules/plugin_dbui/converter.py
+++ b/modules/plugin_dbui/converter.py
@@ -1,6 +1,6 @@
-""" Converters transforming Web2py DAL objects into ExtJS widgets.
+""" a series of converter to transform L{gluon.dal} objects into Ext JS widgets.
-Author: R. Le Gac
+@author: R. Le Gac
"""
import gluon.dal
@@ -41,14 +41,26 @@ TOTAL = 'count'
def _to_field(field, **kwargs):
- """Private converter. It is recommended to used to_field.
+ """Build the configurator L{Field} associated to the database C{field}.
+ The conversion takes into account the L{FieldsModifier} instructions
+ but does not handle C{CompositeField}.
- Convert a gluon.dal.Field into an ExtJS.form.Field and its
- inherited class. It does not handle composite field.
- The conversion takes into account the FieldsModifier instructions.
+ @param field:
+ @type field: gluon.dal.Field
- ExtJS configuration parameters are applied in the following order:
- constructor, modifiers, keyword arguments.
+ @keyword kwargs: any Ext JS configuration parameters of the
+ C{Ext.form.Field} class. They are applied in the following order:
+ constructor, modifiers and keyword arguments.
+
+ @rtype: Field
+
+ @note: The return configurator is a L{Field}. However it can be a
+ L{ComboBox}, a L{DateField}, a L{TextArea}, ...
+ depending on the C{type} of the database field.
+ The association is defined in the dictionary L{FTYPE_TO_XTYPE}.
+
+ @attention: It is recommended to used the more general method L{to_field}
+ which also understands C{CompositeField}.
"""
T = current.T
@@ -130,16 +142,33 @@ def _to_field(field, **kwargs):
def to_field(field, composite=True, **kwargs):
- """Convert a gluon.dal.Field into an Ext.form.Field and its inherited class
- as well as into a composite field, i.e Ext.form.CompositeField.
-
- Composite fields are set using the FieldsModifer.
- Return None if the field is consumed by a CompositeField.
- composite field can be ignore when the keyword argument composite is False.
+ """Build the configurator L{Field} for the database field.
+ The conversion handles L{CompositeField} and takes into account
+ the C{FieldsModifier} instructions.
- ExtJS configuration parameters are applied in the following order:
- constructor, modifiers, keyword arguments.
+ @note: The return configurator is a L{Field}. However it can be a
+ L{ComboBox}, a L{DateField}, a L{TextArea}, ...
+ depending on the C{type} of the database field.
+ The association is defined in the dictionary L{FTYPE_TO_XTYPE}.
+
+ @note: The database fields can be organized in L{CompositeField}
+ in the application model using the modifiers L{FieldsModifier}.
+ @type field: gluon.dal.Field
+ @param field:
+
+ @type composite: bool
+ @param composite: C{CompositeField} is ignored when C{False}.
+
+ @param kwargs: any Ext JS configuration parameter of the C{Ext.form.Field}
+ class. They are applied in the following order:
+ constructor, modifiers and keyword arguments.
+
+ @rtype: Field or C{None}
+
+ @note: Return None when composite is C{True} and when
+ the field is consumed by a C{CompositeField}.
+
"""
table = field.table
tablename = field.tablename
@@ -179,15 +208,23 @@ def to_field(field, composite=True, **kwargs):
def to_fields(table):
- """Convert a gluon.dal.Table into a list of Ext.form.Field,
- Ext.form.CompositeField or and Ext.form.FieldSet.
-
- Individual fields can be organized in Fieldset and in CompositeField.
- They are defined in the application model using modifiers namely
- the FormModifier and the FieldsModifier respectively.
-
- The conversion takes into account the modifier instructions.
-
+ """Build the list of configurators L{Field} for each field
+ of the database C{table}.
+
+ @note: The return configurator is a L{Field}. However it can be a
+ L{ComboBox}, a L{DateField}, a L{TextArea}, ...
+ depending on the C{type} of the database field.
+ The association is defined in the dictionary L{FTYPE_TO_XTYPE}.
+
+ @note: The function handles L{FieldSet} and L{CompositeField}
+ as well as the L{FieldsModifier} instructions.
+ The C{FieldSet} and C{CompositeField} can be defined in the application
+ model using the modifier L{FormModifier} and the L{FieldsModifier}
+ respectively.
+
+ @type table: gluon.dal.Table
+ @rtype: list
+
"""
li = []
tablename = table._tablename
@@ -252,12 +289,19 @@ def to_fields(table):
def to_formPanel(table, **kwargs):
- """Convert a gluon.dal.Table into a ExtJS App.form.FormPanel.
- The conversion takes into account the form modifier instructions.
+ """Build the configurator L{FormPanel} for the database C{table}.
+ The conversion takes into account the L{FormModifier} instructions.
- ExtJS configuration parameters are applied in the following order:
- constructor, modifiers, keyword arguments.
+ @type table: gluon.dal.Table
+ @param table:
+ @param kwargs: any Ext JS configuration parameter of the
+ C{Ext.form.FormPanel} class. They are
+ applied in the following order: constructor, modifiers
+ and keyword arguments.
+
+ @rtype: FormPanel
+
"""
tablename = table._tablename
@@ -280,11 +324,18 @@ def to_formPanel(table, **kwargs):
def to_gridColumn(field, **kwargs):
- """Convert a gluon.dal.Field into an Ext.grid.Column.
- The conversion takes into account the grid modifier instructions.
+ """Build the configurator L{GridColumn} for the database C{field}.
+ The conversion takes into account the L{GridModifier} instructions.
- ExtJS configuration parameters are applied in the following order:
- constructor, modifiers, keyword arguments.
+ @type field: gluon.dal.Field
+ @param field:
+
+ @param kwargs: any Ext JS configuration parameter of the
+ C{Ext.grid.Column} class.
+ They are applied in the following order: constructor, modifiers
+ and keyword arguments.
+
+ @rtype: GridColumn
"""
T = current.T
@@ -332,11 +383,14 @@ def to_gridColumn(field, **kwargs):
def to_gridColumnModel(table):
- """Convert a gluon.dal.Table into an Ext.grid.ColumnModel.
- The conversion takes into account the grid modifier instructions.
-
- Currently the gridColumModel is implemented as a list of gridColumn.
+ """Build the configurator L{GridColumnModel} for the database C{table}.
+ The conversion takes into account the L{GridModifier} instructions.
+
+ @type table: gluon.dal.Table
+ @param table:
+ @rtype: GridColumnModel
+
"""
delete_columns = []
template_columns = []
@@ -369,19 +423,30 @@ def to_gridColumnModel(table):
def to_gridFilter(table, **kwargs):
- """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
+ """Build the configurator L{GridFilter} for thedatabase C{table}.
+ The GridFilter is parametrized using the L{GridModifier}.
- ExtJS configuration parameters are applied in the following order:
+ @type table: gluon.dal.Table
+ @param table:
+
+ @keyword kwargs: any of the Ext JS configuration parameters of the
+ C{App.grid.GridFilter} class. They are applied in the following order:
constructor, modifiers, keyword arguments.
- @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}.
+ @rtype: GridFilter
+
+ @note: Return an empty dictionary if the GridFilter is
+ not defined in the application model.
+
+ @note: A filter rule is defined in the model via the L{GridModifier}.
+ The rule is a C{tuple} containing 3 strings
+ C{("field1", "operator", "comment")}
+ where C{field1} is the name of a field belonging to the C{table}.
+ A more elaborate filter rule allows to filter on any foreign field using
+ the syntax is C{("table2.field1", "operator", "comments")}.
+ Valid operators are defined in L{Dbsvc._encode_query}.
+
+ @note: Rules are store in the modifier section C{grid_filters}.
"""
T = current.T
@@ -470,12 +535,18 @@ def to_gridFilter(table, **kwargs):
def to_gridPanel(table, **kwargs):
- """Convert a gluon.dal.Table into an ExtJS App.grid.GridPanel.
- The conversion takes into account the grid modifier instructions.
+ """Build the configurator L{GridPanel} for the database C{table}.
+ The conversion takes into account the L{GridModifier} instructions.
- ExtJS configuration parameters are applied in the following order:
+ @type table: gluon.dal.Table
+ @param table:
+
+ @keyword kwargs: any of the Ext JS configuration parameters of the
+ C{App.grid.GridPanel} class. They are applied in the following order:
constructor, modifiers, keyword arguments.
+ @rtype: GridPanel
+
"""
tablename = table._tablename
@@ -505,11 +576,18 @@ def to_gridPanel(table, **kwargs):
def to_jsonstore(table, **kwargs):
- """Convert a gluon.dal.Table into an App.data.DirectStore.
+ """Build the configurator L{DirectStore} for the database C{table}.
+ The conversion takes into account the L{StoreModifier} instructions.
- ExtJS configuration parameters are applied in the following order:
+ @type table: gluon.dal.Table
+ @param table:
+
+ @keyword kwargs: any of the Ext JS configuration parameters of the
+ C{App.data.DirectStore} class. They are applied in the following order:
constructor, modifiers, keyword arguments.
+ @rtype: DirectStore
+
"""
db = table._db
tablename = table._tablename
@@ -596,19 +674,27 @@ def to_jsonstore(table, **kwargs):
def to_panelWithUrlSelector(table, selectorTitle='Select', **kwargs):
- """Build the configuration for a simple PanelWithUrlSelector
- where the selector is a form derived from the database table.
+ """Build the configurator L{PanelWithUrlSelector}
+ where the selector is a form derived from the database C{table}.
- The selected values are send to a controller defined by the baseUrl.
+ @type table: gluon.dal.Table
+ @param table:
+
+ @type selectorTitle: str
+ @param selectorTitle: the title of the FieldSet encapsulating
+ the selector fields.
+
+ @keyword 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.
-
- The keyword argument selectoTitle define the title of the FieldSet
- encapsulating the selector fields.
+
+ @keyword kwargs: any of the Ext JS configuration parameters of the
+ C{App.PanelWithUrlSelector} class.
- The others keyword arguments are the configuration parameters
- of the PanelWithUrlSelector. By default is_mathjax is False,
- and panelCfg, selectorCfg, selectorCollapsible are defined.
+ @rtype: PanelWithUrlSelector
+
+ @raise BaseException: when baseUrl is not defined.
"""
if 'baseUrl' not in kwargs:
@@ -633,14 +719,16 @@ def to_panelWithUrlSelector(table, selectorTitle='Select', **kwargs):
def to_tree(node):
- """Convert the Node structure into a list of dictionary
- configuring Ext.tree.TreeNode.
-
- The application navigation tree is defined using ViewportModifier.
+ """Build the list of L{Node}.
+ The Node structure is defined in the application model using
+ L{ViewportModifier}.
- The argument node is required by ExtJS 3.4 but it is not
+ @type node: str
+ @param node: is required by ExtJS 3.4 but it is not
used here.
+ @rtype: list
+
"""
cfg = []
@@ -655,10 +743,13 @@ def to_tree(node):
def to_viewport(**kwargs):
- """Return the configuration dictionary for the App.Viewport.
-
- ExtJS configuration parameters are applied in the following order:
- constructor, modifiers, keyword arguments.
+ """Build the configurator L{Viewport}.
+ The conversion takes into account the L{ViewportModifier} instructions.
+
+ @keyword kwargs: any of the Ext JS configuration parameters of the
+ C{App.Viewport} class.
+
+ @rtype: dict
"""
cfg = {}
diff --git a/modules/plugin_dbui/dbsvc.py b/modules/plugin_dbui/dbsvc.py
index ad9c34ef..3f4781e7 100644
--- a/modules/plugin_dbui/dbsvc.py
+++ b/modules/plugin_dbui/dbsvc.py
@@ -1,4 +1,6 @@
-""" Author: R. Le Gac
+""" the database service.
+
+@author: R. Le Gac
"""
@@ -30,22 +32,37 @@ class DbSvcException(BaseException): pass
class DbSvc(BaseSvc):
- """Interface the database and client request.
+ """Interface the database and the client request.
It is the glue between wep2py and ExtJS library.
- It relies on the Ext.Direct protocol exposing dbSvc methods on
+ It relies on the C{Ext.Direct} protocol exposing dbSvc methods on
the client-side.
Main methods allows to:
- - create a new record in a table.
+ - C{create} a new record in a table.
- - read the content of a a table
+ - C{read} the content of a a table
resolving foreign key.
- - update the record of a table.
+ - C{update} the record of a table.
+
+ - C{destroy} the record of a table.
+
+ These methods receive transaction data, C{arg}, which are structured in the
+ following ways:
+
+ - C{tableName}
+ the name of the table in the database
+
+ - C{dbFields}
+ the list of table fields encoded as C{["table1", "field1"]}.
+
+ - C{records} (optional)
+ a dictionary containing the new / update values for field.
+ The keys are the database field encoded as C{Table1Field1}.
+ A record can also be a list containing the C{id} of the
+ record to be deleted.
- - destroy the record of a table.
-
Each method return a dictionary:
C{{success: True, records:{blabla}, msg: 'blalbla'}}
@@ -66,24 +83,33 @@ class DbSvc(BaseSvc):
def _check_request(self, arg, keywords=('tableName', 'records')):
- """Helper function to check that the request C{arg} is well formed.
- The dictionary C{arg} contains the following keys:
+ """Check that the transaction data C{arg} contains the C{keywords}.
+
+ @type arg: dict
+ @param arg: transaction data
+
+ @type keywords: dict
+ @param keywords: list of keys which have to be in C{arg}
+
+ @note: the transaction data dictionary contains the following
+ information:
- - C{tablename}
+ - C{tableName}
the name of the table in the database
- C{dbFields}
- the list of table fields.
+ the list of table fields encoded as ["table1", "field1"].
- 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.
+ a dictionary containing the new / update values for field.
+ The keys are the database field encoded as C{Table1Field1}.
+ A record can also be a list containing the C{id} of the
+ record to be deleted.
- Raise the C{DbSvcException} if a keyword is missing or if the table
+ @raise DbSvcException: if a keyword is missing or if the table
does not exist in the database.
- """
+ """
# check that the request is well formed
for kword in keywords:
if kword not in arg:
@@ -94,23 +120,28 @@ class DbSvc(BaseSvc):
def _encode_query(self, li):
- """Helper method to encode the list of query send by the client
- as a web2py query::
-
- "[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])"
-
- All elements of the list are ANDED.
+ """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::
+
+ "[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])"
+
+ @rtype: gluon.dal.Query
+
+ @note: All elements of the list are ANDED in the web2py query
- Operators are C{==, !=, <, >, <=, >=}
+ @note: comparison operators are C{==, !=, <, >, <=, >=}
- Boolean operators are C{&, |}
+ @note: Boolean operators are C{&, |}
"""
query = ""
diff --git a/modules/plugin_dbui/extjs.py b/modules/plugin_dbui/extjs.py
index ce61e26c..28a24a62 100644
--- a/modules/plugin_dbui/extjs.py
+++ b/modules/plugin_dbui/extjs.py
@@ -1,6 +1,6 @@
-""" ExtJS components configurators
+""" Configurators for Ext JS components.
-Author: R. Le Gac
+@author: R. Le Gac
"""
@@ -14,17 +14,26 @@ class ExtJSException(BaseException): pass
class Base(dict):
- """Base class for ExtJS configurator.
- A protection is set to avoid changing the xtype of the element.
-
- Two helper functions append_items and append_plugins
- to deal with items and plugins.
+ """Base class for Ext JS configurator.
+
+ The base class comes with two methods C{append_items}
+ and C{append_plugins}. They are required to append C{items}
+ and C{plugins}.
+ @note: A protection is set to avoid changing the C{xtype} of the element.
+
"""
xtype = None
def __init__(self, **kwargs):
-
+ """
+
+ @keyword kwargs: any Ext JS configuration parameter of the target class
+
+ @raise ExtJSException: if the keyword C{xtype}
+ is in the keyword arguments.
+
+ """
if 'xtype' in kwargs:
raise ExtJSException(MSG_XTYPE)
@@ -58,44 +67,44 @@ class Base(dict):
class ArrayStore(Base):
- """Configurator for the Ext.data.ArrayStore."""
+ """Configurator for the C{Ext.data.ArrayStore}."""
xtype='arraystore'
class CheckBox(Base):
- """Configurator for Ext.form.Checkbox."""
+ """Configurator for C{Ext.form.Checkbox}."""
xtype = 'checkbox'
class ComboBox(Base):
- """Configurator for App.form.CombBox."""
+ """Configurator for C{App.form.CombBox}."""
xtype = 'xcombobox'
class CompositeField(Base):
- """Configurator for Ext.form.CompositeField."""
+ """Configurator for C{Ext.form.CompositeField}."""
xtype = 'compositefield'
class DateField(Base):
- """Configurator for Ext.form.DateField."""
+ """Configurator for C{Ext.form.DateField}."""
xtype = 'datefield'
class DirectStore(Base):
- """Configurator for App.data.DirectStore."""
+ """Configurator for C{App.data.DirectStore}."""
xtype = 'xdirectstore'
class Field(Base):
- """Configurator for Ext.form.Field."""
+ """Configurator for C{Ext.form.Field}."""
xtype = 'field'
class FieldSet(Base):
- """Configurator for Ext.form.FieldSet.
+ """Configurator for C{Ext.form.FieldSet}.
- By default, the layout for children Field is set to anchor 99%.
+ @note: By default, the layout for children Field is set to C{anchor 99%}.
It can be overwritten using the keywords defaults.
"""
@@ -107,85 +116,86 @@ class FieldSet(Base):
class FormPanel(Base):
- """Configurator for App.form.FormPanel."""
+ """Configurator for C{App.form.FormPanel}."""
xtype = 'xform'
class GridColumn(dict):
- """Configurator for Ext.grid.Column."""
+ """Configurator for C{Ext.grid.Column}."""
class GridColumnModel(list):
- """Configurator for Ext.grid.ColumnModel implemented
- as a list of GridColumn.
+ """Configurator for C{Ext.grid.ColumnModel}.
+
+ @note:It is implemented as a C{list} of L{GridColumn}.
"""
class GridFilter(Base):
- """Configurator for App.grid.GridFilter."""
+ """Configurator for C{App.grid.GridFilter}."""
xtype = 'xgridfilter'
class GridPanel(Base):
- """Configurator for App.grid.Grid."""
+ """Configurator for C{App.grid.Grid}."""
xtype = 'xgrid'
class GridRowNumberer(Base):
- """Configurator for Ext.grid.RowNumberer."""
+ """Configurator for C{Ext.grid.RowNumberer}."""
xtype = 'rownumberer'
class GridTemplateColumn(Base):
- """Configurator for Ext.grid.TemplateColumn."""
+ """Configurator for C{Ext.grid.TemplateColumn}."""
xtype = 'templatecolumn'
class GridWithFilter(Base):
- """Configurator for App.grid.GridWithFilter."""
+ """Configurator for C{App.grid.GridWithFilter}."""
xtype = 'xgridwithfilter'
class JsonStore(Base):
- """Configurator for the Ext.data.JsonStore."""
+ """Configurator for the C{Ext.data.JsonStore}."""
xtype='jsonstore'
class NumberField(Base):
- """Configurator for Ext.form.NumberField."""
+ """Configurator for C{Ext.form.NumberField}."""
xtype = 'numberfield'
class Panel(Base):
- """Configurator for Ext.Panel."""
+ """Configurator for C{Ext.Panel}."""
xtype = 'panel'
class PanelWithUrlSelector(Base):
- """Configurator for App.PanelWithUrlSelector."""
+ """Configurator for C{App.PanelWithUrlSelector}."""
xtype = 'xpanelwithurlselector'
class Spacer(Base):
- """Configurator for Ext.Spacer."""
+ """Configurator for C{Ext.Spacer}."""
xtype = 'spacer'
class Store(Base):
- """Configurator for the Ext.data.Store."""
+ """Configurator for the C{Ext.data.Store}."""
xtype='store'
class TabPanel(Base):
- """Configurator for Ext.TabPanel."""
+ """Configurator for C{Ext.TabPanel}."""
xtype = 'tabpanel'
class TextArea(Base):
- """Configurator for Ext.form.TextArea.
+ """Configurator for C{Ext.form.TextArea}.
- Regular expression for the validation can be written as a string.
+ @note: Regular expression for the validation can be written as a string.
"""
xtype = 'textarea'
@@ -196,9 +206,9 @@ class TextArea(Base):
class TextField(Base):
- """Configurator for Ext.form.TextField.
+ """Configurator for C{Ext.form.TextField}.
- Regular expression for the validation can be written as a string.
+ @note: Regular expression for the validation can be written as a string.
"""
xtype = 'textfield'
@@ -209,16 +219,16 @@ class TextField(Base):
class TimeField(Base):
- """Configurator for Ext.form.TimeField."""
+ """Configurator for C{Ext.form.TimeField}."""
xtype = 'timefield'
class Viewport(Base):
- """Configurator for App.Viewport."""
+ """Configurator for C{App.Viewport}."""
xtype = 'xviewport'
class XmlStore(Base):
- """Configurator for the Ext.data.XmlStore."""
+ """Configurator for the C{Ext.data.XmlStore}."""
xtype='xmlstore'
\ No newline at end of file
--
GitLab