Skip to content

GitLab

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

Sphinxify report_objects.py.

parent 8306e291
Hide whitespace changes
Inline Side-by-side
Showing with 161 additions and 133 deletions
modules/report_objects.py
View file @ d288cf16
......@@ -24,6 +24,13 @@ REG_SINGLE_DBFIELD = re.compile("^ *\w+\.\w+(\.\w+)? *$", re.UNICODE)
def do_title(config, selector):
"""Build the report title.
Args:
config (gluon.dal.Row): the list configuration parameter.
selector (MySelector): selector handling period of time.
Returns:
str:
"""
db = current.globalenv['db']
T = current.T
......@@ -58,27 +65,22 @@ def do_title(config, selector):
def get_value(row, tablename, fieldname, keyname='', **kwargs):
"""Return the row value of the database field
identify by the tablename, fieldname and keyname
@type row: gluon.dal.Row
@param row:
@type tablename: str
@param tablename:
"""Return the value of the database field identified by its
tablename, fieldname and keyname.
@type fieldname: str
@param fieldname:
Args:
row (gluon.dal.Row): one row of the tablename table.
tablename (str): name of a database table.
fieldname (str): name of database field.
keyname (str): key for the JSON type field.
@type keyname: str
@param keyname:
Returns:
@return:
- C{row[tablename][fieldname]} or C{row[fieldname]}
* ``row[tablename][fieldname]`` or ``row[fieldname]``
when tablename and fieldname are defined
- C{row[tablename][fieldname][keyname]} for JSON type field
- C{kwargs[tablename]} when fieldname and keyname are not defined
- None when the field address does not exist in the row
* ``row[tablename][fieldname][keyname]`` for JSON type field
* ``kwargs[tablename]`` when fieldname and keyname are not defined
* ``None`` when the field address does not exist in the row
"""
undefined = None
......@@ -111,17 +113,18 @@ def get_value(row, tablename, fieldname, keyname='', **kwargs):
def split_dbfield(value):
"""The address of a database field is encoded by the user
as C{table.field} or C{table.field.key}. The latter is used for
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.
@type value: string
@param value: the address of the database field, either
tablename.fieldname or tablename.fieldname.key
Args:
value (string):
the address of the database field, either
tablename.fieldname or tablename.fieldname.key
@rtype: tuple
@return: the tuple C{(tablename, fieldname, keyname)}.
The C{keyname} is either a string or an empty string.
Returns:
tuple: ``(tablename, fieldname, keyname)`` where the ``keyname``
is either a string or an empty string.
"""
li = value.split('.')
......@@ -139,33 +142,29 @@ class ReportException(BaseException):
class BaseReport(object):
"""Base class for list, metric and graph reports.
@type db: gluon.dal.DAL
@ivar db: the database connection
Args:
config (gluon.dal.Row): the list configuration parameter.
selector (MySelector): the selector handling user criteria.
@type df: DataFrame or None
@ivar df: The data frame containing the data form well-formed
for the report.
Attributes:
db (gluon.dal.DAL): the database connection.
@type config: gluon.dal.Row
@ivar config: the report configuration extracts from the
database.
df (DataFrame or None):
the data frame containing the data form well-formed
for the report.
@type rows: gluon.dal.Rows or None
@ivar rows: the record selected from the history table.
config (gluon.dal.Row):
the report configuration extracts from the database.
@type selector: MySelector
@ivar selector: the selector containing user criteria
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):
"""
@type config: gluon.dal.Row
@param config: the list configuration parameter
@type selector: MySelector
@param selector: the selector handling user criteria
"""
db = current.globalenv['db']
self.db = db
......@@ -183,11 +182,13 @@ class BaseReport(object):
"""Build a temporarily list with the raw data for each series.
This method handle the "year" database field.
@type maps: list
@param maps: the database field map (tablename, fieldname, keyname).
One per series.
Args:
maps (list):
the database field map (tablename, fieldname, keyname).
One per series.
@rtype: list
Returns:
list:
"""
data = []
......@@ -231,12 +232,13 @@ class BaseReport(object):
def _is_year(self, maps):
"""
@type maps: list
@param maps: the database field map (tablename, fieldname, keyname).
One per series.
Args:
maps (list):
the database field map (tablename, fieldname, keyname).
One per series.
@rtype: boolean
@return: C{True} is the pseudo field C{year} is in maps
Returns:
bool: ``True`` is the pseudo field ``year`` is in maps
"""
li = [True for el in maps if el[0] == 'year']
......@@ -245,7 +247,8 @@ class BaseReport(object):
def to_df(self):
"""Return the pandas DataFrame.
@rtype: pandas.DataFrame
Returns:
pandas.DataFrame:
"""
return self.df
......@@ -258,8 +261,14 @@ class Graph(BaseReport):
the data are possible: plot, histogram, bar charts, errorcharts,
scaterplots, etc.
@type ax: matplotlib.AxesSubplot
@ivar ax:
Args:
config (gluon.dal.Row): the list configuration parameter.
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"):
......@@ -313,7 +322,7 @@ class Graph(BaseReport):
self._do_tick()
def _do_graph(self):
"""Build the graph from the C{DataFrame} structure.
"""Build the graph from the ``DataFrame`` structure.
"""
config = self.config
......@@ -375,8 +384,8 @@ class Graph(BaseReport):
def _savefig(self, fmt):
"""Save the figure as a string.
@type fmt: str
@param fmt: possible values are pdf, png and svg.
Args:
fmt (str): possible values are pdf, png and svg.
"""
fig = self.ax.get_figure()
......@@ -393,24 +402,24 @@ class Graph(BaseReport):
def to_pdf(self):
"""
@rtype: string
@return: encode the graph with the PDF format.
Returns:
str: encode the graph with the PDF format.
"""
return self._savefig('pdf')
def to_png(self):
"""
@rtype: string
@return: encode the graph with the PNG format.
Returns:
str: encode the graph with the PNG format.
"""
return self._savefig('png')
def to_svg(self):
"""
@rtype: string
@return: encode the graph with the SVG format.
Returns:
str: encode the graph with the SVG format.
"""
return self._savefig('svg')
......@@ -422,13 +431,17 @@ class List(BaseReport):
Summary information can be computed for each group as well as for
the whole table.
The list is displayed as the C{App.grid.Panel} widget.
The list is displayed as the ``App.grid.Panel`` widget.
The configuration of the list columns is the configuration of
the C{App.grid.Panel} widget.
the ``App.grid.Panel`` widget.
More technically, this class interfaces the database and the
C{App.grid.Panel} thought the underlying C{Ext.data.Store}.
Its configuration is returned by the method L{to_store}.
``App.grid.Panel`` thought the underlying ``Ext.data.Store``.
Its configuration is returned by the method #to_store.
Args:
config (gluon.dal.Row): the list configuration parameter.
selector (MySelector): selector handling period of time.
"""
def __init__(self, config, selector):
......@@ -462,17 +475,18 @@ class List(BaseReport):
This method avoid this problem. It also convert properly
datetime column allowing computation with them.
@type column: str
@param column: the index of the column in the DataFrame
Args:
column (str):
the index of the column in the DataFrame
@type dbfield: tuple
@param dbfield: address of the database field encoded as
(tablename, fieldname, keyname).
dbfield (tuple):
address of the database field encoded as
(tablename, fieldname, keyname).
@type xtype: str
@param xtype: the xtype of the grid column.
Possible values are booleancolumn, datecolumn, gridcolumn
and numbercolumn.
xtype (str):
the xtype of the grid column.
Possible values are ``booleancolumn``, ``datecolumn``,
``gridcolumn`` and ``numbercolumn``.
"""
df = self.df
......@@ -522,8 +536,8 @@ class List(BaseReport):
- Add the database field map
- Add the dataIndex if not defined
@type column: gluon.storage.Storage
@param column:
Args:
column (gluon.storage.Storage):
"""
T = current.T
......@@ -544,7 +558,7 @@ class List(BaseReport):
def _do_metric(self):
"""Interface the database with the DataFrame structure.
This method handle the "year" database field.
This method handle the ``year`` database field.
"""
......@@ -586,10 +600,10 @@ class List(BaseReport):
df = df[index]
def _set_store_data(self):
""" Generate the C{Ext.data.Store.data} property.
"""Generate the ``Ext.data.Store.data`` property.
It is a list of dictionaries. Each of them contains the data
for one row. One key, value pair for each C{Ext.data.Field} where
the key is the name of the C{Ext.data.Field}.
for one row. One key, value pair for each ``Ext.data.Field`` where
the key is the name of the ``Ext.data.Field``.
"""
# extract the list of records as a JSON-string
......@@ -600,13 +614,14 @@ class List(BaseReport):
self._store.data = json.loads(data)
def _set_store_fields(self):
""" Generate the C{Ext.data.Store.fields} property.
It is a list of C{Ext.data.Field} configuration.
"""Generate the ``Ext.data.Store.fields`` property.
It is a list of ``Ext.data.Field`` configuration.
@note: The name of the C{Ext.data.Field} is derived from the
address of the database field. The former can not contains dot.
Therefore, it is obtained by removing dot in the database
field address.
Note:
The name of the ``Ext.data.Field`` is derived from the
address of the database field. The former can not contains dot.
Therefore, it is obtained by removing dot in the database
field address.
"""
db = self.db
......@@ -672,11 +687,12 @@ class List(BaseReport):
store.fields.append(cfg)
def to_grid(self):
"""Build the configuration of the C{App.grid.Panel}.
"""Build the configuration of the ``App.grid.Panel``.
@rtype: plugin_dbui.Grid
@return: the configuration of the C{App.grid.Panel}.
The properties columns and features are JSON encoded.
Returns:
plugin_dbui.Grid:
the configuration of the ``App.grid.Panel``.
The properties columns and features are JSON encoded.
"""
config = self.config
......@@ -705,16 +721,17 @@ class List(BaseReport):
return grid
def to_store(self):
"""Build the configuration of the C{Ext.data.Store}.
"""Build the configuration of 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/
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.
@rtype: plugin_dbui.Store
@return: the configuration of the C{Ext.data.Store}.
Returns:
plugin_dbui.Store: the configuration of the ``Ext.data.Store``.
"""
config = self.config
......@@ -740,17 +757,17 @@ class List(BaseReport):
class Metric1D(List):
"""A Metric1D is a table displaying metrics when records are
group by value for a given database field. for example, the C{cell[i]}
of the C{table.field2} column contains the sum
of the C{table.field2} when C{table.field1 = group_value[i]}.
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]``.
Each column is associated to a database field.
The first one shows the value of the group while the others correspond
to the database fields on which the aggregation functions are applied.
Many aggregation functions are available:
C{count}, C{max}, C{mean}, C{median}, C{min}, C{size}, C{std}, C{sum}...
In fact, all the computation methods of the C{pandas.DataFrame} class.
Many aggregation functions are available: ``count``, ``max``, ``mean``,
``median``, ``min``, ``size``, ``std``, ``sum``...
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
......@@ -758,6 +775,10 @@ class Metric1D(List):
A summary information can also be computed for each column or rows.
Args:
config (gluon.dal.Row): the list configuration parameter.
selector (MySelector): selector handling period of time.
"""
def __init__(self, config, selector):
......@@ -858,16 +879,17 @@ class Metric1D(List):
def _is_year(self, maps):
"""Supersede the method of the base class.
@return: true if the group_field is year.
Returns:
bool: true if the group_field is year.
"""
return self.config.group_field == 'year'
def _set_store_data(self):
"""Generate the C{Ext.data.Store.data} property.
"""Generate the ``Ext.data.Store.data`` property.
It is a list of dictionaries. Each of them contains the data
for one row. One key, value pair for each C{Ext.data.Field}.
The key is equal to the C{Ext.data.Field} name.
for one row. One key, value pair for each ``Ext.data.Field``.
The key is equal to the ``Ext.data.Field`` name.
"""
df = self.df
......@@ -910,11 +932,12 @@ class Metric1D(List):
store.sorters = [index_groupby]
def to_grid(self):
"""Build the configuration of the C{App.grid.Panel}.
"""Build the configuration of the ``App.grid.Panel``.
@rtype: plugin_dbui.Grid
@return: the configuration of the C{App.grid.Panel}.
The columns and features property are JSON encoded.
Returns:
plugin_dbui.Grid:
the configuration of the ``App.grid.Panel``.
The columns and features property are JSON encoded.
"""
columns = self._columns
......@@ -941,10 +964,10 @@ class Metric1D(List):
return grid
def to_store(self):
"""Build the configuration of the C{Ext.data.Store}.
"""Build the configuration of the ``Ext.data.Store``.
@rtype: plugin_dbui.Store
@return: the configuration of the C{Ext.data.Store}.
Returns:
plugin_dbui.Store: the configuration of the ``Ext.data.Store``.
"""
self._store = Store(data=[], fields=[])
......@@ -958,13 +981,17 @@ 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.
for example, the C{cell[i,j]} contains the sum of the C{table.field3}
when C{table.field1 = group_value1[i]} and
C{table.field2 = group_value2[j]}.
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.
Many aggregation function are available:
C{count}, C{max}, C{mean}, C{median}, C{min}, C{size}, C{std}, C{sum}...
In fact, all the computation methods of the C{pandas.DataFrame} class.
Args:
config (gluon.dal.Row): the list configuration parameter.
selector (MySelector): selector handling period of time.
"""
def __init__(self, config, selector):
......@@ -1068,7 +1095,7 @@ class Metric2D(BaseReport):
self.df = df
def _set_store_data(self):
""" Generate the C{Ext.data.Store.data} property.
"""Generate the ``Ext.data.Store.data`` property.
"""
df = self.df
......@@ -1089,7 +1116,7 @@ class Metric2D(BaseReport):
self._store.data.append(di)
def _set_store_fields(self):
""" Generate the C{Ext.data.Store.fields} property.
"""Generate the ``Ext.data.Store.fields`` property.
"""
store = self._store
......@@ -1108,11 +1135,12 @@ class Metric2D(BaseReport):
store.sorters = [index_group_y]
def to_grid(self):
"""Build the configuration of the C{App.grid.Panel}.
"""Build the configuration of the ``App.grid.Panel``.
@rtype: plugin_dbui.Grid
@return: the configuration of the C{App.grid.Panel}.
The columns and features properties are JSON encoded.
Returns:
plugin_dbui.Grid:
the configuration of the ``App.grid.Panel``.
The columns and features properties are JSON encoded.
"""
config = self.config
......@@ -1144,10 +1172,10 @@ class Metric2D(BaseReport):
return grid
def to_store(self):
"""Build the configuration of the C{Ext.data.Store}.
"""Build the configuration of the ``Ext.data.Store``.
@rtype: plugin_dbui.Store
@return: the configuration of the C{Ext.data.Store}.
Returns:
plugin_dbui.Store: the configuration of the ``Ext.data.Store``.
"""
# get the list of columns
......
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