Reports are used to define a view into your data. At a basic level, reports are used to process a data set, format the data, and return tabular results. But reports can define many options, including:
The next section describes in detail how to write and interact with your own reports. You will also want to check out Data Sources for details on how to pull data; Column formatters for more on formatting report output; and User-input widgets for details on accepting user filtering options.
To write a report, you subclass this base Report class and define your own attributes on it. The standard list of available attributes include:
Various sources used by the report may allow or require other attributes to be specified. This will be specified in the documentation for that source.
Here is a relatively simple example of a report definition:
from blingalytics import base, formats, widgets
from blingalytics.sources import database, derived, key_range
class RevenueReport(base.Report):
display_name = 'Company Revenue'
code_name = 'company_revenue_report'
category = 'business'
cache_time = 60 * 60 * 3 # three hours
database_entity = 'project.models.reporting.RevenueModel'
keys = ('product_id', key_range.SourceKeyRange)
columns = [
('product_id', database.GroupBy('product_id',
format=formats.Integer(label='ID', grouping=False), footer=False)),
('product_name', database.Lookup('project.models.products.Product',
'name', 'product_id', format=formats.String)),
('revenue', database.Sum('purchase_revenue', format=formats.Bling)),
('_cost_of_revenue', database.First('product_cost')),
('gross_margin', derived.Value(
lambda row: (row['revenue'] - row['_cost_of_revenue']) * \
Decimal('100.00') / row['revenue'], format=formats.Bling)),
]
filters = [
('delivered', database.QueryFilter(
lambda entity: entity.is_delivered == True)),
('online_only', database.QueryFilter(
lambda entity, user_input: entity.is_online_purchase == user_input,
widget=widgets.Checkbox(label='Online Purchase'))),
]
default_sort = ('gross_margin', 'desc')
Once you have defined your report subclass, you instantiate it by passing in a cache instance. This tells the report how and where to cache its processed data. For more, see Cache stores. Once you have a report instance, you use the following methods to run it, manipulate it, and retrieve its data.
Returns a list of this report’s widgets, rendered to HTML.
Returns a list of this report’s widget instances. Calling the widgets’ render() method is left to you.
Set user inputs on the report, returning a list of any validation errors that occurred.
The user input should be passed in as keyword arguments the same as they are returned in a GET or POST from the widgets’ HTML. The widgets will be cleaned, converting to the appropriate Python objects.
If there were errors, they are returned as a list of strings. If not, returns None and stores the user inputs on the report. Note that this effectively changes the unique_id property of the report.
If your report has user input widgets, this should be called before run_report; if the report has no widgets, you don’t need to call this at all.
Processes the report data and stores it in cache.
Depending on the size of the data and the processing going on, this call can be time-consuming. If you are deploying this as part of a web application, it’s recommended that you perform this step outside of the request-response cycle.
If run_report() is currently running, this returns True; otherwise, False.
If run_report() has completed and there is a current cached copy of this report, returns True; otherwise, False.
By default, this removes or invalidates (depending on the cache store being used) this cached report. If there are other cached versions of this report (with different user inputs) they are left unchanged.
If you pass in full=True, this will instead perform a full report-wide cache invalidation. This means any version of this report in cache, regardless of user inputs, will be wiped.
Returns the header data for this report, which describes the columns and how to display them.
The header info is returned as a list of dicts, one for each column, in order. Certain column types may add other relevant info, but by default, the header dicts will contain the following:
The first column returned by a Blingalytics report is always a hidden column specifying the row’s cache ID. The first column header is for this internal ID.
Returns the requested rows for the report from cache. There are a number of arguments you can provide to limit, order and format the rows, all of which are optional:
The rows are returned as a list of lists of values. The first column returned by Blingalytics for any report is always a hidden column specifying the row’s internal cache ID.
Returns the computed footer row for the report. There is one argument to control the formatting of the output:
The footer row is returned as a list, including the data for any hidden columns. The first column returned by Blingalytics for any report is reserved for the row’s internal cache ID, so the first item returned for the footer will always be None.
Returns the timestamp when the report instance was originally computed and cached, as a datetime object.
Returns the total number of rows in this report instance.
The blingalytics module provides a few utility methods that are useful for retrieving your reports.
Note
The report registration method is done using a metaclass set on the base.Report class. This means that the modules where you’ve defined your report classes have to be imported before the methods below will know they exist. You can import them when your code initializes, or right before you call the utility functions, or whatever — just be sure to do it.
Returns the report class with the given code_name, or None if not found.
Returns all known reports, organized by category. The result is returned as a dict of category strings to lists of report classes.