strictcli 0.34.0__tar.gz → 0.35.2__tar.gz

{strictcli-0.34.0 → strictcli-0.35.2}/.rlsbl/config.json

@@ -10,6 +10,5 @@
       "target": "pypi",
       "local": false
     }
-  },
-  "coverage_unit": "commit"
+  }
 }

{strictcli-0.34.0 → strictcli-0.35.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strictcli
-Version: 0.34.0
+Version: 0.35.2
 Summary: A strict CLI framework for Python
 Project-URL: Homepage, https://github.com/smm-h/strictcli
 Project-URL: Repository, https://github.com/smm-h/strictcli

{strictcli-0.34.0 → strictcli-0.35.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "strictcli"
-version = "0.34.0"
+version = "0.35.2"
 description = "A strict CLI framework for Python"
 readme = "README.md"
 license = "MIT"

strictcli-0.35.2/scripts/add_effect_classification.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Mechanical sweep: add the mandatory ``effect=`` classification to command
+registrations that lack it.
+
+The effects regime makes ``effect="read_only" | "mutating"`` mandatory on every
+command. This script rewrites ``.command(...)`` call sites that do not already
+declare it, inserting the keyword immediately before the (always present,
+always keyword-passed) ``help=`` argument so the result stays readable:
+
+    @app.command("deploy", effect="read_only", help="deploy the app")
+
+Only ``.command(...)`` attribute calls are touched; ``.group(...)``,
+``.deprecate(...)`` and everything else are left alone. Files are rewritten in
+place. Re-running is a no-op (sites that already declare ``effect=`` are
+skipped).
+
+Usage:
+    scripts/add_effect_classification.py [--effect read_only] FILE [FILE ...]
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import sys
+from pathlib import Path
+
+
+def _insertions(source: str, effect: str) -> list[tuple[int, int, str]]:
+    """Return (lineno, col_offset, text) insertion points, one per call site."""
+    tree = ast.parse(source)
+    points: list[tuple[int, int, str]] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        func = node.func
+        if not isinstance(func, ast.Attribute) or func.attr != "command":
+            continue
+        kw_names = {kw.arg for kw in node.keywords}
+        if "effect" in kw_names:
+            continue
+        help_kw = next((kw for kw in node.keywords if kw.arg == "help"), None)
+        if help_kw is None:
+            raise SystemExit(
+                f"command registration without help= at line {node.lineno}; "
+                "insertion anchor missing"
+            )
+        points.append((help_kw.lineno, help_kw.col_offset, f'effect="{effect}", '))
+    return points
+
+
+def rewrite(path: Path, effect: str) -> int:
+    source = path.read_text()
+    points = _insertions(source, effect)
+    if not points:
+        return 0
+    lines = source.splitlines(keepends=True)
+    # Apply bottom-up so earlier offsets stay valid.
+    for lineno, col, text in sorted(points, reverse=True):
+        line = lines[lineno - 1]
+        lines[lineno - 1] = line[:col] + text + line[col:]
+    path.write_text("".join(lines))
+    return len(points)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--effect", default="read_only",
+                        choices=["read_only", "mutating"],
+                        help="classification to insert (default: read_only)")
+    parser.add_argument("files", nargs="+", type=Path)
+    ns = parser.parse_args(argv)
+
+    total = 0
+    for path in ns.files:
+        n = rewrite(path, ns.effect)
+        if n:
+            print(f"{path}: {n} registration(s)")
+        total += n
+    print(f"total: {total}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

strictcli-0.35.2/scripts/add_forwarding_declaration.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Mechanical sweep: declare forwarding on commands whose handler takes ``**kwargs``.
+
+Guard v2 removed the blanket ``**kwargs`` exemption from handler-signature
+validation: a var-keyword handler is a registration error unless the command
+declares forwarding. This script finds ``@x.command(...)`` decorators applied to
+a function with a ``**kwargs`` parameter and inserts
+
+    forwarding=strictcli.Forwarding(reason="<reason>"),
+
+immediately before the ``help=`` argument.
+
+Passthrough registrations are skipped: a passthrough handler's signature is
+deliberately unpoliced, so it never needs the declaration. Sites that already
+declare ``forwarding=`` are skipped, so re-running is a no-op.
+
+Usage:
+    scripts/add_forwarding_declaration.py --reason "why" FILE [FILE ...]
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import sys
+from pathlib import Path
+
+
+def _insertions(source: str, reason: str, qualifier: str) -> list[tuple[int, int, str]]:
+    tree = ast.parse(source)
+    points: list[tuple[int, int, str]] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if node.args.kwarg is None:
+            continue
+        for dec in node.decorator_list:
+            if not isinstance(dec, ast.Call):
+                continue
+            func = dec.func
+            if not isinstance(func, ast.Attribute) or func.attr != "command":
+                continue
+            kw_names = {kw.arg for kw in dec.keywords}
+            if "forwarding" in kw_names or "passthrough" in kw_names:
+                continue
+            help_kw = next((kw for kw in dec.keywords if kw.arg == "help"), None)
+            if help_kw is None:
+                raise SystemExit(
+                    f"command registration without help= at line {dec.lineno}"
+                )
+            text = f'forwarding={qualifier}Forwarding(reason="{reason}"), '
+            points.append((help_kw.lineno, help_kw.col_offset, text))
+    return points
+
+
+def rewrite(path: Path, reason: str, qualifier: str) -> int:
+    source = path.read_text()
+    points = _insertions(source, reason, qualifier)
+    if not points:
+        return 0
+    lines = source.splitlines(keepends=True)
+    for lineno, col, text in sorted(points, reverse=True):
+        line = lines[lineno - 1]
+        lines[lineno - 1] = line[:col] + text + line[col:]
+    path.write_text("".join(lines))
+    return len(points)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--reason", required=True,
+                        help="the mandatory forwarding reason string")
+    parser.add_argument("--qualifier", default="strictcli.",
+                        help='module qualifier for Forwarding (default "strictcli.")')
+    parser.add_argument("files", nargs="+", type=Path)
+    ns = parser.parse_args(argv)
+
+    total = 0
+    for path in ns.files:
+        n = rewrite(path, ns.reason, ns.qualifier)
+        if n:
+            print(f"{path}: {n} registration(s)")
+        total += n
+    print(f"total: {total}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))