meowplotlib 0.1.0__py3-none-any.whl

meowplotlib/__init__.py

@@ -0,0 +1,9 @@
+"""meowplotlib: whimsical cat decorations for matplotlib figures."""
+
+from meowplotlib.api import config, disable, enable, set_density, set_seed, set_style
+from meowplotlib.render.hook import install as _install
+
+__all__ = ["config", "disable", "enable", "set_density", "set_seed", "set_style"]
+__version__ = "0.1.0"
+
+_install()

meowplotlib/api.py

@@ -0,0 +1,74 @@
+"""User-facing public API: enable/disable/set_style/set_density/set_seed/config."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from meowplotlib.assets.registry import resolve_style_names
+from meowplotlib.core.config import get_config
+
+
+def enable() -> None:
+    """Re-enable cat decoration for the current session."""
+    get_config().enabled = True
+
+
+def disable() -> None:
+    """Disable cat decoration for the current session."""
+    get_config().enabled = False
+
+
+_VALID_DENSITIES = ("sparse", "normal", "chaotic")
+
+
+def _validate_style(style: object) -> None:
+    if not isinstance(style, str | list):
+        raise TypeError(f"style must be a str or list[str], got {type(style).__name__}")
+    resolve_style_names(style)  # fail-fast; "mix" always validates, resolved fresh at render time
+
+
+def _validate_density(density: object) -> None:
+    if density not in _VALID_DENSITIES:
+        raise ValueError(f"Unknown density: {density!r}. Valid options: {_VALID_DENSITIES}")
+
+
+def set_style(style: str | list[str]) -> None:
+    """Select a single style, a mix of styles, or "mix" for all styles.
+
+    Validates eagerly: an unregistered style name raises immediately, rather than
+    surfacing as a silent absence of cats at the next render.
+    """
+    _validate_style(style)
+    get_config().style = style
+
+
+def set_density(density: str) -> None:
+    """Set cat density: "sparse", "normal", or "chaotic"."""
+    _validate_density(density)
+    get_config().density = density
+
+
+def set_seed(seed: int | None) -> None:
+    """Set the RNG seed for reproducible placements, or None for randomized."""
+    get_config().seed = seed
+
+
+@contextmanager
+def config(**overrides: object) -> Iterator[None]:
+    """Temporarily override config values within a `with` block.
+
+    Applies the same validation as `set_style`/`set_density` to any overridden values.
+    """
+    if "style" in overrides:
+        _validate_style(overrides["style"])
+    if "density" in overrides:
+        _validate_density(overrides["density"])
+
+    cfg = get_config()
+    saved = cfg.snapshot()
+    try:
+        cfg.update(**overrides)
+        yield
+    finally:
+        cfg.restore(saved)

meowplotlib/assets/_toml_fallback.py

@@ -0,0 +1,46 @@
+"""Minimal parser for styles.toml on Python < 3.11 (no stdlib tomllib).
+
+NOT a general-purpose TOML parser. Covers exactly the subset styles.toml uses: flat
+`[styles.<name>]` sections, each with a quoted `display_name` string and an optional numeric
+`scale`. See specs/003-style-system/research.md for why this exists instead of a dependency.
+"""
+
+from __future__ import annotations
+
+import re
+
+_SECTION_RE = re.compile(r"^\[styles\.([A-Za-z0-9_-]+)\]\s*$")
+_STRING_KV_RE = re.compile(r'^display_name\s*=\s*"([^"]*)"\s*$')
+_FLOAT_KV_RE = re.compile(r"^scale\s*=\s*([0-9.]+)\s*$")
+
+
+def loads(text: str) -> dict[str, object]:
+    """Parse styles.toml's specific shape into {"styles": {name: {...}}}."""
+    styles: dict[str, dict[str, object]] = {}
+    current: str | None = None
+
+    for raw_line in text.splitlines():
+        line = raw_line.split("#", 1)[0].strip()
+        if not line:
+            continue
+
+        section_match = _SECTION_RE.match(line)
+        if section_match:
+            current = section_match.group(1)
+            styles[current] = {}
+            continue
+
+        if current is None:
+            continue
+
+        string_match = _STRING_KV_RE.match(line)
+        if string_match:
+            styles[current]["display_name"] = string_match.group(1)
+            continue
+
+        float_match = _FLOAT_KV_RE.match(line)
+        if float_match:
+            styles[current]["scale"] = float(float_match.group(1))
+            continue
+
+    return {"styles": styles}

meowplotlib/assets/registry.py

@@ -0,0 +1,103 @@
+"""Discovers styles from the assets dir + manifest. Zero-code-change style extension.
+
+Re-scans the filesystem on every query rather than caching (see research.md) — style counts are
+tiny, and this keeps "drop a file, it just works" true even mid-process.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    from meowplotlib.assets import _toml_fallback as tomllib  # type: ignore[no-redef]
+
+IMAGE_SUFFIXES = (".png",)
+
+
+@dataclass(frozen=True)
+class StyleInfo:
+    """A discovered, valid style: has both an image directory and a manifest entry."""
+
+    name: str
+    display_name: str
+    scale: float = 1.0
+    image_paths: list[Path] = field(default_factory=list)
+
+
+def _parse_manifest(manifest_path: Path) -> dict[str, dict[str, object]]:
+    if not manifest_path.is_file():
+        return {}
+    if sys.version_info >= (3, 11):
+        with manifest_path.open("rb") as f:
+            data = tomllib.load(f)
+    else:
+        data = tomllib.loads(manifest_path.read_text(encoding="utf-8"))
+    styles = data.get("styles", {})
+    return styles if isinstance(styles, dict) else {}
+
+
+def discover_styles(images_dir: Path, manifest_path: Path) -> dict[str, StyleInfo]:
+    """Scan `images_dir` + parse `manifest_path`; return styles with both present."""
+    manifest_styles = _parse_manifest(manifest_path)
+    result: dict[str, StyleInfo] = {}
+
+    if not images_dir.is_dir():
+        return result
+
+    for style_dir in sorted(images_dir.iterdir()):
+        if not style_dir.is_dir():
+            continue
+        name = style_dir.name
+        manifest_entry = manifest_styles.get(name)
+        if not isinstance(manifest_entry, dict):
+            continue
+
+        image_paths = sorted(p for p in style_dir.iterdir() if p.suffix.lower() in IMAGE_SUFFIXES)
+        if not image_paths:
+            continue
+
+        display_name = manifest_entry.get("display_name")
+        if not isinstance(display_name, str):
+            continue
+        scale = manifest_entry.get("scale", 1.0)
+        if not isinstance(scale, int | float):
+            scale = 1.0
+
+        result[name] = StyleInfo(
+            name=name,
+            display_name=display_name,
+            scale=float(scale),
+            image_paths=image_paths,
+        )
+
+    return result
+
+
+def available_styles() -> dict[str, StyleInfo]:
+    """Discover styles from the package's own bundled assets tree."""
+    images_root = importlib.resources.files("meowplotlib.assets") / "images"
+    manifest = importlib.resources.files("meowplotlib.assets") / "styles.toml"
+    with (
+        importlib.resources.as_file(images_root) as images_dir,
+        importlib.resources.as_file(manifest) as manifest_path,
+    ):
+        return discover_styles(images_dir, manifest_path)
+
+
+def resolve_style_names(selection: str | list[str]) -> list[str]:
+    """Resolve set_style()'s raw value to a flat, validated list of style names."""
+    styles = available_styles()
+
+    if selection == "mix":
+        return list(styles)
+
+    names = [selection] if isinstance(selection, str) else selection
+    for name in names:
+        if name not in styles:
+            raise ValueError(f"Unknown style: {name!r}. Available styles: {sorted(styles)}")
+    return list(names)

meowplotlib/assets/styles.toml

@@ -0,0 +1,14 @@
+# Style manifest. Adding a style = a new [styles.<name>] section + a directory
+# of PNGs under assets/images/<name>/. No code changes required.
+
+[styles.classic]
+display_name = "Classic"
+scale = 1.0
+
+[styles.derp]
+display_name = "Derp"
+scale = 1.0
+
+[styles.chonk]
+display_name = "Chonk"
+scale = 1.15

meowplotlib/core/config.py

@@ -0,0 +1,36 @@
+"""Module-level config dataclass. No matplotlib imports, no I/O."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+
+
+@dataclass
+class Config:
+    """Global meowplotlib configuration, mutated by api.py and read by render/hook.py."""
+
+    enabled: bool = True
+    style: str | list[str] = "mix"
+    density: str = "normal"
+    seed: int | None = None
+
+    def snapshot(self) -> dict[str, object]:
+        return {f.name: getattr(self, f.name) for f in fields(self)}
+
+    def restore(self, snapshot: dict[str, object]) -> None:
+        for name, value in snapshot.items():
+            setattr(self, name, value)
+
+    def update(self, **overrides: object) -> None:
+        valid = {f.name for f in fields(self)}
+        for name, value in overrides.items():
+            if name not in valid:
+                raise TypeError(f"Unknown config option: {name}")
+            setattr(self, name, value)
+
+
+_CONFIG = Config()
+
+
+def get_config() -> Config:
+    return _CONFIG

meowplotlib/core/placement.py

@@ -0,0 +1,183 @@
+"""Placement geometry: figure dims + exclusion bboxes -> cat placements.
+
+Pure logic — no matplotlib imports, no I/O (constitution #1).
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Literal
+
+from meowplotlib.core.rng import new_rng
+
+Density = Literal["sparse", "normal", "chaotic"]
+
+# Per-tier area divisor: target count = available_border_area / divisor. Chosen so a reference
+# canvas (unit square, ~70% centered exclusion, default size_range) yields roughly 6/12/24 cats
+# for sparse/normal/chaotic respectively — strictly increasing on any fixed canvas. (Halved from
+# the original 3/6/12 tuning per user request for a denser default look, 2026-07-02.)
+_DENSITY_DIVISORS: dict[Density, float] = {
+    "sparse": 0.0655,
+    "normal": 0.0328,
+    "chaotic": 0.0164,
+}
+
+# Fixed edge margin as a fraction of the smaller canvas dimension.
+_EDGE_MARGIN_FRACTION = 0.03
+
+_MAX_ATTEMPTS_PER_CANDIDATE = 30
+_SHRINK_FACTOR = 0.85
+
+# Defensive upper bound on target count regardless of canvas size, so a pathologically large
+# canvas can't make placement (O(n^2) collision checks against prior placements) unbounded.
+_MAX_TARGET_COUNT = 200
+
+
+@dataclass(frozen=True)
+class Rect:
+    """Axis-aligned bounding rectangle in figure-fraction coordinates."""
+
+    x: float
+    y: float
+    width: float
+    height: float
+
+    def intersects(self, other: Rect) -> bool:
+        return (
+            self.x < other.x + other.width
+            and other.x < self.x + self.width
+            and self.y < other.y + other.height
+            and other.y < self.y + self.height
+        )
+
+
+@dataclass(frozen=True)
+class PlacementConfig:
+    """Input configuration for one `place_cats(...)` call."""
+
+    density: Density
+    size_range: tuple[float, float]
+    seed: int | None
+    styles: list[str]
+
+
+@dataclass(frozen=True)
+class Placement:
+    """One engine output entry."""
+
+    x: float
+    y: float
+    size: float
+    rotation: float
+    style: str
+
+    def bbox(self) -> Rect:
+        """Axis-aligned bounding box of this cat's square footprint AFTER rotation.
+
+        Reserves the true rotated extent (side * (|cos theta| + |sin theta|), up to ~1.41x at
+        45 degrees) rather than the unrotated square, so a rendered, actually-rotated image
+        never exceeds the space collision-checked against exclusions and other placements. See
+        specs/001-core-placement-engine/research.md's 2026-07-02 addendum.
+        """
+        theta = math.radians(self.rotation)
+        side = self.size * (abs(math.cos(theta)) + abs(math.sin(theta)))
+        half = side / 2
+        return Rect(x=self.x - half, y=self.y - half, width=side, height=side)
+
+
+def _margin_rects(canvas_width: float, canvas_height: float, margin: float) -> list[Rect]:
+    """Four thin rectangles covering the edge-margin band, so it composes with exclusions."""
+    return [
+        Rect(x=0, y=0, width=canvas_width, height=margin),  # bottom
+        Rect(x=0, y=canvas_height - margin, width=canvas_width, height=margin),  # top
+        Rect(x=0, y=0, width=margin, height=canvas_height),  # left
+        Rect(x=canvas_width - margin, y=0, width=margin, height=canvas_height),  # right
+    ]
+
+
+def _available_border_area(
+    canvas_width: float, canvas_height: float, exclusions: list[Rect], margin: float
+) -> float:
+    """Coarse Monte Carlo estimate of canvas area outside exclusions and the edge margin."""
+    inner = Rect(
+        x=margin,
+        y=margin,
+        width=max(0.0, canvas_width - 2 * margin),
+        height=max(0.0, canvas_height - 2 * margin),
+    )
+    if inner.width <= 0 or inner.height <= 0:
+        return 0.0
+    total = inner.width * inner.height
+    excluded = 0.0
+    for rect in exclusions:
+        overlap_w = min(inner.x + inner.width, rect.x + rect.width) - max(inner.x, rect.x)
+        overlap_h = min(inner.y + inner.height, rect.y + rect.height) - max(inner.y, rect.y)
+        if overlap_w > 0 and overlap_h > 0:
+            excluded += overlap_w * overlap_h
+    return max(0.0, total - excluded)
+
+
+def _target_count(available_area: float, density: Density) -> int:
+    if available_area <= 0:
+        return 0
+    return min(_MAX_TARGET_COUNT, int(available_area / _DENSITY_DIVISORS[density]))
+
+
+def place_cats(
+    canvas_width: float,
+    canvas_height: float,
+    exclusions: list[Rect],
+    config: PlacementConfig,
+) -> list[Placement]:
+    """Return non-overlapping cat placements confined to the canvas border region.
+
+    See specs/001-core-placement-engine/contracts/placement-api.md for the full contract.
+    """
+    if canvas_width <= 0 or canvas_height <= 0 or not config.styles:
+        return []
+
+    margin = _EDGE_MARGIN_FRACTION * min(canvas_width, canvas_height)
+    blocked = list(exclusions) + _margin_rects(canvas_width, canvas_height, margin)
+    available_area = _available_border_area(canvas_width, canvas_height, exclusions, margin)
+    target = _target_count(available_area, config.density)
+    if target <= 0:
+        return []
+
+    rng = new_rng(config.seed)
+    min_size, max_size = config.size_range
+    placements: list[Placement] = []
+
+    for _ in range(target):
+        size = max_size
+        placed = False
+        while not placed:
+            for _ in range(_MAX_ATTEMPTS_PER_CANDIDATE):
+                rotation = rng.uniform(0, 360)
+                theta = math.radians(rotation)
+                rotated_side = size * (abs(math.cos(theta)) + abs(math.sin(theta)))
+                half = rotated_side / 2
+                x = rng.uniform(half, canvas_width - half)
+                y = rng.uniform(half, canvas_height - half)
+                candidate = Placement(
+                    x=x,
+                    y=y,
+                    size=size,
+                    rotation=rotation,
+                    style=rng.choice(config.styles),
+                )
+                bbox = candidate.bbox()
+                if any(bbox.intersects(r) for r in blocked):
+                    continue
+                if any(bbox.intersects(p.bbox()) for p in placements):
+                    continue
+                placements.append(candidate)
+                placed = True
+                break
+            if placed:
+                break
+            size *= _SHRINK_FACTOR
+            if size < min_size:
+                break
+
+    return placements

meowplotlib/core/rng.py

@@ -0,0 +1,10 @@
+"""Seeded RNG wrapper for reproducible placements. No matplotlib imports, no I/O."""
+
+from __future__ import annotations
+
+import random
+
+
+def new_rng(seed: int | None) -> random.Random:
+    """Return a fresh `random.Random` instance seeded from `seed`, or unseeded if `None`."""
+    return random.Random(seed)

meowplotlib/render/artist.py

@@ -0,0 +1,88 @@
+"""Draws placed cats onto the figure.
+
+Each cat is drawn in its own tiny inset Axes positioned at the placement's exact figure-fraction
+bounding box (`Placement.bbox()`), rather than via OffsetImage/AnnotationBbox's point-space
+`zoom`. This makes the actual rendered footprint match the bbox M1's collision math assumed
+exactly, instead of approximating it through a DPI-dependent zoom factor. Cat axes are tagged
+with `_meowplotlib_cat = True` so `render/bboxes.py` can exclude them from exclusion extraction.
+
+Since M1's `Placement.bbox()` reserves the true rotated footprint (see
+specs/001-core-placement-engine/research.md's 2026-07-02 addendum), the cat axes here is always
+exactly that (larger, square) bbox; the image itself is drawn at its true unrotated size,
+centered, and rotated in data-space via an affine transform. Because the reserved bbox is by
+construction the axis-aligned bounding box of a `placement.size`-side square rotated by
+`placement.rotation`, the rotated image's true footprint always stays within the axes — no
+overflow into neighboring exclusions or other cats regardless of the sampled rotation angle.
+
+Style resolution goes through `assets.registry` (M3): `placement.style` selects a style, and a
+deterministic (not RNG-based) hash of the placement's own fields picks one image from that
+style's pool, so seeded reproducibility survives multi-image pools — see
+specs/003-style-system/research.md.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+from typing import TYPE_CHECKING
+
+import matplotlib.image as mpimg
+import matplotlib.transforms as mtransforms
+
+from meowplotlib.assets.registry import available_styles
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    import numpy as np
+    from matplotlib.figure import Figure
+
+    from meowplotlib.core.placement import Placement
+
+_IMAGE_CACHE: dict[Path, np.ndarray] = {}
+
+
+def _load_image(path: Path) -> np.ndarray:
+    if path not in _IMAGE_CACHE:
+        with importlib.resources.as_file(path) as local_path:
+            _IMAGE_CACHE[path] = mpimg.imread(local_path)
+    return _IMAGE_CACHE[path]
+
+
+def _resolve_image(placement: Placement) -> tuple[np.ndarray, float]:
+    """Return (image array, clamped scale) for `placement`, deterministic given its fields.
+
+    Scale is clamped to <= 1.0: a style's manifest `scale` may only ever shrink a cat's
+    rendered footprint within its reserved bbox, never grow it beyond the box M1's collision
+    math reserved (constitution #2 takes priority over exact visual scale fidelity — see
+    PROGRESS.md for the follow-up needed to let scale genuinely grow a cat's footprint).
+    """
+    styles = available_styles()
+    style_info = styles[placement.style]
+    pool = style_info.image_paths  # already filename-sorted by registry.discover_styles
+    index = hash((placement.x, placement.y, placement.size, placement.rotation)) % len(pool)
+    image = _load_image(pool[index])
+    return image, min(style_info.scale, 1.0)
+
+
+def draw_placements(figure: Figure, placements: list[Placement]) -> None:
+    """Add one rotated cat image per placement, each in its own figure-fraction inset axes."""
+    for placement in placements:
+        image, scale = _resolve_image(placement)
+        bbox = placement.bbox()  # the rotation-inclusive reserved square
+        cat_axes = figure.add_axes((bbox.x, bbox.y, bbox.width, bbox.height))
+        cat_axes._meowplotlib_cat = True  # type: ignore[attr-defined]
+        cat_axes.set_axis_off()
+        cat_axes.patch.set_alpha(0.0)
+
+        half_span = bbox.width / 2
+        cat_axes.set_xlim(-half_span, half_span)
+        cat_axes.set_ylim(-half_span, half_span)
+
+        visual_half = (placement.size * scale) / 2
+        cat_image = cat_axes.imshow(
+            image,
+            extent=(-visual_half, visual_half, -visual_half, visual_half),
+        )
+        cat_image.set_transform(
+            mtransforms.Affine2D().rotate_deg(placement.rotation) + cat_axes.transData
+        )

meowplotlib/render/bboxes.py

@@ -0,0 +1,76 @@
+"""Extracts exclusion zones (axes, labels, ticks, legend) from a live figure."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from meowplotlib.core.placement import Rect
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+    from matplotlib.transforms import Bbox, Transform
+
+
+def extract_exclusions(figure: Figure) -> list[Rect]:
+    """Return one exclusion Rect per axes (tight bbox incl. ticks/labels), plus legends.
+
+    Coordinates are converted to figure-fraction space via `figure.transFigure`.
+    """
+    renderer = figure._get_renderer()  # type: ignore[attr-defined]  # noqa: SLF001
+    exclusions: list[Rect] = []
+    inv = figure.transFigure.inverted()
+
+    for axes in figure.axes:
+        if getattr(axes, "_meowplotlib_cat", False):
+            continue  # a previously-placed cat's own inset axes, not a protected element
+        bbox = axes.get_tightbbox(renderer)
+        if bbox is None:
+            continue
+        exclusions.append(_bbox_to_rect(bbox, inv))
+
+        legend = axes.get_legend()
+        if legend is not None:
+            legend_bbox = legend.get_window_extent(renderer)
+            exclusions.append(_bbox_to_rect(legend_bbox, inv))
+
+    return exclusions
+
+
+def ensure_minimum_margin(figure: Figure, margin: float) -> None:
+    """Shrink each axes so at least `margin` (figure-fraction) of clear space remains between
+    its tight bbox and every figure edge, so cats have room to land on all four sides.
+
+    This actively resizes the user's plot area — a deliberate, opted-in departure from pure
+    "decorate around the existing layout" behavior. See PROGRESS.md for the tradeoff record.
+    Only shrinks when needed: axes with an already-generous margin on a given side are left
+    untouched on that side.
+    """
+    renderer = figure._get_renderer()  # type: ignore[attr-defined]  # noqa: SLF001
+    inv = figure.transFigure.inverted()
+
+    for axes in figure.axes:
+        if getattr(axes, "_meowplotlib_cat", False):
+            continue
+        tight = axes.get_tightbbox(renderer)
+        if tight is None:
+            continue
+        fig_tight = tight.transformed(inv)
+
+        left_deficit = max(0.0, margin - fig_tight.x0)
+        bottom_deficit = max(0.0, margin - fig_tight.y0)
+        right_deficit = max(0.0, margin - (1.0 - fig_tight.x1))
+        top_deficit = max(0.0, margin - (1.0 - fig_tight.y1))
+        if not (left_deficit or bottom_deficit or right_deficit or top_deficit):
+            continue
+
+        pos = axes.get_position()
+        new_width = pos.width - left_deficit - right_deficit
+        new_height = pos.height - bottom_deficit - top_deficit
+        if new_width <= 0 or new_height <= 0:
+            continue  # figure too small to guarantee this margin; leave axes as-is
+        axes.set_position((pos.x0 + left_deficit, pos.y0 + bottom_deficit, new_width, new_height))
+
+
+def _bbox_to_rect(bbox: Bbox, inv: Transform) -> Rect:
+    fig_bbox = bbox.transformed(inv)
+    return Rect(x=fig_bbox.x0, y=fig_bbox.y0, width=fig_bbox.width, height=fig_bbox.height)

meowplotlib/render/hook.py

@@ -0,0 +1,69 @@
+"""Figure draw interception: the single hook point for both display and savefig.
+
+See specs/002-matplotlib-integration/research.md for why `Figure.draw` is the shared
+interception point, and why the patch is permanent (enable/disable only flips a flag).
+"""
+
+from __future__ import annotations
+
+import functools
+from typing import TYPE_CHECKING, Any
+
+from matplotlib.figure import Figure
+
+from meowplotlib.assets.registry import resolve_style_names
+from meowplotlib.core.config import get_config
+from meowplotlib.core.placement import PlacementConfig, place_cats
+from meowplotlib.render import artist, bboxes
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+_installed = False
+
+# Guaranteed clear space (figure-fraction) between each axes' tight bbox and every figure edge,
+# so cats can land on all four sides rather than only wherever the chart's default layout
+# happens to leave room. Sized comfortably above the largest rotated cat footprint (max size
+# 0.16, up to ~1.41x when rotated ~= 0.226) so a typical cat fits without shrinking.
+_GUARANTEED_MARGIN = 0.14
+
+
+def install() -> None:
+    """Wrap `Figure.draw` once, process-wide. Safe to call more than once (no-op after first)."""
+    global _installed
+    if _installed:
+        return
+    _installed = True
+
+    original_draw: Callable[..., Any] = Figure.draw
+
+    @functools.wraps(original_draw)
+    def wrapped_draw(self: Figure, renderer: Any, *args: Any, **kwargs: Any) -> Any:
+        config = get_config()
+        if config.enabled and not getattr(self, "_meowplotlib_decorated", False):
+            _decorate(self, config.density, config.seed, config.style)
+            self._meowplotlib_decorated = True  # type: ignore[attr-defined]
+        return original_draw(self, renderer, *args, **kwargs)
+
+    Figure.draw = wrapped_draw  # type: ignore[assignment]
+
+
+def _decorate(figure: Figure, density: str, seed: int | None, style: str | list[str]) -> None:
+    # bboxes.extract_exclusions() returns rects in figure-fraction space (transFigure-normalized
+    # to 0..1), so the canvas itself is always the unit square in that same coordinate system —
+    # NOT figure.get_size_inches(). This also gives small-figure degradation "for free": at a
+    # fixed font size, a small figure's tick/axis labels occupy a larger fraction of the unit
+    # square, shrinking available border area exactly as intended.
+    bboxes.ensure_minimum_margin(figure, _GUARANTEED_MARGIN)
+    exclusions = bboxes.extract_exclusions(figure)
+    styles = resolve_style_names(style)
+    if not styles:
+        return
+    config = PlacementConfig(
+        density=density,  # type: ignore[arg-type]
+        size_range=(0.06, 0.16),
+        seed=seed,
+        styles=styles,
+    )
+    placements = place_cats(1.0, 1.0, exclusions, config)
+    artist.draw_placements(figure, placements)

meowplotlib-0.1.0.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: meowplotlib
+Version: 0.1.0
+Summary: Whimsical cat decorations for matplotlib figures.
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# meowplotlib
+
+![Before and after adding meowplotlib to a matplotlib chart](docs/before_after.png)
+
+Whimsical cat decorations for `matplotlib` figures. One import, zero required config.
+
+```python
+import matplotlib.pyplot as plt
+import meowplotlib  # cats now appear on every figure you show or save
+
+plt.plot([1, 2, 3], [1, 4, 9])
+plt.savefig("chart.png")
+```
+
+## Quickstart
+
+```bash
+pip install meowplotlib
+```
+
+```python
+import meowplotlib
+
+meowplotlib.set_style("chonk")      # or a list, or "mix"
+meowplotlib.set_density("chaotic")  # "sparse" | "normal" | "chaotic"
+meowplotlib.set_seed(42)            # reproducible layouts
+meowplotlib.disable()               # turn it off for the rest of the session
+meowplotlib.enable()                # turn it back on
+
+with meowplotlib.config(enabled=False):
+    ...  # one chart rendered without cats
+```
+
+## Config
+
+| Function | Values | Effect |
+|---|---|---|
+| `set_style` | style name, list of names, or `"mix"` | which cat art pool(s) to draw from |
+| `set_density` | `"sparse"` \| `"normal"` \| `"chaotic"` | how many cats appear |
+| `set_seed` | `int` \| `None` | lock or randomize placement |
+| `enable()` / `disable()` | — | session on/off switch |
+| `config(**overrides)` | context manager | temporary overrides for one block |
+
+## Art
+
+v1 ships with three real cat art styles: `classic`, `derp`, and `chonk`. Adding or swapping a
+style is a pure file-drop under `src/meowplotlib/assets/images/<style>/` plus one `styles.toml`
+entry — no code changes required. See [ATTRIBUTION.md](ATTRIBUTION.md) for notes.
+
+See `STANDUP_PLAN.md` and `constitution.md` for the full project contract.

meowplotlib-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+meowplotlib/__init__.py,sha256=9-QZnxDNUC2z1xNIcai33KfmyzpM6a63SkaW9oG4Jco,329
+meowplotlib/api.py,sha256=WFy_2bESoUuvfFAZP0dHuwzdb4EbL9fMh7AC0DWx6Q8,2227
+meowplotlib/assets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+meowplotlib/assets/_toml_fallback.py,sha256=w6maFX6mbrYgHc8npn1lXeBFHBNGjyZGD8LXUEpFj-g,1489
+meowplotlib/assets/registry.py,sha256=YJ3h1BzmlfkIAHMZOr4usO4CwgzJXcFetxbEudepnbE,3368
+meowplotlib/assets/styles.toml,sha256=2Ji9AU1kDulnxBpYTTgXtAmEIhDOAeMoAYSa2Ktv21c,300
+meowplotlib/assets/images/chonk/chonk_01.png,sha256=mplF5TjfjRYyfIeCBYwCNNLPb99krr39aemDzPeTWg0,326322
+meowplotlib/assets/images/classic/classic_01.png,sha256=F70_HOuKUn30uEi6BEicVrUsvbw1hsKSx5YHJUTwpFM,538877
+meowplotlib/assets/images/derp/derp_01.png,sha256=mwXEPS0jorHD4HthwUAMW5hRG90Rk9bFFla2kY1hywM,204446
+meowplotlib/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+meowplotlib/core/config.py,sha256=m43IrPzKXynM6Zxs7IaCJey8lDkMXKEOHJ1ckL6gpzM,995
+meowplotlib/core/placement.py,sha256=4Wkr17wS5MivFqda5Z3qr31NwuvV2AwH1vnxOKO_VtU,6348
+meowplotlib/core/rng.py,sha256=WLUgHVCMjruZrZAUIFxmZMK4yEzZqtPT-fuf_gqGk2U,310
+meowplotlib/render/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+meowplotlib/render/artist.py,sha256=DQRKs1qjc6SSZIL1v19xBTgf1W0BAmooArxHhpZRLrU,3983
+meowplotlib/render/bboxes.py,sha256=KdNTsS7xBfaNCyxbKtS1pk-ANir6xJoqFp4csBFZhXI,3073
+meowplotlib/render/hook.py,sha256=hb8TkkTqnbfLVKW-pEtI29pSx-fEAKK03hzZsZQT8-M,2838
+meowplotlib-0.1.0.dist-info/METADATA,sha256=_jLV72fd_bPyr9MqYPSmDT-rHm0n1-xtWGO75qF3U1s,2132
+meowplotlib-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+meowplotlib-0.1.0.dist-info/RECORD,,

meowplotlib-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any