codimate 0.1.3__tar.gz → 0.1.5__tar.gz

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

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

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

@@ -1,8 +1,14 @@
 Metadata-Version: 2.4
 Name: codimate
-Version: 0.1.3
+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}),
@@ -182,6 +191,7 @@ scene.circle(name, r=, at=)
 scene.text(name, content, size=, at=)
 scene.polygon(name, points)                             # cm.ngon, cm.star
 scene.curve(name, points, w=)                           # smooth, through the points
+scene.arc(name, r=, sweep=(0, 120))                     # an arc, a dial, a pie slice
 scene.svg(name, "logo.svg", size=)                       # vector art, as real geometry
 scene.image(name, "photo.jpg", size=)                    # a picture: PNG or JPEG
 scene.line(name, start=slot_or_point, end=slot_or_point, w=)
@@ -334,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.3 → 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}),
@@ -170,6 +173,7 @@ scene.circle(name, r=, at=)
 scene.text(name, content, size=, at=)
 scene.polygon(name, points)                             # cm.ngon, cm.star
 scene.curve(name, points, w=)                           # smooth, through the points
+scene.arc(name, r=, sweep=(0, 120))                     # an arc, a dial, a pie slice
 scene.svg(name, "logo.svg", size=)                       # vector art, as real geometry
 scene.image(name, "photo.jpg", size=)                    # a picture: PNG or JPEG
 scene.line(name, start=slot_or_point, end=slot_or_point, w=)
@@ -322,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.3 → codimate-0.1.5}/crates/codimate-py/Cargo.toml

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

{codimate-0.1.3 → codimate-0.1.5}/crates/codimate-reconcile/src/lib.rs

@@ -85,8 +85,8 @@ pub struct Shape {
 
 /// Every `kind` Python may send. An unknown kind is a Python `ValueError`,
 /// never a silently missing shape.
-pub const KINDS: [&str; 9] = [
-    "rect", "circle", "text", "line", "formula", "polygon", "curve", "svg", "image",
+pub const KINDS: [&str; 10] = [
+    "rect", "circle", "text", "line", "formula", "polygon", "curve", "svg", "image", "arc",
 ];
 
 /// A rectangle with rounded corners, in local space, centred on the anchor.
@@ -235,6 +235,79 @@ fn curve_path(s: &Shape) -> Path {
     Path { segments, closed }
 }
 
+/// How many cubics an arc is built from, whatever it sweeps.
+///
+/// Fixed rather than "one per 90 degrees", because two arcs only tween if they
+/// have the same path structure — the rule `polygon` follows for corners. A
+/// fixed count is what lets a pie fill or an angle mark grow smoothly, which is
+/// the whole reason this kind exists rather than a `curve` through points on a
+/// circle. Eight keeps every span under 45 degrees even at a full turn, where
+/// the cubic approximation is good to a few thousandths of a radius.
+const ARC_SPANS: usize = 8;
+
+/// An arc or a sector in local space.
+///
+/// `w`/`h` are the bounding box, so an ellipse costs nothing extra; `x2`/`y2`
+/// are the start and end angle in degrees; `r` above zero closes it back to the
+/// centre, making a pie slice rather than an open curve.
+///
+/// Angles run clockwise from twelve o'clock, matching `cm.ngon`, whose first
+/// corner also points straight up.
+/// The same arc, from plain numbers — so the tween can interpolate the
+/// *angles* and build a true arc at every instant.
+///
+/// Interpolating the path's control points instead looks right for an open
+/// arc and is wrong for a sector: halfway between a collapsed slice and a
+/// 300-degree one is not a 150-degree slice, it is a self-crossing shape that
+/// fills as a sliver and a half-disc. Caught by rendering one.
+fn arc_at(rx: f32, ry: f32, from_deg: f32, to_deg: f32, sector: bool) -> Path {
+    // Screen y grows downward, so subtracting a quarter turn puts zero at the
+    // top and makes a rising angle read as clockwise.
+    let at = |deg: f32| {
+        let a = deg.to_radians() - std::f32::consts::FRAC_PI_2;
+        (Vec2::new(rx * a.cos(), ry * a.sin()), a)
+    };
+
+    let (start, theta0) = at(from_deg);
+    let (_, theta1) = at(to_deg);
+    let step = (theta1 - theta0) / ARC_SPANS as f32;
+    // The classic cubic fit to a circular span: exact at both ends and at the
+    // midpoint, which is why the error stays small for spans under a quarter
+    // turn.
+    let k = 4.0 / 3.0 * (step / 4.0).tan();
+
+    let mut segments = Vec::with_capacity(ARC_SPANS + 3);
+    if sector {
+        segments.push(Segment::MoveTo(Vec2::new(0.0, 0.0)));
+        segments.push(Segment::Line(Vec2::new(0.0, 0.0), start));
+    } else {
+        segments.push(Segment::MoveTo(start));
+    }
+
+    let mut from = start;
+    let mut a = theta0;
+    for _ in 0..ARC_SPANS {
+        let b = a + step;
+        let to = Vec2::new(rx * b.cos(), ry * b.sin());
+        // The tangent at each end, scaled by the span — the control points sit
+        // along it, which is what keeps the join smooth.
+        let c1 = Vec2::new(from.x - k * rx * a.sin(), from.y + k * ry * a.cos());
+        let c2 = Vec2::new(to.x + k * rx * b.sin(), to.y - k * ry * b.cos());
+        segments.push(Segment::Cubic(from, c1, c2, to));
+        from = to;
+        a = b;
+    }
+
+    if sector {
+        segments.push(Segment::Line(from, Vec2::new(0.0, 0.0)));
+    }
+
+    Path {
+        segments,
+        closed: sector,
+    }
+}
+
 /// A line in local space: from the anchor to the far end.
 fn line_path(s: &Shape) -> Path {
     Path {
@@ -272,6 +345,29 @@ impl Shape {
                 }
             }
 
+            // The angles tween, and the arc is rebuilt at every instant — so
+            // a dial sweeps and a pie fills through shapes that are all
+            // genuinely arcs. This is the point of the kind: a `curve` through
+            // points on a circle changes its point count when the sweep
+            // changes, and then it snaps instead of sweeping.
+            "arc" => {
+                let (rx0, ry0) = (self.w / 2.0, self.h / 2.0);
+                let (rx1, ry1) = (other.w / 2.0, other.h / 2.0);
+                let (a0, b0) = (self.x2, self.y2);
+                let (a1, b1) = (other.x2, other.y2);
+                let sector = other.r > 0.0;
+                Geometry::path(Animated::new(move |t| {
+                    let mix = |x: f32, y: f32| x + (y - x) * t;
+                    arc_at(
+                        mix(rx0, rx1),
+                        mix(ry0, ry1),
+                        mix(a0, a1),
+                        mix(b0, b1),
+                        sector,
+                    )
+                }))
+            }
+
             // Same rule as a polygon: matching sample counts interpolate, and
             // otherwise the later shape stands for the whole segment.
             "curve" => {
@@ -1408,6 +1504,9 @@ fn bounds(shape: &Shape) -> (f32, f32, f32, f32) {
                 ys.iter().cloned().fold(f32::MIN, f32::max),
             );
         }
+        // The whole ellipse, not the swept part: an arc that grows would
+        // otherwise resize the camera as it sweeps.
+        "arc" => (shape.w, shape.h),
         "line" => {
             let (x0, x1) = (shape.x.min(shape.x2), shape.x.max(shape.x2));
             let (y0, y1) = (shape.y.min(shape.y2), shape.y.max(shape.y2));
@@ -1855,6 +1954,108 @@ mod tests {
 
     /// An SVG on disk, because `svg_art` reads a path rather than a string —
     /// the payload carries a file name, so the cache can key on it.
+    fn arc_path(s: &Shape) -> Path {
+        arc_at(s.w / 2.0, s.h / 2.0, s.x2, s.y2, s.r > 0.0)
+    }
+
+    fn arc_shape(r: f32, from: f32, to: f32, sector: bool) -> Shape {
+        Shape {
+            item: "arc".into(),
+            kind: "arc".into(),
+            w: r * 2.0,
+            h: r * 2.0,
+            x2: from,
+            y2: to,
+            r: if sector { 1.0 } else { 0.0 },
+            color: "white".into(),
+            opacity: 1.0,
+            ..Default::default()
+        }
+    }
+
+    /// Every point the arc visits is on the circle it claims to be — the
+    /// eight-span cubic fit is an approximation, so this is what says how good.
+    #[test]
+    fn an_arc_stays_on_its_circle() {
+        for (from, to) in [(0.0, 90.0), (0.0, 270.0), (0.0, 360.0), (45.0, -120.0)] {
+            let path = arc_path(&arc_shape(100.0, from, to, false));
+            for seg in &path.segments {
+                let ends = match *seg {
+                    Segment::Cubic(a, _, _, b) => vec![a, b],
+                    Segment::MoveTo(a) => vec![a],
+                    _ => vec![],
+                };
+                for p in ends {
+                    let radius = (p.x * p.x + p.y * p.y).sqrt();
+                    assert!(
+                        (radius - 100.0).abs() < 0.5,
+                        "{from}..{to}: a point sits at {radius}, not 100"
+                    );
+                }
+            }
+        }
+    }
+
+    /// A sector closes back to its centre and an open arc does not — the
+    /// difference between a pie slice and a curved line.
+    #[test]
+    fn a_sector_returns_to_the_centre() {
+        let open = arc_path(&arc_shape(50.0, 0.0, 120.0, false));
+        let pie = arc_path(&arc_shape(50.0, 0.0, 120.0, true));
+
+        assert!(!open.closed && pie.closed);
+        // Distance from the centre, not `x`: an arc starting at zero degrees
+        // begins at the top, where `x` is zero.
+        assert!(
+            matches!(open.segments.first(), Some(Segment::MoveTo(p)) if p.x.hypot(p.y) > 1.0),
+            "an open arc starts on its circle, not at the centre"
+        );
+        assert!(
+            matches!(pie.segments.first(), Some(Segment::MoveTo(p)) if p.x.abs() < 1e-6 && p.y.abs() < 1e-6),
+            "a pie starts at its centre"
+        );
+        assert!(
+            matches!(pie.segments.last(), Some(Segment::Line(_, p)) if p.x.abs() < 1e-6 && p.y.abs() < 1e-6),
+            "and comes back to it"
+        );
+    }
+
+    /// The reason this kind exists rather than a `curve` through points on a
+    /// circle, and the bug the first version had: halfway through a sweep the
+    /// shape must be a real arc at the halfway angle.
+    ///
+    /// Interpolating the path's control points gives a self-crossing sliver
+    /// instead, which looks fine on an open arc and obviously wrong on a pie.
+    #[test]
+    fn a_sweep_passes_through_real_arcs() {
+        let closed = arc_shape(100.0, 0.0, 0.0, true);
+        let open_to_300 = arc_shape(100.0, 0.0, 300.0, true);
+
+        let geometry = closed.geometry(&open_to_300);
+        let codimate_core::ConcreteGeometry::Path { path: halfway } = geometry.resolve(0.5) else {
+            panic!("an arc resolves to a path");
+        };
+        let expected = arc_path(&arc_shape(100.0, 0.0, 150.0, true));
+
+        let ends = |p: &Path| -> Vec<Vec2> {
+            p.segments
+                .iter()
+                .filter_map(|s| match *s {
+                    Segment::Cubic(_, _, _, b) => Some(b),
+                    _ => None,
+                })
+                .collect()
+        };
+        let (got, want) = (ends(&halfway), ends(&expected));
+        assert_eq!(got.len(), want.len());
+        for (a, b) in got.iter().zip(&want) {
+            assert!(
+                (a.x - b.x).abs() < 0.01 && (a.y - b.y).abs() < 0.01,
+                "halfway through a 0..300 sweep should be the 150 arc: {a:?} vs {b:?}"
+            );
+        }
+    }
+
     fn svg_on_disk(name: &str, body: &str) -> String {
         let path = std::env::temp_dir().join(format!("codimate-test-{name}.svg"));
         std::fs::write(&path, body).expect("temp file");

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

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "codimate"
-version = "0.1.3"
+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.3 → codimate-0.1.5}/python/codimate/__init__.py

@@ -20,7 +20,7 @@ encoding — happens in Rust (ADR 0008).
 
 ## What a moment looks like
 
-- `Scene` — one picture: `rect`, `circle`, `polygon`, `curve`, `arrow`,
+- `Scene` — one picture: `rect`, `circle`, `arc`, `polygon`, `curve`, `arrow`,
   `text`, `line`, `formula`, `svg`, `image`
 - `ngon`, `star` — corners for a polygon, so you do not compute them
 - `Group` — several shapes that move together
@@ -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.3 → 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.3 → codimate-0.1.5}/python/codimate/scene.py

@@ -290,6 +290,36 @@ class Group:
         return self._place(key, "formula", x=x, y=y, text=latex, size=size,
                            layer=10, r=1.0)
 
+    def arc(self, key: Hashable, *, r, sweep, at=None) -> "Handle":
+        """A slice of a circle — an angle mark, a pie, a dial, an orbit.
+
+            scene.arc("angle", r=90, sweep=(0, 50)).fill("none", edge="cyan",
+                                                          edge_w=3)
+            scene.arc("slice", r=120, sweep=(0, 120)).fill("orange").round(1)
+
+        `sweep` is `(start, end)` in degrees, clockwise from twelve o'clock —
+        the same zero `cm.ngon` uses. `r` is the radius, or `(rx, ry)` for an
+        ellipse.
+
+        Open by default, so it draws as a curved line. `.round(1)` closes it
+        back to the centre and makes a pie slice you can fill.
+
+        Two arcs always tween, however far apart their angles are, so an angle
+        mark grows and a pie fills smoothly. That is what this cannot be done
+        with `curve`: a curve through points on a circle changes its point
+        count when the sweep changes, and then it snaps instead of sweeping.
+        """
+        rx, ry = (r, r) if isinstance(r, (int, float)) else r
+        start, end = sweep
+        x, y = self._where(at, 0.0)
+        return self._place(
+            key, "arc", x=x, y=y,
+            # The bounding box, so an ellipse costs nothing extra.
+            w=float(rx) * 2, h=float(ry) * 2,
+            # `x2`/`y2` are the line's endpoints elsewhere and free here.
+            x2=float(start), y2=float(end),
+        )
+
     def image(self, key: Hashable, file, *, size=None, at=None) -> "Handle":
         """A picture — a photo, a screenshot, a figure — drawn into the frame.
 

{codimate-0.1.3 → 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: