diff --git a/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.count.rst b/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.count.rst
new file mode 100644
index 0000000000000000000000000000000000000000..677601c0fa938e7ec3214fd67c054b78c6a9b2a1
--- /dev/null
+++ b/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.count.rst
@@ -0,0 +1,6 @@
+plugin_dbui.dbsvc.DbSvc.count
+=============================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. automethod:: DbSvc.count
\ No newline at end of file
diff --git a/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.create.rst b/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.create.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0ce043453df09466a3320c378be8dc307755ea68
--- /dev/null
+++ b/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.create.rst
@@ -0,0 +1,6 @@
+plugin_dbui.dbsvc.DbSvc.create
+==============================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. automethod:: DbSvc.create
\ No newline at end of file
diff --git a/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.dbg.rst b/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.dbg.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b8f0a087a3e794066542c59ba1ca660c48a7b0a8
--- /dev/null
+++ b/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.dbg.rst
@@ -0,0 +1,6 @@
+plugin_dbui.dbsvc.DbSvc.dbg
+===========================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. automethod:: DbSvc.dbg
\ No newline at end of file
diff --git a/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.destroy.rst b/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.destroy.rst
new file mode 100644
index 0000000000000000000000000000000000000000..98d3a089f9c89b5c5006798f842e0b13b424a98e
--- /dev/null
+++ b/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.destroy.rst
@@ -0,0 +1,6 @@
+plugin_dbui.dbsvc.DbSvc.destroy
+===============================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. automethod:: DbSvc.destroy
\ No newline at end of file
diff --git a/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.read.rst b/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.read.rst
new file mode 100644
index 0000000000000000000000000000000000000000..18e564d7d10fa64a6c027b62df423986f63742bb
--- /dev/null
+++ b/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.read.rst
@@ -0,0 +1,6 @@
+plugin_dbui.dbsvc.DbSvc.read
+============================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. automethod:: DbSvc.read
\ No newline at end of file
diff --git a/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.update.rst b/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.update.rst
new file mode 100644
index 0000000000000000000000000000000000000000..d91545d484d8807e73f279b720bef5947a2f0fa3
--- /dev/null
+++ b/docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.update.rst
@@ -0,0 +1,6 @@
+plugin_dbui.dbsvc.DbSvc.update
+==============================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. automethod:: DbSvc.update
\ No newline at end of file
diff --git a/docs/api/generated/plugin_dbui.dbsvc.DbSvc.rst b/docs/api/generated/plugin_dbui.dbsvc.DbSvc.rst
new file mode 100644
index 0000000000000000000000000000000000000000..45ffdd829009d6cd2e506f4d4d88188563cf5a2c
--- /dev/null
+++ b/docs/api/generated/plugin_dbui.dbsvc.DbSvc.rst
@@ -0,0 +1,24 @@
+plugin_dbui.dbsvc.DbSvc
+=======================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. autoclass:: DbSvc
+ :show-inheritance:
+
+ .. rubric:: Methods
+
+ .. autosummary::
+ :toctree: dbsvc/
+
+ ~DbSvc.count
+ ~DbSvc.create
+ ~DbSvc.dbg
+ ~DbSvc.destroy
+ ~DbSvc.read
+ ~DbSvc.update
+
+
+
+
+
diff --git a/modules/plugin_dbui/dbsvc.py b/modules/plugin_dbui/dbsvc.py
index a4653dfbe6b3f7f40e004ac397a3972c20f6b98a..efffc46e360c466651cba14b73b57a051e797283 100644
--- a/modules/plugin_dbui/dbsvc.py
+++ b/modules/plugin_dbui/dbsvc.py
@@ -46,7 +46,7 @@ class DbSvcException(BaseException): pass
class DbSvc(BaseSvc):
"""Interface the database and the client request.
It is the glue between wep2py and Ext JS library.
- This service is the companion of L{DirectSvc} which implements
+ This service is the companion of :class:`.DirectSvc` which implements
the ``Ext.Direct`` protocol on the server side.
This protocol exposes methods of the ``DbSvc`` service directly
on the client-side.
@@ -60,13 +60,14 @@ class DbSvc(BaseSvc):
.. _input transaction dictionary:
- These methods receive the *transaction data dictionary*, ``arg``:
+ These methods receive the *transaction data dictionary*, ``arg``.
+ It as mainly three keys:
* ``tableName`` the name of the table in the database
* ``dbFields`` The list of database fields of the table,
``[["table1", "field1"], ... ]`` including foreign keys
- and reference fields.
+ and their reference fields.
* ``records`` (optional) A list of dictionaries containing key,
value pairs for fields to be created or updated,
@@ -365,8 +366,9 @@ class DbSvc(BaseSvc):
def create(self, arg):
- """Create new records defined by the transaction data ``arg``.
- Several transactions of the same type are processed together.
+ """Create new records defined by the transaction dictionary *arg*.
+
+ Several *create* transactions can be processed at the same time.
Args:
arg (dict): :ref:`input transaction dictionary <input transaction dictionary>`
@@ -374,12 +376,18 @@ class DbSvc(BaseSvc):
Returns:
dict:
:ref:`output transaction dictionary <output transaction dictionary>`
- The full transaction is aborted when at least one field value
- is not validated by the database engine or when the transaction
- is killed by the callback ``table._before_insert``.
- In that scenario, the ``errors`` key contains either a string,
- the error message return by callback, or the dictionary returns
- by the validator.
+
+ The full transaction is aborted when:
+ * at least one field value is not validated by the
+ database engine. The keyword ``errors`` contains the
+ dictionary returns by the validator (the key is the field
+ identifier encoded as ``Table1Field1`` while the value is
+ the error message).
+
+ * It is is killed by the callback defined in the
+ database model, ``db[tablename]._before_insert``.
+ The keyword ``errors`` contains the string returns by
+ the callback.
"""
self.dbg("Start DbSvc.create")
@@ -428,26 +436,30 @@ class DbSvc(BaseSvc):
def destroy(self, arg):
- """Delete existing records defined by the transaction data ``arg``.
- Several transactions of the same type are processed together.
+ """Delete existing records defined by the transaction dictionary *arg*.
+
+ Several *destroy* transactions can be processed at the same time.
Args:
arg (dict):
:ref:`input transaction dictionary <input transaction dictionary>`
- The key ``records`` is the list of ``id`` to be deleted
+ The keyword ``records`` contains the list of ``id`` to be deleted
*e.g.* ``[id1, id2, ... ]``.
Returns:
dict:
:ref:`output transaction dictionary <output transaction dictionary>`
- * The key``records`` is a list of dictionary containing the ``id``
- of the delete records *e.g.* ``[{TableId:xx}, ..]``.
+ * The keyword ``records`` is the list of dictionary containing the ``id``
+ of the deleted records *e.g.* ``[{TableId:xx}, ..]``.
+
+ * The full transaction is aborted when:
+ - one record does not exist
- * The full transaction is aborted when either one record does
- not exist or when the delete operation is rejected by the
- callback ``table._before_delete``. The ``errors`` key
- contains the error messages return by the callback.
+ - the delete operation is rejected by the
+ callback ``db[tablename]._before_delete`` defined in
+ the database model. The keyword ``errors`` contains
+ the error message returns by the callback.
"""
self.dbg("Start DbSvc.destroy")
@@ -491,39 +503,40 @@ class DbSvc(BaseSvc):
def read(self, arg):
- """Read the content of a table as specified in the transaction data ``arg``.
- The ``arg`` dictionary contains the following keys:
+ """Read the content of a table as specified in the transaction
+ dictionary *arg*.
Args:
- arg (dict):
- :ref:`input transaction dictionary <input transaction dictionary>`
+ arg (dict): :ref:`input transaction dictionary
+ <input transaction dictionary>`
- * The *optional* key ``where`` (optional) is a list of string
- to build the inner join when handling foreign key::
+ * The *optional* key ``where`` is a list of string
+ to build the inner join when handling foreign key::
- ['db.table1.field1 == db.table2.id', ... ]
+ ['db.table1.field1 == db.table2.id', ... ]
- The string syntax follows the web2py convention:
- ``db.table1.field1 == db.table2.id``. An AND is performed
- between the different elements of the list.
+ The syntax follows the web2py convention
+ ``db.table1.field1 == db.table2.id``.
+ The different conditions are ANDed.
- * the *optional* key ``orderby`` is a list of tuples to build
- the order directive::
+ * the *optional* key ``orderby`` is a list of tuples to build
+ the order directive::
- [("table1", "field1", "dir"), ("table2", "field3", "dir"), ...]
+ [("table1", "field1", "dir"), ("table2", "field3", "dir"), ...]
- The third argument is equal to ``"ASC"`` or ``"DESC"``.
+ The third argument is equal to ``"ASC"`` or ``"DESC"``.
- * The transaction dictionary can also contains parameters useful
- for paging. For more detail see the Ext.PagingToolbar
- configuration parameters: ``page``, ``start``, ``limit``,
- ``sort`` and ``dir``.
+ * The transaction dictionary can also contains parameters useful
+ for paging. For more details, see the ``Ext.toolbar.Paging``
+ configuration parameters: ``page``, ``start``, ``limit``,
+ ``sort`` and ``dir``.
Returns:
dict:
:ref:`output transaction dictionary <output transaction dictionary>`
- The key ``records`` is a list of dictionary containing the key value
- pairs for the record found in the database.
+
+ * The keyword ``records`` is a list of dictionary containing all
+ key value pairs for the record found in the database.
"""
self.dbg("Start DbSvc.read")
@@ -597,15 +610,18 @@ class DbSvc(BaseSvc):
def update(self, arg):
- """Update records defined by the transaction data ``arg``.
- Several transactions of the same type are processed together.
+ """Update records defined by the transaction dictionary *arg*.
+
+
+ Several update transactions can be processed at the same time.
Args:
- arg (dict):
- :ref:`input transaction dictionary <input transaction dictionary>`
- the key ``records`` is the list of dictionaries one per record to
- be updated. Each dictionary contains key, value pairs for fields
- to be updated as well as the record ``id``.
+ arg (dict): :ref:`input transaction dictionary
+ <input transaction dictionary>`.
+ The keyword ``records`` is the list of dictionaries,
+ one per record to be updated. Each dictionary contains
+ key, value pairs for fields to be updated as well as
+ the record ``id``.
Returns:
dict:
@@ -614,13 +630,16 @@ class DbSvc(BaseSvc):
* the key ``records`` is a list of dictionary containing the complete
key, value pairs for the ``record`` updated in the database.
- * The full transaction is aborted when either a field value is not
- validated by the database engine or when the transaction
- is kill by the callback ``table._before_update``.
- The *errors* key contains the error message return by callback or
- a dictionary returns by the validator (the key is the field
- identifier encoded as ``Table1Field1`` while the value is
- the error message).
+ * The full transaction is aborted when:
+ - a field value is not validated by the database engine.
+ The *errors* key contains the dictionary returns by the
+ validator (the key is the field identifier encoded as
+ ``Table1Field1`` while the value is the error message).
+
+ - the transaction is killed by the callback
+ ``db[tablename]._before_update`` defined in the database
+ model. The *errors* key contains the message (str)
+ returns by callback
"""
self.dbg("Start DbSvc.update.")