Review dbsvc.py documentation.

docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.count.rst

+plugin_dbui.dbsvc.DbSvc.count
+=============================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. automethod:: DbSvc.count
\ No newline at end of file

docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.create.rst

+plugin_dbui.dbsvc.DbSvc.create
+==============================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. automethod:: DbSvc.create
\ No newline at end of file

docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.dbg.rst

+plugin_dbui.dbsvc.DbSvc.dbg
+===========================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. automethod:: DbSvc.dbg
\ No newline at end of file

docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.destroy.rst

+plugin_dbui.dbsvc.DbSvc.destroy
+===============================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. automethod:: DbSvc.destroy
\ No newline at end of file

docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.read.rst

+plugin_dbui.dbsvc.DbSvc.read
+============================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. automethod:: DbSvc.read
\ No newline at end of file

docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.update.rst

+plugin_dbui.dbsvc.DbSvc.update
+==============================
+
+.. currentmodule:: plugin_dbui.dbsvc
+
+.. automethod:: DbSvc.update
\ No newline at end of file

docs/api/generated/plugin_dbui.dbsvc.DbSvc.rst

+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
+
+
+
+
+

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.")