Source code for osprey_connectors.simulation.logbook

"""The logbook entries a scenario narrates, and the pictures they carry.

:class:`ScenarioLogEntry` is the one entry shape the logbook seed reads.
An entry's pictures are shipped image files or :class:`PlotSpec` records the
seeder draws against the entry's timestamp; :func:`parse_log_attachments`
resolves and checks an entry's ``attachments`` list, and
:func:`parse_plot_spec` validates one decoded plot spec.
"""

import json
import math
from dataclasses import dataclass
from pathlib import Path

from osprey_connectors.relative_time import RelativeTimestamp

__all__ = [
    "IMAGE_SIGNATURES",
    "SIGNATURE_BYTES",
    "PlotSeries",
    "PlotSpec",
    "ScenarioLogEntry",
    "matches_signature",
    "parse_log_attachments",
    "parse_plot_spec",
]

# Logbook attachment-item schema: closed. An item
# carries exactly one of these keys: 'path' names a shipped picture, 'plot' a
# plot spec drawn at seed time against the entry's own timestamp.
_ATTACHMENT_KEYS = ("path", "plot")

# Plot-spec schema: closed. Every key but 'ylim' is required.
_PLOT_SPEC_KEYS = ("filename", "title", "ylabel", "hours_before", "series", "ylim")
_PLOT_SERIES_KEYS = ("label", "values")

# Picture formats a logbook attachment may name: suffix -> accepted file
# signatures as (byte offset, magic bytes).
IMAGE_SIGNATURES: dict[str, tuple[tuple[int, bytes], ...]] = {
    ".png": ((0, b"\x89PNG\r\n\x1a\n"),),
    ".jpg": ((0, b"\xff\xd8\xff"),),
    ".jpeg": ((0, b"\xff\xd8\xff"),),
    ".gif": ((0, b"GIF87a"), (0, b"GIF89a")),
    ".webp": ((8, b"WEBP"),),
}
SIGNATURE_BYTES = 16


[docs] @dataclass(frozen=True) class PlotSeries: """One named line of a :class:`PlotSpec`, one value per axis point.""" label: str values: tuple[float, ...]
[docs] @dataclass(frozen=True) class PlotSpec: """A time-series picture drawn when its entry is seeded, not shipped as a file. The time axis is relative: ``hours_before`` counts back from the instant the entry is written (``0.0``), so the drawn picture carries that entry's real dates whatever anchor the narrative resolves against. Every series has one value per point of that shared axis. Attributes: filename: Name the drawn picture is stored under (a ``.png`` file name). title: Figure title. ylabel: Y-axis label. hours_before: Shared time axis, non-increasing, ending at ``0.0``. series: The lines drawn, in legend order. ylim: Fixed y-axis range ``(low, high)``, or ``None`` to fit the data. """ filename: str title: str ylabel: str hours_before: tuple[float, ...] series: tuple[PlotSeries, ...] ylim: tuple[float, float] | None = None
[docs] @dataclass(frozen=True) class ScenarioLogEntry: """A logbook entry owned by a scenario. The one entry shape the ARIEL DB seed (via ``apply``) reads, whether the entry came from a scenario bundle's ``logbook.json`` or a facility scenario's ``logbook`` block, so the telemetry overlay and its narrative ship together. ``attachments`` are the pictures the entry carries, in the order its ``attachments`` list names them: a shipped picture as an absolute path inside the scenario directory (checked at load time to exist and to be an image), or a :class:`PlotSpec` the seeder draws against the entry's timestamp. """ entry_id: str when: RelativeTimestamp author: str title: str text: str tags: tuple[str, ...] categories: tuple[str, ...] loto_tag: str | None extra: dict[str, object] attachments: tuple[Path | PlotSpec, ...] = ()
[docs] def parse_log_attachments(prefix: str, raw: object, bundle: Path) -> tuple[Path | PlotSpec, ...]: """Resolve a logbook entry's ``attachments`` list to the pictures it carries. Each item holds exactly one key. ``{"path": "<relative path>"}`` names a shipped picture: it must name an existing file with an image suffix that starts with that image format's signature. ``{"plot": "<relative path>"}`` names a plot spec: a ``.json`` file holding a valid spec (see :func:`parse_plot_spec`). Either path is relative to the bundle directory and must stay inside it, and no two pictures of one entry may share a file name, so a misnamed, missing or malformed picture is a load error rather than a seed failure. """ if not isinstance(raw, list): raise ValueError(f"{prefix}: 'attachments' must be a list, got {raw!r}") root = bundle.resolve() pictures: list[Path | PlotSpec] = [] names: set[str] = set() for item in raw: if not isinstance(item, dict): raise ValueError(f"{prefix}: each attachment must be a mapping, got {item!r}") unknown = sorted(set(item) - set(_ATTACHMENT_KEYS)) if unknown: raise ValueError(f"{prefix}: attachment has unknown keys {unknown}") if len(item) != 1: raise ValueError( f"{prefix}: an attachment names exactly one of 'path' or 'plot', got {item!r}" ) (key, rel), *_ = item.items() path = _bundle_file(prefix, key, rel, root) picture = ( _shipped_picture(prefix, rel, path) if key == "path" else _plot_spec(prefix, rel, path) ) name = picture.name if isinstance(picture, Path) else picture.filename if name in names: raise ValueError(f"{prefix}: two attachments are both named {name!r}") names.add(name) pictures.append(picture) return tuple(pictures)
def _bundle_file(prefix: str, key: str, rel: object, root: Path) -> Path: """Resolve an attachment item's relative path, which must stay inside ``root``.""" if not isinstance(rel, str) or not rel: raise ValueError(f"{prefix}: attachment {key!r} must be a non-empty string, got {rel!r}") path = (root / rel).resolve() if Path(rel).is_absolute() or not path.is_relative_to(root): raise ValueError( f"{prefix}: attachment path {rel!r} must be relative to the scenario directory" ) return path def _shipped_picture(prefix: str, rel: str, path: Path) -> Path: """Check that ``path`` is an existing image file whose bytes match its suffix.""" signatures = IMAGE_SIGNATURES.get(path.suffix.lower()) if signatures is None: raise ValueError( f"{prefix}: attachment {rel!r} is not a picture " f"(accepted: {', '.join(sorted(IMAGE_SIGNATURES))})" ) if not path.is_file(): raise ValueError(f"{prefix}: attachment file {rel!r} not found at {path}") with path.open("rb") as handle: head = handle.read(SIGNATURE_BYTES) if not any(matches_signature(head, sig) for sig in signatures): raise ValueError( f"{prefix}: attachment {rel!r} does not hold {path.suffix.lower()} image data" ) return path def _plot_spec(prefix: str, rel: str, path: Path) -> PlotSpec: """Read and validate the plot spec at ``path``.""" if path.suffix.lower() != ".json": raise ValueError(f"{prefix}: plot spec {rel!r} must be a .json file") if not path.is_file(): raise ValueError(f"{prefix}: plot spec {rel!r} not found at {path}") try: raw: object = json.loads(path.read_text(encoding="utf-8")) except (json.JSONDecodeError, UnicodeDecodeError) as exc: raise ValueError(f"{prefix}: plot spec {rel!r} is not valid JSON: {exc}") from exc return parse_plot_spec(raw, f"{prefix}: plot spec {rel!r}")
[docs] def parse_plot_spec(raw: object, where: str = "plot spec") -> PlotSpec: """Validate a decoded plot spec and return it as a :class:`PlotSpec`. The schema is closed: ``filename`` (a ``.png`` file name, no directory), ``title``, ``ylabel``, ``hours_before`` (at least two finite numbers, non-negative, non-increasing, ending at ``0``), ``series`` (a non-empty list of ``{"label", "values"}`` with unique non-empty labels and one finite number per ``hours_before`` point) and optional ``ylim`` (``[low, high]`` with ``low < high``). Args: raw: The decoded JSON value. where: How error messages name the spec. Raises: ValueError: If the spec breaks any of those rules. """ if not isinstance(raw, dict): raise ValueError(f"{where}: must be a JSON object, got {type(raw).__name__}") unknown = sorted(set(raw) - set(_PLOT_SPEC_KEYS)) if unknown: raise ValueError(f"{where}: unknown keys {unknown}") missing = [key for key in _PLOT_SPEC_KEYS if key != "ylim" and key not in raw] if missing: raise ValueError(f"{where}: missing keys {missing}") filename = raw["filename"] if ( not isinstance(filename, str) or Path(filename).name != filename or Path(filename).suffix.lower() != ".png" or Path(filename).stem == "" ): raise ValueError(f"{where}: 'filename' must be a .png file name, got {filename!r}") for key in ("title", "ylabel"): if not isinstance(raw[key], str): raise ValueError(f"{where}: {key!r} must be a string, got {raw[key]!r}") hours = _finite_numbers(where, "'hours_before'", raw["hours_before"]) if len(hours) < 2: raise ValueError(f"{where}: 'hours_before' needs at least two points") if any(later > earlier for earlier, later in zip(hours, hours[1:], strict=False)): raise ValueError(f"{where}: 'hours_before' must be non-increasing") if hours[-1] != 0.0: raise ValueError(f"{where}: 'hours_before' must end at 0, got {hours[-1]!r}") series_raw = raw["series"] if not isinstance(series_raw, list) or not series_raw: raise ValueError(f"{where}: 'series' must be a non-empty list") series: list[PlotSeries] = [] for item in series_raw: if not isinstance(item, dict) or set(item) != set(_PLOT_SERIES_KEYS): raise ValueError( f"{where}: each series is a mapping with exactly 'label' and 'values', got {item!r}" ) label = item["label"] if not isinstance(label, str) or not label: raise ValueError(f"{where}: series 'label' must be a non-empty string, got {label!r}") if any(existing.label == label for existing in series): raise ValueError(f"{where}: two series are both labelled {label!r}") values = _finite_numbers(where, f"series {label!r} 'values'", item["values"]) if len(values) != len(hours): raise ValueError( f"{where}: series {label!r} has {len(values)} values for " f"{len(hours)} 'hours_before' points" ) series.append(PlotSeries(label=label, values=values)) ylim = None if "ylim" in raw: bounds = _finite_numbers(where, "'ylim'", raw["ylim"]) if len(bounds) != 2 or not bounds[0] < bounds[1]: raise ValueError(f"{where}: 'ylim' must be [low, high] with low < high") ylim = (bounds[0], bounds[1]) return PlotSpec( filename=filename, title=raw["title"], ylabel=raw["ylabel"], hours_before=hours, series=tuple(series), ylim=ylim, )
def _finite_numbers(where: str, key: str, raw: object) -> tuple[float, ...]: """``raw`` as a tuple of floats, refusing anything but a list of finite numbers.""" if not isinstance(raw, list) or not all( isinstance(v, int | float) and not isinstance(v, bool) and math.isfinite(v) for v in raw ): raise ValueError(f"{where}: {key} must be a list of finite numbers") return tuple(float(v) for v in raw)
[docs] def matches_signature(head: bytes, signature: tuple[int, bytes]) -> bool: """Whether ``head`` carries ``signature`` (an ``(offset, bytes)`` pair).""" offset, magic = signature return head[offset : offset + len(magic)] == magic