paces 0.0.20__tar.gz → 0.0.22__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.20
+Version: 0.0.22
 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.20 → paces-0.0.22}/paces/measure.py

@@ -45,6 +45,7 @@ from paces.model import MetricGrid, decimal_str, seconds_per_unit
 from paces.segmenters import (
     Capability,
     Segmentation,
+    check_step_durations,
     place_on_grid,
     register,
 )
@@ -231,7 +232,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 +244,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 +268,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))
@@ -300,6 +309,8 @@ def _segment_grid_measured(inputs: Mapping[str, Any]) -> Segmentation:
     partial: MetricGrid | None = inputs["grid"]
     unit = partial.unit if partial is not None else DFLT_UNIT
     subdivisions = partial.subdivisions if partial is not None else DFLT_SUBDIVISIONS
+    # bad durations fail here, before the costly measurement, not after it
+    check_step_durations(inputs["steps"], who="grid-measured")
     total_units = sum(row["duration"] for row in inputs["steps"])
     measurement = measure_grid(
         inputs["media"],

{paces-0.0.20 → paces-0.0.22}/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.20 → paces-0.0.22}/paces/segmenters.py

@@ -39,7 +39,7 @@ from __future__ import annotations
 import importlib
 import math
 import time
-from collections.abc import Mapping, Sequence
+from collections.abc import Iterable, Mapping, Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Callable
@@ -131,18 +131,31 @@ def _slugify(text: str) -> str:
     return slug or "step"
 
 
-def unique_slug_ids(names: Sequence[str], *, fallback: str = "step") -> list[str]:
+def unique_slug_ids(
+    names: Sequence[str], *, fallback: str = "step", taken: Iterable[str] = ()
+) -> list[str]:
     """One unique, git-readable id per name; unnamed ones get ``{fallback}-{i}``.
 
+    An id already in ``taken`` (or produced earlier in this call) gets a
+    ``-2``, ``-3``… suffix — the first one free. ``taken`` is only read.
+
     >>> unique_slug_ids(["Turn", "", "Turn"], fallback="cue")
     ['turn', 'cue-2', 'turn-2']
+    >>> unique_slug_ids(["Turn", "Turn", "Turn 2"])
+    ['turn', 'turn-2', 'turn-2-2']
+    >>> unique_slug_ids(["Turn"], taken={"turn"})
+    ['turn-2']
     """
-    seen: dict[str, int] = {}
+    used = set(taken)
     ids = []
     for index, name in enumerate(names):
-        slug = _slugify(name) if name else f"{fallback}-{index + 1}"
-        seen[slug] = seen.get(slug, 0) + 1
-        ids.append(slug if seen[slug] == 1 else f"{slug}-{seen[slug]}")
+        base = _slugify(name) if name else f"{fallback}-{index + 1}"
+        candidate, n = base, 1
+        while candidate in used:
+            n += 1
+            candidate = f"{base}-{n}"
+        used.add(candidate)
+        ids.append(candidate)
     return ids
 
 
@@ -150,29 +163,104 @@ def _normalize_steps(steps: Sequence | None) -> list[dict]:
     """Accept names, (name, duration) pairs, or mappings; emit uniform dicts.
 
     Uniform shape: ``{id, name, duration (float units or None), spans, children}``.
+    Ids are unique across the whole tree, as a document requires. An id the
+    caller gave is kept as given, and two equal ones are a ``ValueError``
+    naming both paths. A generated one is the name's slug, suffixed ``-2``,
+    ``-3``… when taken; generation runs breadth-first (every top-level row,
+    then each level of children), so editing children never renames a parent.
+    A generated id still follows position among same-named steps — give
+    repeated steps that must keep their identity across edits explicit ids.
+
+    >>> [r["id"] for r in _normalize_steps(["Turn", "Turn", {"name": "x", "id": "turn-2"}])]
+    ['turn', 'turn-3', 'turn-2']
     """
+    rows = _step_rows(steps, where="steps")
+
+    def _paths(rows: list[dict], where: str):
+        for i, row in enumerate(rows):
+            yield f"{where}[{i}]", row
+            yield from _paths(row["children"], f"{where}[{i}].children")
+
+    explicit: dict[str, str] = {}
+    for path, row in _paths(rows, "steps"):
+        if row["id"] is None:
+            continue
+        if row["id"] in explicit:
+            raise ValueError(
+                f"duplicate step id {row['id']!r} at {explicit[row['id']]} and {path}"
+            )
+        explicit[row["id"]] = path
+
+    taken = set(explicit)
+    level = rows
+    while level:
+        pending = [row for row in level if row["id"] is None]
+        ids = unique_slug_ids(
+            [row.get("name") or "step" for row in pending], taken=taken
+        )
+        for row, step_id in zip(pending, ids):
+            row["id"] = step_id
+        taken.update(ids)
+        level = [child for row in level for child in row["children"]]
+    return rows
+
+
+def _walk_rows(rows: list[dict]):
+    """Every row of a normalised step tree, parents before children."""
+    for row in rows:
+        yield row
+        yield from _walk_rows(row["children"])
+
+
+def _undated_ids(rows: list[dict]) -> list[str]:
+    """Ids of the (nested) normalised rows that have no duration."""
+    return [row["id"] for row in _walk_rows(rows) if row["duration"] is None]
+
+
+def check_step_durations(rows: list[dict], *, who: str = "place_on_grid") -> None:
+    """Raise ``ValueError`` unless every (nested) row has a positive, finite
+    duration — the precondition for placing a step list on a grid. ``rows``
+    are normalised step rows (what :func:`segment` hands a segmenter in
+    ``inputs["steps"]``), not the raw forms :func:`segment` accepts."""
+    undated = _undated_ids(rows)
+    if undated:
+        raise ValueError(f"{who} needs a duration for every step: {undated}")
+    bad = [
+        row["id"]
+        for row in _walk_rows(rows)
+        if not (math.isfinite(row["duration"]) and row["duration"] > 0)
+    ]
+    if bad:
+        raise ValueError(f"{who} needs positive, finite durations: {bad}")
+
+
+def _step_rows(steps: Sequence | None, *, where: str) -> list[dict]:
     if steps is None:
         return []
     rows: list[dict] = []
     for i, item in enumerate(steps):
+        is_sequence = isinstance(item, Sequence) and not isinstance(item, bytes)
         if isinstance(item, str):
             row = {"name": item}
         elif isinstance(item, Mapping):
             row = dict(item)
-        elif isinstance(item, Sequence):
+        elif is_sequence and len(item) == 2:
             name, duration = item
             row = {"name": name, "duration": duration}
         else:
+            got = f"a {len(item)}-item sequence" if is_sequence else type(item).__name__
             raise TypeError(
-                f"steps[{i}]: expected a name, a (name, duration) pair, or a "
-                f"mapping — got {type(item).__name__}"
+                f"{where}[{i}]: expected a name, a (name, duration) pair, or a "
+                f"mapping — got {got}"
             )
-        row.setdefault("id", _slugify(row.get("name", "")) or f"step-{i + 1}")
+        row["id"] = row.get("id")
         row["duration"] = (
             None if row.get("duration") is None else float(row["duration"])
         )
         row["spans"] = [tuple(map(float, s)) for s in row.get("spans", ())]
-        row["children"] = _normalize_steps(row.get("children") or row.get("steps"))
+        row["children"] = _step_rows(
+            row.get("children") or row.get("steps"), where=f"{where}[{i}].children"
+        )
         rows.append(row)
     return rows
 
@@ -296,8 +384,8 @@ def _facts(
             pass
     if steps:
         facts.add("steps")
-        if all(row["duration"] is not None for row in steps):
-            facts.add("steps.durations")
+        if not _undated_ids(steps):
+            facts.add("steps.durations")  # children too: placement needs them all
         if any(row["spans"] for row in steps):
             facts.add("steps.spans")
     if boundaries:
@@ -371,6 +459,11 @@ def segment(
     chapters = _normalize_chapters(metadata)
     subtitles, subtitles_problem = _subtitle_cues(metadata)
     problem_flags = (subtitles_problem,) if subtitles_problem else ()
+    undated = _undated_ids(step_rows)
+    if undated and len(undated) < sum(1 for _ in _walk_rows(step_rows)):
+        # durations were given but not for all: say which, so a refused or
+        # unplaced result never just asks for what the caller supplied
+        problem_flags += (f"steps-undated: {undated}",)
     transcript_cues = normalize_timed_text(transcript)
     # fail fast: a malformed log raises before any segmenter runs
     correction_log = (
@@ -412,9 +505,15 @@ def segment(
             raise ValueError(f"unknown segmenter {segmenter!r}; registered: {known}")
         missing_facts = capability.needs - facts
         if missing_facts:
+            undated_note = (
+                f"; steps without a duration: {undated}"
+                if "steps.durations" in missing_facts and undated
+                else ""
+            )
             raise ValueError(
                 f"segmenter {capability.name!r} needs inputs you did not "
-                f"provide: {sorted(missing_facts)} (facts present: {sorted(facts)})"
+                f"provide: {sorted(missing_facts)} (facts present: "
+                f"{sorted(facts)}){undated_note}"
             )
     else:
         candidates = [
@@ -516,11 +615,6 @@ def place_on_grid(steps: Sequence, grid: MetricGrid | Mapping) -> Segmentation:
     ([((1.0, 5.0),), ((5.0, 13.0),)], (1.0, 5.0, 13.0))
     """
 
-    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:
@@ -534,16 +628,7 @@ def place_on_grid(steps: Sequence, grid: MetricGrid | Mapping) -> Segmentation:
         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}")
+    check_step_durations(rows)
     spu = seconds_per_unit(grid)
     origin = float(grid.origin)
 

{paces-0.0.20 → paces-0.0.22}/pyproject.toml

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

{paces-0.0.20 → paces-0.0.22}/tests/test_ask.py

@@ -456,7 +456,8 @@ def test_js_repeated_names_are_separate_rows():
     """verse/chorus/verse: each occurrence is marked on its own, and replays."""
     names = ["verse", "chorus", "verse"]
     proposal = propose(segment(boundaries=CUTS, steps=names))
-    assert [s["id"] for s in proposal["steps"]] == names  # ids repeat
+    # ids are unique now (#47), but rows stay the key: names still repeat
+    assert [s["id"] for s in proposal["steps"]] == ["verse", "chorus", "verse-2"]
     answers = _answers_after(proposal, [{"type": "absent", "index": 2, "on": True}])
     assert [(c["verb"], c["anchorT"]) for c in answers["corrections"]] == [
         ("absent", "25")

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

@@ -199,3 +199,141 @@ def test_place_on_grid_names_what_is_missing(steps, grid, match):
 
     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
+
+
+def test_duplicate_step_names_get_unique_ids_tree_wide():
+    """Edits, locks and the evidence layer address steps by id (#47)."""
+    steps = [
+        ("Turn", 2),
+        ("Turn", 2),
+        {"name": "Kick", "duration": 4, "children": [("Turn", 2), ("Turn", 2)]},
+    ]
+    seg = segment(steps=steps, grid=GRID)
+    ids = [seg.steps[0].id, seg.steps[1].id, *(c.id for c in seg.steps[2].children)]
+    assert ids == ["turn", "turn-2", "turn-3", "turn-4"]
+    doc = to_document(seg, doc_id="d", title="t")
+    from paces.model import validate_document
+
+    assert not [i for i in validate_document(doc) if "duplicate step id" in i]
+
+
+def test_an_explicit_step_id_is_kept_and_never_reused():
+    seg = segment(
+        steps=[("Turn", 1), {"name": "x", "id": "turn", "duration": 1}], grid=GRID
+    )
+    assert [s.id for s in seg.steps] == ["turn-2", "turn"]
+
+
+def test_a_step_that_is_neither_name_pair_nor_mapping_is_named_in_the_error():
+    with pytest.raises(TypeError, match=r"steps\[1\].*3-item sequence"):
+        segment(steps=[("a", 1), ("b", 1, "extra")], grid=GRID)
+    with pytest.raises(TypeError, match=r"steps\[0\]\.children\[0\]"):
+        segment(steps=[{"name": "p", "duration": 1, "children": [3]}], grid=GRID)
+
+
+def test_bytes_is_not_a_name_duration_pair():
+    with pytest.raises(TypeError, match=r"steps\[0\].*got bytes"):
+        segment(steps=[b"ab"], grid=GRID)
+
+
+def test_duplicate_explicit_ids_name_both_paths():
+    steps = [
+        {"name": "a", "id": "x", "duration": 1},
+        ("b", 1),
+        {"name": "c", "duration": 2, "children": [("d", 1), {"name": "e", "id": "x"}]},
+    ]
+    with pytest.raises(
+        ValueError, match=r"'x' at steps\[0\] and steps\[2\]\.children\[1\]"
+    ):
+        segment(steps=steps, grid=GRID)
+
+
+def test_generated_ids_are_breadth_first_so_children_never_rename_parents():
+    before = segment(steps=[{"name": "Turn", "duration": 2}, ("Turn", 2)], grid=GRID)
+    after = segment(
+        steps=[{"name": "Turn", "duration": 2, "children": [("Turn", 2)]}, ("Turn", 2)],
+        grid=GRID,
+    )
+    assert [s.id for s in before.steps] == [s.id for s in after.steps]
+    assert [s.id for s in after.steps] == ["turn", "turn-2"]
+    assert after.steps[0].children[0].id == "turn-3"
+
+
+def test_partly_undated_steps_are_named_in_a_flag():
+    """The refused state's 'try:' must not read as if no durations were given."""
+    steps = [("a", 2), {"name": "p", "duration": 2, "children": ["u"]}]
+    seg = segment(steps=steps, grid=GRID)
+    assert "steps-undated: ['u']" in seg.flags
+    assert not [f for f in segment(steps=["a"], grid=GRID).flags if "undated" in f]
+
+
+def _forbid_measuring(monkeypatch):
+    import paces.measure
+
+    def _measure_grid(*args, **kwargs):
+        raise AssertionError("measure_grid must not be called")
+
+    monkeypatch.setattr(paces.measure, "measure_grid", _measure_grid)
+
+
+def test_an_undated_child_keeps_placement_from_being_selected(tmp_path, monkeypatch):
+    """'steps.durations' covers children, so no placing segmenter is chosen —
+    and grid-measured is never asked to measure for a list it cannot place."""
+    steps = [{"name": "p", "duration": 2, "children": ["undated"]}]
+    seg = segment(steps=steps, grid=GRID)
+    assert seg.method != "grid-placed"
+    media = tmp_path / "song.wav"
+    media.write_bytes(b"")
+    _forbid_measuring(monkeypatch)
+    with pytest.raises(
+        ValueError,
+        match=r"needs inputs you did not provide: \['steps\.durations'\]"
+        r".*steps without a duration: \['undated'\]",
+    ):
+        segment(str(media), steps=steps, segmenter="grid-measured")
+
+
+@pytest.mark.parametrize("bad", [0, -1, float("nan")])
+def test_grid_measured_rejects_bad_durations_before_measuring(
+    bad, tmp_path, monkeypatch
+):
+    pytest.importorskip("mixing")
+    pytest.importorskip("librosa")
+    media = tmp_path / "song.wav"
+    media.write_bytes(b"")
+    _forbid_measuring(monkeypatch)
+    steps = [("a", 1), {"name": "p", "duration": 2, "children": [("c", bad)]}]
+    with pytest.raises(ValueError, match=r"positive, finite durations: \['c'\]"):
+        segment(str(media), steps=steps, segmenter="grid-measured")