Metadata-Version: 2.3
Name: briefing
Version: 0.2.3
Summary: Build beautiful self-contained HTML reports from Python analysis
Project-URL: Homepage, https://github.com/jeanmidevacc/briefing
Project-URL: Documentation, https://briefing.readthedocs.io
Project-URL: Repository, https://github.com/jeanmidevacc/briefing
Project-URL: Issues, https://github.com/jeanmidevacc/briefing/issues
Project-URL: Changelog, https://github.com/jeanmidevacc/briefing/blob/main/CHANGELOG.md
Author: jeanmidevacc
License: Apache-2.0
Keywords: data,html,pandas,polars,reporting,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jinja2>=3.1
Requires-Dist: latex2mathml>=3.77
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: pygments>=2.15
Provides-Extra: altair
Requires-Dist: altair>=5.0; extra == 'altair'
Requires-Dist: vl-convert-python>=1.0; extra == 'altair'
Provides-Extra: bokeh
Requires-Dist: bokeh>=3.0; extra == 'bokeh'
Provides-Extra: charts
Requires-Dist: altair>=5.0; extra == 'charts'
Requires-Dist: bokeh>=3.0; extra == 'charts'
Requires-Dist: matplotlib>=3.7; extra == 'charts'
Requires-Dist: plotly>=5.0; extra == 'charts'
Requires-Dist: vl-convert-python>=1.0; extra == 'charts'
Provides-Extra: dev
Requires-Dist: altair>=5.0; extra == 'dev'
Requires-Dist: beautifulsoup4>=4.14; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: matplotlib>=3.7; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: nox>=2024.4; extra == 'dev'
Requires-Dist: pandas-stubs>=2.0; extra == 'dev'
Requires-Dist: pandas>=2.0; extra == 'dev'
Requires-Dist: plotly>=5.0; extra == 'dev'
Requires-Dist: pyarrow>=15.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-playwright>=0.5; extra == 'dev'
Requires-Dist: pytest-snapshot>=0.9; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: vl-convert-python>=1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.1.29; extra == 'docs'
Requires-Dist: matplotlib>=3.7; extra == 'docs'
Requires-Dist: myst-parser>=2.0; extra == 'docs'
Requires-Dist: pandas>=2.0; extra == 'docs'
Requires-Dist: plotly>=5.0; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: email
Requires-Dist: kaleido>=0.2; extra == 'email'
Requires-Dist: premailer>=3.10; extra == 'email'
Provides-Extra: image
Requires-Dist: playwright>=1.40; extra == 'image'
Provides-Extra: lab
Requires-Dist: pandas>=2.0; extra == 'lab'
Provides-Extra: matplotlib
Requires-Dist: matplotlib>=3.7; extra == 'matplotlib'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Provides-Extra: plotly
Requires-Dist: plotly>=5.0; extra == 'plotly'
Description-Content-Type: text/markdown

# briefing

[![Documentation](https://readthedocs.org/projects/briefing/badge/?version=latest)](https://briefing.readthedocs.io)
[![PyPI](https://img.shields.io/pypi/v/briefing)](https://pypi.org/project/briefing/)

Build beautiful, self-contained reports from Python, authored by a person, a coding agent, or both.

A report is a short list of blocks (`Text`, `BigNumber`, `Plot`, `DataTable`, `Group`, `Select`, …),
saved as **one HTML file** with every script, style and image inside it: no CDN, no server, no
account. It opens offline, forever, and prints, or exports to PNG and PDF, cleanly.

![A briefing report: three KPIs above a line chart](https://raw.githubusercontent.com/jeanmidevacc/briefing/main/docs/_static/export/page.png)

## Why briefing exists

Three things led me here:

- **Coding agents are good at making something to show you, not at making it consistently.** A few months of building with coding agents surfaced the same gap every time: they're happy to produce an artifact, but each one comes out with its own structure, and nothing tracks how a piece of content evolved across a project. There was no shared grammar a person and an agent could both build reports from as the report generation was opaque.
- **[datapane](https://github.com/datapane/datapane) was the cleanest report builder I'd used.** Block-based, self-contained HTML output, a dead-simple API. I relied on it constantly to turn Python analysis into reports for stakeholders and to monitor pipelines. It was decommissioned in 2023 when the SaaS behind it shut down, and nothing since has replaced it.
- **No visualization tool covers everything, and the ones that push furthest often don't stick around.** Years of building visualizations taught me that every tool, however good, eventually falls short of the next thing you want to show. The niche packages that *do* push past that, like [Facets](https://github.com/PAIR-code/facets) (PAIR / Google) and its Facets Dive explorer, bring real value but rarely stay maintained. I wanted a place of my own to keep building and sharing that kind of custom, interactive visualization, without depending on someone else's side project staying alive.

briefing is built to close all three gaps at once: a block grammar solid enough for me *and* my coding agents to build reports from consistently, with datapane's simplicity and a home for the custom, interactive visualization that inspired it. All of it self-contained, offline, with no cloud account required.

## Install

```bash
pip install briefing                 # the block grammar and the HTML renderer
pip install "briefing[pandas]"       # tables from dataframes
pip install "briefing[lab]"          # DataProfile, DataDive, CalendarHeatmap
pip install "briefing[image]"        # save_image / save_pdf (then: playwright install chromium)
```

The core has no plotting or dataframe dependency. `Plot` takes a Plotly, Altair, Matplotlib or
Bokeh figure and imports only the library you pass; install `[plotly]`, `[altair]`, `[bokeh]`,
`[matplotlib]` or all of them with `[charts]`. Python 3.11+, pandas 2 and 3; polars and pyarrow
tables are converted for you.

## Quick start

```python
import briefing as bf

report = bf.Briefing(
    bf.Text("# Sales Analysis, Q1 2024"),
    bf.Group(
        bf.BigNumber("Revenue", "$4.2M", change="-12%", is_upward_change=False),
        bf.BigNumber("Active Users", "142K", change="+3%", is_upward_change=True),
        columns=2,
    ),
    bf.Select(
        bf.Plot(fig, label="Trend"),
        bf.DataTable(df, label="Raw Data"),
        bf.lab.DataProfile(df, label="Profile"),
    ),
)

bf.save(report, "q1_analysis.html", name="Sales, Q1 2024")
```

Here `df` is a dataframe and `fig` a chart from any supported library. In a notebook, any block
previews itself as the last expression of a cell.

With `briefing[image]`, `bf.save_image(report, "q1.png", size="og")` renders a 1200×630 social
card and `bf.save_pdf(report, "q1.pdf")` a PDF of every page, both offline in headless Chromium.

## Documentation

**[briefing.readthedocs.io](https://briefing.readthedocs.io)** has a guide for each block family
with live examples, themes, notebooks, printing and export, the `briefing.lab` blocks, recipes and
the full API reference.

- [Changelog](CHANGELOG.md)
- [`examples/notebook_walkthrough.ipynb`](examples/notebook_walkthrough.ipynb): build a report
  cell by cell, then save it ([the report it saves](examples/sales_report.html))
- [Issues](https://github.com/jeanmidevacc/briefing/issues): bugs, ideas and the roadmap
