cli-to-py 0.1.0__tar.gz

cli_to_py-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Run tests and build package
+        run: make ci

cli_to_py-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,59 @@
+name: Docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build docs
+        run: make docs
+
+      - name: Configure Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

cli_to_py-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+scratch/
+.venv/
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.pytest_cache/
+.coverage

cli_to_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mehmet Oner Yalcin
+
+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.

cli_to_py-0.1.0/Makefile

@@ -0,0 +1,58 @@
+UV ?= uv --no-config
+PYTEST ?= python -m pytest
+PYPI_CHECK_URL ?= https://pypi.org/simple/
+
+.PHONY: help test test-unit test-integration build clean ci smoke docs docs-serve publish-check publish
+
+help:
+	@printf '%s\n' \
+		'Targets:' \
+		'  make test              Run unit and integration tests' \
+		'  make test-unit         Run unit tests only' \
+		'  make test-integration  Run integration tests only' \
+		'  make build             Build sdist and wheel' \
+		'  make ci                Run CI-equivalent checks except matrix Python' \
+		'  make smoke             Run local smoke script (not used in CI)' \
+		'  make docs              Build MkDocs documentation' \
+		'  make docs-serve        Serve MkDocs documentation locally' \
+		'  make clean             Remove local generated artifacts' \
+		'  make publish-check     Dry-run publish built artifacts' \
+		'  make publish           Publish built artifacts to PyPI'
+
+test:
+	$(UV) run --locked --extra dev $(PYTEST) -q
+
+test-unit:
+	$(UV) run --locked --extra dev $(PYTEST) tests/unit -q
+
+test-integration:
+	$(UV) run --locked --extra dev $(PYTEST) tests/integration -q
+
+build:
+	$(UV) build
+
+ci: test build
+
+smoke:
+	$(UV) run --locked python smoke_test.py
+
+docs:
+	$(UV) run --with mkdocs-material mkdocs build --strict
+
+docs-serve:
+	$(UV) run --with mkdocs-material mkdocs serve
+
+clean:
+	rm -rf .pytest_cache dist site *.egg-info
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +
+
+publish-check: build
+	@if [ -n "$$PYPI_TOKEN" ]; then \
+		UV_PUBLISH_TOKEN="$$PYPI_TOKEN" $(UV) publish --dry-run --check-url $(PYPI_CHECK_URL) dist/*; \
+	else \
+		$(UV) publish --dry-run --check-url $(PYPI_CHECK_URL) dist/*; \
+	fi
+
+publish: build
+	@test -n "$(PYPI_TOKEN)" || (printf '%s\n' 'PYPI_TOKEN is required' >&2; exit 1)
+	@UV_PUBLISH_TOKEN="$(PYPI_TOKEN)" $(UV) publish --check-url $(PYPI_CHECK_URL) dist/*

cli_to_py-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: cli-to-py
+Version: 0.1.0
+Summary: Turn any CLI into a Python API, automatically.
+License: MIT
+License-File: LICENSE
+Keywords: agent,cli,introspection,subprocess,wrapper
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Shells
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cli-to-py
+
+[![PyPI version](https://img.shields.io/pypi/v/cli-to-py)](https://pypi.org/project/cli-to-py/)
+[![Python versions](https://img.shields.io/pypi/pyversions/cli-to-py)](https://pypi.org/project/cli-to-py/)
+[![CI](https://github.com/oneryalcin/cli-to-py/actions/workflows/ci.yml/badge.svg)](https://github.com/oneryalcin/cli-to-py/actions/workflows/ci.yml)
+[![Docs](https://github.com/oneryalcin/cli-to-py/actions/workflows/pages.yml/badge.svg)](https://github.com/oneryalcin/cli-to-py/actions/workflows/pages.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Turn CLI binaries into Python APIs.
+
+`cli-to-py` reads a command's help output, builds a callable Python wrapper, and
+lets you run subcommands with keyword arguments instead of hand-built shell
+strings.
+
+Full documentation: <https://oneryalcin.github.io/cli-to-py/>
+
+## Install
+
+```bash
+pip install cli-to-py
+```
+
+or:
+
+```bash
+uv add cli-to-py
+```
+
+Requires Python 3.11 or newer.
+
+## Quick Start
+
+```python
+import asyncio
+from cli_to_py import convert
+
+async def main():
+    git = await convert("git")
+
+    result = await git.status(short=True)
+    print(result.stdout)
+
+    branch = await git.branch(show_current=True).text()
+    changed = await git("diff", name_only=True, _=["HEAD~1"]).lines()
+
+    print(branch)
+    print(changed)
+
+asyncio.run(main())
+```
+
+Flags use Python names and are converted to CLI flags:
+
+```python
+await git.commit(message="fix", all=True)
+# runs: git commit --message fix --all
+```
+
+Use `_` for positional arguments:
+
+```python
+await git("diff", name_only=True, _=["HEAD~1"])
+# runs: git diff --name-only HEAD~1
+```
+
+## Why Use It
+
+- Convert CLIs into async Python APIs with no runtime dependencies.
+- Validate flags and arguments before spawning a subprocess.
+- Keep subprocess output ergonomic with `.text()`, `.lines()`, and `.json()`.
+- Stream output, inherit stdio, set timeouts, pass env/cwd, and cancel work.
+- Generate standalone wrapper modules for tools you want to check into a project.
+
+## Documentation
+
+- [Installation](https://oneryalcin.github.io/cli-to-py/getting-started/installation/)
+- [Quick start](https://oneryalcin.github.io/cli-to-py/getting-started/quickstart/)
+- [Validation](https://oneryalcin.github.io/cli-to-py/user-guide/validation/)
+- [Runtime control](https://oneryalcin.github.io/cli-to-py/user-guide/runtime-control/)
+- [Code generation](https://oneryalcin.github.io/cli-to-py/user-guide/code-generation/)
+- [Parser limits](https://oneryalcin.github.io/cli-to-py/user-guide/parser-limits/)
+- [Public API](https://oneryalcin.github.io/cli-to-py/api-reference/public-api/)
+
+## CLI Wrapper Generation
+
+Generate a dependency-free Python wrapper from a CLI:
+
+```bash
+cli-to-py git -o git_wrapper.py
+```
+
+The generated `.py` module and `.pyi` stub can be committed to another project
+without depending on `cli-to-py` at runtime.
+
+## Development
+
+```bash
+make test      # unit and integration tests
+make ci        # full CI path, including package build
+make docs      # strict MkDocs build
+make build     # source distribution and wheel
+```
+
+See the [release checklist](https://oneryalcin.github.io/cli-to-py/development/release-checklist/)
+for publishing steps.
+
+## Status
+
+This project parses common `--help` formats pragmatically. It is useful for many
+CLIs, but it is not a formal parser for every help style. See
+[parser limits](https://oneryalcin.github.io/cli-to-py/user-guide/parser-limits/)
+before relying on generated wrappers for unusual CLIs.

cli_to_py-0.1.0/README.md

@@ -0,0 +1,112 @@
+# cli-to-py
+
+[![PyPI version](https://img.shields.io/pypi/v/cli-to-py)](https://pypi.org/project/cli-to-py/)
+[![Python versions](https://img.shields.io/pypi/pyversions/cli-to-py)](https://pypi.org/project/cli-to-py/)
+[![CI](https://github.com/oneryalcin/cli-to-py/actions/workflows/ci.yml/badge.svg)](https://github.com/oneryalcin/cli-to-py/actions/workflows/ci.yml)
+[![Docs](https://github.com/oneryalcin/cli-to-py/actions/workflows/pages.yml/badge.svg)](https://github.com/oneryalcin/cli-to-py/actions/workflows/pages.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Turn CLI binaries into Python APIs.
+
+`cli-to-py` reads a command's help output, builds a callable Python wrapper, and
+lets you run subcommands with keyword arguments instead of hand-built shell
+strings.
+
+Full documentation: <https://oneryalcin.github.io/cli-to-py/>
+
+## Install
+
+```bash
+pip install cli-to-py
+```
+
+or:
+
+```bash
+uv add cli-to-py
+```
+
+Requires Python 3.11 or newer.
+
+## Quick Start
+
+```python
+import asyncio
+from cli_to_py import convert
+
+async def main():
+    git = await convert("git")
+
+    result = await git.status(short=True)
+    print(result.stdout)
+
+    branch = await git.branch(show_current=True).text()
+    changed = await git("diff", name_only=True, _=["HEAD~1"]).lines()
+
+    print(branch)
+    print(changed)
+
+asyncio.run(main())
+```
+
+Flags use Python names and are converted to CLI flags:
+
+```python
+await git.commit(message="fix", all=True)
+# runs: git commit --message fix --all
+```
+
+Use `_` for positional arguments:
+
+```python
+await git("diff", name_only=True, _=["HEAD~1"])
+# runs: git diff --name-only HEAD~1
+```
+
+## Why Use It
+
+- Convert CLIs into async Python APIs with no runtime dependencies.
+- Validate flags and arguments before spawning a subprocess.
+- Keep subprocess output ergonomic with `.text()`, `.lines()`, and `.json()`.
+- Stream output, inherit stdio, set timeouts, pass env/cwd, and cancel work.
+- Generate standalone wrapper modules for tools you want to check into a project.
+
+## Documentation
+
+- [Installation](https://oneryalcin.github.io/cli-to-py/getting-started/installation/)
+- [Quick start](https://oneryalcin.github.io/cli-to-py/getting-started/quickstart/)
+- [Validation](https://oneryalcin.github.io/cli-to-py/user-guide/validation/)
+- [Runtime control](https://oneryalcin.github.io/cli-to-py/user-guide/runtime-control/)
+- [Code generation](https://oneryalcin.github.io/cli-to-py/user-guide/code-generation/)
+- [Parser limits](https://oneryalcin.github.io/cli-to-py/user-guide/parser-limits/)
+- [Public API](https://oneryalcin.github.io/cli-to-py/api-reference/public-api/)
+
+## CLI Wrapper Generation
+
+Generate a dependency-free Python wrapper from a CLI:
+
+```bash
+cli-to-py git -o git_wrapper.py
+```
+
+The generated `.py` module and `.pyi` stub can be committed to another project
+without depending on `cli-to-py` at runtime.
+
+## Development
+
+```bash
+make test      # unit and integration tests
+make ci        # full CI path, including package build
+make docs      # strict MkDocs build
+make build     # source distribution and wheel
+```
+
+See the [release checklist](https://oneryalcin.github.io/cli-to-py/development/release-checklist/)
+for publishing steps.
+
+## Status
+
+This project parses common `--help` formats pragmatically. It is useful for many
+CLIs, but it is not a formal parser for every help style. See
+[parser limits](https://oneryalcin.github.io/cli-to-py/user-guide/parser-limits/)
+before relying on generated wrappers for unusual CLIs.

cli_to_py-0.1.0/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-0.1.0/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