cli-to-py 0.1.0__py3-none-any.whl

cli_to_py/__init__.py

@@ -0,0 +1,113 @@
+"""cli_to_py — Turn any CLI into a Python API, automatically.
+
+Public API:
+
+    from cli_to_py import convert, convert_sync, from_help_text
+
+    # Async
+    git = await convert("git")
+    result = await git.status(short=True)
+    branch = await git.branch(show_current=True).text()
+    errors = git.validate("commit", massage="x")    # returns [ValidationError]
+
+    # Sync
+    git = convert_sync("git")
+    result = git.status(short=True)
+
+    # Static help text
+    api = from_help_text("my-tool", help_text)
+"""
+
+from __future__ import annotations
+
+from .api import CliApi
+from .cache import cache_dir, clear_cache, load_cached_schema, save_cached_schema
+from .command_future import CommandFuture
+from .command_string import to_command_string
+from .convert import convert, convert_sync, from_help_text, from_help_text_sync
+from .exec import (
+    BinaryNotFoundError,
+    CommandAborted,
+    CommandProcess,
+    CommandTimeout,
+    run_command,
+    run_for_help,
+    spawn_command,
+)
+from .generate import generate_json, generate_stub, generate_wrapper
+from .load_schema import load_schema, load_schema_sync
+from .options_to_args import options_to_args
+from .parse_help import parse_help_text, strip_ansi
+from .parse_subcommands import enrich_subcommands, parse_subcommand_help
+from .run_config import RunConfig
+from .schema import (
+    CliSchema,
+    CommandResult,
+    ParsedCommand,
+    ParsedFlag,
+    ParsedPositionalArg,
+    ParsedSubcommand,
+)
+from .script import Script, script
+from .sync_api import SyncCliApi
+from .sync_exec import run_command_sync, run_for_help_sync
+from .validate import ValidationError, validate_options
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # version
+    "__version__",
+    # entry points
+    "convert",
+    "convert_sync",
+    "from_help_text",
+    "from_help_text_sync",
+    "load_schema",
+    "load_schema_sync",
+    # api objects
+    "CliApi",
+    "SyncCliApi",
+    "CommandFuture",
+    "CommandProcess",
+    # schema types
+    "CliSchema",
+    "ParsedCommand",
+    "ParsedSubcommand",
+    "ParsedFlag",
+    "ParsedPositionalArg",
+    "CommandResult",
+    # config
+    "RunConfig",
+    # validation
+    "validate_options",
+    "ValidationError",
+    # execution
+    "run_command",
+    "run_command_sync",
+    "run_for_help",
+    "run_for_help_sync",
+    "spawn_command",
+    "CommandTimeout",
+    "CommandAborted",
+    "BinaryNotFoundError",
+    # parsing
+    "parse_help_text",
+    "strip_ansi",
+    "parse_subcommand_help",
+    "enrich_subcommands",
+    "options_to_args",
+    "to_command_string",
+    # codegen
+    "generate_wrapper",
+    "generate_stub",
+    "generate_json",
+    # script chaining
+    "Script",
+    "script",
+    # cache
+    "cache_dir",
+    "load_cached_schema",
+    "save_cached_schema",
+    "clear_cache",
+]

cli_to_py/_api_base.py

@@ -0,0 +1,112 @@
+"""Shared plumbing for CliApi (async) and SyncCliApi (sync).
+
+These helpers were duplicated across api.py and sync_api.py byte-for-byte.
+Extracted here so a change to alias resolution or kwargs handling lands
+in exactly one place.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .case import kebab_to_snake, snake_to_kebab
+from .run_config import RunConfig
+from .schema import CliSchema, ParsedSubcommand
+
+
+class _BaseCliApi:
+    """Base class holding dispatch/resolution plumbing shared by CliApi and SyncCliApi.
+
+    Subclasses own `__call__` and `__getattr__` semantics (async vs sync) but
+    share alias resolution, equals-flag collection, config merging, and the
+    `_config` kwarg extraction convention.
+    """
+
+    binary_name: str
+    schema: CliSchema
+    _default_config: RunConfig
+    _equals_flags: set[str]
+
+    def __init__(
+        self,
+        binary_name: str,
+        schema: CliSchema,
+        default_config: RunConfig | None = None,
+    ):
+        self.binary_name = binary_name
+        self.schema = schema
+        self._default_config = default_config or RunConfig()
+        self._equals_flags = {
+            kebab_to_snake(f.long_name) for f in schema.command.flags if f.uses_equals
+        }
+
+    # --- resolution helpers
+
+    def _resolve_alias(self, name: str) -> str:
+        normalized = snake_to_kebab(name)
+        for sub in self.schema.command.subcommands:
+            if (
+                sub.name == name
+                or sub.name == normalized
+                or (sub.aliases and (name in sub.aliases or normalized in sub.aliases))
+            ):
+                return sub.name
+        return name
+
+    def _find_subcommand(self, name: str) -> ParsedSubcommand | None:
+        normalized = snake_to_kebab(name)
+        for sub in self.schema.command.subcommands:
+            if (
+                sub.name == name
+                or sub.name == normalized
+                or (sub.aliases and (name in sub.aliases or normalized in sub.aliases))
+            ):
+                return sub
+        return None
+
+    def _equals_for(self, resolved_sub: str) -> set[str]:
+        sub = self._find_subcommand(resolved_sub)
+        if sub is None or not sub.flags:
+            return self._equals_flags
+        sub_equals = {kebab_to_snake(f.long_name) for f in sub.flags if f.uses_equals}
+        return self._equals_flags | sub_equals
+
+    def _split_kwargs(
+        self, kwargs: dict[str, Any]
+    ) -> tuple[dict[str, Any], RunConfig | None]:
+        """Extract an optional `_config` kwarg (a RunConfig) from user options.
+
+        Also guards against the common typo where a user passes
+        `config=RunConfig(...)` instead of `_config=RunConfig(...)` — without
+        the underscore it would serialize to argv as `--config <repr>`, which
+        is never what the user intended.
+        """
+        config = kwargs.pop("_config", None)
+        if config is not None and not isinstance(config, RunConfig):
+            raise TypeError("_config must be a RunConfig instance")
+        # Stray RunConfig values under non-underscore keys are almost always typos.
+        for key, value in kwargs.items():
+            if isinstance(value, RunConfig):
+                raise TypeError(
+                    f"kwarg {key!r} holds a RunConfig — did you mean `_config=...`?"
+                )
+        return kwargs, config
+
+    def _merged_config(self, per_call: RunConfig | None) -> RunConfig:
+        return self._default_config.merge(per_call)
+
+    # --- introspection helpers
+
+    def _subcommand_names(self) -> list[str]:
+        """Return known subcommand names and aliases, without duplicates."""
+        names: list[str] = []
+        seen: set[str] = set()
+        for sub in self.schema.command.subcommands:
+            if sub.name not in seen:
+                names.append(sub.name)
+                seen.add(sub.name)
+            for alias in sub.aliases or ():
+                if alias not in seen:
+                    names.append(alias)
+                    seen.add(alias)
+        return names

cli_to_py/api.py

@@ -0,0 +1,159 @@
+"""Public CliApi class — async Pythonic wrapper around a CLI binary.
+
+Pythonic design: `__getattr__` + `__call__` replace JS's Proxy. Ordinary
+attributes (binary_name, schema, helper methods) are resolved normally;
+only attribute names that match a parsed subcommand get routed through
+`__getattr__` to a dynamic dispatcher. Unknown attribute names raise
+AttributeError (so `hasattr(api, 'nonexistent')` is False and IDE
+introspection works).
+
+Usage:
+    api = await convert("git")
+    await api.status(short=True)
+    await api("diff", name_only=True, _=["HEAD~1"])
+    await api.branch(show_current=True).text()
+
+    api.schema                                       # parsed schema
+    api.validate("commit", massage="x")              # typo catcher
+    api.command_string("commit", message="x")        # shell string
+    proc = await api.spawn("log", oneline=True)      # streaming
+    async for line in proc: ...
+
+Reserved method names (can't reach a same-named subcommand via dot
+notation): `validate`, `command_string`, `spawn`, `parse`, `schema`,
+`binary_name`. If your CLI has a subcommand named (e.g.) `validate`,
+use `api("validate", ...)` or `api.__call__("validate", ...)` instead.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._api_base import _BaseCliApi
+from .command_future import CommandFuture
+from .command_string import to_command_string
+from .exec import CommandProcess, run_command, spawn_command
+from .parse_subcommands import parse_subcommand_help
+from .schema import ParsedCommand, ParsedSubcommand
+from .validate import ValidationError, validate_options
+
+
+class CliApi(_BaseCliApi):
+    """Async, callable Pythonic wrapper around a CLI binary."""
+
+    def __call__(self, subcommand: str | None = None, /, **kwargs: Any) -> CommandFuture:
+        options, per_call = self._split_kwargs(kwargs)
+        if subcommand is not None:
+            resolved = self._resolve_alias(subcommand)
+            equals = self._equals_for(resolved)
+            return CommandFuture(run_command(
+                self.binary_name, [resolved], options,
+                self._merged_config(per_call), equals,
+            ))
+        return CommandFuture(run_command(
+            self.binary_name, [], options,
+            self._merged_config(per_call), self._equals_flags,
+        ))
+
+    def __getattr__(self, name: str) -> Any:
+        # Only called if normal attribute lookup fails — so class methods
+        # like `validate`, `spawn`, `command_string`, `parse` still win.
+        if name.startswith("_"):
+            raise AttributeError(name)
+        if self._find_subcommand(name) is None:
+            raise AttributeError(
+                f"{type(self).__name__!s} has no subcommand {name!r}. "
+                f"Use api({name!r}, ...) if your CLI exposes it but --help didn't list it."
+            )
+        resolved = self._resolve_alias(name)
+        equals = self._equals_for(resolved)
+
+        def dispatch(**kwargs: Any) -> CommandFuture:
+            options, per_call = self._split_kwargs(kwargs)
+            return CommandFuture(run_command(
+                self.binary_name, [resolved], options,
+                self._merged_config(per_call), equals,
+            ))
+        dispatch.__name__ = name
+        return dispatch
+
+    def __dir__(self) -> list[str]:
+        """Expose known subcommands + helper methods for IDEs / dir()."""
+        base = set(super().__dir__())
+        base.update(self._subcommand_names())
+        return sorted(base)
+
+    # ------------------------------------------------------------------ helpers
+
+    def validate(
+        self, subcommand: str | None = None, /, **options: Any
+    ) -> list[ValidationError]:
+        if subcommand is None:
+            return validate_options(self.schema.command, options)
+        sub = self._find_subcommand(subcommand)
+        if sub is None:
+            raise ValueError(
+                f'Unknown subcommand "{subcommand}". Pass subcommands=True to convert().'
+            )
+        if sub.flags is None:
+            raise ValueError(
+                f'Subcommand "{subcommand}" not enriched. Call parse("{subcommand}") first '
+                f'or pass subcommands=True to convert().'
+            )
+        fake_command = ParsedCommand(
+            name=sub.name,
+            description=sub.description,
+            flags=sub.flags,
+            positional_args=sub.positional_args or [],
+        )
+        return validate_options(fake_command, options)
+
+    def command_string(self, subcommand: str | None = None, /, **options: Any) -> str:
+        if subcommand is None:
+            return to_command_string(self.binary_name, [], options, self._equals_flags)
+        resolved = self._resolve_alias(subcommand)
+        return to_command_string(
+            self.binary_name, [resolved], options, self._equals_for(resolved)
+        )
+
+    async def spawn(
+        self, subcommand: str | None = None, /, **kwargs: Any
+    ) -> CommandProcess:
+        options, per_call = self._split_kwargs(kwargs)
+        subs = [self._resolve_alias(subcommand)] if subcommand else []
+        equals = self._equals_for(subs[0]) if subs else self._equals_flags
+        return await spawn_command(
+            self.binary_name, subs, options, self._merged_config(per_call), equals
+        )
+
+    async def parse(self, subcommand_name: str | None = None) -> ParsedCommand | None:
+        """Lazily enrich one subcommand (or all) by re-running its --help."""
+        if subcommand_name is None:
+            from .parse_subcommands import enrich_subcommands
+            await enrich_subcommands(
+                self.binary_name, self.schema,
+                timeout=self._default_config.resolved_timeout(),
+                cwd=self._default_config.cwd,
+                env=self._default_config.env,
+            )
+            return None
+        parsed = await parse_subcommand_help(
+            self.binary_name, subcommand_name,
+            timeout=self._default_config.resolved_timeout(),
+            cwd=self._default_config.cwd,
+            env=self._default_config.env,
+        )
+        if parsed is not None:
+            existing = self._find_subcommand(subcommand_name)
+            if existing is not None:
+                existing.flags = parsed.flags
+                existing.positional_args = parsed.positional_args
+            else:
+                self.schema.command.subcommands.append(ParsedSubcommand(
+                    name=subcommand_name,
+                    aliases=[],
+                    description=parsed.description,
+                    flags=parsed.flags,
+                    positional_args=parsed.positional_args,
+                ))
+        return parsed

cli_to_py/best_help.py

@@ -0,0 +1,45 @@
+"""Pick the better of stdout / stderr when asking a binary for its help text.
+
+Some tools print --help to stdout (GNU convention), some to stderr.
+Score each by counting "usage/options/commands" signal patterns, pick the
+winner. If they tie, prefer the longer one. If both are empty, return "".
+"""
+
+from __future__ import annotations
+
+import re
+
+HELP_SIGNAL_PATTERNS = [
+    re.compile(r"usage:", re.IGNORECASE),
+    re.compile(r"options:", re.IGNORECASE),
+    re.compile(r"commands:", re.IGNORECASE),
+    re.compile(r"^\s+-", re.MULTILINE),
+]
+
+
+def _score(text: str) -> int:
+    return sum(1 for pattern in HELP_SIGNAL_PATTERNS if pattern.search(text))
+
+
+def select_help_output(stdout: str, stderr: str) -> str:
+    trimmed_out = stdout.strip()
+    trimmed_err = stderr.strip()
+
+    if not trimmed_out and not trimmed_err:
+        return ""
+    if not trimmed_err:
+        return stdout
+    if not trimmed_out:
+        return stderr
+
+    out_signals = _score(trimmed_out)
+    err_signals = _score(trimmed_err)
+
+    if out_signals and not err_signals:
+        return stdout
+    if err_signals and not out_signals:
+        return stderr
+    if out_signals and err_signals:
+        return stdout if out_signals >= err_signals else stderr
+
+    return stdout if len(trimmed_out) >= len(trimmed_err) else stderr

cli_to_py/cache.py

@@ -0,0 +1,165 @@
+"""Persistent schema cache for parsed CLI help text.
+
+Rationale: parsing --help + enriching N subcommands costs ~300-1500ms per
+binary. For frequently-used binaries (git, uv, kubectl), that adds up.
+Cache the parsed CliSchema as JSON in ~/.cache/cli-to-py/, keyed by the
+binary's absolute path + mtime, so cache invalidates when the binary is
+upgraded.
+
+The cache is optional and opt-in. Pass use_cache=True to convert() / convert_sync().
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .constants import CACHE_DEFAULT_SUBDIR, CACHE_DIR_ENV, CACHE_SCHEMA_VERSION
+from .schema import CliSchema, ParsedCommand, ParsedFlag, ParsedPositionalArg, ParsedSubcommand
+
+
+def cache_dir() -> Path:
+    """Return the cache directory (respects CLI_TO_PY_CACHE_DIR env override)."""
+    override = os.environ.get(CACHE_DIR_ENV)
+    if override:
+        return Path(override)
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    if xdg:
+        return Path(xdg) / CACHE_DEFAULT_SUBDIR
+    return Path.home() / ".cache" / CACHE_DEFAULT_SUBDIR
+
+
+def _resolve_binary(binary_name: str) -> Path | None:
+    """Resolve binary to absolute path via shutil.which (or None if not found)."""
+    found = shutil.which(binary_name)
+    return Path(found) if found else None
+
+
+def _cache_key(binary_name: str, *, subcommands: bool = True) -> str:
+    """Build a cache key: hash of (absolute path, mtime, name, subcommands scope)."""
+    resolved = _resolve_binary(binary_name)
+    scope = "full" if subcommands else "root"
+    if resolved is None:
+        return hashlib.sha1(f"{binary_name}|{scope}".encode()).hexdigest()[:16]
+    try:
+        mtime = int(resolved.stat().st_mtime)
+    except OSError:
+        mtime = 0
+    raw = f"{binary_name}|{resolved}|{mtime}|{scope}"
+    return hashlib.sha1(raw.encode()).hexdigest()[:16]
+
+
+def _cache_path(binary_name: str, *, subcommands: bool = True) -> Path:
+    """Build a cache file path.
+
+    The binary_name may contain path separators (e.g. '/usr/local/bin/uv' or
+    './node_modules/.bin/foo'); strip them to a safe basename before embedding
+    in the filename. Uniqueness comes from the hash, not the label.
+    """
+    safe_label = os.path.basename(binary_name).replace(os.sep, "_")
+    if os.altsep:
+        safe_label = safe_label.replace(os.altsep, "_")
+    if not safe_label:
+        safe_label = "bin"
+    return cache_dir() / f"{safe_label}-{_cache_key(binary_name, subcommands=subcommands)}.json"
+
+
+# ------------------------------------------------------------------ serialization
+
+def _schema_to_dict(schema: CliSchema) -> dict[str, Any]:
+    return {
+        "version": CACHE_SCHEMA_VERSION,
+        "binary_name": schema.binary_name,
+        "command": dataclasses.asdict(schema.command),
+    }
+
+
+def _dict_to_command(d: dict[str, Any]) -> ParsedCommand:
+    return ParsedCommand(
+        name=d["name"],
+        description=d.get("description", ""),
+        flags=[ParsedFlag(**f) for f in d.get("flags", [])],
+        positional_args=[ParsedPositionalArg(**p) for p in d.get("positional_args", [])],
+        subcommands=[_dict_to_subcommand(s) for s in d.get("subcommands", [])],
+    )
+
+
+def _dict_to_subcommand(d: dict[str, Any]) -> ParsedSubcommand:
+    flags = d.get("flags")
+    positional = d.get("positional_args")
+    subs = d.get("subcommands")
+    return ParsedSubcommand(
+        name=d["name"],
+        aliases=d.get("aliases", []),
+        description=d.get("description", ""),
+        flags=[ParsedFlag(**f) for f in flags] if flags is not None else None,
+        positional_args=[ParsedPositionalArg(**p) for p in positional] if positional is not None else None,
+        subcommands=[_dict_to_subcommand(s) for s in subs] if subs else None,
+    )
+
+
+def _dict_to_schema(d: dict[str, Any]) -> CliSchema:
+    if d.get("version") != CACHE_SCHEMA_VERSION:
+        raise ValueError(f"cache schema version mismatch: {d.get('version')}")
+    return CliSchema(
+        binary_name=d["binary_name"],
+        command=_dict_to_command(d["command"]),
+    )
+
+
+# ------------------------------------------------------------------ public
+
+def load_cached_schema(binary_name: str, *, subcommands: bool = True) -> CliSchema | None:
+    path = _cache_path(binary_name, subcommands=subcommands)
+    if not path.exists():
+        return None
+    try:
+        with path.open("r") as fh:
+            data = json.load(fh)
+        return _dict_to_schema(data)
+    except (OSError, json.JSONDecodeError, ValueError, KeyError, TypeError):
+        return None
+
+
+def save_cached_schema(schema: CliSchema, *, subcommands: bool = True) -> Path:
+    path = _cache_path(schema.binary_name, subcommands=subcommands)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Per-process tmp suffix avoids concurrent writers racing the same .tmp file.
+    tmp = path.with_suffix(f".{os.getpid()}.tmp")
+    try:
+        with tmp.open("w") as fh:
+            json.dump(_schema_to_dict(schema), fh, indent=2)
+        tmp.replace(path)
+    except Exception:
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+        raise
+    return path
+
+
+def clear_cache(binary_name: str | None = None) -> int:
+    """Remove cached schemas. If binary_name is None, clear all. Returns count removed."""
+    removed = 0
+    base = cache_dir()
+    if not base.exists():
+        return 0
+    if binary_name is not None:
+        # Clear both subcommands=True and subcommands=False cache entries.
+        for scope in (True, False):
+            target = _cache_path(binary_name, subcommands=scope)
+            if target.exists():
+                target.unlink()
+                removed += 1
+        return removed
+    for entry in base.iterdir():
+        if entry.is_file() and entry.suffix == ".json":
+            entry.unlink()
+            removed += 1
+    return removed

cli_to_py/case.py

@@ -0,0 +1,11 @@
+"""Case conversion between Python snake_case and CLI --kebab-case."""
+
+from __future__ import annotations
+
+
+def snake_to_kebab(name: str) -> str:
+    return name.replace("_", "-")
+
+
+def kebab_to_snake(name: str) -> str:
+    return name.replace("-", "_")