CardReport
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 |
|---|---|
Spanish campaign report — the reference report with localized dates/numbers, tables and charts. Example and provenance.
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 |
|---|---|
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, and
| datetime('dd.MM.yyyy HH:mm XXX') formats a timestamp. Set report.timezone
(e.g. Asia/Nicosia) to display timestamps in one zone; otherwise their supplied
offsets are preserved. 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
- Quickstart — build from application data; return strings/bytes.
- KPI dashboards — compact charts, category legends and larger KPI values; multi-page dashboards use flow to carry whole rows and split tables.
- Templates — JSON presentation with separate named datasets.
- YAML and JSON Schema — YAML embedding, schemas, data validation and editor setup.
- Datasets — native Python data and typed JSON storage.
- User guide — cards, layout, formatting and multiple pages.
- Language and display formats — report language tags, custom dates, number precision and the Spanish example.
- API reference — signatures, defaults, constraints and errors.
- Renderers — installation, supported features and extensions.
- Examples and integration — the original report, tables and async code.
- Command line — render JSON templates with JSON or CSV datasets using
python -m cardreport.
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.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cardreport-0.9.1.tar.gz | 1.9 MB | Without provenance | Details for cardreport-0.9.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cardreport-0.9.1-py3-none-any.whl | Python 3 | none | any | Details for cardreport-0.9.1-py3-none-any.whl |
Total release size: 2.7 MB
Release files / cardreport-0.9.1.tar.gz
| Download URL | cardreport-0.9.1.tar.gz |
|---|---|
| Size | 1.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
09c68605b8e283df2220459f12ba247fb9483ca446621a005228860090ef8ac1
|
|
BLAKE2b-256 checksum How to use checksums |
1fa634df882d61e60e42fba3205cf947212fbb316a9442b4afa9cd78e31001c2
|
| 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.1-py3-none-any.whl
| Download URL | cardreport-0.9.1-py3-none-any.whl |
|---|---|
| Size | 810.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
739796837184285b05f0f708bee577b6b10d7c5168cd3933e8b0ce1a41d5dae9
|
|
BLAKE2b-256 checksum How to use checksums |
10f98c3290c3e83857ec9a04e6cdacacba9208cfd57c997ac707f64a93a790a8
|
| 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.1
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.