mosaickit 0.1.0__py3-none-any.whl

mosaickit/__init__.py

@@ -0,0 +1,103 @@
+"""Domain-neutral diagram construction and rendering."""
+
+from mosaickit.canvas import Animation, Canvas, CanvasGrid, Layout, Span
+from mosaickit.canvas_spec import CanvasSpec
+from mosaickit.colors import TRANSPARENT, Color
+from mosaickit.config import Config, use_config
+from mosaickit.errors import BindingError, ConfigurationError, MosaicKitError, RenderError
+from mosaickit.interval import Interval
+from mosaickit.parameter import Constant, Expression, Parameter, ParameterValues
+from mosaickit.rendering import (
+    CacheBypassWarning,
+    CacheKey,
+    RenderCache,
+    Renderer,
+    RendererRegistry,
+    SaveOptions,
+)
+from mosaickit.scene import (
+    ArrowLayer,
+    AxisSpec,
+    FillLayer,
+    GroupLayer,
+    Layer,
+    LegendLayer,
+    MarkerLayer,
+    PathLayer,
+    Scene,
+    TextLayer,
+    box_frame,
+    build_axes,
+    crosshair_axes,
+    quadrant_axes,
+)
+from mosaickit.styles import (
+    ArrowPlacement,
+    ArrowStyle,
+    DashStyle,
+    Fill,
+    LegendStyle,
+    Marker,
+    SparseStyle,
+    Stroke,
+    TextStyle,
+)
+from mosaickit.themes import RolePack, StyleBundle, Theme, ThemeRegistry, expand_roles
+
+__version__ = "0.1.0"
+__all__ = [
+    "Animation",
+    "ArrowLayer",
+    "ArrowPlacement",
+    "ArrowStyle",
+    "AxisSpec",
+    "BindingError",
+    "CacheBypassWarning",
+    "CacheKey",
+    "Canvas",
+    "CanvasGrid",
+    "CanvasSpec",
+    "Color",
+    "Config",
+    "ConfigurationError",
+    "Constant",
+    "DashStyle",
+    "MosaicKitError",
+    "Expression",
+    "Fill",
+    "FillLayer",
+    "GroupLayer",
+    "Interval",
+    "Layer",
+    "Layout",
+    "LegendLayer",
+    "LegendStyle",
+    "Marker",
+    "MarkerLayer",
+    "Parameter",
+    "ParameterValues",
+    "PathLayer",
+    "RenderCache",
+    "RenderError",
+    "Renderer",
+    "RendererRegistry",
+    "RolePack",
+    "SaveOptions",
+    "Scene",
+    "Span",
+    "SparseStyle",
+    "Stroke",
+    "StyleBundle",
+    "TRANSPARENT",
+    "TextLayer",
+    "TextStyle",
+    "Theme",
+    "ThemeRegistry",
+    "__version__",
+    "box_frame",
+    "build_axes",
+    "crosshair_axes",
+    "expand_roles",
+    "quadrant_axes",
+    "use_config",
+]

mosaickit/canvas/__init__.py

@@ -0,0 +1,7 @@
+from mosaickit.canvas.animation import Animation
+from mosaickit.canvas.canvas import Canvas
+from mosaickit.canvas.grid import CanvasGrid
+from mosaickit.canvas.layout import Layout
+from mosaickit.canvas.span import Span
+
+__all__ = ["Animation", "Canvas", "CanvasGrid", "Layout", "Span"]

mosaickit/canvas/animation.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mosaickit.canvas.canvas import Canvas
+from mosaickit.errors import ConfigurationError, RenderError
+from mosaickit.parameter import Parameter, ParameterValues
+from mosaickit.rendering import RenderCache, Renderer
+from mosaickit.scene import Scene
+
+
+@dataclass(frozen=True, slots=True)
+class Animation:
+    template: Canvas
+    parameter: Parameter
+    values: tuple[Any, ...]
+    fps: int = 30
+
+    def __post_init__(self) -> None:
+        if isinstance(self.fps, bool) or not isinstance(self.fps, int) or self.fps < 1:
+            raise ConfigurationError("Animation.fps must be a positive integer")
+        values = ParameterValues(self.parameter, self.values).values
+        if not values:
+            raise ConfigurationError("Animation requires at least one value")
+        object.__setattr__(self, "values", values)
+        object.__setattr__(self, "template", self.template.copy())
+
+    @staticmethod
+    def sweep(canvas: Canvas, values: ParameterValues, *, fps: int = 30) -> Animation:
+        return Animation(canvas, values.parameter, values.values, fps)
+
+    def frames(self) -> Iterator[Scene]:
+        for value in self.values:
+            yield self.template.bind(self.parameter, value).snapshot()
+
+    def save(
+        self,
+        path: str | Path,
+        *,
+        renderer: Renderer | str | None = None,
+        cache: RenderCache | None = None,
+    ) -> list[Path]:
+        selected = self.template._renderer(renderer)
+        if not hasattr(selected, "save_animation"):
+            raise RenderError(f"Renderer {selected.name!r} does not support animation output")
+        return selected.save_animation(
+            self, Path(path), cache if cache is not None else RenderCache()
+        )

mosaickit/canvas/canvas.py

@@ -0,0 +1,110 @@
+"""Fluent scene construction with isolated render snapshots."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+from mosaickit.canvas_spec import CanvasSpec
+from mosaickit.config import Config, current_config
+from mosaickit.errors import RenderError
+from mosaickit.parameter import Parameter, bind
+from mosaickit.rendering import RenderCache, Renderer, RendererRegistry, SaveOptions
+from mosaickit.rendering.context import _RenderContext
+from mosaickit.scene import Layer, Scene
+from mosaickit.themes import StyleBundle, Theme
+
+
+class Canvas:
+    def __init__(
+        self,
+        spec: CanvasSpec | None = None,
+        theme: Theme | None = None,
+        config: Config | None = None,
+        renderer: Renderer | str | None = None,
+        *,
+        role_overrides: Mapping[str, StyleBundle] | None = None,
+    ) -> None:
+        self.config = config if config is not None else current_config()
+        self.spec = spec if spec is not None else self.config.canvas_spec
+        self.theme = theme if theme is not None else self.config.theme
+        self.renderer = renderer if renderer is not None else self.config.renderer
+        self.role_overrides = MappingProxyType(dict(role_overrides or {}))
+        self._scene = Scene.empty()
+        self._bindings: tuple = ()
+
+    def add(self, layer: Layer) -> Canvas:
+        self._scene = self._scene.add(layer)
+        return self
+
+    def extend(self, layers: Iterable[Layer]) -> Canvas:
+        self._scene = self._scene.extend(layers)
+        return self
+
+    def remove(self, layer_id: str) -> Canvas:
+        self._scene = self._scene.remove(layer_id)
+        return self
+
+    def clear(self) -> Canvas:
+        self._scene = self._scene.clear()
+        return self
+
+    def snapshot(self) -> Scene:
+        return self._scene
+
+    def copy(self) -> Canvas:
+        canvas = Canvas(
+            self.spec, self.theme, self.config, self.renderer, role_overrides=self.role_overrides
+        )
+        canvas._scene = self._scene
+        canvas._bindings = self._bindings
+        return canvas
+
+    def bind(self, parameter: Parameter | Mapping[Parameter, Any], value: Any = None) -> Canvas:
+        bindings = dict(parameter) if isinstance(parameter, Mapping) else {parameter: value}
+        for item, bound in bindings.items():
+            item.evaluate({item: bound})
+        canvas = self.copy()
+        canvas._scene = bind(self._scene, bindings)
+        canvas._bindings = (*self._bindings, *bindings.items())
+        return canvas
+
+    def _context(self, cache: RenderCache | None = None) -> _RenderContext:
+        return _RenderContext(
+            self.spec,
+            self.theme,
+            self.config.role_overrides,
+            self.role_overrides,
+            cache if cache is not None else RenderCache(),
+            self._bindings,
+        )
+
+    def _renderer(self, renderer: Renderer | str | None = None) -> Renderer:
+        selected = self.renderer if renderer is None else renderer
+        return RendererRegistry().get(selected) if isinstance(selected, str) else selected
+
+    def render(
+        self, *, renderer: Renderer | str | None = None, cache: RenderCache | None = None
+    ) -> Any:
+        return self._renderer(renderer).render(self.snapshot(), self._context(cache))
+
+    def save(
+        self,
+        target: str | Path,
+        *,
+        renderer: Renderer | str | None = None,
+        cache: RenderCache | None = None,
+        **options: Any,
+    ) -> list[Path]:
+        target = Path(target)
+        if target.suffix.lower() not in {".png", ".pdf", ".svg"}:
+            raise RenderError(f"Unsupported output format: {target.suffix!r}")
+        selected = self._renderer(renderer)
+        result = selected.render(self.snapshot(), self._context(cache))
+        try:
+            return selected.save(result, target, SaveOptions(**options))
+        finally:
+            if hasattr(result, "close"):
+                result.close()

mosaickit/canvas/grid.py

@@ -0,0 +1,186 @@
+"""Validated grid placement with real row and column spans."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mosaickit.canvas.canvas import Canvas
+from mosaickit.canvas.layout import Layout
+from mosaickit.canvas.span import Span
+from mosaickit.errors import ConfigurationError, RenderError
+from mosaickit.parameter import ParameterValues
+from mosaickit.rendering import RenderCache, Renderer, RendererRegistry, SaveOptions
+
+
+@dataclass(frozen=True, slots=True)
+class _Placement:
+    canvas: Canvas
+    row: int
+    col: int
+    rows: int
+    cols: int
+
+
+class CanvasGrid:
+    def __init__(
+        self,
+        cells: Any,
+        rows: int | None = None,
+        cols: int | None = None,
+        shape: tuple[int, int] | None = None,
+    ) -> None:
+        if shape is not None:
+            if rows is not None or cols is not None or len(shape) != 2:
+                raise ConfigurationError("Use shape=(rows, cols) or rows/cols, not both")
+            rows, cols = shape
+        for name, value in (("rows", rows), ("cols", cols)):
+            if value is not None and (
+                isinstance(value, bool) or not isinstance(value, int) or value < 1
+            ):
+                raise ConfigurationError(f"CanvasGrid.{name} must be a positive integer")
+        cells = list(cells)
+        if not cells:
+            raise ConfigurationError("CanvasGrid requires at least one cell")
+        nested = isinstance(cells[0], (list, tuple))
+        if nested:
+            if not all(isinstance(row, (list, tuple)) for row in cells):
+                raise ConfigurationError("CanvasGrid cannot mix rows and flat cells")
+            matrix = [list(row) for row in cells]
+            rows = rows if rows is not None else len(matrix)
+            if len(matrix) > rows:
+                raise ConfigurationError(f"Grid has {len(matrix)} rows; expected at most {rows}")
+            cols = (
+                cols
+                if cols is not None
+                else max(
+                    sum(cell.cols if isinstance(cell, Span) else 1 for cell in row)
+                    for row in matrix
+                )
+            )
+        else:
+            if any(isinstance(cell, Span) and cell.rows != 1 for cell in cells):
+                raise ConfigurationError("Row spans require nested grid rows")
+            count = sum(cell.cols if isinstance(cell, Span) else 1 for cell in cells)
+            cols = (
+                cols
+                if cols is not None
+                else (math.ceil(count / rows) if rows else math.ceil(math.sqrt(count)))
+            )
+            rows = rows if rows is not None else math.ceil(count / cols)
+            if count > rows * cols:
+                raise ConfigurationError(
+                    f"Grid has {count} cells; shape ({rows}, {cols}) is too small"
+                )
+            matrix = [[]]
+            width = 0
+            for cell in cells:
+                span_width = cell.cols if isinstance(cell, Span) else 1
+                if width + span_width > cols:
+                    matrix.append([])
+                    width = 0
+                matrix[-1].append(cell)
+                width += span_width
+        if not cols:
+            raise ConfigurationError("CanvasGrid rows cannot all be empty")
+        occupied: set[tuple[int, int]] = set()
+        placements = []
+        for row_index, row in enumerate(matrix):
+            cursor = 0
+            for cell_index, cell in enumerate(row):
+                while (row_index, cursor) in occupied:
+                    cursor += 1
+                span = cell if isinstance(cell, Span) else Span(cell) if cell is not None else None
+                height, width = (span.rows, span.cols) if span else (1, 1)
+                if cursor + width > cols or row_index + height > rows:
+                    raise ConfigurationError(
+                        f"Grid row {row_index}, cell {cell_index}: span "
+                        f"({height}, {width}) exceeds shape ({rows}, {cols})"
+                    )
+                region = {
+                    (r, c)
+                    for r in range(row_index, row_index + height)
+                    for c in range(cursor, cursor + width)
+                }
+                if region & occupied:
+                    raise ConfigurationError(
+                        f"Grid row {row_index}, cell {cell_index}: overlapping span"
+                    )
+                occupied.update(region)
+                if span:
+                    placements.append(
+                        _Placement(span.canvas.copy(), row_index, cursor, height, width)
+                    )
+                cursor += width
+        if nested:
+            for row_index in range(rows):
+                missing = [col for col in range(cols) if (row_index, col) not in occupied]
+                if missing:
+                    raise ConfigurationError(
+                        f"Grid row {row_index}: missing columns {missing}; use None for empty cells"
+                    )
+        self.rows, self.cols = rows, cols
+        self.placements = tuple(placements)
+
+    @classmethod
+    def sweep(
+        cls, template: Canvas, values: ParameterValues, *, cols: int | None = None
+    ) -> CanvasGrid:
+        return cls([template.bind(values.parameter, value) for value in values.values], cols=cols)
+
+    @classmethod
+    def from_layout(cls, canvases: list[Canvas], layout: Layout) -> CanvasGrid:
+        if layout == Layout.TOP_TWO_BOTTOM_ONE:
+            if len(canvases) != 3:
+                raise ConfigurationError("TOP_TWO_BOTTOM_ONE requires 3 canvases")
+            return cls([[canvases[0], canvases[1]], [Span(canvases[2], cols=2)]])
+        if layout == Layout.TOP_ONE_BOTTOM_TWO:
+            if len(canvases) != 3:
+                raise ConfigurationError("TOP_ONE_BOTTOM_TWO requires 3 canvases")
+            return cls([[Span(canvases[0], cols=2)], [canvases[1], canvases[2]]])
+        shapes = {
+            Layout.SINGLE: (1, 1),
+            Layout.STACKED: (2, 1),
+            Layout.SIDE_BY_SIDE: (1, 2),
+            Layout.GRID_2X2: (2, 2),
+            Layout.GRID_3X3: (3, 3),
+        }
+        return cls(canvases, shape=shapes[layout])
+
+    def _renderer(self, renderer: Renderer | str | None) -> Renderer:
+        if renderer is None:
+            return (
+                self.placements[0].canvas._renderer()
+                if self.placements
+                else RendererRegistry().get("matplotlib")
+            )
+        return RendererRegistry().get(renderer) if isinstance(renderer, str) else renderer
+
+    def render(
+        self, *, renderer: Renderer | str | None = None, cache: RenderCache | None = None
+    ) -> Any:
+        selected = self._renderer(renderer)
+        if not hasattr(selected, "render_grid"):
+            raise RenderError(f"Renderer {selected.name!r} does not support grids")
+        return selected.render_grid(self, cache if cache is not None else RenderCache())
+
+    def save(
+        self,
+        target: str | Path,
+        *,
+        renderer: Renderer | str | None = None,
+        cache: RenderCache | None = None,
+        **options: Any,
+    ) -> list[Path]:
+        target = Path(target)
+        if target.suffix.lower() not in {".png", ".pdf", ".svg"}:
+            raise RenderError(f"Unsupported output format: {target.suffix!r}")
+        selected = self._renderer(renderer)
+        result = self.render(renderer=selected, cache=cache)
+        try:
+            return selected.save(result, target, SaveOptions(**options))
+        finally:
+            if hasattr(result, "close"):
+                result.close()

mosaickit/canvas/layout.py

@@ -0,0 +1,11 @@
+from enum import Enum
+
+
+class Layout(str, Enum):
+    SINGLE = "single"
+    STACKED = "stacked"
+    SIDE_BY_SIDE = "side_by_side"
+    GRID_2X2 = "grid_2x2"
+    GRID_3X3 = "grid_3x3"
+    TOP_TWO_BOTTOM_ONE = "top_two_bottom_one"
+    TOP_ONE_BOTTOM_TWO = "top_one_bottom_two"

mosaickit/canvas/span.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+
+from mosaickit.canvas.canvas import Canvas
+from mosaickit.errors import ConfigurationError
+
+
+@dataclass(frozen=True, slots=True)
+class Span:
+    canvas: Canvas
+    rows: int = 1
+    cols: int = 1
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.canvas, Canvas):
+            raise ConfigurationError("Span.canvas must be a Canvas")
+        for name in ("rows", "cols"):
+            value = getattr(self, name)
+            if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+                raise ConfigurationError(f"Span.{name} must be a positive integer")

mosaickit/canvas_spec.py

@@ -0,0 +1,56 @@
+"""Physical and coordinate dimensions of a diagram."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, replace
+from typing import Any
+
+from mosaickit.errors import ConfigurationError
+from mosaickit.interval import Interval
+
+
+@dataclass(frozen=True, slots=True)
+class CanvasSpec:
+    x_range: tuple[float, float] = (0.0, 10.0)
+    y_range: tuple[float, float] = (0.0, 10.0)
+    width: float = 6.0
+    height: float = 6.0
+    dpi: int = 300
+    x_label: str = "X"
+    y_label: str = "Y"
+    title: str | None = None
+
+    def __post_init__(self) -> None:
+        for name in ("x_range", "y_range"):
+            value = getattr(self, name)
+            try:
+                interval = Interval(*value)
+            except (TypeError, ValueError) as exc:
+                raise ConfigurationError(f"CanvasSpec.{name}: {exc}") from exc
+            object.__setattr__(self, name, (interval.lo, interval.hi))
+        for name in ("width", "height"):
+            value = getattr(self, name)
+            if not math.isfinite(value) or value <= 0:
+                raise ConfigurationError(f"CanvasSpec.{name} must be positive and finite")
+        if isinstance(self.dpi, bool) or not isinstance(self.dpi, int) or not 1 <= self.dpi <= 1200:
+            raise ConfigurationError("CanvasSpec.dpi must be an integer in [1, 1200]")
+
+    @property
+    def x_min(self) -> float:
+        return self.x_range[0]
+
+    @property
+    def x_max(self) -> float:
+        return self.x_range[1]
+
+    @property
+    def y_min(self) -> float:
+        return self.y_range[0]
+
+    @property
+    def y_max(self) -> float:
+        return self.y_range[1]
+
+    def replace(self, **changes: Any) -> CanvasSpec:
+        return replace(self, **changes)

mosaickit/colors.py

@@ -0,0 +1,51 @@
+"""Immutable, backend-independent RGBA colors."""
+
+from __future__ import annotations
+
+import math
+import string
+from dataclasses import dataclass
+
+from mosaickit.errors import ConfigurationError
+
+
+@dataclass(frozen=True, slots=True)
+class Color:
+    red: float
+    green: float
+    blue: float
+    alpha: float = 1.0
+
+    def __post_init__(self) -> None:
+        if not all(math.isfinite(v) and 0 <= v <= 1 for v in self.channels):
+            raise ConfigurationError("Color channels must be finite and in [0, 1]")
+
+    @property
+    def channels(self) -> tuple[float, float, float, float]:
+        return self.red, self.green, self.blue, self.alpha
+
+    @classmethod
+    def from_channels(cls, red: float, green: float, blue: float, alpha: float = 1) -> Color:
+        return cls(red, green, blue, alpha)
+
+    @classmethod
+    def from_hex(cls, value: str) -> Color:
+        if not isinstance(value, str) or not value.startswith("#"):
+            raise ConfigurationError("Color must be #RGB, #RRGGBB, or #RRGGBBAA")
+        digits = value[1:]
+        if len(digits) == 3:
+            digits = "".join(c * 2 for c in digits)
+        if len(digits) not in (6, 8) or any(char not in string.hexdigits for char in digits):
+            raise ConfigurationError(f"Invalid hex color: {value!r}")
+        try:
+            channels = [int(digits[i : i + 2], 16) / 255 for i in range(0, len(digits), 2)]
+        except ValueError as exc:
+            raise ConfigurationError(f"Invalid hex color: {value!r}") from exc
+        return cls(*channels)
+
+    def to_hex(self, *, include_alpha: bool | None = None) -> str:
+        alpha = self.alpha != 1 if include_alpha is None else include_alpha
+        return "#" + "".join(f"{round(v * 255):02X}" for v in self.channels[: 4 if alpha else 3])
+
+
+TRANSPARENT = Color(0, 0, 0, 0)