briefing 0.1.2__tar.gz → 0.2.0__tar.gz

{briefing-0.1.2 → briefing-0.2.0}/.gitignore

@@ -32,3 +32,6 @@ coverage.xml
 
 # Playwright failure screenshots
 test-results/
+
+# Sphinx build output
+docs/_build/

{briefing-0.1.2 → briefing-0.2.0}/CHANGELOG.md

@@ -10,6 +10,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-11-04
+
+### Added
+
+- Printing a report (or saving it as PDF from the browser) shows everything: every
+  page and tab prints under its label, with each top-level `Page` on a new sheet;
+  toggles print open; search boxes, pagination, tab bars, dropdowns and DataDive
+  selectors are hidden; a `DataTable` prints up to 1,000 rows matching its search,
+  with a note giving the total; charts are resized to the paper's width and KPI
+  groups, charts and alerts avoid splitting across sheets; colours print. The
+  screen layout is restored afterwards (#37).
+- `bf.save_image(report, "q1.png", page="all")` renders report pages as PNG, JPEG or
+  WebP in headless Chromium, offline: one image per top-level `Page` (named after it),
+  or one page by title, `name` or index; `width` and `scale` set the pixel size;
+  `size="og" | "square" | "portrait"` shrinks the page to fit a social-card size
+  without cropping; `expand=True` opens toggles first. Accepts a `Briefing` or a saved
+  `.html`. New extra: `pip install "briefing[image]"` (Playwright), then
+  `playwright install chromium` (#49).
+- `bf.save_pdf(report, "q1.pdf", page="all", paper="a4", landscape=False)` writes the
+  report as one PDF with the print layout: each top-level page on a new sheet, text
+  selectable, links clickable, charts vector. One page by title, `name` or index;
+  `paper` is `a4`, `letter`, `legal`, `a3` or `a5` (#49).
+- Command line for saved reports: `python -m briefing image report.html --page all -o out/`
+  and `python -m briefing pdf report.html -o report.pdf`, with the same options as
+  `save_image` / `save_pdf` and `--help` (#49).
+- Opt-in export menu: `bf.Briefing(..., export=("png", "pdf"))` adds "Save as PNG" (the
+  open page, drawn in the reader's browser at 2×, no library, no network) and "Print"
+  to the report header. Reports without `export=` contain no export code. Best effort:
+  Bokeh's iframe charts and WebGL Plotly traces come out blank in the PNG. The menu
+  never appears in prints, PDFs or `save_image` images (#49, #100).
+- `bf.lab.CalendarHeatmap(df, date="run_at", value=None, agg="sum")`: a GitHub-style
+  calendar, one cell per day and weeks as columns, drawn as SVG in Python. It counts
+  rows or aggregates a value per day; runs continuously across year boundaries with
+  month labels and a year marker; shows days without data differently from zeros;
+  `group=` stacks one calendar per group on a shared scale; `colors=` replaces the
+  GitHub greens and `center=` gives a diverging scale; `expected=` (a number, a
+  date-indexed Series or a DataFrame) flags days below target; `events=` marks single
+  days and multi-day spans; each day has a tooltip (#19).
+- `CalendarHeatmap(views=("days", "hours"))` adds a 7 × 24 weekday-by-hour grid, with
+  tabs between the views, and `tz="America/Montreal"` converts timezone-aware timestamps
+  (naive timestamps and plain dates are left on their own day) (#19).
+- `CalendarHeatmap(on_click="rows")`: clicking a day or an hour (or pressing Enter on
+  it) lists the rows behind it in a panel, shown as plain text, up to 50 per cell with a
+  note when there are more (#19).
+- `bf.Banner(md, image=..., text_position=50, opacity=80, side="right", fade=True)`: markdown
+  text over a background image, as a report cover or section opener. The text sits on a
+  veil of the theme background that eases in over 20 % of the width; `height`, `focus`
+  and `alt` are optional; at phone width the image stacks above the text. The image (a
+  path or bytes) is embedded once; files over 2 MB warn. `Formatting` gains a
+  `--bf-bg-rgb` token for the veil (#50).
+- `bf.Banner(..., fade=False)`: one uniform veil at `opacity` over the whole image, for
+  full-width backgrounds and textures; the text still follows `text_position` (#50).
+- API reference documentation, built with Sphinx (`nox -s docs`): every public block
+  and function in `briefing` and `briefing.lab` documents each argument and gives an
+  example. New extra: `pip install "briefing[docs]"` (#41).
+- Documentation guides with a live gallery: a quick start, one guide per block family,
+  themes, notebooks, printing and export, the lab, recipes and the changelog. Every
+  example runs when the docs are built and is embedded as the report it saves; a test
+  runs the same examples against the report contract (#41).
+- The documentation is at https://briefing.readthedocs.io; the README is now a short
+  pitch and quick start that links to it, and the package metadata gains a
+  `Documentation` URL (#41).
+
 ## [0.1.2] - 2026-11-03
 
 Bug fixes after 0.1.1, plus one rendering change: a `BigNumber` change with no
@@ -136,7 +199,8 @@ First public release.
   inherits its base's renderer.
 - Ships inline type hints (`py.typed`). Python 3.11+.
 
-[Unreleased]: https://github.com/jeanmidevacc/briefing/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/jeanmidevacc/briefing/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/jeanmidevacc/briefing/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/jeanmidevacc/briefing/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/jeanmidevacc/briefing/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/jeanmidevacc/briefing/releases/tag/v0.1.0

briefing-0.2.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.3
+Name: briefing
+Version: 0.2.0
+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

briefing-0.2.0/README.md

@@ -0,0 +1,75 @@
+# 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

{briefing-0.1.2 → briefing-0.2.0}/noxfile.py

@@ -39,6 +39,21 @@ def typecheck(session: nox.Session) -> None:
     session.run("mypy", "src/briefing", "tests")
 
 
+@nox.session(python="3.11")
+def docs(session: nox.Session) -> None:
+    """Build the Sphinx site into docs/_build/html; any warning fails the build."""
+    session.install("-e", ".[docs]")
+    session.run("sphinx-build", "-W", "--keep-going", "-b", "html", "docs", "docs/_build/html")
+
+
+@nox.session(name="docs-assets", python="3.11")
+def docs_assets(session: nox.Session) -> None:
+    """Regenerate the committed export samples in docs/_static/export/ (needs a browser)."""
+    session.install("-e", ".[image,docs]")
+    session.run("playwright", "install", "chromium")
+    session.run("python", "docs/make_export_assets.py")
+
+
 # Re-executes the walkthrough in place. SOURCE_DATE_EPOCH pins every timestamp, so
 # re-running it without code changes leaves the notebook and its saved report as they are.
 _RUN_WALKTHROUGH = """

{briefing-0.1.2 → briefing-0.2.0}/pyproject.toml

@@ -62,6 +62,7 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://github.com/jeanmidevacc/briefing"
+Documentation = "https://briefing.readthedocs.io"
 Repository = "https://github.com/jeanmidevacc/briefing"
 Issues = "https://github.com/jeanmidevacc/briefing/issues"
 Changelog = "https://github.com/jeanmidevacc/briefing/blob/main/CHANGELOG.md"
@@ -82,6 +83,19 @@ bokeh = ["bokeh>=3.0"]
 matplotlib = ["matplotlib>=3.7"]
 # pip install briefing[charts] — every supported Plot backend at once
 charts = ["plotly>=5.0", "altair>=5.0", "vl-convert-python>=1.0", "bokeh>=3.0", "matplotlib>=3.7"]
+# pip install briefing[image] — bf.save_image / bf.save_pdf in headless Chromium;
+#   run `playwright install chromium` once after installing
+image = ["playwright>=1.40"]
+# pip install briefing[docs] — build the Sphinx site (nox -s docs); the examples it
+#   runs need pandas and the chart libraries, not Playwright
+docs = [
+    "sphinx>=7.0",
+    "furo>=2024.1.29",
+    "myst-parser>=2.0",
+    "pandas>=2.0",
+    "matplotlib>=3.7",
+    "plotly>=5.0",
+]
 # pip install briefing[email]
 email = [
     "premailer>=3.10",

{briefing-0.1.2 → briefing-0.2.0}/src/briefing/__init__.py

@@ -37,6 +37,7 @@ from briefing.blocks import (
     HTML,
     Alert,
     AlertLevel,
+    Banner,
     BigNumber,
     Block,
     Briefing,
@@ -55,6 +56,9 @@ from briefing.blocks import (
     wrap_block,
 )
 
+# ── export: images and PDFs (Playwright is imported only when called) ────────
+from briefing.export import save_image, save_pdf
+
 # ── formatting ────────────────────────────────────────────────────────────────
 from briefing.renderers.formatting import Formatting, TextAlignment, Width
 
@@ -110,12 +114,27 @@ def stringify(
     as an isolated preview, and :func:`preview` adds a name or a theme.
 
     Pass *now* (or set ``SOURCE_DATE_EPOCH``) for byte-reproducible output.
+
+    Args:
+        blocks: A :class:`Briefing`, a list of blocks, or a single block.
+        name: Report title, shown in the browser tab and the header.
+        formatting: A :class:`Formatting` instance controlling the theme.
+        now: Pin the header timestamp for byte-reproducible output (see also
+            the ``SOURCE_DATE_EPOCH`` environment variable).
+
+    Returns:
+        The complete HTML document.
+
+    Example::
+
+        html = bf.stringify(bf.Text("# Hello"), name="Greeting")
+        email_body = html  # or write it anywhere a string goes
     """
     wrapped = Briefing.wrap(blocks)
     return render_report(wrapped, name=name, formatting=formatting, now=now)
 
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"
 
 __all__: list[str] = [
     # error
@@ -139,6 +158,7 @@ __all__: list[str] = [
     "VAlign",
     "wrap_block",
     # blocks — asset
+    "Banner",
     "DataTable",
     "Plot",
     "Table",
@@ -152,6 +172,8 @@ __all__: list[str] = [
     "Preview",
     "preview",
     "save",
+    "save_image",
+    "save_pdf",
     "stringify",
     # meta
     "__version__",

briefing-0.2.0/src/briefing/__main__.py

@@ -0,0 +1,9 @@
+"""``python -m briefing``: export saved reports (see :mod:`briefing._cli`)."""
+from __future__ import annotations
+
+import sys
+
+from briefing._cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

briefing-0.2.0/src/briefing/_cli.py

@@ -0,0 +1,86 @@
+"""Command line for saved reports: ``python -m briefing image|pdf report.html``."""
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from briefing._error import BriefingError
+from briefing.export import PAPERS, PRESETS, save_image, save_pdf
+
+_FORMATS = ("png", "jpg", "webp")
+
+
+def _page(value: str) -> str | int:
+    """``--page``: "all", a 0-based index, or a page title or name."""
+    return int(value) if value.isdigit() else value
+
+
+def _output(source: Path, output: Path | None, suffix: str) -> Path:
+    """Where to write: the given file, inside the given directory, or next to the input."""
+    if output is None:
+        return source.with_suffix(suffix)
+    if output.is_dir():
+        return output / source.with_suffix(suffix).name
+    return output
+
+
+def _parser() -> argparse.ArgumentParser:
+    from briefing import __version__
+
+    parser = argparse.ArgumentParser(
+        prog="python -m briefing",
+        description="Export a saved briefing report as images or a PDF, in headless Chromium, offline. "
+        'Needs pip install "briefing[image]" and, once, playwright install chromium.',
+    )
+    parser.add_argument("--version", action="version", version=f"briefing {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True, metavar="{image,pdf}")
+
+    image = commands.add_parser("image", help="save report pages as PNG, JPEG or WebP images",
+                                description="Save report pages as images (see bf.save_image).")
+    image.add_argument("report", type=Path, help="a saved report .html file")
+    image.add_argument("-o", "--output", type=Path,
+                       help="output file, or a directory (default: next to the report, same name)")
+    image.add_argument("--page", type=_page, default="all",
+                       help='"all" (default: one image per page), a page title or name, or a 0-based index')
+    image.add_argument("--format", choices=_FORMATS, default=None,
+                       help="image format when --output is a directory or omitted (default: png)")
+    image.add_argument("--size", choices=sorted(PRESETS), default=None,
+                       help="social-card size: og 1200x630, square 1080x1080, portrait 1080x1350 "
+                       "(default: full height)")
+    image.add_argument("--width", type=int, default=1200, help="layout width in CSS pixels (default: 1200)")
+    image.add_argument("--scale", type=float, default=2.0, help="device pixels per CSS pixel (default: 2)")
+    image.add_argument("--no-expand", dest="expand", action="store_false", help="leave toggles closed")
+
+    pdf = commands.add_parser("pdf", help="save the report as one PDF",
+                              description="Save a report as a PDF (see bf.save_pdf).")
+    pdf.add_argument("report", type=Path, help="a saved report .html file")
+    pdf.add_argument("-o", "--output", type=Path, help="output .pdf file, or a directory (default: next to the report)")
+    pdf.add_argument("--page", type=_page, default="all",
+                     help='"all" (default), a page title or name, or a 0-based index')
+    pdf.add_argument("--paper", choices=sorted(PAPERS), default="a4", help="paper size (default: a4)")
+    pdf.add_argument("--landscape", action="store_true", help="turn the paper sideways")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line; returns the exit status."""
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "image":
+            suffix = "." + (args.format or (args.output.suffix.lstrip(".") if args.output and args.output.suffix
+                                            and not args.output.is_dir() else "png"))
+            written = save_image(
+                args.report, _output(args.report, args.output, suffix),
+                page=args.page, width=args.width, scale=args.scale, size=args.size, expand=args.expand,
+            )
+        else:
+            written = [save_pdf(args.report, _output(args.report, args.output, ".pdf"),
+                                page=args.page, paper=args.paper, landscape=args.landscape)]
+    except BriefingError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    for path in written:
+        print(path)
+    return 0

briefing-0.2.0/src/briefing/_error.py

@@ -0,0 +1,10 @@
+class BriefingError(Exception):
+    """Raised for invalid input; the message says what to pass instead.
+
+    Example::
+
+        try:
+            bf.Group("a", "b", columns=2, widths=[1])  # one width for two columns
+        except bf.BriefingError as exc:
+            print(exc)
+    """

{briefing-0.1.2 → briefing-0.2.0}/src/briefing/_preview.py

@@ -57,7 +57,17 @@ def _attribute(text: str) -> str:
 
 
 class Preview:
-    """A notebook preview of *blocks* with a report name and theme; see :func:`preview`."""
+    """A notebook preview of *blocks* with a report name and theme; see :func:`preview`.
+
+    Args:
+        blocks: A block, a list of blocks, or a :class:`~briefing.Briefing`.
+        name: Report title, shown in the header.
+        formatting: The theme.
+
+    Example::
+
+        bf.Preview(report, name="Q1 review", formatting=bf.Formatting.dark())
+    """
 
     def __init__(self, blocks: t.Any, *, name: str = "Report", formatting: Formatting | None = None) -> None:
         self.blocks = blocks

{briefing-0.1.2 → briefing-0.2.0}/src/briefing/blocks/__init__.py

@@ -3,6 +3,7 @@
 Custom-visualisation blocks (DataProfile, DataDive) live in ``briefing.lab``.
 """
 from briefing.blocks.asset import DataTable, Plot, Table
+from briefing.blocks.banner import Banner
 from briefing.blocks.base import Block, BlockId, BlockOrPrimitive, ContainerBlock, wrap_block
 from briefing.blocks.layout import Briefing, Group, Page, Select, SelectType, Toggle, VAlign
 from briefing.blocks.text import HTML, Alert, AlertLevel, BigNumber, Code, Formula, Text
@@ -31,6 +32,7 @@ __all__: list[str] = [
     "Toggle",
     "VAlign",
     # asset
+    "Banner",
     "DataTable",
     "Plot",
     "Table",

{briefing-0.1.2 → briefing-0.2.0}/src/briefing/blocks/asset.py

@@ -24,6 +24,7 @@ class Plot(Block):
     """Chart / figure block — library agnostic.
 
     Auto-detects the figure type at render time:
+
     - **Plotly** → embedded as interactive HTML (inline JS)
     - **Altair / Vega-Lite** → embedded as Vega spec (inline runtime)
     - **Matplotlib / Seaborn / Plotnine** → embedded as inline SVG
@@ -35,6 +36,8 @@ class Plot(Block):
         responsive: Let the chart fill the width of its container.
         scale: Deprecated, has no effect, and is removed after 0.2. Size the figure
             in its plotting library instead, e.g. Matplotlib's ``figsize=(w, h)``.
+        name: Stable block id (letters, digits, ``_`` and ``-``), for referencing the block.
+        label: Tab or dropdown label when the block is inside a ``Select``.
 
     Example::
 
@@ -73,6 +76,12 @@ class Table(Block):
     formatting to be preserved. A Styler is used verbatim; any other frame
     (pandas, polars, pyarrow, …) is normalised to pandas.
 
+    Args:
+        data: A dataframe (as for :class:`DataTable`) or a pandas ``Styler``, kept as-is.
+        caption: Optional caption below the table.
+        name: Stable block id (letters, digits, ``_`` and ``-``), for referencing the block.
+        label: Tab or dropdown label when the block is inside a ``Select``.
+
     Example::
 
         bf.Table(df)
@@ -102,6 +111,14 @@ class DataTable(Block):
     Handles large datasets via client-side pagination. Viewers can also sort
     columns and filter rows by typing in the search box.
 
+    Args:
+        df: The data: pandas, polars, pyarrow, anything with the dataframe
+            interchange protocol, or a dict of columns.
+        caption: Optional caption below the table.
+        max_rows: Rows beyond this are dropped with a warning.
+        name: Stable block id (letters, digits, ``_`` and ``-``), for referencing the block.
+        label: Tab or dropdown label when the block is inside a ``Select``.
+
     Example::
 
         bf.DataTable(df, caption="Top 1 000 orders")