Commit 7bb893a4 authored by LE GAC Renaud's avatar LE GAC Renaud
Browse files

First pass to remove epydoc error.

parent 46f8ab1b
......@@ -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
......
......@@ -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,
......
......@@ -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())
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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