report-toolkit

Build analytical reports in Python or Markdown templates and export styled HTML with tables, charts, sections, and column layouts.

Install

Install the package:

pip install report-toolkit

From a checkout:

uv sync

For tables, charts, and YAML template metadata, use uv sync --extra all. Individual extras are pandas, altair, matplotlib, plotly, and templates; offline additionally supports embedding Altair's JavaScript.

Quick start

from report_toolkit import Report

report = Report('Sales review', author='Report author')
report.heading(1, 'Summary')
report.markdown('Revenue **increased** this month.')
report.unordered(['Review the results', 'Plan the next month'])
report.write('sales.html', toc=True)

Open sales.html in a browser.

Jupyter notebooks

Install report-toolkit[notebook] (or run uv sync --extra notebook from a checkout), then call report.display() in a notebook cell:

report = Report('Notebook review')
with report.columns(2):
    report.markdown('**First column**')
    report.markdown('**Second column**')
report.display()

Artifacts use native IPython display, including objects without HTML adapters. Columns require a frontend with ipywidgets support. Text and metadata use notebook defaults; captions, artifact sizing, centering, expansion, themes, and navigation are omitted. This displays the report in the current notebook; it does not export an .ipynb file.

See the example notebook for a small report with a Pandas table, Matplotlib and Altair charts, lists, and text in columns.

Documentation

Start with Getting Started, use Common Tasks for recipes, and consult the API Reference for signatures and constraints. See the Changelog for release history and upcoming changes.

Two equivalent examples

Python composition and Markdown templates, using monthly_sales.md, generate the same sales report. They demonstrate shared text, list, table, chart, and layout capabilities.

uv run --extra all python examples/sales_report.py
uv run --extra all python examples/template_report.py

Each prints its report tree and output path. Open examples/sales_report.html and examples/template_report.html in a browser. Altair and Plotly charts require network access for their JavaScript. Raw HTML is covered in the recipes, including the explicit raw_html template tag for trusted HTML.

Themes

Export with style={'mode': 'dark'}, or use style={'mode': 'auto'} to follow the reader's system appearance. Choose slate, azure, parchment, or ember with style={'palette': 'parchment'}. The default preserves the previous light appearance. Define reusable Style, Theme, and Palette objects; see Themes for customization and migration from theme=, and the theme gallery.

Rendering profiles

Use profile='rich' (the default) for interactive reports, profile='portable' for static SVG charts, or profile='content' for a content fragment with minimal layout CSS and interactive charts. Install portable for SVG exporters; Plotly also requires Chrome at export time. Derive immutable profiles with get_profile(...).with_overrides(...), including HTML tag-to-class mappings for host applications. See Rendering profiles.

Development

uv run --extra all pytest
uv run --extra all make test
uv run ruff check .
uv run ruff format --check .
uv run make build

make test and pytest both run the unittest-compatible suite, including the example integration test. Optional integration tests skip when dependencies are absent. Version tags run tests, Ruff lint, and a format check before the release workflow builds and publishes to PyPI.

Browser navigation tests

Browser tests are optional and skip if Playwright or Chromium is unavailable. Install and run them without adding a runtime dependency:

uv run --with playwright python -m playwright install chromium
uv run --with playwright pytest tests/test_navigation_options.py -q

These tests exercise long TOCs, desktop and mobile layouts, print layout, and navigation in full documents and fragments.

Styling resources

Theming code lives in src/report_toolkit/themes/: structural defaults belong in theme.py, color values in palette.py, and configuration normalization in style.py. Edit src/report_toolkit/resources/report.css for static report CSS; HTML-specific scoping and dynamic style generation live in the writer. CSS is packaged with the library and embedded in exported HTML. After changing resources or package-data settings, run make build and verify the built distributions.

Artifact layout is configurable per item:

report.add(table, center=True)
report.add(chart, width='full', expand='always')
report.write('report.html', pretty=True)  # Compact markup is the default.

Tables and charts use native width by default and display their full height. With the default rich profile and JavaScript enabled, artifacts that overflow horizontally offer a bottom-right Expand button opening a centered expanded view with zoom controls and a Close icon. Zoom is available only in the expanded preview. The portable and content profiles omit expansion and zoom controls. See artifact options for details.