Gil Cleber Barboza

Projects/isis-report-lib

Python library · PyPI · MIT

Tabular PDF reports, from Python.

Hierarchical layouts, Jinja2 rendering and Playwright PDF. One function call from data to a print-ready document — sync or async, from a Python dict or a compact .toon file.

  • Python
  • MIT
  • PyPI v0.4.0
  • Jinja2
  • Playwright

Install from PyPI View on GitHub

What it does

From nested records to a polished PDF.

  • Hierarchical layouts

    Nested groups become sections; flat child lists render as tables. The document adapts to the data instead of rigid bands.

  • JSON or .toon

    Pass a dict / ReportPayload or a compact indented .toon document with the same structure.

  • Jinja2 templates

    Templates are bundled in the package. Point template_dir at your own directory to override the layout or reuse its macros.

  • Playwright PDF

    Chromium renders the final document. The sync API opens and closes the browser per call; the async API reuses a shared pool.

  • Sync and async

    generate_pdf, agenerate_pdf and render_html for the intermediate HTML — no browser needed for the latter.

  • Locale-aware masks

    str, int, float, date, percent, currency and bool — via Babel/CLDR, with pt-BR, en-US and more.

Quick start

Python package + Chromium for PDF rendering.

pip install isis-report-lib
playwright install chromium
from isis_report_lib import generate_pdf

payload = {
    "meta": {"title": "Sales Order", "sub_title": "2024", "mode": "exact"},
    "layout": {
        "company": {"label": "Company", "format_mask": "str", "alignment": "left"},
        "orders": {
            "order": {"label": "Code", "format_mask": "int", "alignment": "right"},
            "total": {"label": "Total", "format_mask": "float", "alignment": "right"},
        },
    },
    "data": [
        {"company": "ACME", "orders": [{"order": 750, "total": 4000}]},
    ],
}

pdf = generate_pdf(payload)
open("report.pdf", "wb").write(pdf)
# Async
from isis_report_lib import agenerate_pdf
pdf = await agenerate_pdf(payload)

# Intermediate HTML, without a browser
html = render_html(payload)
# CLI
isis-report generate examples/sales_order.toon -o report.pdf
isis-report render examples/sales_order.toon -o report.html

After upgrading Playwright, reinstall the browser: each Playwright version pins a specific Chromium build.

Payload at a glance

Declarative behavior, not a rigid template.

FieldWhat it controls
meta Title, subtitle, mode, locale, currency, accent color, page size/orientation and printed_at (auto-filled).
layout Hierarchical field definitions — labels, masks, alignment, visibility. Omit to infer from the data.
data Raw records or the template format with nested groups.
aggregate sum, count, avg, min, max — group footers, detail footers and grand summaries.
$print_when Keep only rows matching a field condition.
$order_by Sort rows by one or more fields, with nulls last.
visible / visible_when Hide a column, conditionally.

Templates are code: only load template_dir from sources you trust. Report data is never executed as template code — it is interpolated only.