protocli 0.1.0__py3-none-any.whl

protocli/__init__.py

@@ -0,0 +1,337 @@
+"""Signature-driven CLI dispatcher.
+
+Command values are either module paths (``str``) for lazy import, or callables
+for direct invocation. Module-backed commands support nested dispatch (set a
+module-level ``_dispatcher``) or signature-driven argument parsing.
+
+Argument handling: if the leaf's ``main`` (or a callable target) takes no
+parameters, the dispatcher intercepts ``-h``/``--help`` and prints
+``Usage: <prog> [args...]`` + the docstring. If it takes parameters, the
+dispatcher introspects the signature and builds an ``argparse`` parser from
+it. Signature → CLI shape:
+
+- ``name: str``                → required positional
+- ``name: str | None = None``  → optional positional (``nargs="?"``)
+- ``*files: str``              → variadic positional (``nargs="*"``)
+- ``*, force: bool = False``   → ``--force`` (``store_true``); bools must be
+                                  keyword-only with default ``False`` (name with
+                                  negation built in if needed, e.g. ``no_color``)
+- ``*, n: int = 5``            → ``--n N`` with default
+- ``*, m: Literal["a","b"]``   → ``--m`` restricted to choices
+- ``*, xs: list[float] = []``  → ``--xs 1.5,3.5`` (comma-separated; ``""`` → [];
+                                  keyword-only, like bools)
+
+Argparse owns ``--help`` and error messages for signature-dispatched leaves.
+"""
+
+import argparse
+import importlib
+import inspect
+import pkgutil
+import sys
+import types
+import typing
+from collections.abc import Callable
+
+__version__ = "0.1.0"
+
+_SKIP = frozenset({"__main__", "__init__", "constants", "cli"})
+DISP_VAR = "_dispatcher"
+COMP_FUN = "get_completions"
+_HELP_FLAGS = (["-h"], ["--help"])
+
+# Sentinel a leaf's ``get_completions`` may return (as the sole candidate) to
+# request the shell's native pathname completion — handles ``~``, ``/``, ``$VAR``
+# and absolute/relative paths, which a static candidate list cannot. Recognised
+# by the ``_proto_complete`` bash function; keep the two literals in sync.
+FILE_COMPLETION = "\x1bFILES"
+
+
+def _unwrap_annotation(ann: object) -> tuple[object, list | None]:
+    """Return ``(base_type, choices_or_None)``.
+
+    Handles ``Literal[...]`` (returns element type + values as choices) and
+    ``Optional[T]``/``T | None`` (returns ``T``, no choices).
+    """
+    origin = typing.get_origin(ann)
+    args = typing.get_args(ann)
+    if origin is typing.Literal:
+        return type(args[0]), list(args)
+    if origin is typing.Union or origin is types.UnionType:
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) == 1:
+            return _unwrap_annotation(non_none[0])
+    return ann, None
+
+
+def _csv_of(elem: type) -> Callable[[str], list]:
+    """Parser for a comma-separated ``list[elem]`` flag value; ``""`` → []."""
+
+    def parse(s: str) -> list:
+        return [elem(e) for e in s.split(",") if e]
+
+    return parse
+
+
+def _build_parser(prog: str, fn: Callable) -> argparse.ArgumentParser:
+    """Generate an argparse parser from ``fn``'s signature."""
+    sig = inspect.signature(fn)
+    hints = typing.get_type_hints(fn)
+    doc = (fn.__doc__ or "").strip().split("\n", 1)[0]
+    parser = argparse.ArgumentParser(prog=prog, description=doc)
+    for name, param in sig.parameters.items():
+        raw_ann = hints.get(name, str)
+        ann, choices = _unwrap_annotation(raw_ann)
+        kwargs: dict = {}
+        if choices is not None:
+            kwargs["choices"] = choices
+        kind = param.kind
+        if kind is inspect.Parameter.VAR_POSITIONAL:
+            kwargs["type"] = ann
+            kwargs["nargs"] = "*"
+            parser.add_argument(name, **kwargs)
+            continue
+        if ann is bool:
+            if kind is not inspect.Parameter.KEYWORD_ONLY or param.default is not False:
+                raise TypeError(
+                    f"bool param {name!r} must be keyword-only with default False"
+                )
+            kwargs["action"] = "store_true"
+            parser.add_argument(f"--{name.replace('_', '-')}", **kwargs)
+            continue
+        if typing.get_origin(ann) is list:
+            if kind is not inspect.Parameter.KEYWORD_ONLY:
+                raise TypeError(f"list param {name!r} must be keyword-only")
+            elem = (typing.get_args(ann) or (str,))[0]
+            kwargs["type"] = _csv_of(elem)
+            kwargs["default"] = param.default
+            parser.add_argument(f"--{name.replace('_', '-')}", **kwargs)
+            continue
+        kwargs["type"] = ann
+        if kind is inspect.Parameter.KEYWORD_ONLY:
+            kwargs["default"] = param.default
+            parser.add_argument(f"--{name.replace('_', '-')}", **kwargs)
+        elif param.default is not inspect.Parameter.empty:
+            kwargs["default"] = param.default
+            kwargs["nargs"] = "?"
+            parser.add_argument(name, **kwargs)
+        else:
+            parser.add_argument(name, **kwargs)
+    return parser
+
+
+def _sig_help(prog: str, fn: Callable) -> list[str] | None:
+    """Return ``[parser.format_help().rstrip()]`` if ``fn`` has parameters."""
+    if not inspect.signature(fn).parameters:
+        return None
+    return [_build_parser(prog, fn).format_help().rstrip()]
+
+
+def _sig_completions(fn: Callable, rest: list[str]) -> list[str]:
+    """Derive shell-completion candidates from ``fn``'s signature.
+
+    Returns the keyword-only flag names; if the previous token is a flag whose
+    annotation is ``Literal[...]``, returns those choices instead.
+    """
+    sig = inspect.signature(fn)
+    if not sig.parameters:
+        return []
+    hints = typing.get_type_hints(fn)
+    if rest:
+        last = rest[-1]
+        for name, param in sig.parameters.items():
+            if param.kind is not inspect.Parameter.KEYWORD_ONLY:
+                continue
+            if last != f"--{name.replace('_', '-')}":
+                continue
+            _, choices = _unwrap_annotation(hints.get(name, str))
+            return choices or []
+    return [
+        f"--{name.replace('_', '-')}"
+        for name, param in sig.parameters.items()
+        if param.kind is inspect.Parameter.KEYWORD_ONLY
+    ]
+
+
+class Dispatcher:
+    """Unified CLI dispatcher.
+
+    Construct directly with an explicit command dict, or via ``from_package``
+    for auto-discovery. Dict values that are ``str`` are treated as module
+    paths (lazy-imported on dispatch); callables are invoked directly. Leaf
+    ``main()`` / callable targets either take no params (dispatcher handles
+    ``--help`` via docstring) or accept signature-driven args (argparse owns
+    ``--help`` and parsing).
+    """
+
+    def __init__(self, prog: str, commands: dict[str, str | Callable]):
+        self._prog = prog
+        self._commands = commands
+
+    @classmethod
+    def from_package(cls, package: str, prog: str | None = None) -> "Dispatcher":
+        mod = importlib.import_module(package)
+        commands: dict[str, str | Callable] = {
+            m.name: f"{package}.{m.name}"
+            for m in pkgutil.iter_modules(mod.__path__)
+            if m.name not in _SKIP and not m.name.startswith("_")
+        }
+        return cls(prog=prog or package.rsplit(".", 1)[-1], commands=commands)
+
+    def commands(self) -> list[str]:
+        return sorted(self._commands)
+
+    def tree(self) -> dict[str, dict | None]:
+        """Return nested command tree. Leaves are ``None``."""
+        result: dict[str, dict | None] = {}
+        for cmd in self.commands():
+            target = self._commands[cmd]
+            if callable(target):
+                result[cmd] = None
+                continue
+            try:
+                mod = importlib.import_module(target)
+            except ImportError:
+                result[cmd] = None
+                continue
+            child = getattr(mod, DISP_VAR, None)
+            result[cmd] = child.tree() if child is not None else None
+        return result
+
+    def _get_doc(self, cmd: str) -> str:
+        target = self._commands[cmd]
+        if callable(target):
+            return (target.__doc__ or "").strip().split("\n")[0]
+        try:
+            mod = importlib.import_module(target)
+            return (mod.__doc__ or "").strip().split("\n")[0]
+        except ImportError:
+            return ""
+
+    def _help_lines(self) -> list[str]:
+        cmds = self.commands()
+        lines = [f"Usage: {self._prog} <command> [args...]"]
+        if cmds:
+            width = max(len(c) for c in cmds)
+            lines.append("Commands:")
+            for cmd in cmds:
+                doc = self._get_doc(cmd)
+                suffix = f"  {doc}" if doc else ""
+                lines.append(f"  {cmd:<{width}}{suffix}")
+        return lines
+
+    def _collect_help_all(self, sections: list[list[str]]) -> None:
+        sections.append(self._help_lines())
+        for cmd in self.commands():
+            prog = f"{self._prog} {cmd}"
+            target = self._commands[cmd]
+            if callable(target):
+                sig = _sig_help(prog, target)
+                if sig:
+                    sections.append(sig)
+                continue
+            try:
+                mod = importlib.import_module(target)
+            except ImportError:
+                continue
+            child = getattr(mod, DISP_VAR, None)
+            if child is not None:
+                child._collect_help_all(sections)
+                continue
+            sig = _sig_help(prog, mod.main)
+            if sig:
+                sections.append(sig)
+                continue
+            complete_fn = getattr(mod, COMP_FUN, None)
+            if complete_fn:
+                subs = complete_fn([])
+                if subs:
+                    sections.append([prog, f"  {', '.join(subs)}"])
+
+    @staticmethod
+    def _print_leaf_help(prog: str, doc: str | None) -> None:
+        print(f"Usage: {prog} [args...]")
+        text = (doc or "").strip()
+        if text:
+            print(text)
+
+    def _invoke(
+        self, prog: str, fn: Callable, rest: list[str], doc: str | None
+    ) -> None:
+        sys.argv = [prog, *rest]
+        if not inspect.signature(fn).parameters:
+            if rest[:1] in _HELP_FLAGS:
+                self._print_leaf_help(prog, doc)
+                return
+            fn()
+            return
+        parser = _build_parser(prog, fn)
+        parsed = parser.parse_args(rest)
+        call_args, call_kwargs = [], {}
+        for pname, param in inspect.signature(fn).parameters.items():
+            val = getattr(parsed, pname)
+            if param.kind is inspect.Parameter.VAR_POSITIONAL:
+                call_args.extend(val)
+            elif param.kind is inspect.Parameter.KEYWORD_ONLY:
+                call_kwargs[pname] = val
+            else:
+                call_args.append(val)
+        fn(*call_args, **call_kwargs)
+
+    def run(self) -> None:
+        argv = sys.argv[1:]
+        cmds = self.commands()
+
+        if not argv or [argv[0]] in _HELP_FLAGS:
+            print("\n".join(self._help_lines()))
+            return
+
+        if argv[0] == "--help-all":
+            sections: list[list[str]] = []
+            self._collect_help_all(sections)
+            print("\n\n".join("\n".join(s) for s in sections))
+            return
+
+        if argv[0] == "--complete":
+            for line in self.get_completions(argv[1:]):
+                print(line)
+            return
+
+        cmd, *rest = argv
+        if cmd not in cmds:
+            print(f"Unknown command: {cmd}", file=sys.stderr)
+            raise SystemExit(1)
+
+        target = self._commands[cmd]
+        prog = f"{self._prog} {cmd}"
+
+        if callable(target):
+            self._invoke(prog, target, rest, target.__doc__)
+            return
+
+        mod = importlib.import_module(target)
+        child = getattr(mod, DISP_VAR, None)
+        if child is not None:
+            sys.argv = [prog, *rest]
+            child.run()
+            return
+        self._invoke(prog, mod.main, rest, mod.__doc__)
+
+    def get_completions(self, args: list[str]) -> list[str]:
+        cmds = self.commands()
+        if not args:
+            return cmds
+        cmd, *rest = args
+        if cmd not in cmds:
+            return []
+        target = self._commands[cmd]
+        if callable(target):
+            return _sig_completions(target, rest)
+        mod = importlib.import_module(target)
+        child = getattr(mod, DISP_VAR, None)
+        if child is not None:
+            return child.get_completions(rest)
+        complete_fn = getattr(mod, COMP_FUN, None)
+        if complete_fn is not None:
+            return complete_fn(rest)
+        return _sig_completions(mod.main, rest)

protocli/tests/test_dispatcher.py

@@ -0,0 +1,146 @@
+import sys
+import types
+import typing
+
+import pytest
+
+from protocli import (
+    FILE_COMPLETION,
+    Dispatcher,
+    _build_parser,
+    _unwrap_annotation,
+)
+
+
+def test_unwrap_annotation() -> None:
+    assert _unwrap_annotation(int) == (int, None)
+    assert _unwrap_annotation(typing.Literal["a", "b"]) == (str, ["a", "b"])
+    assert _unwrap_annotation(typing.Optional[int]) == (int, None)
+    assert _unwrap_annotation(str | None) == (str, None)
+
+
+def test_parser_shapes() -> None:
+    def fn(
+        name: str,
+        opt: str | None = None,
+        *files: str,
+        force: bool = False,
+        n: int = 5,
+        mode: typing.Literal["a", "b"] = "a",
+    ) -> None: ...
+
+    parser = _build_parser("prog", fn)
+    ns = parser.parse_args(["x", "y", "f1", "f2", "--force", "--n", "7", "--mode", "b"])
+    assert (ns.name, ns.opt, ns.files) == ("x", "y", ["f1", "f2"])
+    assert (ns.force, ns.n, ns.mode) == (True, 7, "b")
+    ns = parser.parse_args(["x"])
+    assert (ns.opt, ns.files, ns.force, ns.n, ns.mode) == (None, [], False, 5, "a")
+    with pytest.raises(SystemExit):
+        parser.parse_args(["x", "--mode", "c"])
+
+
+def test_list_flags() -> None:
+    def fn(*, bins: list[float] = [], procs: list[int] = [16, 1]) -> None: ...
+
+    parser = _build_parser("prog", fn)
+    ns = parser.parse_args(["--bins", "1.5,3.5", "--procs", "4"])
+    assert ns.bins == [1.5, 3.5] and ns.procs == [4]
+    ns = parser.parse_args(["--bins", ""])
+    assert ns.bins == [] and ns.procs == [16, 1]
+
+
+def test_list_must_be_keyword_only() -> None:
+    def fn(bins: list[float] = []) -> None: ...
+
+    with pytest.raises(TypeError, match="keyword-only"):
+        _build_parser("prog", fn)
+
+
+def test_bool_constraints() -> None:
+    def positional(flag: bool) -> None: ...
+
+    def defaulted_true(*, flag: bool = True) -> None: ...
+
+    for fn in (positional, defaulted_true):
+        with pytest.raises(TypeError, match="keyword-only with default False"):
+            _build_parser("prog", fn)
+
+
+def _run(disp: Dispatcher, *argv: str, monkeypatch) -> None:
+    monkeypatch.setattr(sys, "argv", ["prog", *argv])
+    disp.run()
+
+
+def test_callable_dispatch(monkeypatch) -> None:
+    calls = []
+
+    def greet(name: str, *, loud: bool = False) -> None:
+        calls.append((name, loud))
+
+    disp = Dispatcher("prog", {"greet": greet})
+    _run(disp, "greet", "ada", "--loud", monkeypatch=monkeypatch)
+    assert calls == [("ada", True)]
+
+
+def test_module_and_nested_dispatch(monkeypatch, capsys) -> None:
+    leaf = types.ModuleType("fake_leaf")
+    leaf.__doc__ = "Leaf docs."
+    calls = []
+    leaf.main = lambda: calls.append("ran")
+    sys.modules["fake_leaf"] = leaf
+
+    inner = types.ModuleType("fake_nested")
+    inner.ping = lambda: calls.append("pong")
+    inner._dispatcher = Dispatcher("prog nest", {"ping": inner.ping})
+    sys.modules["fake_nested"] = inner
+
+    disp = Dispatcher("prog", {"leaf": "fake_leaf", "nest": "fake_nested"})
+    _run(disp, "leaf", monkeypatch=monkeypatch)
+    _run(disp, "nest", "ping", monkeypatch=monkeypatch)
+    assert calls == ["ran", "pong"]
+    assert disp.tree() == {"leaf": None, "nest": {"ping": None}}
+
+    _run(disp, "leaf", "-h", monkeypatch=monkeypatch)
+    out = capsys.readouterr().out
+    assert "Usage: prog leaf [args...]" in out and "Leaf docs." in out
+
+
+def test_unknown_command_exits(monkeypatch) -> None:
+    disp = Dispatcher("prog", {})
+    with pytest.raises(SystemExit):
+        _run(disp, "ghost", monkeypatch=monkeypatch)
+
+
+def test_top_help_lists_commands(monkeypatch, capsys) -> None:
+    def doer() -> None:
+        """Does things."""
+
+    disp = Dispatcher("prog", {"do": doer})
+    _run(disp, monkeypatch=monkeypatch)
+    out = capsys.readouterr().out
+    assert "Usage: prog <command>" in out and "do  Does things." in out
+
+
+def test_completions() -> None:
+    def fn(*, mode: typing.Literal["x", "y"] = "x", n: int = 1) -> None: ...
+
+    disp = Dispatcher("prog", {"cmd": fn})
+    assert disp.get_completions([]) == ["cmd"]
+    assert sorted(disp.get_completions(["cmd"])) == ["--mode", "--n"]
+    assert disp.get_completions(["cmd", "--mode"]) == ["x", "y"]
+    assert disp.get_completions(["ghost"]) == []
+    assert FILE_COMPLETION.startswith("\x1b")
+
+
+def test_from_package(tmp_path, monkeypatch) -> None:
+    pkg = tmp_path / "fakepkg"
+    pkg.mkdir()
+    (pkg / "__init__.py").write_text("")
+    (pkg / "hello.py").write_text('"""Say hi."""\ndef main():\n    print("hi")\n')
+    (pkg / "_private.py").write_text("def main():\n    pass\n")
+    monkeypatch.syspath_prepend(str(tmp_path))
+
+    disp = Dispatcher.from_package("fakepkg")
+    assert disp.commands() == ["hello"]
+    monkeypatch.setattr(sys, "argv", ["fakepkg", "hello"])
+    disp.run()

protocli-0.1.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: protocli
+Version: 0.1.0
+Summary: Signature-driven CLI dispatcher: typed function signatures become argparse parsers, modules become lazily-imported subcommands, with nested dispatch, --help-all and shell completions.
+Project-URL: Homepage, https://github.com/endremborza/protocli
+Author-email: Endre Márk Borza <endremborza@gmail.com>
+License: Copyright 2026 Endre Márk Borza
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# protocli
+
+[![pypi](https://img.shields.io/pypi/v/protocli.svg)](https://pypi.org/project/protocli/)
+
+Signature-driven CLI dispatcher: typed function signatures become argparse parsers, modules become lazily-imported subcommands, with nested dispatch, `--help-all` and shell completions.
+
+```python
+# mytool/__main__.py
+from protocli import Dispatcher
+
+Dispatcher(
+    "mytool",
+    {
+        "greet": greet,          # a callable: its signature IS the parser
+        "db": "mytool.db",       # a module path: lazy-imported on dispatch
+    },
+).run()
+```
+
+A callable (or a module's `main`) maps to CLI arguments by signature:
+
+```python
+def greet(
+    name: str,                        # required positional
+    title: str | None = None,         # optional positional
+    *rest: str,                       # variadic
+    loud: bool = False,               # --loud   (keyword-only, default False)
+    times: int = 1,                   # --times N
+    lang: Literal["en", "hu"] = "en", # --lang restricted to choices
+    tags: list[str] = [],             # --tags a,b,c  (comma-separated)
+): ...
+```
+
+A module can instead expose its own nested `_dispatcher = Dispatcher(...)`,
+or a `get_completions(rest)` hook for custom shell completion (return
+`[FILE_COMPLETION]` to request native pathname completion).
+
+`mytool --help-all` prints every parser in the tree; `mytool --complete <args…>`
+emits completion candidates for shell integration.
+
+Auto-discovery over a package's public modules:
+
+```python
+Dispatcher.from_package("mytool").run()
+```

protocli-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+protocli/__init__.py,sha256=quPZbR5ugsPI3t2zTLsdPlhjf463cTPeNp1sqqbJidc,12578
+protocli/tests/test_dispatcher.py,sha256=5Zr3FOGvKtg4ZYAgT_uw6V0zZU8waFgSwG_qvP-x5dk,4729
+protocli-0.1.0.dist-info/METADATA,sha256=VieX6jr-KQbRSku2wXjFP8NXfWvHuRAyVMdcelaoBTY,3110
+protocli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+protocli-0.1.0.dist-info/licenses/LICENSE,sha256=NrHeFb1pfm6nQHXGcuumvUALSfJjJv9EZTv4rK-jwR0,1056
+protocli-0.1.0.dist-info/RECORD,,

protocli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

protocli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Endre Márk Borza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.