From 1d61fa471dfc52b65f4c24308555c4910c8e5cb9 Mon Sep 17 00:00:00 2001
From: Renaud Le Gac <legac@cppm.in2p3.fr>
Date: Wed, 15 Apr 2015 18:19:51 +0200
Subject: [PATCH] Review dbsvc.py documentation.
---
.../dbsvc/plugin_dbui.dbsvc.DbSvc.count.rst | 6 +
.../dbsvc/plugin_dbui.dbsvc.DbSvc.create.rst | 6 +
.../dbsvc/plugin_dbui.dbsvc.DbSvc.dbg.rst | 6 +
.../dbsvc/plugin_dbui.dbsvc.DbSvc.destroy.rst | 6 +
.../dbsvc/plugin_dbui.dbsvc.DbSvc.read.rst | 6 +
.../dbsvc/plugin_dbui.dbsvc.DbSvc.update.rst | 6 +
.../api/generated/plugin_dbui.dbsvc.DbSvc.rst | 24 ++++
modules/plugin_dbui/dbsvc.py | 127 ++++++++++--------
8 files changed, 133 insertions(+), 54 deletions(-)
create mode 100644 docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.count.rst
create mode 100644 docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.create.rst
create mode 100644 docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.dbg.rst
create mode 100644 docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.destroy.rst
create mode 100644 docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.read.rst
create mode 100644 docs/api/generated/dbsvc/plugin_dbui.dbsvc.DbSvc.update.rst
create mode 100644 docs/api/generated/plugin_dbui.dbsvc.DbSvc.rst
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 00000000..677601c0
--- /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 00000000..0ce04345
--- /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 00000000..b8f0a087
--- /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 00000000..98d3a089
--- /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 00000000..18e564d7
--- /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 00000000..d91545d4
--- /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 00000000..45ffdd82
--- /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 a4653dfb..efffc46e 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.")
--
GitLab