Skip to main content

CardReport

Latest release PyPI version

What’s new

Build static reports in Python from cards, KPIs, charts and tables. Compose a report, then get standalone HTML or PDF bytes for your application. PDF text is selectable and charts are vector graphics.

Chromium is the default renderer. The experimental SVG/WeasyPrint renderer works without JavaScript or a browser, with a smaller supported feature set. Both can render grouped/stacked bars, multiple line series and funnels, including the series example. Both also render the original reference example.

For agents building reports

Start with the CardReport skill for choosing an API and layout, rendering, and checking the finished report.

Reports in practice

These are images of PDFs produced by the library, not design mockups.

Operations dashboard — large KPIs, compact line charts and a color-coded ranking. Snapshot values come from an operations dashboard screenshot; trends are explicitly synthetic demonstration data. Python, template and datasets.

The same template and datasets, rendered by both engines. Open either image for a full-size view.

Chromium SVG/WeasyPrint
Operations dashboard rendered by Chromium Operations dashboard rendered by SVG/WeasyPrint

Spanish campaign report — the reference report with localized dates/numbers, tables and charts. Example and provenance.

Spanish campaign report rendered by CardReport

Table across pages — a 120-row demonstration report using mode="flow". Chromium moves complete rows to the next page and repeats the column headings and card title. The first two pages show the continuation from ROW-027 to ROW-028. Python example · Embedding and pagination.

Page 1 Page 2 — continued
Long table, page 1 ending at ROW-027 Long table, page 2 starting at ROW-028 with repeated headings

Install in your project

Python 3.12+ is required. Install from PyPI with uv, then install the PDF browser runtime:

uv add "cardreport[pdf]"
uv run python -m playwright install chromium

Keep your application’s uv.lock to pin the installed version. For HTML-only use, omit [pdf] and the browser-install command. See installation and quickstart for local checkouts, wheels and how to embed exports.

For browser-free PDF export, follow the WeasyPrint setup, including native libraries and the library search path on macOS.

Use from Python

1. Python components

from cardreport import BarChart, Card, KPI, Report

report = Report("Call results")
report.add(Card(KPI("Total calls", 34)))
report.row(
    Card(BarChart(labels=["Answered", "No answer"], values=[24, 10])),
    height_mm=70,
)

html: str = report.to_html()
pdf: bytes = report.to_pdf()

2. JSON template and named datasets

The same report, with presentation and data kept separately. Both JSON documents are inline in this single Python file; your application can also load them from files or a database.

from cardreport import ReportTemplate, datasets_from_json

TEMPLATE_JSON = """
{
  "format": "cardreport.template/1",
  "datasets": {
    "summary": {
      "cardinality": "one",
      "fields": {"total": {"type": "integer"}}
    },
    "calls": {
      "cardinality": "many",
      "fields": {
        "result": {"type": "text"},
        "count": {"type": "integer"}
      }
    }
  },
  "report": {
    "title": "Call results",
    "blocks": [
      {"type": "card", "content": {
        "type": "kpi", "label": "Total calls",
        "value": {"bind": {"dataset": "summary", "field": "total"}}
      }},
      {"type": "row", "height_mm": 70, "children": [
        {"type": "card", "content": {
          "type": "bar", "dataset": "calls",
          "category": "result", "value": "count"
        }}
      ]}
    ]
  }
}
"""

DATA_JSON = """
{
  "format": "cardreport.data/1",
  "datasets": {
    "summary": {"columns": ["total"], "rows": [{"total": 34}]},
    "calls": {
      "columns": ["result", "count"],
      "rows": [
        {"result": "Answered", "count": 24},
        {"result": "No answer", "count": 10}
      ]
    }
  }
}
"""

template = ReportTemplate.from_json(TEMPLATE_JSON)
datasets = datasets_from_json(DATA_JSON)
report = template.bind(datasets)

html: str = report.to_html()
pdf: bytes = report.to_pdf()

The template declares the expected datasets and their fields; the data document provides the values. bind() creates an ordinary Report, with the same export API as the component-based example. See templates and datasets for other data sources and binding options.

Return pdf from your application, put it in storage, or use report.write_pdf("report.pdf") to save a file. Existing files are preserved by default. Reports reject content that does not fit rather than silently shrinking it.

Daily titles can use typed data directly, for example "Daily report for {{ datasets.summary.report_date }}". Dates and numbers inherit report formatting; | date('MMMM yyyy') overrides a date's display. See text substitutions and the daily report example.

Use from the command line

Render JSON or YAML template/data files without a Python runner:

python -m cardreport render --template report.json --data data.json --output report.pdf
python -m cardreport render --template report.json --csv summary.csv --csv calls.csv --output report.html

Use .yaml or .yml for either input; JSON, YAML and CSV can be mixed. python -m cardreport validate checks inputs without rendering. CSV dataset names come from filenames; use --csv-as NAME PATH to rename one. The installed cardreport command is equivalent. See the complete CLI example and options.

Documentation

For architecture, decisions and contributing, see project documentation.

License

MIT. Bundled DejaVu fonts retain their font license. Third-party rendering packages retain their own licenses.

Metadata

Release files for cardreport 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cardreport 0.9.0
File Size Uploaded Provenance Actions
cardreport-0.9.0.tar.gz 1.9 MB Without provenance Details for cardreport-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cardreport 0.9.0
File Interpreter ABI Platform Actions
cardreport-0.9.0-py3-none-any.whl Python 3 none any Details for cardreport-0.9.0-py3-none-any.whl

Total release size: 2.7 MB

Release files / cardreport-0.9.0.tar.gz

Download URL cardreport-0.9.0.tar.gz
Size 1.9 MB
Tags Source
SHA-256 checksum
How to use checksums
4c1c929c31c19c5b39d1cae8cde885e5bb6a011545ecf36b42ff1d7d948fcae9
BLAKE2b-256 checksum
How to use checksums
e89c3163b25c47a0031fe971a9783c1f8ecd85094119a5d8d27f74c5ad849d1b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.10.6 {"installer":{"name":"uv","version":"0.10.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / cardreport-0.9.0-py3-none-any.whl

Download URL cardreport-0.9.0-py3-none-any.whl
Size 809.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
70fc1c3a1e5922d3cad1c7de8935baeedf2eb50041e95ce4a5857bb32a6f4e44
BLAKE2b-256 checksum
How to use checksums
afe76a7d3c9dcf820ffc2b9a4bc8d90fc47927a6ac8220dab8bc93e8be4370f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.10.6 {"installer":{"name":"uv","version":"0.10.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for cardreport 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page