"""Backend-neutral single and multi-page plot output values."""
from __future__ import annotations
import json
import math
from dataclasses import dataclass, field
from datetime import date, datetime, timedelta
from typing import Any, Literal, Mapping, TypeAlias
FigureLike: TypeAlias = Any
class FigureInputUnavailable(RuntimeError):
"""``inspect()`` cannot draw this figure here, for this image.
Raised by a provider whose figure is drawn from state only its own
``apply()`` produces -- such as the as-shot pixels an image corrector
overwrites -- when that ``apply()`` did not run in this process on the
image it was given. It says where the figure can be drawn, not that the
figure failed: the CLI keeps a stored copy of it when one exists.
"""
def figure_backend_of(figure: Any) -> Literal["plotly", "mpl"] | None:
"""Return the rendering backend of ``figure``, or ``None`` if unknown.
Identification is by module string so this module stays standard-library
only at runtime -- importing plotly or matplotlib to answer the question
would defeat the lazy-import contract this package is held to.
Args:
figure: Any object that might be a supported figure.
Returns:
``"plotly"``, ``"mpl"``, or ``None`` for anything unrecognised. Never
raises: callers that need an error raise their own, with the context
only they have.
"""
module = type(figure).__module__
if type(figure).__name__ != "Figure":
return None
if module.startswith("plotly."):
return "plotly"
if module.startswith("matplotlib."):
return "mpl"
return None
[docs]
@dataclass(frozen=True)
class PlotPage:
"""One independently saveable figure page.
Args:
key: Stable logical page key; names the page's file.
figure: Plotly or Matplotlib figure.
label: Optional human-readable page label.
metadata: Immutable-by-convention selector metadata.
plot: The plot this page belongs to; names the folder its file is
stored in. ``None`` means the page is a plot of its own, stored
at ``<key>/<key>`` (spec 2026-09-30 §1).
"""
key: str
figure: FigureLike
label: str | None = None
metadata: Mapping[str, str | int | float | bool | None] = field(
default_factory=dict
)
plot: str | None = None
def __post_init__(self) -> None:
if not isinstance(self.key, str) or not self.key:
raise ValueError("plot page key must be a non-empty string")
if self.plot is not None and (
not isinstance(self.plot, str) or not self.plot or "/" in self.plot
):
raise ValueError(
"plot page plot must be None or a non-empty string without '/'"
)
@property
def plot_name(self) -> str:
"""The plot (folder) this page is stored under: ``plot``, else ``key``."""
return self.plot if self.plot is not None else self.key
[docs]
@dataclass(frozen=True)
class PlotOutput:
"""Ordered pages returned by a plotting invocation."""
pages: tuple[PlotPage, ...]
def __post_init__(self) -> None:
ids = [(page.plot_name, page.key) for page in self.pages]
duplicates = sorted(
{f"{plot}/{key}" for plot, key in ids if ids.count((plot, key)) > 1}
)
if duplicates:
raise ValueError(f"plot output contains duplicate page keys: {duplicates}")
[docs]
def canonical_group_key(
pairs: list[tuple[str, Any]],
) -> str:
"""Encode typed grouping pairs without ambiguous string concatenation.
Integer, float, temporal, and string values retain distinct tags. Numeric
and temporal payloads use canonical strings so JSON encoder settings and
platform formatting cannot change a page identity.
"""
encoded: list[list[str | None]] = []
for column, value in pairs:
if hasattr(value, "item"):
value = value.item()
if value is None:
kind = "null"
canonical = None
elif isinstance(value, bool):
kind = "bool"
canonical = "true" if value else "false"
elif isinstance(value, datetime):
kind = "datetime"
canonical = value.isoformat()
elif isinstance(value, date):
kind = "date"
canonical = value.isoformat()
elif isinstance(value, timedelta):
kind = "timedelta_ns"
canonical = str(
(
value.days * 86_400
+ value.seconds
)
* 1_000_000_000
+ value.microseconds * 1_000
)
elif isinstance(value, int):
kind = "int"
canonical = str(value)
elif isinstance(value, float):
if not math.isfinite(value):
raise ValueError("grouping floats must be finite")
kind = "float"
canonical = value.hex()
elif isinstance(value, str):
kind = "str"
canonical = value
else:
raise TypeError(
f"unsupported grouping value {value!r} "
f"({type(value).__name__})"
)
encoded.append([column, kind, canonical])
return json.dumps(encoded, ensure_ascii=False, separators=(",", ":"))
__all__ = [
"FigureInputUnavailable",
"FigureLike",
"PlotOutput",
"PlotPage",
"canonical_group_key",
"figure_backend_of",
]