briefing 0.1.0__py3-none-any.whl

briefing/__init__.py

@@ -0,0 +1,192 @@
+"""briefing — build beautiful, self-contained HTML reports from Python analysis.
+
+Quick start::
+
+    import briefing as bf
+
+    report = bf.Briefing(
+        bf.Text("# My Analysis"),
+        bf.Group(
+            bf.BigNumber("Accuracy", "92.4%", change="+1.2%", is_upward_change=True),
+            bf.BigNumber("F1 Score", 0.89),
+            columns=2,
+        ),
+        bf.Select(
+            bf.Plot(fig, label="Chart"),
+            bf.DataTable(df, label="Data"),
+        ),
+    )
+
+    bf.save(report, "analysis.html")
+"""
+import typing as t
+import warnings
+import webbrowser
+from datetime import datetime
+from pathlib import Path
+
+# ── lab: custom-visualisation blocks (briefing.lab.DataProfile / .DataDive) ───
+# Same wheel; importing it registers its renderers. `briefing[lab]` only adds
+# the pandas dependency those blocks need at render time.
+from briefing import lab
+from briefing._error import BriefingError
+
+# ── blocks ────────────────────────────────────────────────────────────────────
+from briefing.blocks import (
+    HTML,
+    Alert,
+    AlertLevel,
+    BigNumber,
+    Block,
+    Briefing,
+    Code,
+    DataTable,
+    Formula,
+    Group,
+    Page,
+    Plot,
+    Select,
+    SelectType,
+    Table,
+    Text,
+    Toggle,
+    VAlign,
+    wrap_block,
+)
+
+# ── formatting ────────────────────────────────────────────────────────────────
+from briefing.renderers.formatting import Formatting, TextAlignment, Width
+
+# ── renderer ──────────────────────────────────────────────────────────────────
+from briefing.renderers.html import render_report
+
+# ── public API ────────────────────────────────────────────────────────────────
+
+
+def save(
+    blocks: Briefing | list[t.Any] | object,
+    path: str,
+    *,
+    open: bool = False,  # noqa: A002
+    name: str = "Report",
+    formatting: Formatting | None = None,
+    now: datetime | None = None,
+) -> None:
+    """Save *blocks* as a self-contained HTML file at *path*.
+
+    Args:
+        blocks: A :class:`~briefing.Briefing` instance, a list of blocks, or a
+            single block.  Lists and single blocks are automatically wrapped.
+        path: Destination file path (e.g. ``"report.html"``).
+        open: Open the file in your default browser after saving.
+        name: Document title shown in the browser tab and report header.
+        formatting: A :class:`~briefing.Formatting` instance controlling the theme.
+        now: Pin the header timestamp for byte-reproducible output (see also the
+            ``SOURCE_DATE_EPOCH`` environment variable).
+
+    Example::
+
+        bf.save(report, "analysis.html", name="Q1 Analysis", open=True)
+    """
+    wrapped = Briefing.wrap(blocks)
+    html = render_report(wrapped, name=name, formatting=formatting, now=now)
+    dest = Path(path)
+    dest.write_text(html, encoding="utf-8")
+    if open:
+        webbrowser.open(dest.resolve().as_uri())
+
+
+def stringify(
+    blocks: Briefing | list[t.Any] | object,
+    *,
+    name: str = "Report",
+    formatting: Formatting | None = None,
+    now: datetime | None = None,
+) -> str:
+    """Render *blocks* to a self-contained HTML string.
+
+    Useful for inline display in Jupyter notebooks::
+
+        from IPython.display import HTML, display
+        display(HTML(bf.stringify(report)))
+
+    Pass *now* (or set ``SOURCE_DATE_EPOCH``) for byte-reproducible output.
+    """
+    wrapped = Briefing.wrap(blocks)
+    return render_report(wrapped, name=name, formatting=formatting, now=now)
+
+
+__version__ = "0.1.0"
+
+__all__: list[str] = [
+    # error
+    "BriefingError",
+    # blocks — text
+    "Alert",
+    "AlertLevel",
+    "BigNumber",
+    "Code",
+    "Formula",
+    "HTML",
+    "Text",
+    # blocks — layout
+    "Block",
+    "Briefing",
+    "Group",
+    "Page",
+    "Select",
+    "SelectType",
+    "Toggle",
+    "VAlign",
+    "wrap_block",
+    # blocks — asset
+    "DataTable",
+    "Plot",
+    "Table",
+    # custom-visualisation subpackage (bf.lab.DataProfile / bf.lab.DataDive)
+    "lab",
+    # formatting
+    "Formatting",
+    "TextAlignment",
+    "Width",
+    # api
+    "save",
+    "stringify",
+    # meta
+    "__version__",
+]
+
+
+# ── deprecated aliases (removed after 0.2) ───────────────────────────────────
+
+#: old name -> (new name, object)
+_RENAMED: dict[str, tuple[str, object]] = {
+    "Blocks": ("Briefing", Briefing),
+    "BaseBlock": ("Block", Block),
+    "save_report": ("save", save),
+    "stringify_report": ("stringify", stringify),
+}
+
+#: names that moved into the briefing.lab subpackage
+_MOVED_TO_LAB: frozenset[str] = frozenset({"DataProfile", "DataDive"})
+
+
+def __getattr__(name: str) -> t.Any:
+    if name in _RENAMED:
+        new, obj = _RENAMED[name]
+        warnings.warn(
+            f"briefing.{name} is deprecated and will be removed after 0.2 — "
+            f"use briefing.{new}.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return obj
+    if name in _MOVED_TO_LAB:
+        warnings.warn(
+            f"briefing.{name} moved to briefing.lab.{name} (pip install briefing[lab]) "
+            f"and will be removed after 0.2 — use briefing.lab.{name}.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return getattr(lab, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

briefing/_error.py

@@ -0,0 +1,2 @@
+class BriefingError(Exception):
+    """Base exception for all briefing errors."""

briefing/_frames.py

@@ -0,0 +1,91 @@
+"""Dataframe intake — accept more than just pandas.
+
+``briefing`` renders tables and profiles against a pandas DataFrame internally,
+but pandas is an optional extra (``pip install briefing[pandas]``) and callers
+should not be forced to use pandas as *their* dataframe library.
+
+:func:`to_pandas` normalises whatever a data block is handed into a pandas
+DataFrame:
+
+* a pandas DataFrame passes straight through;
+* anything implementing the dataframe interchange protocol (``__dataframe__`` —
+  polars, pyarrow, modin, cuDF, vaex, …) is converted via
+  ``pandas.api.interchange.from_dataframe``;
+* anything else exposing ``.to_pandas()`` (pyarrow Table, polars, …) uses that;
+* a plain ``dict`` / list-of-rows is passed to the ``pandas.DataFrame``
+  constructor.
+
+A native pandas-free rendering path is out of scope for now (tracked in the
+development plan); this keeps the door open to other dataframe libraries without
+that rewrite.
+"""
+from __future__ import annotations
+
+import contextlib
+import typing as t
+
+from briefing._error import BriefingError
+
+if t.TYPE_CHECKING:
+    import pandas as pd
+
+_INSTALL_HINT = "install it with:  pip install briefing[pandas]"
+
+
+def _import_pandas() -> t.Any:
+    try:
+        import pandas
+    except ImportError as exc:  # pragma: no cover - exercised only without pandas
+        raise BriefingError(f"This block needs pandas — {_INSTALL_HINT}") from exc
+    return pandas
+
+
+def is_pandas_dataframe(obj: object) -> bool:
+    """True if *obj* is a pandas DataFrame, without importing pandas eagerly."""
+    return any(
+        f"{c.__module__}.{c.__qualname__}" == "pandas.core.frame.DataFrame"
+        for c in type(obj).__mro__
+    )
+
+
+def looks_like_dataframe(obj: object) -> bool:
+    """Heuristic for auto-wrapping: does *obj* look like a tabular frame?"""
+    return (
+        is_pandas_dataframe(obj)
+        or hasattr(obj, "__dataframe__")
+        or (hasattr(obj, "to_pandas") and callable(obj.to_pandas))
+    )
+
+
+def to_pandas(obj: object, *, block: str = "This block") -> pd.DataFrame:
+    """Return *obj* as a pandas DataFrame, converting from other libraries.
+
+    Args:
+        obj: a pandas / polars / pyarrow / interchange-protocol frame, or
+            something the ``pandas.DataFrame`` constructor accepts.
+        block: name used in error messages (e.g. ``"DataTable"``).
+    """
+    pandas = _import_pandas()
+
+    if isinstance(obj, pandas.DataFrame):
+        return t.cast("pd.DataFrame", obj)
+
+    # Dataframe interchange protocol — polars, pyarrow, modin, cuDF, vaex, …
+    if hasattr(obj, "__dataframe__"):
+        with contextlib.suppress(Exception):
+            return t.cast("pd.DataFrame", pandas.api.interchange.from_dataframe(obj))
+
+    # pyarrow.Table, polars.DataFrame, …
+    to_pd = getattr(obj, "to_pandas", None)
+    if callable(to_pd):
+        return t.cast("pd.DataFrame", to_pd())
+
+    # dict of columns / list of row dicts / numpy structured array …
+    if isinstance(obj, dict | list):
+        return t.cast("pd.DataFrame", pandas.DataFrame(obj))
+
+    raise BriefingError(
+        f"{block} could not turn {type(obj).__module__}.{type(obj).__qualname__} "
+        "into a table. Pass a pandas / polars / pyarrow DataFrame, an object "
+        "implementing the dataframe interchange protocol, or a dict of columns."
+    )

briefing/blocks/__init__.py

@@ -0,0 +1,37 @@
+"""briefing.blocks — core block types re-exported from one place.
+
+Custom-visualisation blocks (DataProfile, DataDive) live in ``briefing.lab``.
+"""
+from briefing.blocks.asset import DataTable, Plot, Table
+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
+
+__all__: list[str] = [
+    # base
+    "Block",
+    "BlockId",
+    "BlockOrPrimitive",
+    "ContainerBlock",
+    "wrap_block",
+    # text
+    "Alert",
+    "AlertLevel",
+    "BigNumber",
+    "Code",
+    "Formula",
+    "HTML",
+    "Text",
+    # layout
+    "Briefing",
+    "Group",
+    "Page",
+    "Select",
+    "SelectType",
+    "Toggle",
+    "VAlign",
+    # asset
+    "DataTable",
+    "Plot",
+    "Table",
+]

briefing/blocks/asset.py

@@ -0,0 +1,124 @@
+"""Asset-based blocks: Plot, Table, DataTable.
+
+These blocks hold external data (figures, DataFrames) and are serialised
+into the HTML as inline assets during the render pass.
+
+``Table`` / ``DataTable`` accept any dataframe library ``briefing`` can
+normalise (see :mod:`briefing._frames`); the data is stored internally as a
+pandas DataFrame.
+"""
+from __future__ import annotations
+
+import typing as t
+import warnings
+
+from briefing._frames import is_pandas_dataframe, to_pandas
+from briefing.blocks.base import _MAX_CAPTION_LEN, Block, BlockId, _truncate
+
+if t.TYPE_CHECKING:
+    import pandas as pd
+    from pandas.io.formats.style import Styler
+
+
+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
+    - **Bokeh** → embedded with inline resources
+
+    Example::
+
+        fl.Plot(plotly_fig, caption="Revenue over time")
+        fl.Plot(altair_chart, label="Chart", responsive=True)
+    """
+
+    def __init__(
+        self,
+        figure: t.Any,
+        caption: str | None = None,
+        responsive: bool = True,
+        scale: float = 1.0,
+        name: BlockId | None = None,
+        label: str | None = None,
+    ) -> None:
+        super().__init__(name=name, label=label)
+        self.figure = figure
+        self.caption = _truncate(caption, _MAX_CAPTION_LEN) if caption else caption
+        self.responsive = responsive
+        self.scale = scale
+
+
+class Table(Block):
+    """Static HTML table rendered from a dataframe or a pandas Styler.
+
+    Best for multidimensional DataFrames where you want pandas' Styler
+    formatting to be preserved. A Styler is used verbatim; any other frame
+    (pandas, polars, pyarrow, …) is normalised to pandas.
+
+    Example::
+
+        bf.Table(df)
+        bf.Table(df.style.highlight_max(color="lightgreen"))
+    """
+
+    def __init__(
+        self,
+        data: pd.DataFrame | Styler | t.Any,
+        caption: str | None = None,
+        name: BlockId | None = None,
+        label: str | None = None,
+    ) -> None:
+        super().__init__(name=name, label=label)
+        # A Styler carries its own formatting rules — keep it as-is. Everything
+        # else goes through the dataframe intake layer.
+        if type(data).__name__ == "Styler" or is_pandas_dataframe(data):
+            self.data = data
+        else:
+            self.data = to_pandas(data, block="Table")
+        self.caption = _truncate(caption, _MAX_CAPTION_LEN) if caption else caption
+
+
+class DataTable(Block):
+    """Interactive, sortable and searchable table rendered from a pandas DataFrame.
+
+    Handles large datasets via client-side pagination. Viewers can also sort
+    columns and filter rows by typing in the search box.
+
+    Example::
+
+        fl.DataTable(df, caption="Top 1 000 orders")
+    """
+
+    #: Maximum rows rendered by default; larger DataFrames are truncated with a warning.
+    MAX_ROWS: t.ClassVar[int] = 10_000
+
+    def __init__(
+        self,
+        df: pd.DataFrame | t.Any,
+        caption: str | None = None,
+        max_rows: int = MAX_ROWS,
+        name: BlockId | None = None,
+        label: str | None = None,
+    ) -> None:
+        super().__init__(name=name, label=label)
+        df = to_pandas(df, block="DataTable")
+
+        if len(df) > max_rows:
+            warnings.warn(
+                f"DataTable: DataFrame has {len(df):,} rows — truncating to {max_rows:,}. "
+                "Increase 'max_rows' to render more.",
+                stacklevel=2,
+            )
+            df = df.head(max_rows)
+
+        self.df = df
+        self.caption = _truncate(caption, _MAX_CAPTION_LEN) if caption else caption
+        self.max_rows = max_rows
+
+
+# ── public re-exports ─────────────────────────────────────────────────────────
+
+__all__: list[str] = ["DataTable", "Plot", "Table"]

briefing/blocks/base.py

@@ -0,0 +1,113 @@
+"""Core block primitives: Block, ContainerBlock, and wrap_block."""
+from __future__ import annotations
+
+import re
+import typing as t
+from collections.abc import Sequence
+
+from briefing._error import BriefingError
+
+_NAME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9_-]*$")
+_MAX_LABEL_LEN = 256
+_MAX_CAPTION_LEN = 512
+
+BlockId = str
+BlockOrPrimitive = t.Union["Block", t.Any]
+
+
+class Block:
+    """Base class for all briefing blocks.
+
+    All blocks carry an optional ``name`` (a stable ID for referencing the
+    block) and an optional ``label`` (a human-readable display string used
+    e.g. as a tab title inside a Select).
+    """
+
+    def __init__(
+        self,
+        name: BlockId | None = None,
+        label: str | None = None,
+    ) -> None:
+        if name is not None and not _NAME_RE.match(name):
+            raise BriefingError(
+                f"Invalid block name {name!r}: must start with a letter and contain "
+                "only letters, digits, underscores, or hyphens."
+            )
+        self.name = name
+        self.label = _truncate(label, _MAX_LABEL_LEN) if label else label
+
+    def __repr__(self) -> str:
+        parts = []
+        if self.name:
+            parts.append(f"name={self.name!r}")
+        if self.label:
+            parts.append(f"label={self.label!r}")
+        return f"{self.__class__.__name__}({', '.join(parts)})"
+
+
+class ContainerBlock(Block):
+    """Block that holds a list of child blocks (forms a subtree)."""
+
+    #: Subclasses can raise the bar; checked during rendering, not construction.
+    min_blocks: t.ClassVar[int] = 1
+
+    def __init__(
+        self,
+        *arg_blocks: BlockOrPrimitive,
+        blocks: Sequence[BlockOrPrimitive] | None = None,
+        name: BlockId | None = None,
+        label: str | None = None,
+    ) -> None:
+        super().__init__(name=name, label=label)
+        resolved = list(blocks if blocks is not None else arg_blocks)
+        self.blocks: list[Block] = [wrap_block(b) for b in resolved]
+
+    def __iter__(self) -> t.Iterator[Block]:
+        return iter(self.blocks)
+
+    def __len__(self) -> int:
+        return len(self.blocks)
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"{len(self.blocks)} block(s)"
+            + (f", name={self.name!r}" if self.name else "")
+            + ")"
+        )
+
+
+def wrap_block(b: BlockOrPrimitive) -> Block:
+    """Auto-wrap primitives into appropriate blocks.
+
+    Supported auto-wrapping:
+    - ``str``       → :class:`~briefing.blocks.text.Text`
+    - a dataframe   → :class:`~briefing.blocks.asset.DataTable`
+      (pandas / polars / pyarrow / dataframe-interchange objects)
+    """
+    if isinstance(b, Block):
+        return b
+
+    if isinstance(b, str):
+        from briefing.blocks.text import Text
+
+        return Text(text=b)
+
+    from briefing._frames import looks_like_dataframe
+
+    if looks_like_dataframe(b):
+        from briefing.blocks.asset import DataTable
+
+        return DataTable(b)
+
+    raise BriefingError(
+        f"Cannot auto-wrap {type(b).__name__!r} into a briefing block. "
+        "Pass a briefing block, a string, or a dataframe."
+    )
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+
+def _truncate(s: str, max_len: int) -> str:
+    return s[: max_len - 3] + "..." if len(s) > max_len else s