paces 0.0.19__tar.gz → 0.0.20__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.19
+Version: 0.0.20
 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.20}/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,
 )
 
@@ -318,7 +318,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.20}/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.20}/pyproject.toml

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

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

@@ -170,3 +170,32 @@ 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)