article 0.1.2__tar.gz → 0.1.3__tar.gz

{article-0.1.2 → article-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: article
-Version: 0.1.2
+Version: 0.1.3
 Summary: Tools to semi-automate the publication of articles
 Project-URL: Homepage, https://github.com/thorwhalen/article
 Project-URL: Repository, https://github.com/thorwhalen/article
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Text Processing :: Markup
 Requires-Python: >=3.10
-Requires-Dist: argh
+Requires-Dist: cw<0.2,>=0.1.1
 Requires-Dist: httpx
 Requires-Dist: pydantic-settings>=2
 Requires-Dist: pydantic>=2
@@ -158,7 +158,7 @@ async def publish(article, *, canonical_url, config, secrets):
 | Registry | `article/registry.py` | `PublishAdapter` protocol + open-closed registry |
 | Engine | `article/engine.py` | Orchestrates phase 1 → phase 2; canonical handoff; graceful errors |
 | Adapters | `article/adapters/*` | One module per platform (config + secrets injected) |
-| CLI | `article/__main__.py` | `argh` dispatch of the two commands |
+| CLI | `article/__main__.py` | `cw` dispatch of the two commands |
 
 > **Status:** the layers above are complete and tested; each adapter's actual
 > network / Playwright call is a clearly-marked `TODO` stub that returns a typed

{article-0.1.2 → article-0.1.3}/README.md

@@ -120,7 +120,7 @@ async def publish(article, *, canonical_url, config, secrets):
 | Registry | `article/registry.py` | `PublishAdapter` protocol + open-closed registry |
 | Engine | `article/engine.py` | Orchestrates phase 1 → phase 2; canonical handoff; graceful errors |
 | Adapters | `article/adapters/*` | One module per platform (config + secrets injected) |
-| CLI | `article/__main__.py` | `argh` dispatch of the two commands |
+| CLI | `article/__main__.py` | `cw` dispatch of the two commands |
 
 > **Status:** the layers above are complete and tested; each adapter's actual
 > network / Playwright call is a clearly-marked `TODO` stub that returns a typed

{article-0.1.2 → article-0.1.3}/article/__main__.py

@@ -15,10 +15,11 @@ takes ``--platforms medium,dev_to`` to syndicate a subset.
 
 from __future__ import annotations
 
+import argparse
 import json
 from typing import Optional
 
-import argh
+import cw
 
 from .base import ArticleError, RunSummary
 from .config import load_article, load_settings
@@ -39,12 +40,11 @@ def _prepare(article_path: str, *, env_file: Optional[str], state_path: Optional
         settings = load_settings(env_file=env_file, **overrides)
         article = load_article(article_path)
     except ArticleError as e:
-        raise argh.CommandError(str(e)) from e
+        raise cw.CommandError(str(e)) from e
     store = JsonStateStore(settings.state_path)
     return settings, article, store
 
 
-@argh.arg("article_path", help="Path to the article JSON file")
 def publish_primary(
     article_path: str,
     *,
@@ -60,7 +60,6 @@ def publish_primary(
     return _render(summary, json_out=json_out)
 
 
-@argh.arg("article_path", help="Path to the article JSON file")
 def syndicate_secondary(
     article_path: str,
     *,
@@ -81,26 +80,40 @@ def syndicate_secondary(
             )
         )
     except ArticleError as e:
-        raise argh.CommandError(str(e)) from e
+        raise cw.CommandError(str(e)) from e
     return _render(summary, json_out=json_out)
 
 
-#: SSOT list of dispatchable commands (argh maps ``_`` in names to ``-``).
+#: SSOT list of dispatchable commands (``cw`` maps ``_`` in names to ``-``).
 _dispatch_funcs = [publish_primary, syndicate_secondary]
 
+#: Per-parameter ``add_argument`` particulars the signature cannot carry -- here, the
+#: one ``help`` string that used to ride on an ``@argh.arg`` decorator. ``cw`` reads
+#: ``config``, never decorator metadata, so this is where such declarations live now.
+_dispatch_config = {
+    command: {"article_path": {"help": "Path to the article JSON file"}}
+    for command in ("publish-primary", "syndicate-secondary")
+}
 
-def main() -> None:
-    """Assemble the argh parser and dispatch (with optional tab completion)."""
-    parser = argh.ArghParser()
-    parser.add_commands(_dispatch_funcs)
-    try:
-        import argcomplete
 
-        argcomplete.autocomplete(parser)
-    except ImportError:
-        pass
-    parser.dispatch()
+def mk_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser -- a plain :class:`argparse.ArgumentParser`, no I/O.
+
+    The single place the command list and its per-parameter declarations meet, so a
+    test that inspects the grammar inspects the very parser :func:`main` dispatches.
+    """
+    return cw.mk_parser(_dispatch_funcs, config=_dispatch_config)
+
+
+def main() -> int:
+    """Dispatch a CLI command and return its exit code.
+
+    ``cw.run`` offers the parser to ``argcomplete`` itself (the
+    ``# PYTHON_ARGCOMPLETE_OK`` marker on line 1 is what the shell hook looks for),
+    so there is no hand-written completion block to keep in step.
+    """
+    return cw.run(mk_parser())
 
 
 if __name__ == "__main__":
-    main()
+    raise SystemExit(main())

{article-0.1.2 → article-0.1.3}/article/misc/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 AI-assisted change log (major changes only).
 
+## 2026-09-04 — CLI dispatch moves from argh to cw
+
+- **CLI** (`__main__.py`): replaced `argh` (LGPL) with
+  [`cw`](https://github.com/i2mint/cw) (MIT, zero runtime dependencies), which
+  reproduces argh's grammar bit-for-bit. All 11 recorded argv vectors — help
+  surfaces, argh's usage-to-stdout-and-exit-0 no-argument case, four grammar
+  errors and both `CommandError` paths — replay byte-identically in stdout,
+  stderr and exit code.
+- The two `@argh.arg(help=...)` decorators became a `_dispatch_config` mapping:
+  `cw` reads `config`, never decorator metadata, so the declaration had to move
+  or the help string would have been dropped silently.
+- `main()` now **returns** the exit code (`cw.run` returns where argh raised),
+  and the `__main__` guard does `raise SystemExit(main())`.
+- The hand-written `argcomplete` block is gone — `cw.run` fires completion itself.
+- **Tests** (`tests/test_cli.py`): new characterization suite pinning the grammar,
+  the migrated help string, the `CommandError` contract and the exit codes.
+
 ## 2026-06-21 — Initial pipeline scaffold (0.1.0)
 
 Built the full SSOT publishing pipeline skeleton, fully wired and importable:

{article-0.1.2 → article-0.1.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "article"
-version = "0.1.2"
+version = "0.1.3"
 description = "Tools to semi-automate the publication of articles"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -37,7 +37,7 @@ classifiers = [
 dependencies = [
     "pydantic>=2",
     "pydantic-settings>=2",
-    "argh",
+    "cw>=0.1.1,<0.2",
     "httpx",
     "python-dotenv",
 ]

article-0.1.3/tests/test_cli.py

@@ -0,0 +1,186 @@
+"""Characterization tests pinning the ``article`` command-line grammar.
+
+Recorded from the pre-migration ``argh`` implementation and replayed against
+:mod:`cw`. Three things here would not be caught by any other test:
+
+* the ``article-path`` **help string**, which used to ride on an ``@argh.arg``
+  decorator. ``cw`` reads ``config``, never decorator metadata, so deleting the
+  decorator without moving the declaration drops the help silently — no error, just a
+  quietly poorer ``--help``;
+* the ``CommandError`` contract — one line to stderr, no traceback, **exit 1**;
+* the exit code itself, which ``cw.dispatch`` *returns* where argh raised it, so
+  ``__main__`` must ``raise SystemExit(main())``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+
+import pytest
+
+from article.__main__ import _dispatch_funcs, main, mk_parser
+
+COMMANDS = ("publish-primary", "syndicate-secondary")
+
+
+@pytest.fixture(scope="module")
+def parser():
+    """The very parser :func:`article.__main__.main` dispatches, built without I/O.
+
+    Built through ``mk_parser`` rather than reassembled here, so a declaration that
+    stops reaching the real parser cannot keep passing these tests. ``sys.argv[0]`` is
+    pinned because argparse derives ``prog`` from it at construction time.
+    """
+    argv = sys.argv
+    sys.argv = ["article"]
+    try:
+        return mk_parser()
+    finally:
+        sys.argv = argv
+
+
+@pytest.fixture(scope="module")
+def subparsers(parser):
+    action = next(
+        a for a in parser._actions if isinstance(a, argparse._SubParsersAction)
+    )
+    return action.choices
+
+
+def _run(*argv, cwd=None):
+    """Run ``python -m article ARGV`` end to end."""
+    env = {k: v for k, v in os.environ.items() if k != "COLUMNS"}
+    return subprocess.run(
+        [sys.executable, "-m", "article", *argv],
+        capture_output=True,
+        text=True,
+        cwd=cwd,
+        env={"COLUMNS": "80", **env},
+    )
+
+
+# --------------------------------------------------------------------------- grammar
+
+
+def test_the_two_phases_are_the_two_commands(parser, subparsers):
+    assert [f.__name__ for f in _dispatch_funcs] == [
+        "publish_primary",
+        "syndicate_secondary",
+    ]
+    assert tuple(subparsers) == COMMANDS
+    assert parser.format_usage() == (
+        "usage: article [-h] {publish-primary,syndicate-secondary} ...\n"
+    )
+
+
+@pytest.mark.parametrize(
+    "command, usage",
+    [
+        (
+            "publish-primary",
+            "usage: article publish-primary [-h] [-e ENV_FILE] [-s STATE_PATH] [-j]"
+            " article-path",
+        ),
+        (
+            "syndicate-secondary",
+            "usage: article syndicate-secondary [-h] [-e ENV_FILE] [-s STATE_PATH]"
+            " [-p PLATFORMS] [-j] article-path",
+        ),
+    ],
+)
+def test_each_command_keeps_its_recorded_usage_line(subparsers, command, usage):
+    """Flag spellings and short options, exactly as argh rendered them.
+
+    Line wrapping is normalised away — it depends on the terminal width the test
+    happens to run under.
+    """
+    assert " ".join(subparsers[command].format_usage().split()) == usage
+
+
+@pytest.mark.parametrize("command", COMMANDS)
+def test_the_positional_keeps_the_help_that_used_to_be_an_argh_arg(
+    subparsers, command
+):
+    """The migrated ``@argh.arg(help=...)`` declaration.
+
+    ``cw`` does **not** read argh's decorator metadata, so dropping
+    ``_dispatch_config`` would leave this help string at the ``-`` placeholder with no
+    error anywhere. This test is the only thing that would notice.
+    """
+    positional = next(
+        a for a in subparsers[command]._actions if not a.option_strings
+    )
+    assert positional.dest == "article-path"  # argh hyphenates positionals
+    assert positional.help == "Path to the article JSON file"
+
+
+@pytest.mark.parametrize("command", COMMANDS)
+def test_defaults_match_the_function_signatures(subparsers, command):
+    namespace = subparsers[command].parse_args(["a.json"])
+    assert getattr(namespace, "article-path") == "a.json"
+    assert namespace.env_file is None
+    assert namespace.state_path is None
+    assert namespace.json_out is False
+
+
+def test_platforms_is_only_on_phase_two(subparsers):
+    def usage(command):
+        return " ".join(subparsers[command].format_usage().split())
+
+    assert "-p PLATFORMS" in usage("syndicate-secondary")
+    assert "-p PLATFORMS" not in usage("publish-primary")
+
+
+# ------------------------------------------------------------------------ exit codes
+
+
+def test_no_arguments_prints_usage_to_stdout_and_exits_zero():
+    """argh's behaviour, which bare argparse does not reproduce. Pinned deliberately."""
+    done = _run()
+    assert done.returncode == 0
+    assert done.stdout.startswith("usage: ")
+    assert done.stderr == ""
+
+
+@pytest.mark.parametrize(
+    "argv",
+    [
+        ("no-such-command",),
+        ("publish-primary",),  # missing required positional
+        ("syndicate-secondary",),  # missing required positional
+        ("publish-primary", "--env-file"),  # option missing its value
+    ],
+)
+def test_bad_invocations_exit_two(argv):
+    done = _run(*argv)
+    assert done.returncode == 2
+    assert done.stdout == ""
+    assert done.stderr.startswith("usage: ")
+
+
+@pytest.mark.parametrize("command", COMMANDS)
+def test_an_unreadable_article_is_a_command_error_not_a_traceback(command, tmp_path):
+    """``CommandError``: one line to stderr, **exit 1**, and no traceback."""
+    done = _run(command, "no_such_article.json", cwd=tmp_path)
+    assert done.returncode == 1
+    assert done.stdout == ""
+    assert done.stderr.startswith("CommandError: Could not read article from ")
+    assert "Traceback" not in done.stderr
+
+
+def test_main_returns_the_exit_code_rather_than_swallowing_it(monkeypatch, tmp_path):
+    """The in-process half: ``main()`` yields an int, not ``None``.
+
+    This is what makes ``raise SystemExit(main())`` in ``__main__`` — and the console
+    script's own ``sys.exit(main())`` — report the failure instead of success.
+    """
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(sys, "argv", ["article", "no-such-command"])
+    assert main() == 2
+    monkeypatch.setattr(
+        sys, "argv", ["article", "publish-primary", "no_such_article.json"]
+    )
+    assert main() == 1