Time Series Reports

Developer guide for the Enezaframework reporting engine. Part of the Add Report series.

Overview
How Buckets Are Built
Attributes
Supported Patterns
Example
Validation
Related Guides

Overview

TimeSeriesReportView partitions a date range into chronological buckets and computes per-bucket aggregates. It is the right choice for revenue-by-month, activity-by-week, and similar trend reports.

How Buckets Are Built

flowchart LR
    RANGE["Date range<br/>start_date → end_date"] --> SPLIT["Split by pattern<br/>daily / weekly / monthly / ..."]
    SPLIT --> B1["Bucket 1"]
    SPLIT --> B2["Bucket 2"]
    SPLIT --> B3["Bucket N"]
    B1 --> AGG["Per-bucket aggregates<br/>time_series_columns"]
    B2 --> AGG
    B3 --> AGG
    AGG --> TABLE["Time series table"]

Attributes

Attribute	Required	Description
`report_model`	Yes	Django model for the data source.
`time_series_pattern`	Yes	Bucket size: `daily`, `weekly`, `bi-weekly`, `monthly`, `quarterly`, `semiannually`, `annually`, or `custom`.
`time_series_columns`	Yes	Computation fields computed per bucket.
`date_field`	Yes	Model date field used to partition rows.
`time_series_custom_dates`	No	List of custom date tuples when `time_series_pattern="custom"`.
`time_series_selector`	No	Show a UI selector to change the pattern at runtime.
`time_series_selector_choices`	No	Choices for the runtime selector.
`columns`	No	Leading (non-bucketed) columns.

Supported Patterns

Pattern	Bucket length
`daily`	One day
`weekly`	One week
`bi-weekly`	Two weeks
`monthly`	One calendar month
`quarterly`	Three months
`semiannually`	Six months
`annually`	One year
`custom`	The date tuples supplied in `time_series_custom_dates`

The supported set is declared on TimeSeriesReportGenerator.get_time_series_dates (enezareporting/generators/time_series.py:26-37).

Example

python

from enezareporting.report_base import TimeSeriesReportView
from enezareporting.parameters import ParameterSet, DateRangeParam
from myapp.models import SalesLine


class MonthlyRevenue(TimeSeriesReportView):
    report_title = "Monthly Revenue"
    report_model = SalesLine
    date_field = "date_placed"
    time_series_pattern = "monthly"
    time_series_columns = ["__total__"]
    columns = []
    parameter_spec = ParameterSet(
        DateRangeParam(name="date_range", start_field="date_placed"),
    )

Validation

TimeSeriesReportView raises ImproperlyConfigured at class creation when time_series_pattern, time_series_columns, or date_field is missing.