paces 0.0.21__tar.gz → 0.0.23__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.21
+Version: 0.0.23
 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.21 → paces-0.0.23}/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,
 )
@@ -308,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.21 → paces-0.0.23}/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,10 +384,10 @@ def _facts(
             pass
     if steps:
         facts.add("steps")
-        if all(row["duration"] is not None for row in steps):
-            facts.add("steps.durations")
-        if any(row["spans"] for row in steps):
-            facts.add("steps.spans")
+        if not _undated_ids(steps):
+            facts.add("steps.durations")  # children too: placement needs them all
+        if any(row["spans"] for row in _walk_rows(steps)):
+            facts.add("steps.spans")  # like steps.durations: the whole tree
     if boundaries:
         facts.add("boundaries")
     if grid is not None and grid.tempo_bpm is not None and grid.origin is not None:
@@ -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.21 → paces-0.0.23}/pyproject.toml

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

{paces-0.0.21 → paces-0.0.23}/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.21 → paces-0.0.23}/tests/test_segment.py

@@ -8,7 +8,13 @@ import pytest
 
 from paces.model import MetricGrid
 from paces.projection import to_document
-from paces.segmenters import Capability, capabilities, register, segment
+from paces.segmenters import (
+    Capability,
+    Segmentation,
+    capabilities,
+    register,
+    segment,
+)
 
 GRID = {"unit": "eight", "subdivisions": 8, "tempoBpm": "129.2", "origin": "51.2"}
 #: The POC routine as (name, eights) pairs — kickoff's "common real case".
@@ -231,3 +237,132 @@ def test_resolve_treats_a_numeric_zero_origin_as_an_origin():
     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")
+
+
+def _spans_reader(inputs):
+    return Segmentation(boundaries=(0.0, 1.0))
+
+
+def test_the_spans_fact_reads_the_whole_step_tree():
+    """A span on a child counts, as a duration on a child does (#51): a
+    segmenter that needs ``steps.spans`` is selectable from a nested span."""
+    needs_spans = Capability(
+        name="needs-spans",
+        gives="segmentation",
+        summary="test double",
+        target=f"{__name__}:_spans_reader",
+        needs=frozenset({"steps", "steps.spans"}),
+    )
+    catalog = {"needs-spans": needs_spans}
+    nested = [
+        {"name": "p", "duration": 2, "children": [{"name": "c", "spans": [(1, 2)]}]}
+    ]
+    assert segment(steps=nested, catalog=catalog).method == "needs-spans"
+    refused = segment(steps=[("p", 2)], catalog=catalog)
+    assert refused.method == "" and "no-signal" in refused.flags