From c5397581b1da3ac5e7435c7579b283389c94c33a Mon Sep 17 00:00:00 2001
From: legac <renaud.legac@free.fr>
Date: Sun, 7 Apr 2013 16:42:10 +0200
Subject: [PATCH] Imorice the documentation of dbsvc using epytext.
---
modules/plugin_dbui/converter.py | 2 +-
modules/plugin_dbui/dbsvc.py | 476 +++++++++++++++++++------------
2 files changed, 302 insertions(+), 176 deletions(-)
diff --git a/modules/plugin_dbui/converter.py b/modules/plugin_dbui/converter.py
index f7a73d3c..0d183a3f 100644
--- a/modules/plugin_dbui/converter.py
+++ b/modules/plugin_dbui/converter.py
@@ -444,7 +444,7 @@ def to_gridFilter(table, **kwargs):
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}.
+ Valid operators are defined in the method L{DbSvc._encode_query}.
@note: Rules are store in the modifier section C{grid_filters}.
diff --git a/modules/plugin_dbui/dbsvc.py b/modules/plugin_dbui/dbsvc.py
index 3f4781e7..3a097b11 100644
--- a/modules/plugin_dbui/dbsvc.py
+++ b/modules/plugin_dbui/dbsvc.py
@@ -34,10 +34,10 @@ class DbSvcException(BaseException): pass
class DbSvc(BaseSvc):
"""Interface the database and the client request.
It is the glue between wep2py and ExtJS library.
- It relies on the C{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:
+ The main methods allow to:
- C{create} a new record in a table.
@@ -48,65 +48,100 @@ class DbSvc(BaseSvc):
- C{destroy} the record of a table.
- These methods receive transaction data, C{arg}, which are structured in the
- following ways:
+ These methods receive transaction data dictionary, C{arg}:
- - C{tableName}
- the name of the table in the database
-
- - C{dbFields}
- the list of table fields encoded as C{["table1", "field1"]}.
+ - C{tableName}
+ the name of the table in the database
+
+ - C{dbFields}
+
+ - C{[["table1", "field1"], ... ]}
+
+ - The list of database fields of the table.
+
+ - Include foreign keys and reference fields.
- - 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.
+ - C{records} (optional)
+
+ - C{[{"Table1Field1": val1,...}]}
+
+ - A list of dictionaries containing key, value pairs for fields
+ to be created or updated
+
+ - Includes foreign key and reference field values.
+
+ - Contains the C{id} of the record to be updated.
+
+ - The keys are encoded as C{Table1Field1}.
+
+ - The C{records} can also be a list containing the C{id} of the
+ records to be deleted.
Each method return a dictionary:
- C{{success: True, records:{blabla}, msg: 'blalbla'}}
+
+ - C{{success: True, records:[{blabla}, ..], msg: 'blalbla'}}
- 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.
+ - The keyword C{success} is always present. It is mandatory for
+ the C{FormPanel} widget of the Ext JS library, but not strictly
+ required since failure can be propagated through HTTP errors.
- In the records dictionary database field are encoded as C{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.
+ - If the action failed the C{DbSvcException} is raised.
+ The exception can be catch to generate an HTTP error.
"""
def __init__(self, environment):
-
+ """
+ @param environment: contains the global variables
+ namely C{db} and C{T}.
+
+ >>> svc = DbSvc(globals())
+
+ """
BaseSvc.__init__(self, environment)
db = self.environment['db']
def _check_request(self, arg, keywords=('tableName', 'records')):
- """Check that the transaction data C{arg} contains the C{keywords}.
+ """Check that the transaction data dictionary 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}
the name of the table in the database
- C{dbFields}
- the list of table fields encoded as ["table1", "field1"].
+
+ - C{[["table1", "field1"], ... ]}
+
+ - The list of database fields of the table.
+
+ - Include foreign keys and reference fields.
- 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.
+
+ - C{[{"Table1Field1": val1,...}]}
+
+ - A list of dictionaries containing key, value pairs for fields
+ to be created or updated
+
+ - Includes foreign key and reference field values.
+
+ - Contains the C{id} of the record to be updated.
+
+ - The keys are encoded as C{Table1Field1}.
+
+ - The C{records} can also be a list containing the C{id} of the
+ records to be deleted.
- @raise DbSvcException: if a keyword is missing or if the table
+
+ @type keywords: dict
+ @param keywords: list of keys which have to be in C{arg}
+
+ @raise DbSvcException: when a keyword is missing or when the table
does not exist in the database.
"""
@@ -120,7 +155,7 @@ class DbSvc(BaseSvc):
def _encode_query(self, li):
- """Encode the query send by the client to a web2py Query.
+ """Encode the query send by the client to a web2py l{Query}.
@type li: list
@param li: the query send by the client as a list of string.
@@ -166,9 +201,18 @@ class DbSvc(BaseSvc):
def _get_record(self, table, id):
- """Helper function to get the record id in a form which can be decoded
- by the JsonReader running on the client side. Foreign key are resolved.
- Return a dictionary where key are encoded as TableField.
+ """Get the record C{id} located in the database C{table}.
+
+ @type table: gluon.dal.Table
+ @param table:
+
+ @type id: int
+ @param id:
+
+ @rtype: dict
+ @return: key, value pairs where each key corresponds
+ to a field of the table. Foreign keys are resolved.
+ The key are encoded as C{Table1Field1}.
"""
db = self.environment['db']
@@ -189,19 +233,36 @@ class DbSvc(BaseSvc):
def _is_field_in_table(self, table, field):
- """Helper method to check that the field belongs to the table.
- Return a boolean.
+ """Check that the C{field} belongs to the C{table}.
+
+ @type table: gluon.dal.Table
+ @param table:
+
+ @type field: gluon.dal.Field
+ @param field:
+
+ @rtype: bool
"""
return field in self.environment['db'][table].fields
def _is_fields_values_valid(self, table, fields):
- """Helper method to check each field value against its validators.
+ """Check each C{field} value against its C{validators}.
+
+
+ @type table: gluon.dal.Table
+ @param table:
- Return an empty dictionary when everything is OK or a dictionary
- with fields failing check: {field1: error1, field2: error2,...}
+ @type fields: dict
+ @param fields: key, value pairs where each key corresponds
+ to a C{gluon.dal.Field}
+ @rtype: dict
+ @return: key, value pairs for each field with errors.
+ The key is encoded as C{Table1Field1} and the value is a string
+ describing the error message.
+
"""
di = {}
db = self.environment['db']
@@ -223,10 +284,14 @@ class DbSvc(BaseSvc):
def _is_table_in_db(self, tablename):
- """Helper method to check that a table exist in the database.
- The method handles regular and alias tables.
+ """Check that the table exists in the database.
+
+ @type tablename: str
+ @param tablename: name of the table
- Raise the DbSvcException if not.
+ @raise DbSvcException: when the table does not exists
+
+ @note: The method works with regular and alias tables.
"""
db = self.environment['db']
@@ -237,45 +302,59 @@ class DbSvc(BaseSvc):
def _prepare_records(self, arg):
- """Helper method to prepare the records for their insertion
+ """Prepare the transaction data dictionary, C{arg}, for its insertion
in the database (create or update).
- The current transaction is defined in the dictionary C{arg}.
- It is associated to one table and can contain several records.
+ The method removes fields in the record which do not belong to the
+ table since the JsonStore send the foreign key and the reference field.
+ The latter are not used in create / update transaction.
+
+ The method also validates each value.
+
+ @type arg: dict
+ @param arg: transaction data
- - C{tablename}
+ - C{tableName}
the name of the table in the database
- 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)}
- 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.
- Pointing fields are not used here.
-
- The method also validates values.
+
+ - C{[["table1", "field1"], ... ]}
+
+ - The list of database fields of the table.
+
+ - Include foreign keys and reference fields.
- Return a Storage::
-
- {
- "errors": [None,...],
- "records": [{TableField: value,...}, ..]
- }
-
- 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::
-
- {TableField: "error message", ...}
-
+ - C{records}
+
+ - C{[{"Table1Field1": val1,...}]}
+
+ - A list of dictionaries containing key, value pairs for fields
+ to be created or updated
+
+ - Includes foreign key and reference field values.
+
+ - Contains the C{id} of the record to be updated.
+
+ - The keys are encoded as C{Table1Field1}.
+
+ @rtype: gluon.storage.Storage
+ @return:
+
+ - C{Storage(errors=[], records=[])}
+
+ - One to one correspondence between the errors
+ and the records lists
+
+ - C{records} is a list of dictionaries containing key value pairs
+ where the key corresponds to a database field.
+ The keys are encoded as C{Table1Field1}.
+
+ - The C{error} is C{None} when the C{record} is validated.
+ Otherwise the error is a dictionary
+ C{{Table1Field1: "error message", ...}}
+
"""
- data = Storage(errors=[], records=[])
table = arg['tableName']
for record in arg[ROOT]:
@@ -305,37 +384,49 @@ class DbSvc(BaseSvc):
def create(self, arg):
- """Create new records defined in the transaction C{arg}.
- The dictionary C{arg} contains the following keys:
+ """Create new records defined by the transaction data C{arg}.
+ Several transactions of the same type are processed together.
+
+ @type arg: dict
+ @param arg: transaction data
- C{tableName}
the name of the table in the database
- 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 C{status}, message and the update row::
-
- {
- success: True,
- msg: 'blalbla',
- records: [{TableId: xxx,....}, ...]
- }
+ - C{[["table1", "field1"], ... ]}
+
+ - The list of database fields of the table.
+
+ - Include foreign keys and reference fields.
- 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::
-
- {
- success: False,
- errors: {TableField: error message, ..},
- records:{TableField: xxx, ...}
- }
+ - C{records}
+
+ - C{[{"Table1Field1": val1,...}]}
+
+ - A list of dictionaries containing key, value pairs for fields
+ to be created.
+
+ - Includes foreign key and reference field values.
+
+ - The keys are encoded as C{Table1Field1}.
+
+ @rtype: dict
+ @return:
+
+ - C{{success: True, records:[{Table1Field1: val, ... }, ... ],
+ msg: 'blalbla'}}
+
+ - C{records} is a list of dictionary containing the complete
+ key, value pairs for the C{record} created in the database.
+
+ - The record keys are encoded as C{Table1Field1}.
+
+ - When at least a field value is not validated, abort the full
+ transaction and append the dictionary C{errors}. It contains
+ the error messages for the first bad record,
+ C{{Table1Field1: error message, ..}}.
"""
self.dbg("Start DbSvc.create")
@@ -368,37 +459,40 @@ class DbSvc(BaseSvc):
def destroy(self, arg):
- """Destroy the record defined in the transaction C{arg}.
- The dictionary C{arg} contains the following keys:
+ """Delete existing records defined by the transaction data C{arg}.
+ Several transactions of the same type are processed together.
+
+ @type arg: dict
+ @param arg: transaction data
-
- C{tableName}
- the name of the table in the database.
+ the name of the table in the database
- 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 with id numbers
- Return a dictionary with C{status}, message and ids of the deleted row::
-
- {
- success: True,
- msg: 'blalbla',
- records:[{TableId:xx}, ..]
- }
+ - C{[["table1", "field1"], ... ]}
+
+ - The list of database fields of the table.
+
+ - Include foreign keys and reference fields.
- 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::
-
- {
- success: False,
- msg: 'blalbla',
- records:{TableId:xx}
- }
+ - C{records} the list of C{id} for the records
+ to be deleted, C{[id1, id2, ... ]}.
+
+ @rtype: dict
+ @return:
+
+ - C{{success: True, records:[{Table1Id1: id}, ...], msg: 'blalbla'}}
+
+ - C{records} is a list of dictionary containing the C{id}
+ of the delete records: C{[{TableId:xx}, ..]}.
+
+ - The record key are encoded as C{Table1Field1}.
+
+ - When at least one record does not exist, abort the full transaction
+ and add the dictionary C{errors}. It contains
+ the error messages for the first bad record,
+ C{{Table1Field1: error message, ..}}.
"""
self.dbg("Start DbSvc.destroy")
@@ -428,43 +522,61 @@ class DbSvc(BaseSvc):
def read(self, arg):
- """Read the content of a table as specified in the transaction C{arg}.
+ """Read the content of a table as specified in the transaction data C{arg}.
The C{arg} dictionary contains the following keys:
-
+
+ @type arg: dict
+ @param arg: transaction data
+
- C{tableName}
- name of the database table
+ the name of the table in the database
- C{dbFields}
- a list of field to be read.
- It also include pointing field resolving foreign keys.
- C{[(table1, field1), (table1, field2), (table2, field3), ...]}
+
+ - C{[["table1", "field1"], ... ]}
+
+ - The list of database fields of the table.
+
+ - Include foreign keys and reference fields.
- - 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{where} (optional)
+
+ - C{['db.table1.field1 == db.table2.id', ... ]}
+
+ - a list of string to build the inner join
+ when handling foreign key.
+
+ - The string 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"}
+
+ - C{[("table1", "field1", "dir"), ("table2", "field3", "dir"), ...]}
- The dictionary can also contains parameters useful for paging.
+ - a list of tuples to build the order directive.
+
+ - the third argument is equal to C{"ASC"} or C{"DESC"}.
+
+ The transaction data can also contains parameters useful for paging.
For more detail see Ext.PagingToolbar:
- start
- limit
- sort
- dir
- The method return a list of records::
+ @rtype: dict
+ @return:
+
+ - C{{success: True, records: [{TableField: value, ...}, ...]}}
+
+ - C{records} is a list of dictionary containing the key value
+ pairs for the record found in the database.
+
+ - the record keys are encoded as C{Table1Field1}.
- {
- success: True,
- records: [{TableField: value, ...}, ...]
- }
-
"""
self.dbg("Start DbSvc.read")
@@ -519,37 +631,51 @@ class DbSvc(BaseSvc):
def update(self, arg):
- """Update records defined in the transaction C{arg}.
- The C{arg} dictionary contains the following keys:
+ """Update records defined by the transaction data C{arg}.
+ Several transactions of the same type are processed together.
+ @type arg: dict
+ @param arg: transaction data
+
- C{tableName}
the name of the table in the database
- 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 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::
-
- {
- success: True,
- msg: 'blalbla',
- records: [{TableId: xxx,....}, ...]
- }
-
- 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::
-
- {
- success: False,
- errors: {TableField: error message, ..},
- records:{TableField: xxx, ...}
- }
+
+ - C{[["table1", "field1"], ... ]}
+
+ - The list of database fields of the table.
+
+ - Include foreign keys and reference fields.
+
+ - C{records}
+
+ - C{[{"Table1Field1": val1,...}]}
+
+ - A list of dictionaries containing key, value pairs for fields
+ to be updated
+
+ - Includes foreign key and reference field values.
+
+ - Contains the C{id} of the record to be updated.
+
+ - The keys are encoded as C{Table1Field1}.
+
+ @rtype: dict
+ @return:
+
+ - C{{success: True, records:[{Table1Field1: val, ... }, ... ],
+ msg: 'blalbla'}}
+
+ - C{records} is a list of dictionary containing the complete
+ key, value pairs for the C{record} updated in the database.
+
+ - The record keys are encoded as C{Table1Field1}.
+
+ - When at least a field value is not validated, abort the full
+ transaction and append the dictionary C{errors}. It contains
+ the error messages for the first bad record,
+ C{{Table1Field1: error message, ..}}.
"""
self.dbg("Start DbSvc.update.")
--
GitLab