paces 0.0.19__tar.gz → 0.0.21__tar.gz

{paces-0.0.19 → paces-0.0.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.19
+Version: 0.0.21
 Summary: Turn instructional media into structured, interactive learning material
 Project-URL: Homepage, https://github.com/thorwhalen/paces
 Project-URL: Repository, https://github.com/thorwhalen/paces

{paces-0.0.19 → paces-0.0.21}/paces/measure.py

@@ -45,7 +45,7 @@ from paces.model import MetricGrid, decimal_str, seconds_per_unit
 from paces.segmenters import (
     Capability,
     Segmentation,
-    _segment_grid_placed,
+    place_on_grid,
     register,
 )
 
@@ -231,7 +231,7 @@ def measure_grid(
         flags += (f"tempo-unmeasured: {tempo_unmeasured_note}{suffix}",)
 
     # Explicit beats inferred — but a disagreement is a finding, not a secret.
-    final_tempo = known_tempo or measured_tempo
+    final_tempo = known_tempo if known_tempo is not None else measured_tempo
     if (
         known_tempo is not None
         and measured_tempo is not None
@@ -243,7 +243,7 @@ def measure_grid(
             f"measures {measured_tempo} — using yours; drop tempoBpm from "
             "grid= to use the measured value",
         )
-    final_origin = known_origin or measured_origin
+    final_origin = known_origin if known_origin is not None else measured_origin
     if known_origin is None and measured_origin is not None:
         flags += (
             f"origin-estimated: first beat of the music region "
@@ -267,11 +267,19 @@ def measure_grid(
         confidence = UNMEASURED_CONFIDENCE
     else:
         confidence = (
-            KNOWN_ORIGIN_CONFIDENCE if known_origin else DFLT_MEASURED_CONFIDENCE
+            KNOWN_ORIGIN_CONFIDENCE
+            if known_origin is not None
+            else DFLT_MEASURED_CONFIDENCE
         )
 
     spu = seconds_per_unit(grid)
-    if total_units and total_units > 0 and spu and final_origin and region:
+    if (
+        total_units
+        and total_units > 0
+        and spu
+        and final_origin is not None
+        and region is not None
+    ):
         routine_s = total_units * spu
         region_s = region.end - float(Fraction(final_origin))
         evidence.update(routine_s=round(routine_s, 2), region_s=round(region_s, 2))
@@ -318,7 +326,7 @@ def _segment_grid_measured(inputs: Mapping[str, Any]) -> Segmentation:
     grid = measurement.grid
     if grid.tempo_bpm is None or grid.origin is None:
         return Segmentation(grid=grid, confidence=measurement.confidence, flags=flags)
-    placed = _segment_grid_placed({**inputs, "grid": grid})
+    placed = place_on_grid(inputs["steps"], grid)
     return Segmentation(
         steps=placed.steps,
         boundaries=placed.boundaries,

{paces-0.0.19 → paces-0.0.21}/paces/model.py

@@ -345,7 +345,11 @@ def resolve(doc: StepDocument) -> dict:
     """
     grid = doc.metric
     spu = seconds_per_unit(grid) if grid is not None else None
-    origin = float(Fraction(grid.origin)) if grid and grid.origin else None
+    origin = (
+        float(Fraction(grid.origin))
+        if grid is not None and grid.origin is not None
+        else None
+    )
 
     def _wall(offset_units: float) -> float | None:
         if spu is None or origin is None:

{paces-0.0.19 → paces-0.0.21}/paces/segmenters.py

@@ -499,42 +499,77 @@ def segment(
 # ── the two v1 segmenters ───────────────────────────────────────────────────
 
 
-def _segment_grid_placed(inputs: Mapping[str, Any]) -> Segmentation:
+def place_on_grid(steps: Sequence, grid: MetricGrid | Mapping) -> Segmentation:
     """Place an ordered step list on the timeline using a metric grid.
 
     The que-calor shape: cumulative domain durations from the grid's origin,
     ``span = origin + cumulative_units * seconds_per_unit``. Children subdivide
-    their parent's span the same way.
+    their parent's span the same way. ``steps`` takes any form
+    :func:`segment` takes (``(name, duration)`` pairs, mappings with
+    ``children``); every step needs a positive duration, and the grid a tempo
+    and an origin — anything missing or invalid is a ``ValueError`` naming it.
+
+    >>> seg = place_on_grid([("a", 1), ("b", 2)],
+    ...                     {"unit": "eight", "subdivisions": 8,
+    ...                      "tempoBpm": "120", "origin": "1"})
+    >>> [s.spans for s in seg.steps], seg.boundaries
+    ([((1.0, 5.0),), ((5.0, 13.0),)], (1.0, 5.0, 13.0))
     """
-    grid: MetricGrid = inputs["grid"]
+
+    def _all_rows(rows: list[dict]):
+        for row in rows:
+            yield row
+            yield from _all_rows(row["children"])
+
+    grid = _normalize_grid(grid)
+    rows = _normalize_steps(steps)
+    if grid is None:
+        raise ValueError("place_on_grid needs a grid; got None")
+    missing = [
+        name
+        for name, value in (("tempoBpm", grid.tempo_bpm), ("origin", grid.origin))
+        if value is None
+    ]
+    if missing:
+        raise ValueError(f"place_on_grid needs a grid with {' and '.join(missing)}")
+    if not rows:
+        raise ValueError("place_on_grid needs at least one step")
+    undated = [row["id"] for row in _all_rows(rows) if row["duration"] is None]
+    if undated:
+        raise ValueError(f"place_on_grid needs a duration for every step: {undated}")
+    bad = [
+        row["id"]
+        for row in _all_rows(rows)
+        if not (math.isfinite(row["duration"]) and row["duration"] > 0)
+    ]
+    if bad:
+        raise ValueError(f"place_on_grid needs positive, finite durations: {bad}")
     spu = seconds_per_unit(grid)
-    origin = float(grid.origin)  # guaranteed by the 'grid' fact
+    origin = float(grid.origin)
 
-    def _place(rows: list[dict], at_units: float) -> tuple[list[SegStep], float]:
+    def _place(rows: list[dict], at_units: float) -> list[SegStep]:
         placed = []
         for row in rows:
             duration = row["duration"]
             start = origin + at_units * spu
             end = origin + (at_units + duration) * spu
-            children, _ = _place(row["children"], at_units)
             placed.append(
                 SegStep(
                     id=row["id"],
                     name=row["name"],
                     spans=((start, end),),
                     confidence=DFLT_GRID_CONFIDENCE,
-                    children=tuple(children),
+                    children=tuple(_place(row["children"], at_units)),
                     source="grid-placed",
                     evidence={"duration_units": duration, "offset_units": at_units},
                 )
             )
             at_units += duration
-        return placed, at_units
+        return placed
 
-    steps, total_units = _place(inputs["steps"], 0.0)
-    boundaries = tuple(origin + units * spu for units in _cumulative(inputs["steps"]))
+    boundaries = tuple(origin + units * spu for units in _cumulative(rows))
     return Segmentation(
-        steps=tuple(steps),
+        steps=tuple(_place(rows, 0.0)),
         boundaries=boundaries,
         unit=grid.unit,
         grid=grid,
@@ -542,6 +577,11 @@ def _segment_grid_placed(inputs: Mapping[str, Any]) -> Segmentation:
     )
 
 
+def _segment_grid_placed(inputs: Mapping[str, Any]) -> Segmentation:
+    """The ``grid-placed`` capability: :func:`place_on_grid` over the facade's inputs."""
+    return place_on_grid(inputs["steps"], inputs["grid"])
+
+
 def _cumulative(rows: list[dict]) -> list[float]:
     offsets, at = [0.0], 0.0
     for row in rows:

{paces-0.0.19 → paces-0.0.21}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paces"
-version = "0.0.19"
+version = "0.0.21"
 description = "Turn instructional media into structured, interactive learning material"
 readme = "README.md"
 license = "MIT"

{paces-0.0.19 → paces-0.0.21}/tests/test_segment.py

@@ -170,3 +170,64 @@ def test_decimal_str_refuses_non_finite_values(value):
 
     with pytest.raises(ValueError, match="non-finite"):
         decimal_str(value)
+
+
+def test_place_on_grid_is_the_public_placement():
+    from paces.segmenters import place_on_grid
+
+    seg = place_on_grid(ROUTINE_STEPS, GRID)
+    assert [s.spans for s in seg.steps] == [
+        s.spans for s in segment(steps=ROUTINE_STEPS, grid=GRID).steps
+    ]
+
+
+@pytest.mark.parametrize(
+    "steps, grid, match",
+    [
+        (ROUTINE_STEPS, {"unit": "eight", "subdivisions": 8}, "tempoBpm and origin"),
+        (ROUTINE_STEPS, {**GRID, "origin": None}, "with origin$"),
+        ([], GRID, "at least one step"),
+        ([("back", -1)], GRID, r"positive, finite durations: \['back'\]"),
+        ([("nan", float("nan"))], GRID, "positive, finite"),
+        ([("zero", 0)], GRID, "positive, finite"),
+        (["no duration"], GRID, "duration for every step"),
+        ([{"name": "p", "duration": 2, "children": ["c"]}], GRID, r"\['c'\]"),
+    ],
+)
+def test_place_on_grid_names_what_is_missing(steps, grid, match):
+    from paces.segmenters import place_on_grid
+
+    with pytest.raises(ValueError, match=match):
+        place_on_grid(steps, grid)
+
+
+@pytest.mark.parametrize("origin, start", [("0", 0.0), ("0.0", 0.0), ("51.2", 51.2)])
+def test_resolve_computes_wall_clock_from_any_origin_including_zero(origin, start):
+    """An origin of 0 is a real origin, not a missing one (#46)."""
+    from paces.model import resolve
+
+    doc = to_document(
+        segment(steps=[("a", 1)], grid={**GRID, "origin": origin}),
+        doc_id="d",
+        title="t",
+    )
+    assert resolve(doc)["steps"][0]["start_s"] == pytest.approx(start)
+
+
+def test_resolve_without_an_origin_has_no_wall_clock():
+    from paces.model import resolve
+
+    doc = to_document(segment(steps=[("a", 1)], grid=GRID), doc_id="d", title="t")
+    doc = doc.model_copy(
+        update={"metric": doc.metric.model_copy(update={"origin": None})}
+    )
+    assert resolve(doc)["steps"][0]["start_s"] is None
+
+
+def test_resolve_treats_a_numeric_zero_origin_as_an_origin():
+    """A grid updated in place skips wire validation; 0 must still be 0 (#46)."""
+    from paces.model import resolve
+
+    doc = to_document(segment(steps=[("a", 1)], grid=GRID), doc_id="d", title="t")
+    doc = doc.model_copy(update={"metric": doc.metric.model_copy(update={"origin": 0})})
+    assert resolve(doc)["steps"][0]["start_s"] == 0.0