codimate 0.1.4__tar.gz → 0.1.5__tar.gz

{codimate-0.1.4 → codimate-0.1.5}/Cargo.lock

@@ -217,7 +217,7 @@ dependencies = [
 
 [[package]]
 name = "codimate-py"
-version = "0.1.4"
+version = "0.1.5"
 dependencies = [
  "codimate-animation",
  "codimate-core",

{codimate-0.1.4 → codimate-0.1.5}/PKG-INFO

@@ -1,8 +1,14 @@
 Metadata-Version: 2.4
 Name: codimate
-Version: 0.1.4
+Version: 0.1.5
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Multimedia :: Video
 Classifier: Topic :: Education
 Requires-Dist: imageio-ffmpeg>=0.4.9
@@ -15,6 +21,10 @@ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 [![PyPI](https://img.shields.io/pypi/v/codimate)](https://pypi.org/project/codimate/)
 [![Python](https://img.shields.io/pypi/pyversions/codimate)](https://pypi.org/project/codimate/)
 
+![Planets tracing helices around the Sun's path through the galaxy](docs/media/helical_solar_system.gif)
+
+*Two seconds of [`helical_solar_system/`](python/examples/helical_solar_system/)*
+
 Turn a running algorithm into an explainer video.
 
 You write your algorithm as normal Python and say what each step looks like.
@@ -23,14 +33,13 @@ Codimate works out the motion, the timing, and every frame.
 ```python
 import codimate as cm
 
-@cm.trace()
-def bubble_sort(values):
+def bubble_sort(values, emit):
     for i in range(len(values)):
         for j in range(len(values) - 1 - i):
-            cm.emit("compare", items=[values[j], values[j + 1]])
+            emit("compare", items=[values[j], values[j + 1]])
             if values[j] > values[j + 1]:
                 values[j], values[j + 1] = values[j + 1], values[j]
-                cm.emit("swap", items=[values[j], values[j + 1]])
+                emit("swap", items=[values[j], values[j + 1]])
 
 def bars(frame):
     scene = cm.Scene()
@@ -45,7 +54,7 @@ def bars(frame):
     return scene
 
 cm.explain(
-    trace=bubble_sort(cm.items([3, 1, 4, 2])),
+    trace=cm.trace(bubble_sort, cm.items([3, 1, 4, 2])),
     view=bars,
     motion=[cm.Rule("*", position="lift_carry_drop", clearance=90)],
     timing=cm.Timing(default=0.55, events={"swap": 0.9}),
@@ -335,7 +344,7 @@ with `python docs/build_site.py`.
    authored, and the one decision you have to make.
 4. [Reference](docs/reference.md) — every call and parameter, on one page.
 
-Then [`python/examples/`](python/examples/), eight worked examples with notes, and
+Then [`python/examples/`](python/examples/), eleven worked examples with notes, and
 [the decisions](docs/adr/) behind the design.
 
 ```bash

{codimate-0.1.4 → codimate-0.1.5}/README.md

@@ -3,6 +3,10 @@
 [![PyPI](https://img.shields.io/pypi/v/codimate)](https://pypi.org/project/codimate/)
 [![Python](https://img.shields.io/pypi/pyversions/codimate)](https://pypi.org/project/codimate/)
 
+![Planets tracing helices around the Sun's path through the galaxy](docs/media/helical_solar_system.gif)
+
+*Two seconds of [`helical_solar_system/`](python/examples/helical_solar_system/)*
+
 Turn a running algorithm into an explainer video.
 
 You write your algorithm as normal Python and say what each step looks like.
@@ -11,14 +15,13 @@ Codimate works out the motion, the timing, and every frame.
 ```python
 import codimate as cm
 
-@cm.trace()
-def bubble_sort(values):
+def bubble_sort(values, emit):
     for i in range(len(values)):
         for j in range(len(values) - 1 - i):
-            cm.emit("compare", items=[values[j], values[j + 1]])
+            emit("compare", items=[values[j], values[j + 1]])
             if values[j] > values[j + 1]:
                 values[j], values[j + 1] = values[j + 1], values[j]
-                cm.emit("swap", items=[values[j], values[j + 1]])
+                emit("swap", items=[values[j], values[j + 1]])
 
 def bars(frame):
     scene = cm.Scene()
@@ -33,7 +36,7 @@ def bars(frame):
     return scene
 
 cm.explain(
-    trace=bubble_sort(cm.items([3, 1, 4, 2])),
+    trace=cm.trace(bubble_sort, cm.items([3, 1, 4, 2])),
     view=bars,
     motion=[cm.Rule("*", position="lift_carry_drop", clearance=90)],
     timing=cm.Timing(default=0.55, events={"swap": 0.9}),
@@ -323,7 +326,7 @@ with `python docs/build_site.py`.
    authored, and the one decision you have to make.
 4. [Reference](docs/reference.md) — every call and parameter, on one page.
 
-Then [`python/examples/`](python/examples/), eight worked examples with notes, and
+Then [`python/examples/`](python/examples/), eleven worked examples with notes, and
 [the decisions](docs/adr/) behind the design.
 
 ```bash

{codimate-0.1.4 → codimate-0.1.5}/crates/codimate-py/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "codimate-py"
-version = "0.1.4"
+version = "0.1.5"
 edition = "2021"
 
 [lib]

{codimate-0.1.4 → codimate-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "codimate"
-version = "0.1.4"
+version = "0.1.5"
 description = "Turn a running algorithm into an explainer video"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -13,9 +13,19 @@ requires-python = ">=3.9"
 # own — so `pip install codimate` is enough on a bare machine. `typst`, which
 # only `scene.formula` needs, stays a documented prerequisite.
 dependencies = ["imageio-ffmpeg>=0.4.9"]
+# The per-version entries are not decoration: `requires-python` above is what
+# pip enforces, but PyPI's sidebar and the shields.io badge both read these
+# instead, and without them the badge reads "missing". One abi3-py39 wheel
+# serves every version listed.
 classifiers = [
     "Programming Language :: Rust",
     "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Multimedia :: Video",
     "Topic :: Education",
 ]
@@ -41,7 +51,6 @@ select = ["E", "W", "F", "PLR0913"]
 ignore = ["E741"]
 
 [tool.ruff.lint.per-file-ignores]
-"python/examples/attention/weights.py" = ["E501"]
 
 [tool.ruff.lint.pylint]
 max-args = 5

{codimate-0.1.4 → codimate-0.1.5}/python/codimate/__init__.py

@@ -48,8 +48,8 @@ encoding — happens in Rust (ADR 0008).
 from __future__ import annotations
 
 from .explain import Explanation, Rule, Timing, ease, explain
-from .layout import (Place, Slot, at, canvas, column, height, measure, measure_math,
-                     ngon, row, star, width)
+from .layout import (Axes, Place, Slot, at, axes, canvas, column, height, measure,
+                     measure_math, ngon, row, star, width)
 from .scene import Group, Handle, Scene
 from .trace import Event, Frame, Item, Trace, emit, items, trace
 
@@ -77,6 +77,8 @@ __all__ = [
     "at",
     "row",
     "column",
+    "axes",
+    "Axes",
     "ngon",
     "star",
     # putting it together

{codimate-0.1.4 → codimate-0.1.5}/python/codimate/layout.py

@@ -306,3 +306,217 @@ def _resolve(given, half, names, default=_UNSET):
     if low is not None:
         return float(low) + half
     return float(high) - half
+
+
+# --------------------------------------------------------------------------
+# Axes: a coordinate map, not a drawing (ADR 0016)
+# --------------------------------------------------------------------------
+
+
+def _nice_step(span: float, about: int) -> float:
+    """A round step near ``span / about``, from the 1-2-5 sequence.
+
+    Round steps are not a nicety. A tick is a named shape, so the set of them
+    is an identity that survives from one Scene to the next; a step that
+    drifted with every frame would rename every tick every frame, and a still
+    picture would flicker. 1-2-5 holds steady until the range really changes.
+    """
+    import math
+
+    if span <= 0:
+        raise ValueError(f"a range needs width, got {span}")
+    raw = span / max(int(about), 1)
+    power = 10.0 ** math.floor(math.log10(raw))
+    for nice in (1.0, 2.0, 5.0):
+        if raw <= nice * power:
+            return nice * power
+    return 10.0 * power
+
+
+def _places(step: float) -> int:
+    """How many decimals a label needs so that two ticks never read alike."""
+    import math
+
+    return max(0, -math.floor(math.log10(step) + 1e-9))
+
+
+@dataclass(frozen=True)
+class Axes:
+    """A map from your numbers to pixels. Built by :func:`axes`.
+
+    It draws nothing you did not ask it to and owns none of your names — see
+    :meth:`at`. Its own shapes (frame, ticks, labels) are drawn by
+    :meth:`draw`, under names you choose the prefix of.
+    """
+
+    x0: float
+    x1: float
+    y0: float
+    y1: float
+    left: float
+    top: float
+    w: float
+    h: float
+    ink: str = "#8b96a8"
+    label: float = 20.0
+    layer: int = 0
+
+    def looks(self, ink: str = None, label: float = None,
+              layer: int = None) -> "Axes":
+        """Restyle the frame, ticks and labels. Returns a new Axes.
+
+            plot = cm.axes(x=(0, 10), y=(0, 5)).looks(ink="#334", label=16)
+
+        A separate call rather than more arguments on :meth:`draw`, which the
+        shapes made the same choice about: no call in this library takes more
+        than five things.
+        """
+        import dataclasses
+
+        return dataclasses.replace(
+            self,
+            ink=self.ink if ink is None else str(ink),
+            label=self.label if label is None else float(label),
+            layer=self.layer if layer is None else int(layer))
+
+    @property
+    def right(self) -> float:
+        return self.left + self.w
+
+    @property
+    def bottom(self) -> float:
+        return self.top + self.h
+
+    def at(self, x: float, y: float) -> tuple[float, float]:
+        """One data point as a pixel pair, for any shape's ``at=``.
+
+            scene.circle("dot", r=8, at=plot.at(2.0, 4.0))
+
+        Handing back pixels rather than drawing is the whole design: what you
+        do with them is an ordinary shape with a name of yours, so it tweens,
+        `focus` frames it, and a motion Rule can be aimed at it.
+        """
+        across = (float(x) - self.x0) / (self.x1 - self.x0)
+        up = (float(y) - self.y0) / (self.y1 - self.y0)
+        return (self.left + across * self.w, self.bottom - up * self.h)
+
+    def line(self, f, steps: int = 200, over=None) -> list:
+        """``steps + 1`` points along ``y = f(x)``, as pixels.
+
+            scene.curve("f", plot.line(lambda x: x * x), w=4).fill("red")
+
+        ``over=(lo, hi)`` samples part of the range instead of all of it.
+
+        An open `curve` is *drawn* rather than filled, so its colour is
+        ``fill()`` and its thickness is ``w=`` — ``fill("none", edge=...)``
+        draws nothing at all.
+
+        Every sample is returned, including any that fall outside the box.
+        Dropping them would be prettier and is wrong: two curves with different
+        point counts do not interpolate (ADR 0010), so a curve that shed a
+        point as it left the frame would stop animating. Keep the count and
+        clamp the range with ``over=`` if you need it inside.
+        """
+        lo, hi = (self.x0, self.x1) if over is None else (float(over[0]),
+                                                          float(over[1]))
+        steps = max(int(steps), 1)
+        return [self.at(x, f(x))
+                for x in (lo + (hi - lo) * i / steps for i in range(steps + 1))]
+
+    def ticks(self, axis: str = "x", about: int = 6) -> list:
+        """``(n, value, label)`` per tick, where ``n`` is the step multiple.
+
+        ``n`` is what a tick is named after, not the value. A float that drifts
+        by one part in a billion is a different name, and a renamed shape
+        leaves and re-enters — which is a fade, on a picture that did not move.
+        An integer count of steps cannot drift.
+        """
+        import math
+
+        lo, hi = (self.x0, self.x1) if axis == "x" else (self.y0, self.y1)
+        step = _nice_step(hi - lo, about)
+        digits = _places(step)
+        first = math.ceil(lo / step - 1e-9)
+        last = math.floor(hi / step + 1e-9)
+        out = []
+        for n in range(int(first), int(last) + 1):
+            value = n * step
+            label = f"{value:.{digits}f}"
+            out.append((n, value, "0" if label.lstrip("-").strip("0.") == ""
+                        else label))
+        return out
+
+    def draw(self, scene, name="plot", *, about: int = 6,
+             grid: bool = False) -> "Axes":
+        """Draw the frame, ticks and labels. Returns the Axes, for chaining.
+
+            plot = cm.axes(x=(-4, 4), y=(-2, 6)).draw(scene)
+
+        Every shape is named ``(name, ...)``, so two plots on one canvas do not
+        collide and you can restyle or omit any of them by drawing your own.
+        Colours and sizes come from :meth:`looks`.
+        """
+        ink, layer = self.ink, self.layer
+        zero_y = self.y0 <= 0.0 <= self.y1
+        zero_x = self.x0 <= 0.0 <= self.x1
+        base = self.at(self.x0, 0.0)[1] if zero_y else self.bottom
+        spine = self.at(0.0, self.y0)[0] if zero_x else self.left
+
+        scene.line((name, "x-axis"), start=(self.left, base),
+                   end=(self.right, base), w=1.6).fill(ink).on(layer=layer)
+        scene.line((name, "y-axis"), start=(spine, self.top),
+                   end=(spine, self.bottom), w=1.6).fill(ink).on(layer=layer)
+
+        for axis, along in (("x", True), ("y", False)):
+            for n, value, words in self.ticks(axis, about):
+                if n == 0 and (zero_x if along else zero_y):
+                    continue            # the other axis already draws through it
+                x, y = (self.at(value, 0.0)[0], base) if along else \
+                    (spine, self.at(0.0, value)[1])
+                if grid:
+                    ends = ((x, self.top), (x, self.bottom)) if along else \
+                        ((self.left, y), (self.right, y))
+                    scene.line((name, "grid", axis, n), start=ends[0],
+                               end=ends[1], w=1.0).fill(ink) \
+                         .on(layer=layer - 1, opacity=0.18)
+                mark = ((x, y - 5), (x, y + 5)) if along else \
+                    ((x - 5, y), (x + 5, y))
+                scene.line((name, "tick", axis, n), start=mark[0], end=mark[1],
+                           w=1.6).fill(ink).on(layer=layer)
+                where = at(x=x, top=y + 10) if along else at(x=x - 18, y=y)
+                scene.text((name, "label", axis, n), words, size=self.label,
+                           at=where).fill(ink).on(layer=layer)
+        return self
+
+
+def axes(*, x, y, at=None, size=None, within: "Slot | None" = None) -> Axes:
+    """A coordinate map from your numbers to pixels.
+
+        plot = cm.axes(x=(-4, 4), y=(-2, 6), size=(760, 420)).draw(scene)
+        scene.curve("f", plot.line(lambda t: t * t), w=4).fill("orange")
+        scene.circle("dot", r=8, at=plot.at(t, t * t))
+
+    ``x`` and ``y`` are ``(low, high)``. ``size`` is ``(w, h)`` in pixels, or
+    one number for a square; it defaults to most of the canvas. ``at`` places
+    the box's centre, and ``within=slot`` fits it to part of the canvas.
+
+    It returns points rather than drawing, so what you plot is a shape with a
+    name of yours — which is what lets it tween, be framed by `focus`, and be
+    aimed at by a motion Rule. See ADR 0016.
+    """
+    box = _within(within)
+    w, h = _size(size)
+    if w is None:
+        w = box.w * 0.72
+    if h is None:
+        h = box.h * 0.66
+    place = at or Place()
+    cx = box.x if place.x is None else place.x
+    cy = _resolve((place.y, place.top, place.bottom), h / 2.0,
+                  ("y", "top", "bottom"), box.y)
+    x0, x1 = (float(v) for v in x)
+    y0, y1 = (float(v) for v in y)
+    if x0 == x1 or y0 == y1:
+        raise ValueError(f"a range needs width, got x={x!r} y={y!r}")
+    return Axes(x0=x0, x1=x1, y0=y0, y1=y1,
+                left=cx - w / 2.0, top=cy - h / 2.0, w=float(w), h=float(h))

{codimate-0.1.4 → codimate-0.1.5}/python/codimate/trace.py

@@ -99,15 +99,75 @@ def emit(name: str, **data: Any) -> None:
     rec.events.append(Event(name=name, state=rec.snapshot(), data=data))
 
 
-def trace(*, snapshot: Callable[..., Any] = None):
-    """Turn a normal, state-mutating function into a Trace.
+_MISSING = object()
 
-    ``snapshot`` receives the same arguments as your function and returns a
-    copy of the data worth showing. Defaults to a deep copy of the first
-    argument — Items keep their identity through it.
+
+def _emitter(rec: "_Recorder") -> Callable[..., None]:
+    """The `emit` handed to an algorithm: record that something happened."""
+
+    def emit(name: str, **data: Any) -> None:
+        rec.events.append(Event(name=name, state=rec.snapshot(), data=data))
+
+    emit.__doc__ = globals()["emit"].__doc__
+    return emit
+
+
+def trace(fn=_MISSING, state=_MISSING, /, *, snapshot=None) -> "Trace":
+    """Run `fn` over `state` and record what happened.
+
+        def bubble_sort(values, emit):
+            ...
+            emit("compare", items=[a, b])
+
+        cm.explain(trace=cm.trace(bubble_sort, cm.items([3, 1, 4, 2])), ...)
+
+    Your function is handed the state and an `emit`. Call `emit` *after*
+    changing the state — Codimate snapshots the result for you.
+
+    `emit` is an argument rather than something ambient, so the answer to
+    "where did that come from?" is the line above it, and so the function
+    stays ordinary Python: `bubble_sort(values, print)` runs it and prints the
+    events.
+
+    `snapshot(state)` returns the part worth showing, if a deep copy of the
+    whole state is not what you want. Items keep their identity through the
+    default copy.
+
+    The older form — `@cm.trace()` on a function that calls the module-level
+    `cm.emit` — still works and warns. It goes in 0.2.
     """
+    if fn is _MISSING or state is _MISSING:
+        return _decorator(snapshot) if fn is _MISSING else _decorator(snapshot)(fn)
+
+    def capture():
+        return snapshot(state) if snapshot is not None else copy.deepcopy(state)
+
+    rec = _Recorder(snapshot=capture, events=[])
+    initial = capture()
+
+    # The ContextVar is still set, so a helper that has not been moved over
+    # yet and still calls `cm.emit` keeps working during the transition.
+    token = _recorder.set(rec)
+    try:
+        fn(state, _emitter(rec))
+    finally:
+        _recorder.reset(token)
+
+    return Trace(initial=initial, events=tuple(rec.events))
+
+
+def _decorator(snapshot):
+    """The older `@cm.trace()`, kept working until 0.2."""
+    import warnings
+
+    def decorate(fn):
+        warnings.warn(
+            "@cm.trace() and the ambient cm.emit are removed in 0.2. Take `emit` "
+            "as an argument and call cm.trace(fn, state) instead:\n"
+            f"    def {fn.__name__}(state, emit): ...\n"
+            f"    cm.explain(trace=cm.trace({fn.__name__}, state), ...)",
+            DeprecationWarning, stacklevel=3)
 
-    def decorator(fn):
         def run(*args, **kwargs) -> Trace:
             def capture():
                 if snapshot is not None:
@@ -116,20 +176,30 @@ def trace(*, snapshot: Callable[..., Any] = None):
 
             rec = _Recorder(snapshot=capture, events=[])
             initial = capture()
-
             token = _recorder.set(rec)
             try:
                 fn(*args, **kwargs)
             finally:
                 _recorder.reset(token)
-
             return Trace(initial=initial, events=tuple(rec.events))
 
         run.__name__ = fn.__name__
         run.__doc__ = fn.__doc__
         return run
 
-    return decorator
+    return decorate
+
+
+    def items(self, key: str = "items") -> list:
+        """The things this event named, e.g. ``frame.items()``.
+
+        Use it when you emitted a list: ``cm.emit("compare", items=[a, b])``.
+        Empty for the opening moment.
+        """
+        if self.event is None:
+            return []
+        return list(self.event.data.get(key, ()))
+
 
 @dataclass(frozen=True)
 class Frame: