dbReport’s Documentation ¶

The dbReport package will generate HTML reports from a sqlite database. It uses views defined in the database to collect the data for the reports, and a JSON file to configure how the reports are generated and related to each other. The project can be found on github

Layout Configuration ¶

Contents

Layout Configuration
- categories
- ignore_views
- titles
- paths
- captions
- descriptions

The layout file defines how the reports are generated, the database that should be queried, aliases, and other options for rendering. It can also be used to pass parameters to the parse function to process data before report is rendered.

This is a JSON file that defines the following keys. Each JSON key is described below.

categories ¶

The categories is a dictionary defining the menu and the items in the menus on each report. This is useful for categorizing the reports together.

Each key is the menu name, how it should appear in the report. The values for the key is a list of view names, (note it should be the view name, not the alias or title) to be under that heading. The name that will appear in the rendered report is the title for that report, if one is given.

A view name can be under multiple menus.

If a view name does not appear under any menus, it will be automatically included in a Misc menu item. Unless it is listed in the ignore_views key.

ignore_views ¶

List of view names to be ignored. These will not be included in any of the menus, including the Misc menu. These must correspond to the keys in the data returned by the parse function.

titles ¶

A dictionary of aliases for the reports. The keys are the view names from the database, (keys in dictionary returned by parse function) and the values are the alias that should be used. This alias will be used as the report title, and the menu item text.

paths ¶

Paths given to the report. They are given as key-value pairs, where the required keys are listed below.

database: path to the database to be queried

report_dir: path to directory where reports are saved. This must be a directory. Defaults to reports

template: path to html template. Defaults to templates/base.html.j2

css_styles: directory to css files. All css files in directory are included. Defaults to templates/css

sql: defaults to templates/sql,

javascript: list to paths javascript plugins to be included in reports

"templates/javascript/jquery-timeago/jquery.timeago.js"

"templates/javascript/multifilter/multifilter.js"

"templates/javascript/tablesorter/jquery.tablesorter.js"

The paths listed may be absolute or relative to the calling function.

captions ¶

Dictionary of key value pairs that define the table caption for each report.

The keys match the report name (view name, not alias) and the value is the caption as it should appear in the report.

Defaults to None (no caption)

descriptions ¶

Dictionary of key value pairs that define a description (introductory text) for each report.

The keys match the report name (view name, not alias) and the value is the description text as it should appear in the report.

Defaults to None (no description).

dbReport Package¶

This module will will generate HTML reports for the views in a sqlite database.

class dbreport.dbreport.Report(layout_path=None, **kwargs)[source]¶

Bases: object

The Report will handle querying the database and generating the reports

Parameters

layout_path (str | None) – path to the layout file, or None when using kwargs
kwargs – Any keyword argument defined in the layout configuration

Raises

ValueError – When both layout_path and kwargs defined

property categories¶

Categories for reports

The categories is a dictionary defining the menu and the items in the menus on each report. This is useful for categorizing the reports together.

Each key is the menu name, how it should appear in the report. The values for the key is a list of view names, (note it should be the view name, not the alias or title) to be under that heading. The name that will appear in the rendered report is the title for that report, if one is given.

A view name can be under multiple menus.

If a view name does not appear under any menus, it will be automatically included in a Misc menu item. Unless it is listed in ignore.

Raises

ValueError – when an item is not in views
TypeError – when setting value that is not a dict
TypeError – when key is not of type str
Typeerror – when value is not of type list

property ignore¶

List of views in database that should not be included in reports

When setting the ignore property, it must be an iterable (list or tuple) of view names.

When a view is listed here, it will not be included in any menu, including the Misc category.

Defaults to an empty list

Raises: ValueError – When any item listed is not in views

parse(data)[source]¶

The parse function may be called to intercept data before rendering

Parameters

data (dict) – data as queried from database. The keys are view names from database, and values are a list of queried results.

Returns

data as it should be rendered by report.: The keys are view names as used in layout file, and values are a list of results to be included in reports.

Return type

dict

Raises

NotImplementedError – When the default parse function is used. This must be overloaded by a custom parse function before use.

This function is useful to filter, format, add hyperlinks, or otherwise manipulate raw data queried from database before it gets rendered in report.

To be sure the parse function is called, create a class that inherits from the base Report class and overload the parse function in the custom class. Then render the reports with render(parse=True). If you try to parse data without overloading the default parse function, it will raise a NotImplementedError.

Notes

The data format for both data parameter and the returned value are defined below.

keys: view names where the data was queried from; and the
filename of the report if using the write method.
values: list of tuples, each tuple is a row of data
- (list): list of rows, with each row defined as a tuple
- (tuple): each element in values is a tuple.
  The elements of the tuple are the values from the database, and/or the values that will be shown in the report.

Note

The elements of each row must be a single item (str, bool, int, etc) or a tuple in the form (value, href), where href is where the generated hyperlink for that value is directed to.

property paths¶

render(views=None, parse=False)[source]¶

Renders html for each view in views

Parameters

views (list | None) – list of view names to render, defaults to None, all views
parse (bool) – whether the parse function is called on query results. Defaults to False (don’t parse)

Returns

Rendered html of reports

Return type

dict

Changed in version 0.3.3a1: returns results; parse default was True

property views¶: list of views in the database

write(report_dir=None, **kwargs)[source]¶

Write rendered reports to files

Parameters

report_dir (str | None) –

path where reports are written to defaults to None,
which will use the path in the layout.
kwargs (dict) – all other keyword arguments are passed directly to the render function.

Returns

No return value

Return type

None

Raises

NotADirectoryError – When report path does not exist

New in version 0.3.3a1.

License¶

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contents

dbReport’s Documentation
- Installation
- Example Setup

Installation ¶

This project is not hosted on PyPi, so to install it will require building the project from source.

Since this module has several sub-modules (js plugins), to clone, perform the following steps to clone it with all the sub-modules populated.

>> git clone https://github.com/josephjcontreras/dbreport.git
>> cd dbReport
>> git submodule init
>> git submodule update

For further details about submodules, refer to the git documentation.

Once cloned, install the requirements by running pip install -r requirements.txt or pip install -r requirements-dev.txt, depending on how you will use the project.

Example Setup ¶

Once dbReport has been installed, it can be used to start generating reports.

{
"paths": {
    "database": ".\\test-database.db",
    "report_dir": ".\\reports"
    }
}

For simple cases that do not require processing of data queried from the database, the reports can be rendered as shown.

def main():
    report = Report('layout.json')
    report.render(parse=False)

In other cases where the parse function is required, create a python class that inherits from the dbreport.Report class. This will allow the parse method to be overloaded and changed.

from dbreport import Report

class myCustomReport(Report):
    def __init__(self, layout_path):
        super().__init__(layout_path=layout_path)

    def parse(self, data):
        """
        This custom parse function will be called on the data

        See documentation for more details.
        """

        # for this case, we're just going to print the data to
        # show that it is working
        print(data)

        # be sure to return the data
        return data


def main():
    # use this function to instantiate the class and generate reports
    report = myCustomReport('layout.json')
    report.render()

After running these examples, there will be an html report for each view defined in test-database.db.

dbReport’s Documentation ¶

Layout Configuration ¶

categories ¶

ignore_views ¶

titles ¶

paths ¶

captions ¶

descriptions ¶

dbReport Package¶

License¶

Installation ¶

Example Setup ¶

dbReport

Navigation

Related Topics