fnox-py 0.1.0__tar.gz

fnox_py-0.1.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: fnox-py
+Version: 0.1.0
+Summary: Python bindings for fnox
+Author: Zach Fuller
+Author-email: Zach Fuller <zach.fuller1222@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# fnox-py
+
+`fnox-py` is a thin Python wrapper around the [`fnox`](https://github.com/jdx/fnox) binary.
+
+It does not reimplement `fnox` behavior in Python. Instead, it:
+
+- locates a real `fnox` binary
+- builds argv for common commands
+- runs the binary
+- returns parsed results or typed errors
+
+Python requirement: `>=3.12`
+
+## Installation
+
+### pip
+
+```bash
+pip install fnox-py
+```
+
+### uv
+
+```bash
+uv add fnox-py
+```
+
+If you want the CLI available outside a project environment, you can also use a tool install:
+
+```bash
+uv tool install fnox-py
+```
+
+### Bundled binary vs source install
+
+Platform wheels are intended to bundle the `fnox` binary.
+
+If you install from source instead of a platform wheel, `fnox-py` requires a real `fnox` executable to be available via:
+
+- `PATH`, or
+- `FNOX_PY_BINARY=/absolute/path/to/fnox`
+
+Examples:
+
+```bash
+pip install --no-binary fnox-py fnox-py
+```
+
+```bash
+FNOX_PY_BINARY=/usr/local/bin/fnox python -c "import fnox_py; print(fnox_py.version())"
+```
+
+## Binary Resolution
+
+At runtime, `fnox-py` resolves the `fnox` binary in this order:
+
+1. `FNOX_PY_BINARY`
+2. bundled/installed locations in the current environment
+3. bundled/installed fallback locations associated with the base or target install
+4. user scheme script location
+5. `PATH`
+
+If `FNOX_PY_BINARY` is set but points to a missing file, `fnox-py` raises `FnoxNotFoundError`.
+
+## Python API
+
+```python
+from fnox_py import (
+    config_files,
+    export_json,
+    get,
+    lease_create,
+    profiles,
+    providers,
+    schema,
+    version,
+)
+
+value = get("MY_SECRET")
+all_values = export_json()
+schema_doc = schema()
+profile_names = profiles()
+provider_names = providers()
+config_paths = config_files()
+lease = lease_create("vault", duration="1h", label="local-dev")
+fnox_version = version()
+```
+
+### Common examples
+
+Get a single value:
+
+```python
+from fnox_py import get
+
+token = get("API_TOKEN")
+```
+
+Get a value from a specific profile:
+
+```python
+from fnox_py import get
+
+token = get("API_TOKEN", profile="prod")
+```
+
+Decode base64 output:
+
+```python
+from fnox_py import get
+
+decoded = get("TLS_CERT", base64_decode=True)
+```
+
+Export all secrets as JSON:
+
+```python
+from fnox_py import export_json
+
+data = export_json(profile="dev")
+```
+
+Inspect schema, profiles, providers, and config files:
+
+```python
+from fnox_py import config_files, profiles, providers, schema
+
+print(schema())
+print(profiles())
+print(providers())
+print(config_files())
+```
+
+Create a lease:
+
+```python
+from fnox_py import lease_create
+
+lease = lease_create("vault", duration="30m", label="ci-job")
+```
+
+Get the underlying `fnox` version:
+
+```python
+from fnox_py import version
+
+print(version())
+```
+
+## CLI
+
+The package installs the `fnox-py` console script.
+
+### Built-in subcommands
+
+Locate the resolved binary:
+
+```bash
+fnox-py which
+```
+
+Show the wrapper version and attempt to print the underlying `fnox` version:
+
+```bash
+fnox-py version
+```
+
+Print basic environment diagnostics:
+
+```bash
+fnox-py doctor
+```
+
+### Passthrough behavior
+
+Any arguments other than `which`, `version`, and `doctor` are passed directly through to `fnox`.
+
+For example:
+
+```bash
+fnox-py get MY_SECRET
+fnox-py profiles
+fnox-py export --format json
+```
+
+With no arguments, `fnox-py` runs `fnox` with no extra argv.
+
+## Public API
+
+`fnox-py` currently exports:
+
+- `config_files`
+- `export_json`
+- `get`
+- `lease_create`
+- `profiles`
+- `providers`
+- `schema`
+- `version`
+- `find_fnox_bin`
+- `run`
+- `FnoxResult`
+- `FnoxCommandError`
+- `FnoxError`
+- `FnoxNotFoundError`
+- `FnoxTimeoutError`
+
+## Errors
+
+Library calls raise typed exceptions:
+
+- `FnoxNotFoundError` when the binary cannot be found
+- `FnoxCommandError` when `fnox` exits non-zero
+- `FnoxTimeoutError` on subprocess timeout
+- `FnoxError` as the base exception type
+
+## Development
+
+This project uses `uv`, `pytest`, `ruff`, and `mypy`.
+
+Install dependencies:
+
+```bash
+uv sync
+```
+
+Run tests:
+
+```bash
+uv run pytest -v
+```
+
+Run a single test:
+
+```bash
+uv run pytest tests/test_api.py::test_get -q
+```
+
+Lint:
+
+```bash
+uv run ruff check src tests scripts
+```
+
+Type-check:
+
+```bash
+uv run mypy src
+```
+
+Build distributions:
+
+```bash
+uv build
+```
+
+## Release / Platform Wheel Build
+
+`scripts/build_platform_wheel.py` builds platform-specific wheels by:
+
+1. building a pure Python wheel
+2. downloading upstream `fnox` release binaries
+3. injecting the binary into the wheel
+4. rewriting wheel metadata
+5. building an sdist
+
+Example:
+
+```bash
+uv run python scripts/build_platform_wheel.py --fnox-version 1.0.0 --output dist/
+```
+
+## Notes
+
+- `fnox-py` is intentionally small and wrapper-focused.
+- For behavior, flags, and command semantics, prefer the upstream `fnox` documentation.
+- If you need lower-level control, use `run()` directly and inspect `FnoxResult`.

fnox_py-0.1.0/README.md

@@ -0,0 +1,277 @@
+# fnox-py
+
+`fnox-py` is a thin Python wrapper around the [`fnox`](https://github.com/jdx/fnox) binary.
+
+It does not reimplement `fnox` behavior in Python. Instead, it:
+
+- locates a real `fnox` binary
+- builds argv for common commands
+- runs the binary
+- returns parsed results or typed errors
+
+Python requirement: `>=3.12`
+
+## Installation
+
+### pip
+
+```bash
+pip install fnox-py
+```
+
+### uv
+
+```bash
+uv add fnox-py
+```
+
+If you want the CLI available outside a project environment, you can also use a tool install:
+
+```bash
+uv tool install fnox-py
+```
+
+### Bundled binary vs source install
+
+Platform wheels are intended to bundle the `fnox` binary.
+
+If you install from source instead of a platform wheel, `fnox-py` requires a real `fnox` executable to be available via:
+
+- `PATH`, or
+- `FNOX_PY_BINARY=/absolute/path/to/fnox`
+
+Examples:
+
+```bash
+pip install --no-binary fnox-py fnox-py
+```
+
+```bash
+FNOX_PY_BINARY=/usr/local/bin/fnox python -c "import fnox_py; print(fnox_py.version())"
+```
+
+## Binary Resolution
+
+At runtime, `fnox-py` resolves the `fnox` binary in this order:
+
+1. `FNOX_PY_BINARY`
+2. bundled/installed locations in the current environment
+3. bundled/installed fallback locations associated with the base or target install
+4. user scheme script location
+5. `PATH`
+
+If `FNOX_PY_BINARY` is set but points to a missing file, `fnox-py` raises `FnoxNotFoundError`.
+
+## Python API
+
+```python
+from fnox_py import (
+    config_files,
+    export_json,
+    get,
+    lease_create,
+    profiles,
+    providers,
+    schema,
+    version,
+)
+
+value = get("MY_SECRET")
+all_values = export_json()
+schema_doc = schema()
+profile_names = profiles()
+provider_names = providers()
+config_paths = config_files()
+lease = lease_create("vault", duration="1h", label="local-dev")
+fnox_version = version()
+```
+
+### Common examples
+
+Get a single value:
+
+```python
+from fnox_py import get
+
+token = get("API_TOKEN")
+```
+
+Get a value from a specific profile:
+
+```python
+from fnox_py import get
+
+token = get("API_TOKEN", profile="prod")
+```
+
+Decode base64 output:
+
+```python
+from fnox_py import get
+
+decoded = get("TLS_CERT", base64_decode=True)
+```
+
+Export all secrets as JSON:
+
+```python
+from fnox_py import export_json
+
+data = export_json(profile="dev")
+```
+
+Inspect schema, profiles, providers, and config files:
+
+```python
+from fnox_py import config_files, profiles, providers, schema
+
+print(schema())
+print(profiles())
+print(providers())
+print(config_files())
+```
+
+Create a lease:
+
+```python
+from fnox_py import lease_create
+
+lease = lease_create("vault", duration="30m", label="ci-job")
+```
+
+Get the underlying `fnox` version:
+
+```python
+from fnox_py import version
+
+print(version())
+```
+
+## CLI
+
+The package installs the `fnox-py` console script.
+
+### Built-in subcommands
+
+Locate the resolved binary:
+
+```bash
+fnox-py which
+```
+
+Show the wrapper version and attempt to print the underlying `fnox` version:
+
+```bash
+fnox-py version
+```
+
+Print basic environment diagnostics:
+
+```bash
+fnox-py doctor
+```
+
+### Passthrough behavior
+
+Any arguments other than `which`, `version`, and `doctor` are passed directly through to `fnox`.
+
+For example:
+
+```bash
+fnox-py get MY_SECRET
+fnox-py profiles
+fnox-py export --format json
+```
+
+With no arguments, `fnox-py` runs `fnox` with no extra argv.
+
+## Public API
+
+`fnox-py` currently exports:
+
+- `config_files`
+- `export_json`
+- `get`
+- `lease_create`
+- `profiles`
+- `providers`
+- `schema`
+- `version`
+- `find_fnox_bin`
+- `run`
+- `FnoxResult`
+- `FnoxCommandError`
+- `FnoxError`
+- `FnoxNotFoundError`
+- `FnoxTimeoutError`
+
+## Errors
+
+Library calls raise typed exceptions:
+
+- `FnoxNotFoundError` when the binary cannot be found
+- `FnoxCommandError` when `fnox` exits non-zero
+- `FnoxTimeoutError` on subprocess timeout
+- `FnoxError` as the base exception type
+
+## Development
+
+This project uses `uv`, `pytest`, `ruff`, and `mypy`.
+
+Install dependencies:
+
+```bash
+uv sync
+```
+
+Run tests:
+
+```bash
+uv run pytest -v
+```
+
+Run a single test:
+
+```bash
+uv run pytest tests/test_api.py::test_get -q
+```
+
+Lint:
+
+```bash
+uv run ruff check src tests scripts
+```
+
+Type-check:
+
+```bash
+uv run mypy src
+```
+
+Build distributions:
+
+```bash
+uv build
+```
+
+## Release / Platform Wheel Build
+
+`scripts/build_platform_wheel.py` builds platform-specific wheels by:
+
+1. building a pure Python wheel
+2. downloading upstream `fnox` release binaries
+3. injecting the binary into the wheel
+4. rewriting wheel metadata
+5. building an sdist
+
+Example:
+
+```bash
+uv run python scripts/build_platform_wheel.py --fnox-version 1.0.0 --output dist/
+```
+
+## Notes
+
+- `fnox-py` is intentionally small and wrapper-focused.
+- For behavior, flags, and command semantics, prefer the upstream `fnox` documentation.
+- If you need lower-level control, use `run()` directly and inspect `FnoxResult`.

fnox_py-0.1.0/pyproject.toml

@@ -0,0 +1,104 @@
+[project]
+name = "fnox-py"
+version = "0.1.0"
+description = "Python bindings for fnox"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "Zach Fuller", email = "zach.fuller1222@gmail.com" }]
+requires-python = ">=3.12"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.10.11,<0.11.0"]
+build-backend = "uv_build"
+
+[project.scripts]
+fnox-py = "fnox_py.cli:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "prek>=0.3.6",
+    "ruff>=0.15.6",
+    "pytest>=8.0",
+    "urllib3>=2.6.3",
+    "rich>=14.3.3",
+]
+
+[tool.pyright]
+include = ["src/**", "tests/**"]
+typeCheckingMode = "standard"
+
+[tool.mypy]
+warn_redundant_casts = true
+warn_unused_ignores = true
+disallow_any_generics = true
+check_untyped_defs = true
+no_implicit_reexport = true
+disallow_untyped_defs = true
+local_partial_types = true
+warn_return_any = true
+enable_error_code = [
+    "ignore-without-code",
+    "no-untyped-def",
+    "unreachable",
+    "unused-awaitable",
+    "explicit-override",
+    "mutable-override",
+    "exhaustive-match",
+]
+
+[tool.ruff]
+include = ["src/**", "tests/**", "scripts/**"]
+exclude = ["tests/data/*.txt", ".venv"]
+line-length = 120
+indent-width = 4
+
+target-version = "py313"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "C90",
+    "I",
+    "N",
+    "UP",
+    "ASYNC",
+    "S",
+    "B",
+    "ERA",
+    "PLE",
+    "PLW",
+    "PLC",
+    "PLW",
+    "PERF",
+    "RUF",
+    "SIM",
+    "PT",
+    "T20",
+    "PTH",
+    "LOG",
+    "G",
+]
+ignore = ["E501", "S101", "PLC0415"]
+
+# Allow fix for all enabled rules (when `--fix`) is provided.
+fixable = ["ALL"]
+unfixable = []
+
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/*" = ["S603", "S607", "S202", "T201"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.ty.rules]
+possibly-unresolved-reference = "warn"

fnox_py-0.1.0/src/fnox_py/__init__.py

@@ -0,0 +1,31 @@
+from .api import (
+    config_files,
+    export_json,
+    get,
+    lease_create,
+    profiles,
+    providers,
+    schema,
+    version,
+)
+from .binary import find_fnox_bin
+from .errors import FnoxCommandError, FnoxError, FnoxNotFoundError, FnoxTimeoutError
+from .runner import FnoxResult, run
+
+__all__ = [
+    "FnoxCommandError",
+    "FnoxError",
+    "FnoxNotFoundError",
+    "FnoxResult",
+    "FnoxTimeoutError",
+    "config_files",
+    "export_json",
+    "find_fnox_bin",
+    "get",
+    "lease_create",
+    "profiles",
+    "providers",
+    "run",
+    "schema",
+    "version",
+]

fnox_py-0.1.0/src/fnox_py/api.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from . import runner
+
+
+def get(
+    key: str,
+    *,
+    profile: str | None = None,
+    base64_decode: bool = False,
+    env: Mapping[str, str] | None = None,
+    cwd: str | Path | None = None,
+    timeout: float | None = None,
+) -> str:
+    """Get a single secret value by key."""
+    args: list[str] = ["get"]
+    if profile is not None:
+        args.extend(["--profile", profile])
+    if base64_decode:
+        args.append("--base64-decode")
+    args.append(key)
+    result = runner.run(args, env=env, cwd=cwd, timeout=timeout)
+    return result.stdout.rstrip("\n")
+
+
+def export_json(
+    *,
+    profile: str | None = None,
+    env: Mapping[str, str] | None = None,
+    cwd: str | Path | None = None,
+    timeout: float | None = None,
+) -> dict[str, str]:
+    """Export all secrets as a JSON dictionary."""
+    args: list[str] = ["export"]
+    if profile is not None:
+        args.extend(["--profile", profile])
+    args.extend(["--format", "json"])
+    result = runner.run(args, env=env, cwd=cwd, timeout=timeout)
+    return json.loads(result.stdout)  # type: ignore[no-any-return]
+
+
+def schema(
+    *,
+    timeout: float | None = None,
+) -> dict[str, Any]:
+    """Return the fnox JSON schema."""
+    result = runner.run(["schema"], timeout=timeout)
+    return json.loads(result.stdout)  # type: ignore[no-any-return]
+
+
+def profiles(
+    *,
+    env: Mapping[str, str] | None = None,
+    cwd: str | Path | None = None,
+    timeout: float | None = None,
+) -> list[str]:
+    """List available profiles."""
+    result = runner.run(["profiles"], env=env, cwd=cwd, timeout=timeout)
+    return result.stdout.strip().splitlines()
+
+
+def providers(
+    *,
+    env: Mapping[str, str] | None = None,
+    cwd: str | Path | None = None,
+    timeout: float | None = None,
+) -> list[str]:
+    """List available providers."""
+    result = runner.run(["providers"], env=env, cwd=cwd, timeout=timeout)
+    return result.stdout.strip().splitlines()
+
+
+def config_files(
+    *,
+    env: Mapping[str, str] | None = None,
+    cwd: str | Path | None = None,
+    timeout: float | None = None,
+) -> list[str]:
+    """List config file paths."""
+    result = runner.run(["config-files"], env=env, cwd=cwd, timeout=timeout)
+    return result.stdout.strip().splitlines()
+
+
+def lease_create(
+    backend: str,
+    *,
+    duration: str | None = None,
+    label: str | None = None,
+    env: Mapping[str, str] | None = None,
+    cwd: str | Path | None = None,
+    timeout: float | None = None,
+) -> dict[str, Any]:
+    """Create a lease and return its metadata."""
+    args: list[str] = ["lease", "create"]
+    if duration is not None:
+        args.extend(["--duration", duration])
+    if label is not None:
+        args.extend(["--label", label])
+    args.extend(["--format", "json", backend])
+    result = runner.run(args, env=env, cwd=cwd, timeout=timeout)
+    return json.loads(result.stdout)  # type: ignore[no-any-return]
+
+
+def version(
+    *,
+    timeout: float | None = None,
+) -> str:
+    """Return the fnox version string."""
+    result = runner.run(["version"], timeout=timeout)
+    return result.stdout.strip()

fnox_py-0.1.0/src/fnox_py/binary.py

@@ -0,0 +1,94 @@
+# Binary discovery for fnox.
+#
+# Resolution order mirrors prek (MIT, Astral Software Inc.) with an
+# additional env-var override and PATH fallback.
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+import sysconfig
+from fnmatch import fnmatch
+from pathlib import Path
+
+from .errors import FnoxNotFoundError
+
+_MODULE_DIR = str(Path(__file__).parent)
+
+
+def find_fnox_bin() -> str:
+    """Return the path to the fnox binary."""
+
+    # 1. Env-var override (hard error if set but missing)
+    env_path = os.environ.get("FNOX_PY_BINARY")
+    if env_path is not None:
+        if Path(env_path).is_file():
+            return env_path
+        raise FnoxNotFoundError(f"FNOX_PY_BINARY is set to {env_path!r} but the file does not exist")
+
+    fnox_exe = "fnox" + sysconfig.get_config_var("EXE")
+
+    targets: list[str | None] = [
+        # 2. Current venv scripts
+        sysconfig.get_path("scripts"),
+        # 3. Base prefix scripts
+        sysconfig.get_path("scripts", vars={"base": sys.base_prefix}),
+        # 4. Parent-of-package-root (platform-aware)
+        (
+            _join(_matching_parents(_MODULE_DIR, "Lib/site-packages/fnox_py"), "Scripts")
+            if sys.platform == "win32"
+            else _join(_matching_parents(_MODULE_DIR, "lib/python*/site-packages/fnox_py"), "bin")
+        ),
+        # 5. Adjacent-to-package-root (--target installs)
+        _join(_matching_parents(_MODULE_DIR, "fnox_py"), "bin"),
+        # 6. User scheme scripts
+        sysconfig.get_path("scripts", scheme=sysconfig.get_preferred_scheme("user")),
+    ]
+
+    seen: list[str] = []
+    for target in targets:
+        if not target:
+            continue
+        if target in seen:
+            continue
+        seen.append(target)
+        candidate = Path(target) / fnox_exe
+        if candidate.is_file():
+            return str(candidate)
+
+    # 7. PATH fallback (for sdist installs without bundled binary)
+    which = shutil.which("fnox")
+    if which is not None:
+        return which
+
+    locations = "\n".join(f" - {target}" for target in seen)
+    raise FnoxNotFoundError(
+        f"Could not find the fnox binary in any of the following locations:\n{locations}\n"
+        "Install fnox or set the FNOX_PY_BINARY environment variable."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Helpers (ported from prek, MIT license, Astral Software Inc.)
+# ---------------------------------------------------------------------------
+
+
+def _matching_parents(path: str, match: str) -> str | None:
+    parts = Path(path).parts
+    match_parts = match.split("/")
+    if len(parts) < len(match_parts):
+        return None
+
+    if not all(
+        fnmatch(part, match_part) for part, match_part in zip(reversed(parts), reversed(match_parts), strict=False)
+    ):
+        return None
+
+    return str(Path(*parts[: -len(match_parts)]))
+
+
+def _join(path: str | None, *parts: str) -> str | None:
+    if not path:
+        return None
+    return str(Path(path).joinpath(*parts))

fnox_py-0.1.0/src/fnox_py/cli.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import sys
+
+from .binary import find_fnox_bin
+from .errors import FnoxNotFoundError
+from .runner import run, run_passthrough
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        run_passthrough([])
+        return
+
+    subcmd = sys.argv[1]
+
+    if subcmd == "which":
+        _cmd_which()
+    elif subcmd == "version":
+        _cmd_version()
+    elif subcmd == "doctor":
+        _cmd_doctor()
+    else:
+        run_passthrough(sys.argv[1:])
+
+
+def _cmd_which() -> None:
+    try:
+        path = find_fnox_bin()
+    except FnoxNotFoundError as exc:
+        print(str(exc), file=sys.stderr)  # noqa: T201
+        sys.exit(1)
+    print(path)  # noqa: T201
+
+
+def _cmd_version() -> None:
+    from importlib.metadata import version as pkg_version
+
+    wrapper_version = pkg_version("fnox-py")
+    print(f"fnox-py {wrapper_version}")  # noqa: T201
+    try:
+        result = run(["version"], check=False)
+        print(result.stdout.strip())  # noqa: T201
+    except FnoxNotFoundError:
+        print("fnox binary not found", file=sys.stderr)  # noqa: T201
+
+
+def _cmd_doctor() -> None:
+    import shutil
+    from importlib.metadata import version as pkg_version
+
+    print(f"fnox-py {pkg_version('fnox-py')}")  # noqa: T201
+    print(f"Python  {sys.version}")  # noqa: T201
+    try:
+        path = find_fnox_bin()
+        print(f"Binary  {path}")  # noqa: T201
+        is_bundled = shutil.which("fnox") != path
+        print(f"Bundled {is_bundled}")  # noqa: T201
+        result = run(["version"], check=False)
+        print(f"fnox    {result.stdout.strip()}")  # noqa: T201
+    except FnoxNotFoundError as exc:
+        print(f"Binary  NOT FOUND: {exc}", file=sys.stderr)  # noqa: T201

fnox_py-0.1.0/src/fnox_py/errors.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+
+class FnoxError(Exception):
+    """Base exception for fnox-py."""
+
+
+class FnoxNotFoundError(FnoxError, FileNotFoundError):
+    """The fnox binary could not be found."""
+
+
+class FnoxCommandError(FnoxError):
+    """fnox exited with a non-zero return code."""
+
+    def __init__(self, returncode: int, stdout: str, stderr: str, cmd: list[str]) -> None:
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+        self.cmd = cmd
+        super().__init__(f"fnox failed with exit code {returncode}: {stderr.strip() or stdout.strip()}")
+
+
+class FnoxTimeoutError(FnoxError):
+    """fnox subprocess timed out."""

fnox_py-0.1.0/src/fnox_py/runner.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import dataclasses
+import os
+import subprocess
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import NoReturn
+
+from .binary import find_fnox_bin
+from .errors import FnoxCommandError, FnoxNotFoundError, FnoxTimeoutError
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class FnoxResult:
+    returncode: int
+    stdout: str
+    stderr: str
+    cmd: list[str]
+
+
+def run(
+    args: Sequence[str],
+    *,
+    env: Mapping[str, str] | None = None,
+    cwd: str | Path | None = None,
+    check: bool = True,
+    timeout: float | None = None,
+    input: str | None = None,
+) -> FnoxResult:
+    """Run fnox with the given arguments and return the result."""
+    fnox = find_fnox_bin()
+    cmd = [fnox, *args]
+
+    run_env: dict[str, str] | None = None
+    if env is not None:
+        run_env = {**os.environ, **env}
+
+    try:
+        proc = subprocess.run(  # noqa: S603
+            cmd,
+            capture_output=True,
+            text=True,
+            env=run_env,
+            cwd=cwd,
+            timeout=timeout,
+            input=input,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise FnoxTimeoutError(f"fnox timed out after {exc.timeout}s") from exc
+    except FileNotFoundError as exc:
+        raise FnoxNotFoundError(str(exc)) from exc
+
+    result = FnoxResult(
+        returncode=proc.returncode,
+        stdout=proc.stdout,
+        stderr=proc.stderr,
+        cmd=cmd,
+    )
+
+    if check and proc.returncode != 0:
+        raise FnoxCommandError(proc.returncode, proc.stdout, proc.stderr, cmd)
+
+    return result
+
+
+def run_passthrough(
+    args: Sequence[str],
+    *,
+    env: Mapping[str, str] | None = None,
+    cwd: str | Path | None = None,
+) -> NoReturn:
+    """Run fnox, forwarding stdio directly. On Unix, replaces the process."""
+    fnox = find_fnox_bin()
+    cmd = [fnox, *args]
+
+    if sys.platform == "win32":
+        try:
+            proc = subprocess.run(cmd, env=env, cwd=cwd, check=False)  # noqa: S603
+        except KeyboardInterrupt:
+            sys.exit(2)
+        sys.exit(proc.returncode)
+    else:
+        if env is not None:
+            os.environ.update(env)
+        if cwd is not None:
+            os.chdir(cwd)
+        os.execvp(fnox, cmd)  # noqa: S606