Commit fe6278a4 authored by LE GAC Renaud's avatar LE GAC Renaud
Browse files

Polish the documentation API.

parent d934670b
......@@ -2,6 +2,8 @@
Callbacks
---------
A collections of functions to be call before a database operation is completed.
Functions
^^^^^^^^^
......
......@@ -2,6 +2,9 @@
Report objects
--------------
A collection of methods and classes to build report: *list*, *graph* or
*metrics*.
Helper functions
^^^^^^^^^^^^^^^^
......
......@@ -11,11 +11,14 @@ MSG_INHIBIT_DELETE = \
def INHIBIT_CASCADE_DELETE(myset):
"""Inhibit the delete when at least one history row uses
the reference field.
"""Inhibit the delete.
The *history* table is linked to several foreign tables.
This function inhibits the delete of a row, belonging to a foreign table,
when the row is referenced in the *history* table.
Args:
myset (gluon.dal.Set): set object used for delete
myset (gluon.dal.Set): object describing the row to be deleted.
Returns:
bool: ``True`` when the delete is inhibited
......
......@@ -65,8 +65,11 @@ def do_title(config, selector):
def get_value(row, tablename, fieldname, keyname='', **kwargs):
"""Return the value of the database field identified by its
tablename, fieldname and keyname.
"""Helper function returning the value of a database field.
The method is designed to handle standard and JSON-type database field.
The field is identified by its ``tablename``, ``fieldname`` and
``keyname``.
Args:
row (gluon.dal.Row): one row of the tablename table.
......@@ -75,7 +78,6 @@ def get_value(row, tablename, fieldname, keyname='', **kwargs):
keyname (str): key for the JSON type field.
Returns:
* ``row[tablename][fieldname]`` or ``row[fieldname]``
when tablename and fieldname are defined
* ``row[tablename][fieldname][keyname]`` for JSON type field
......@@ -112,15 +114,17 @@ def get_value(row, tablename, fieldname, keyname='', **kwargs):
def split_dbfield(value):
"""The address of a database field is encoded by the user
as ``table.field`` or ``table.field.key``. The latter is used for
JSON type field. It is decode as a 3-elements tuple in
which the last element is equal to key or an empty string.
"""Helper function to decode database field name as 3-elements tuple.
The name of a database field is encoded as ``table.field`` or
``table.field.key``. The latter syntax is used for JSON type field.
The function decodes as a 3-elements tuple (``tablename``,
``fieldname``, ``keyname``).
Args:
value (string):
the address of the database field, either
tablename.fieldname or tablename.fieldname.key
the name of the database field, either
``tablename.fieldname`` or ``tablename.fieldname.key``
Returns:
tuple: ``(tablename, fieldname, keyname)`` where the ``keyname``
......@@ -140,28 +144,12 @@ class ReportException(BaseException):
class BaseReport(object):
"""Base class for list, metric and graph reports.
"""Base class to build list, metric or graph reports.
Args:
config (gluon.dal.Row): the list configuration parameter.
config (gluon.dal.Row): the configuration parameter for the report.
selector (MySelector): the selector handling user criteria.
Attributes:
db (gluon.dal.DAL): the database connection.
df (DataFrame or None):
the data frame containing the data form well-formed
for the report.
config (gluon.dal.Row):
the report configuration extracts from the database.
rows (gluon.dal.Rows or None):
the record selected from the history table.
selector (MySelector):
the selector containing user criteria
"""
def __init__(self, config, selector):
......@@ -255,21 +243,24 @@ class BaseReport(object):
class Graph(BaseReport):
"""Any data encapsulated in list, 1-dim or 2-dim metrics
"""Build a report as a graph.
Any data encapsulated in list, 1-dim or 2-dim metrics
can be displayed as a graph. The rendering is performed by
the matplotlib library. Therefore, many representations of
the data are possible: plot, histogram, bar charts, errorcharts,
scaterplots, etc.
the data are possible: plot, histogram, bar charts, error charts,
scater plots, *etc*.
Args:
config (gluon.dal.Row): the list configuration parameter.
selector (MySelector): selector handling period of time.
config (gluon.dal.Row):
the configuration parameter for the graph.
selector (MySelector):
selector handling period of time.
backend (str):
the name of the matplotlib backend uses to produce figure.
Attributes:
ax (matplotlib.AxesSubplot):
"""
def __init__(self, config, selector, backend="Agg"):
......@@ -401,46 +392,51 @@ class Graph(BaseReport):
return data
def to_pdf(self):
"""
"""Encode the graph using the PDF format
Returns:
str: encode the graph with the PDF format.
str:
"""
return self._savefig('pdf')
def to_png(self):
"""
"""Encode the graph using the PNG format.
Returns:
str: encode the graph with the PNG format.
str:
"""
return self._savefig('png')
def to_svg(self):
"""
"""Encode the graph using the SVG format.
Returns:
str: encode the graph with the SVG format.
str:
"""
return self._savefig('svg')
class List(BaseReport):
"""A list is a table in which each column contains the values of
"""Build a report as a list.
A list is a table in which each column contains the values of
one database field. The rows can be grouped per value of a given column.
Summary information can be computed for each group as well as for
the whole table.
The list is displayed as the ``App.grid.Panel`` widget.
The configuration of the list columns is the configuration of
the ``App.grid.Panel`` widget.
the ``App.grid.Panel`` object.
More technically, this class interfaces the database and the
``App.grid.Panel`` thought the underlying ``Ext.data.Store``.
Its configuration is returned by the method #to_store.
Its configuration is returned by the method *to_store*.
Args:
config (gluon.dal.Row): the list configuration parameter.
config (gluon.dal.Row): the configuration parameter for the list.
selector (MySelector): selector handling period of time.
"""
......@@ -687,7 +683,7 @@ class List(BaseReport):
store.fields.append(cfg)
def to_grid(self):
"""Build the configuration of the ``App.grid.Panel``.
"""Build the configuration for the ``App.grid.Panel``.
Returns:
plugin_dbui.Grid:
......@@ -721,14 +717,14 @@ class List(BaseReport):
return grid
def to_store(self):
"""Build the configuration of the ``Ext.data.Store``.
"""Build the configuration for the ``Ext.data.Store``.
Note:
The name of the ``Ext.data.Field`` is extract from the column
definition of the list where it is equal to ``table.field`` or
``table.field.key``. The dot is remove in the ``Ext.data.Field``
name. Therefore the dataIndex used in the grid column configuration
has to be modified accordingly.
name. Therefore the ``dataIndex`` used in the grid column
configuration has to be modified accordingly.
Returns:
plugin_dbui.Store: the configuration of the ``Ext.data.Store``.
......@@ -756,7 +752,9 @@ class List(BaseReport):
class Metric1D(List):
"""A Metric1D is a table displaying metrics when records are
"""Build a report as a 1-dim metric.
A Metric1D is a table displaying metrics when records are
group by value for a given database field. for example, the ``cell[i]``
of the ``table.field2`` column contains the sum
of the ``table.field2`` when ``table.field1 = group_value[i]``.
......@@ -766,17 +764,17 @@ class Metric1D(List):
to the database fields on which the aggregation functions are applied.
Many aggregation functions are available: ``count``, ``max``, ``mean``,
``median``, ``min``, ``size``, ``std``, ``sum``...
``median``, ``min``, ``size``, ``std``, ``sum``, *etc*.
In fact, all the computation methods of the ``pandas.DataFrame`` class.
A metric is defined by a database field an an aggregation function.
several metric can be computed as the same time applying different
A metric is defined by a database field and an aggregation function.
several metrics can be computed as the same time applying different
aggregation function possibly on different field.
A summary information can also be computed for each column or rows.
Args:
config (gluon.dal.Row): the list configuration parameter.
config (gluon.dal.Row): the configuration parameter for the metric.
selector (MySelector): selector handling period of time.
"""
......@@ -932,7 +930,7 @@ class Metric1D(List):
store.sorters = [index_groupby]
def to_grid(self):
"""Build the configuration of the ``App.grid.Panel``.
"""Build the configuration for the ``App.grid.Panel``.
Returns:
plugin_dbui.Grid:
......@@ -964,7 +962,7 @@ class Metric1D(List):
return grid
def to_store(self):
"""Build the configuration of the ``Ext.data.Store``.
"""Build the configuration for the ``Ext.data.Store``.
Returns:
plugin_dbui.Store: the configuration of the ``Ext.data.Store``.
......@@ -979,18 +977,20 @@ class Metric1D(List):
class Metric2D(BaseReport):
"""A Metric2D is a table displaying a single metric for two database fields
one against the other. For both database field the values a grouped.
"""Build a report as a 2-dim metric.
A Metric2D is a table displaying a single metric for two database fields
one against the other. For both database field the values are grouped.
for example, the ``cell[i,j]`` contains the sum of the ``table.field3``
when ``table.field1 = group_value1[i]`` and
``table.field2 = group_value2[j]``.
Many aggregation function are available: ``count``, ``max``, ``mean``,
``median``, ``min``, ``size``, ``std``, ``sum``,...
In fact, all the computation methods of the``pandas.DataFrame`` class.
``median``, ``min``, ``size``, ``std``, ``sum``, *etc*.
In fact, all the computation methods of the ``pandas.DataFrame`` class.
Args:
config (gluon.dal.Row): the list configuration parameter.
config (gluon.dal.Row): the configuration parameter for the metric.
selector (MySelector): selector handling period of time.
"""
......@@ -1135,7 +1135,7 @@ class Metric2D(BaseReport):
store.sorters = [index_group_y]
def to_grid(self):
"""Build the configuration of the ``App.grid.Panel``.
"""Build the configuration for the ``App.grid.Panel``.
Returns:
plugin_dbui.Grid:
......@@ -1172,7 +1172,7 @@ class Metric2D(BaseReport):
return grid
def to_store(self):
"""Build the configuration of the ``Ext.data.Store``.
"""Build the configuration for the ``Ext.data.Store``.
Returns:
plugin_dbui.Store: the configuration of the ``Ext.data.Store``.
......
......@@ -15,7 +15,7 @@ class SelectorActiveItems(Selector):
"""Selector to get records active during a given period of time.
The period of time are defined by the selector fields
``_period_start`` and ``_period_end`` as well as ``_year}``.
``year_start`` and ``year_end``.
Args:
table (gluon.dal.Table): the virtual table defining the selector.
......@@ -46,9 +46,10 @@ class SelectorActiveItems(Selector):
raise SelectorActiveItemsException("Period is not defined.")
def get_years(self):
"""
"""The list of year between period start and end.
Returns:
list: the list of year between period start and end
list:
"""
if self._cache_period:
......@@ -61,9 +62,10 @@ class SelectorActiveItems(Selector):
return range(start, end + 1)
def query(self, table):
"""Build the database query for the database table
including inner join for foreign keys, selector constraints and
extra queries.
"""Build the database query for the database *table*.
The query includes inner join for foreign keys, selector constraints
as well as extra queries.
Args:
table (gluon.dal.Table):
......@@ -117,16 +119,17 @@ class MySelector(SelectorActiveItems):
- focus on history record
- Select record active during the selected period of time.
- Selection can be performed on category defined as a string.
- For each record computes virtual field age, coverage, duration,
fte and is_over.
- For each record computes virtual field: ``age``, ``coverage``,
``duration``, ``fte`` and ``is_over``.
Args:
table (gluon.dal.Table): the virtual table defining the selector.
exclude_fields (tuple of string):
extend the list selector fields which are
excluded in the query. The field category, period_end, period_start
and year are systematically excluded.
excluded in the query. The field related to people / object
categories, year_end, year_start and year are systematically
excluded.
"""
def __init__(self, table, exclude_fields=()):
......@@ -311,18 +314,11 @@ class MySelector(SelectorActiveItems):
return False
def query(self, table):
"""Supersede the base class method to handle quality constraints.
"""Supersede the base class method to handle categories constraints.
Args:
table (gluon.dal.Table):
Notes:
* Translate the selector category, defined as a string,
into a query.
* append the query on events for table containing the field
id_events.
"""
db = table._db
query = SelectorActiveItems.query(self, table)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment