Prepared report templates

[Flix6x]

Description

Defining a report means writing reporter configuration, and writing it from nothing is the step that
stops people defining reports at all. FlexMeasures now ships prepared report templates: a reporter
class, a complete configuration and a parameters skeleton, ready to fill in and run.

Two templates, packaged under flexmeasures/data/templates/reports/ and shipped in the wheel.
energy-costs uses the ProfitOrLossReporter to report energy costs over the reporting window, from
a power or energy sensor and a consumption price sensor, as positive values. self-consumption uses
the PandasReporter to report the share of produced energy consumed on-site, from a production and a
consumption sensor: the elementwise minimum of the two, averaged per reporting period, over average
production.

Each template is complete except for the sensors. It carries a name, a description, the reporter,
a working configuration, and a parameters skeleton whose sensors are FILL_IN placeholders. It also
carries a recommended rolling window — start-offset: -1D,DB, end-offset: DB — which is what makes
a template useful to a recurring report rather than only a one-off.

Discovering them. flexmeasures show report-templates lists the templates with their reporter and
description; --name prints one in full, as commented YAML, ready to redirect to a file and edit.

Using them. --template on flexmeasures add report and on
flexmeasures add automation --type reporting loads the template's reporter, configuration and
parameters as defaults:

flexmeasures show report-templates --name self-consumption > my-report.yml
# fill in the FILL_IN sensor ids, then:
flexmeasures add automation --asset 3 --name "Daily self-consumption" \
  --cron "0 1 * * *" --type reporting --template self-consumption --parameters my-report.yml

What the user writes always wins, at a deliberate granularity. An explicit --reporter is kept
over the template's. Top-level keys of a --config or --parameters file override the template's.
Timing fields — start, end and the offsets, whether in the parameters file or given as CLI
options — replace the template's recommended window as a group, so a half-overridden window can
never be assembled out of two different intentions.

Placeholders left unfilled abort with a validation error naming the exact fields still holding
FILL_IN, rather than failing later inside the reporter with something less legible. Combining
--template with --source is refused, since the data source already determines the reporter and
its configuration, and --template on a non-report automation is refused too.

• Added changelog item in documentation/changelog.rst

How to test

See the manual test walkthrough in the PR comments.

pytest flexmeasures/cli/tests/test_report_templates.py

Eight tests. Both templates' configurations, and their filled-in parameter skeletons, are validated
against their reporter's own schemas, so a template that drifts from the reporter it names fails here
rather than in a user's terminal. show report-templates is checked to list both templates and to
print valid YAML for each. The end-to-end test fills in self-consumption's sensors, creates the
automation, runs it, and checks the stored daily self-consumption shares. The error paths are covered
too: unfilled placeholders, an unknown template, --template on a non-report automation, --template
combined with --source, and an override file that is not a mapping. One test pins what
self-consumption means with no production at all, which is undefined rather than zero.

Further improvements

• Two templates is a starting set rather than a catalogue. The mechanism is the point here; further
  templates are cheap to add once its shape is agreed.
• Templates are packaged with FlexMeasures. Letting a plugin contribute its own would follow the same
  discovery path, and is not attempted here.
• The templates were verified to be present in the built wheel — hatchling ships everything under the
  flexmeasures package — so no MANIFEST or package-data change was needed.

Related items

Part of the automations story #2334, and of #2288. Stacked on #2297, which it needs for
--type reporting.

---

Sign-off

• I agree to contribute to the project under Apache 2 License.
• To the best of my knowledge, the proposed patch is not based on code under GPL or another incompatible license.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #34460525 | 📁 Comparing 2141df2 against latest (4a5892f)

  🔍 Preview build  

155 files changed · + 28 added · ± 127 modified

+ Added

• _autodoc/COUPLING.html
• _autodoc/COUPLING_COEFFICIENT.html
• _autodoc/GROUP.html
• _autodoc/INFLEXIBLE_CONSUMPTION.html
• _autodoc/INFLEXIBLE_PRODUCTION.html
• _autodoc/OPERATION_MODES.html
• _autosummary/flexmeasures.api.common.rate_limiting.html
• _autosummary/flexmeasures.api.v3_0.utils.html
• _autosummary/flexmeasures.data.models.automations.html
• _autosummary/flexmeasures.data.models.planning.devices.html
• and 18 more...

± Modified

• changelog.html
• configuration.html
• genindex.html
• getting-started.html
• http-routingtable.html
• index.html
• py-modindex.html
• _autodoc/COMMITMENTS.html
• _autodoc/CONSUMPTION_CAPACITY.html
• _autodoc/INFLEXIBLE_DEVICE_SENSORS.html
• and 117 more...