paces 0.0.6__tar.gz → 0.0.7__tar.gz

{paces-0.0.6 → paces-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.6
+Version: 0.0.7
 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
@@ -17,9 +17,9 @@ Requires-Dist: mixing[audio,beats]>=0.0.36; extra == 'audio'
 Requires-Dist: numba>=0.59; extra == 'audio'
 Provides-Extra: cli
 Requires-Dist: argcomplete>=3; extra == 'cli'
-Requires-Dist: argh>=0.30; extra == 'cli'
+Requires-Dist: cw<0.2,>=0.1.1; extra == 'cli'
 Provides-Extra: dev
-Requires-Dist: argh>=0.30; extra == 'dev'
+Requires-Dist: cw<0.2,>=0.1.1; extra == 'dev'
 Requires-Dist: mixing[audio,beats]>=0.0.39; extra == 'dev'
 Requires-Dist: numba>=0.59; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'

paces-0.0.7/paces/__main__.py

@@ -0,0 +1,39 @@
+# PYTHON_ARGCOMPLETE_OK
+"""paces CLI entry point — ``python -m paces`` / ``paces`` (after install)."""
+
+from __future__ import annotations
+
+import dataclasses
+
+import cw
+
+from paces.tools import _dispatch_funcs
+
+#: Positional args (with or without defaults) stay positional; the keyword-only args
+#: every tool uses become ``--flags``.
+#:
+#: This is ``argh``'s post-0.30 ``BY_NAME_IF_KWONLY`` policy, which this CLI has always
+#: run on and which cw spells the same way. It is **not** cw's default: ``cw.ARGH``
+#: reproduces ``argh.dispatch_commands`` instead, under which a defaulted positional
+#: becomes an option. ``segment(media=None, *, ...)`` is exactly that shape, so the
+#: difference is the difference between ``paces segment video.mp4`` and
+#: ``paces segment --media video.mp4``. The former is what the docs, the smoke test and
+#: the vertical-slice test all type.
+CONVENTION = dataclasses.replace(cw.ARGH, naming=cw.BY_NAME_IF_KWONLY)
+
+
+def main() -> None:
+    """Build the parser over the paces tools and dispatch.
+
+    ``cw.run`` offers the parser to ``argcomplete`` before parsing, exactly where
+    ``argh``'s dispatch did, so ``PYTHON_ARGCOMPLETE_OK`` above still applies with no
+    hand-written completion block here. It *returns* the exit code rather than raising
+    it, which is why the ``SystemExit`` is written out: without it every usage error
+    would exit 0, and the end-to-end tests all assert ``returncode == 0``.
+    """
+    parser = cw.mk_parser(_dispatch_funcs, convention=CONVENTION)
+    raise SystemExit(cw.run(parser))
+
+
+if __name__ == "__main__":
+    main()

{paces-0.0.6 → paces-0.0.7}/paces/tools.py

@@ -1,7 +1,7 @@
 """Agent-callable tool surface over ``paces`` — plain functions with JSON-able
 arguments returning JSON-ready values, deliberately CLI/MCP/HTTP-agnostic.
 
-This module is the SSOT for "what paces can do": every surface (the ``argh``
+This module is the SSOT for "what paces can do": every surface (the ``cw``
 CLI in ``__main__.py`` today; ``py2mcp``/``qh`` wrappers tomorrow) dispatches
 over ``_dispatch_funcs`` and nothing else. Arguments that carry structure
 (steps, grids, documents) accept a Python object, a JSON string, or a path to

{paces-0.0.6 → paces-0.0.7}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paces"
-version = "0.0.6"
+version = "0.0.7"
 description = "Turn instructional media into structured, interactive learning material"
 readme = "README.md"
 license = "MIT"
@@ -36,7 +36,7 @@ Documentation = "https://thorwhalen.github.io/paces"
 paces = "paces.__main__:main"
 
 [project.optional-dependencies]
-cli = ["argh>=0.30", "argcomplete>=3"]
+cli = ["cw>=0.1.1,<0.2", "argcomplete>=3"]
 audio = [
     # Grid measurement (issue #2): the fleet's `mixing` owns speech/music
     # segmentation and beat tracking; [beats] pulls librosa, [audio] pulls
@@ -63,9 +63,9 @@ dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
     "ruff>=0.1.0",
-    # The CLI smoke test runs `python -m paces ...`; without argh in dev it
+    # The CLI smoke test runs `python -m paces ...`; without cw in dev it
     # would fail rather than silently skip — keep it mirrored with [cli].
-    "argh>=0.30",
+    "cw>=0.1.1,<0.2",
     # The grid-measurement tests exercise the real mixing/librosa path on
     # synthesized audio; mirrored with [audio] so they run rather than skip.
     # The derivation tests do the same on synthetic video — mirrored with

paces-0.0.7/tests/test_cli_surface.py

@@ -0,0 +1,133 @@
+"""The command line itself: which argv spellings `paces` accepts, and what they exit.
+
+``tests/test_smoke.py`` and ``tests/test_vertical_slice.py`` already drive the CLI
+end to end — but both only ever pass argv that works, and both assert
+``returncode == 0``, so a CLI that had stopped reporting failure at all would sail
+through them. This file pins the shape of the surface instead: the naming policy in
+both directions, and the exit codes.
+
+Recorded from the ``argh`` implementation before the ``cw`` migration and replayed
+after: 20 argv vectors compared byte-for-byte on stdout, stderr and exit code, plus
+four vectors whose stderr carries a traceback (compared on exit code and the
+exception's own line, since a traceback names line numbers that the edit moved).
+No diffs. That full-body diff cannot live in CI, because CPython rewrites argparse's
+own option column between versions, so what is asserted here is the grammar.
+
+**The naming policy is the load-bearing part.** `paces` runs on argh's post-0.30
+``BY_NAME_IF_KWONLY``: positional parameters stay positional, keyword-only parameters
+become ``--flags``. That is *not* cw's default — ``cw.ARGH`` reproduces
+``argh.dispatch_commands``, under which a parameter with a default becomes an option.
+``segment(media=None, *, ...)`` is exactly that shape, so under the default
+``paces segment video.mp4`` would become ``paces segment --media video.mp4``: the
+form every doc, the smoke test and the vertical slice actually type would stop
+parsing. So both halves are asserted — the positional is accepted AND the option
+spelling is rejected.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+import pytest
+
+from paces.__main__ import CONVENTION
+from paces.tools import _dispatch_funcs
+
+_CLI_TIMEOUT = 120
+
+#: Every verb the CLI exposes, spelled as the command line spells it.
+COMMAND_NAMES = [f.__name__.replace("_", "-") for f in _dispatch_funcs]
+
+
+def run_cli(*argv, cwd):
+    """Run ``python -m paces <argv>``, which is how both existing CLI tests enter."""
+    return subprocess.run(
+        [sys.executable, "-m", "paces", *argv],
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+        timeout=_CLI_TIMEOUT,
+        env={**os.environ, "COLUMNS": "80"},
+    )
+
+
+def test_every_tool_is_reachable_and_documents_itself(tmp_path):
+    """``_dispatch_funcs`` is the SSOT; every name in it is a subcommand."""
+    top = run_cli("--help", cwd=tmp_path)
+    assert top.returncode == 0
+    for name in COMMAND_NAMES:
+        assert name in top.stdout, f"{name} missing from `paces --help`"
+        sub = run_cli(name, "--help", cwd=tmp_path)
+        assert sub.returncode == 0, sub.stderr
+        assert "usage: " in sub.stdout
+
+
+def test_media_is_a_positional_not_an_option(tmp_path):
+    """The naming policy, in both directions. See the module docstring."""
+    help_ = run_cli("segment", "--help", cwd=tmp_path)
+    assert "[media]" in help_.stdout
+    assert "--media" not in help_.stdout
+
+    # Accepted as a bare word — the form the smoke test and the docs type.
+    positional = run_cli("segment", "media.mp4", cwd=tmp_path)
+    assert positional.returncode == 0
+
+    # And the option spelling does not exist. Under cw's default convention this
+    # would be the *only* spelling that worked.
+    optional = run_cli("segment", "--media", "media.mp4", cwd=tmp_path)
+    assert optional.returncode == 2
+
+
+def test_keyword_only_parameters_are_flags(tmp_path):
+    """The other half of BY_NAME_IF_KWONLY: every kwonly arg is a ``--flag``."""
+    help_ = run_cli("to-document", "--help", cwd=tmp_path)
+    for flag in ("--doc-id", "--title", "--source", "--domain", "--lang", "--output"):
+        assert flag in help_.stdout
+    # ...and the one positional parameter is still a bare word in the usage line.
+    usage = help_.stdout.split("\n\n", 1)[0]
+    assert "segmentation" in usage
+    assert "--segmentation" not in help_.stdout
+
+
+def test_the_convention_is_the_one_the_cli_was_built_on():
+    """A guard on the constant itself, so a refactor cannot quietly drop it."""
+    import cw
+
+    assert CONVENTION.naming is cw.BY_NAME_IF_KWONLY
+    assert CONVENTION.naming is not cw.ARGH.naming
+
+
+@pytest.mark.parametrize(
+    "argv",
+    [
+        ("no-such-command",),
+        ("segment", "--no-such-flag"),
+        ("render",),  # a required positional, omitted
+        ("segment", "extra1", "extra2"),
+        ("edit", "doc"),  # `edits` and the required --by are both missing
+    ],
+)
+def test_usage_errors_exit_two(argv, tmp_path):
+    """``cw.run`` returns the code, so ``main`` must ``raise SystemExit`` on it.
+
+    Both existing end-to-end CLI tests assert ``returncode == 0``; without this,
+    a CLI that had stopped reporting failure entirely would still pass them.
+    """
+    assert run_cli(*argv, cwd=tmp_path).returncode == 2
+
+
+def test_a_failing_command_exits_nonzero(tmp_path):
+    """An unknown segmenter is a real failure, and the shell has to hear about it."""
+    result = run_cli("segment", "--segmenter", "nope", cwd=tmp_path)
+    assert result.returncode != 0
+    assert "unknown segmenter" in result.stderr
+
+
+def test_no_arguments_prints_usage_to_stdout_and_exits_zero(tmp_path):
+    """argh's behaviour; plain argparse with a required subparser does NOT do this."""
+    result = run_cli(cwd=tmp_path)
+    assert result.returncode == 0
+    assert result.stdout.startswith("usage: ")
+    assert result.stderr == ""

paces-0.0.6/paces/__main__.py

@@ -1,31 +0,0 @@
-# PYTHON_ARGCOMPLETE_OK
-"""paces CLI entry point — ``python -m paces`` / ``paces`` (after install)."""
-
-from __future__ import annotations
-
-import argh
-
-from paces.tools import _dispatch_funcs
-
-
-def main() -> None:
-    """Build the argh parser over the paces tools and dispatch."""
-    from argh.assembling import NameMappingPolicy
-
-    parser = argh.ArghParser()
-    # Positional args (with or without defaults) stay positional; the
-    # keyword-only args every tool uses become --flags.
-    parser.add_commands(
-        _dispatch_funcs, name_mapping_policy=NameMappingPolicy.BY_NAME_IF_KWONLY
-    )
-    try:
-        import argcomplete
-
-        argcomplete.autocomplete(parser)
-    except ImportError:
-        pass
-    parser.dispatch()
-
-
-if __name__ == "__main__":
-    main()