Metadata-Version: 2.5
Name: cardreport
Version: 0.3.0
Summary: Composable Python reports with cards, constrained charts, and HTML-to-PDF output
Project-URL: Repository, https://github.com/arch7tect/cardreport
Project-URL: Documentation, https://github.com/arch7tect/cardreport/blob/main/docs/user/quickstart.md
Project-URL: Issues, https://github.com/arch7tect/cardreport/issues
Author: Oleg Orlov
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: babel<3,>=2.17
Requires-Dist: fonttools<5,>=4.59
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: langcodes<4,>=3.5
Requires-Dist: plotly<7,>=6.9
Provides-Extra: pandas
Requires-Dist: pandas<4,>=2.2; extra == 'pandas'
Provides-Extra: pdf
Requires-Dist: playwright==1.64.1; extra == 'pdf'
Requires-Dist: psutil<8,>=7; extra == 'pdf'
Requires-Dist: pypdf<7,>=6; extra == 'pdf'
Provides-Extra: weasyprint
Requires-Dist: matplotlib==3.11.2; extra == 'weasyprint'
Requires-Dist: pdfplumber<1,>=0.11.10; extra == 'weasyprint'
Requires-Dist: psutil<8,>=7; extra == 'weasyprint'
Requires-Dist: pypdf<7,>=6; extra == 'weasyprint'
Requires-Dist: weasyprint==70.0; extra == 'weasyprint'
Description-Content-Type: text/markdown

# CardReport

[![Latest release](https://img.shields.io/github/v/release/arch7tect/cardreport)](https://github.com/arch7tect/cardreport/releases/latest)
[![PyPI version](https://img.shields.io/pypi/v/cardreport?cacheSeconds=300)](https://pypi.org/project/cardreport/)

[What’s new](https://github.com/arch7tect/cardreport/blob/main/CHANGELOG.md)

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.

## Install in your project

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

```sh
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](https://github.com/arch7tect/cardreport/blob/main/docs/user/quickstart.md)
for local checkouts, wheels and how to embed exports.

## Use from Python

```python
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()
```

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.

## Documentation

- [Quickstart](https://github.com/arch7tect/cardreport/blob/main/docs/user/quickstart.md) — build from application data; return strings/bytes.
- [Templates](https://github.com/arch7tect/cardreport/blob/main/docs/user/templates.md) — JSON presentation with separate named datasets.
- [Datasets](https://github.com/arch7tect/cardreport/blob/main/docs/user/datasets.md) — native Python data and typed JSON storage.
- [User guide](https://github.com/arch7tect/cardreport/blob/main/docs/user/guide.md) — cards, layout, formatting and multiple pages.
- [API reference](https://github.com/arch7tect/cardreport/blob/main/docs/user/api.md) — signatures, defaults, constraints and errors.
- [Renderers](https://github.com/arch7tect/cardreport/blob/main/docs/user/renderers.md) — installation, supported features and extensions.
- [Examples and integration](https://github.com/arch7tect/cardreport/blob/main/docs/user/examples.md) — the original report, tables and async code.
- [Command-line examples](https://github.com/arch7tect/cardreport/blob/main/docs/user/command-line.md) — optional script runners.

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 the [original reference example](https://github.com/arch7tect/cardreport/blob/main/docs/user/examples.md#reference-report).
Local macOS/Python 3.12 is verified; Linux and Windows are not yet verified.

For architecture, decisions and contributing, see [project documentation](https://github.com/arch7tect/cardreport/blob/main/docs/project/README.md).

## License

[MIT](https://github.com/arch7tect/cardreport/blob/main/LICENSE). Bundled DejaVu fonts retain their [font license](https://github.com/arch7tect/cardreport/blob/main/src/cardreport/assets/LICENSE_DEJAVU).
Third-party rendering packages retain their own licenses.

See [language and display formats](https://github.com/arch7tect/cardreport/blob/main/docs/user/localization.md)
for report language tags, custom dates, number precision and the Spanish example.
