Review selector.py documentation.

docs/api/generated/plugin_dbui.selector.Selector.rst

+plugin_dbui.selector.Selector
+=============================
+
+.. currentmodule:: plugin_dbui.selector
+
+.. autoclass:: Selector
+   :show-inheritance:
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree: selector/
+
+      ~Selector.append_query
+      ~Selector.as_dict
+      ~Selector.fields
+      ~Selector.query
+      ~Selector.repr_url
+      ~Selector.select
+
+
+
+
+

docs/api/generated/selector/plugin_dbui.selector.Selector.append_query.rst

+plugin_dbui.selector.Selector.append_query
+==========================================
+
+.. currentmodule:: plugin_dbui.selector
+
+.. automethod:: Selector.append_query
\ No newline at end of file

docs/api/generated/selector/plugin_dbui.selector.Selector.as_dict.rst

+plugin_dbui.selector.Selector.as_dict
+=====================================
+
+.. currentmodule:: plugin_dbui.selector
+
+.. automethod:: Selector.as_dict
\ No newline at end of file

docs/api/generated/selector/plugin_dbui.selector.Selector.fields.rst

+plugin_dbui.selector.Selector.fields
+====================================
+
+.. currentmodule:: plugin_dbui.selector
+
+.. automethod:: Selector.fields
\ No newline at end of file

docs/api/generated/selector/plugin_dbui.selector.Selector.query.rst

+plugin_dbui.selector.Selector.query
+===================================
+
+.. currentmodule:: plugin_dbui.selector
+
+.. automethod:: Selector.query
\ No newline at end of file

docs/api/generated/selector/plugin_dbui.selector.Selector.repr_url.rst

+plugin_dbui.selector.Selector.repr_url
+======================================
+
+.. currentmodule:: plugin_dbui.selector
+
+.. automethod:: Selector.repr_url
\ No newline at end of file

docs/api/generated/selector/plugin_dbui.selector.Selector.select.rst

+plugin_dbui.selector.Selector.select
+====================================
+
+.. currentmodule:: plugin_dbui.selector
+
+.. automethod:: Selector.select
\ No newline at end of file

modules/plugin_dbui/selector.py

@@ -33,36 +33,28 @@ from helper import (decode_field,
 class Selector(Storage):
     """Basic tool to build a report:
 
-        * Decode the data send by the selector widget.
+        * Decode the data send by the selector form.
         * Build the query for a given table of the database.
-        * Select Rows for a given table of the database.
-
-    This class handle table and its reference field.
-    The basic query handles the selector constraints
-    and the inner join for reference field. Additional
-    constraints can also be added via the method :meth:`append_query`.
-
-    All fields of the selector are attributes of this class::
-
-        value = myselector.myfield
-        value = myselector['myfield']
-
-    The type of the return value is the type of the field
-    defined in the model.
+          The basic query handles constraints from the selected
+          values as well as the the inner join for reference field.
+          Additional constraints can also be added via the
+          method :meth:`append_query`.
+        * Select Rows for a given table of the database using the query
+          defined in the previous item.
+
+    Args:
+        table (gluon.dal.Table):
+            the model of the database table is used to build the form.
+            Each field of the table is transformed into a form field widget.
+            In addition, each database field is mapped to a selector attribute
+            containing the value chosen by the user.
+
+        exclude_fields (tuple):
+            a list of database field names
+            which have to be ignored in query and select operations.
 
     """
     def __init__(self, table, exclude_fields=()):
-        """
-
-        Args:
-            table (gluon.dal.Table):
-                the table containing the definition of the selector
-
-            exclude_fields (tuple):
-                a list of selector field names
-                which have to be ignored in query and select operations.
-
-        """
 
         self._exclude_fields = exclude_fields
         self._extension = None
@@ -116,7 +108,7 @@ class Selector(Storage):
 
     def append_query(self, query):
         """Add constraints which will be used in the database query
-        and database select operations.
+        and select operations.
 
         Args:
             query (gluon.dal.Query): database query
@@ -156,11 +148,12 @@ class Selector(Storage):
         """Build the database query for the database table.
         It includes:
 
-            * inner join for reference fields,
-            * selector constraints,
+            * inner join for reference fields
+            * selector constraints
             * extra queries added via the :meth:`append_query` method.
-            * the ``extfield`` as well as fields in the ``exclude_fields``
-              tuple are not take into account in the query.
+            * the ``extfield`` attribute as well as the ``exclude_fields``
+              specified in the constructor are not take into account in
+              the query.
 
         Args:
             table (gluon.dal.Table): database table
@@ -229,21 +222,23 @@ class Selector(Storage):
 
 
     def select(self, table, *args, **kwargs):
-        """Select the records of the table according to the selector constraints
-        and to the extra queries.
+        """Select the records of the *table* according to the selector
+        constraints and to the extra queries.
 
-            * The ``extfield`` as well as the fields in the ``exclude_fields``
-              tuple are not take into account in the underlying query.
+        Notes:
+            * The ``extfield`` attribute as well as the ``exclude_fields``
+              specified in the constructor are not take into account in the
+              underlying query.
 
-            * It returns Rows which contains reference tables and columns.
+            * the returns Rows contains reference tables and columns.
 
         Args:
             table (gluon.dal.Table): database table
-            args (list): field with operator (avg, count, max, min and sum)
+            *args (list): variable list of fields with operator
+                like ``avg``, ``count``, ``max``, ``min`` and ``sum``.
 
         Keyword Args:
-            kwargs (dict):
-                The keyword arguments are those of the
+            **kwargs (dict): the keyword arguments are those of the
                 gluon.dal.Set.select method: orderby, groupby, ....
 
         Returns: