codex-python 0.1.0__py3-none-any.whl

codex/__init__.py

@@ -0,0 +1,30 @@
+"""codex
+
+Python interface for the Codex CLI.
+
+Usage:
+    from codex import run_exec
+    output = run_exec("explain this codebase to me")
+"""
+
+from .api import (
+    CodexClient,
+    CodexError,
+    CodexNotFoundError,
+    CodexProcessError,
+    find_binary,
+    run_exec,
+)
+
+__all__ = [
+    "__version__",
+    "CodexError",
+    "CodexNotFoundError",
+    "CodexProcessError",
+    "CodexClient",
+    "find_binary",
+    "run_exec",
+]
+
+# Managed by Hatch via pyproject.toml [tool.hatch.version]
+__version__ = "0.1.0"

codex/api.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+
+
+class CodexError(Exception):
+    """Base exception for codex-python."""
+
+
+class CodexNotFoundError(CodexError):
+    """Raised when the 'codex' binary cannot be found or executed."""
+
+    def __init__(self, executable: str = "codex") -> None:
+        super().__init__(
+            f"Codex CLI not found: '{executable}'.\n"
+            "Install from https://github.com/openai/codex or ensure it is on PATH."
+        )
+        self.executable = executable
+
+
+@dataclass(slots=True)
+class CodexProcessError(CodexError):
+    """Raised when the codex process exits with a non‑zero status."""
+
+    returncode: int
+    cmd: Sequence[str]
+    stdout: str
+    stderr: str
+
+    def __str__(self) -> str:  # pragma: no cover - repr is sufficient
+        return (
+            f"Codex process failed with exit code {self.returncode}.\n"
+            f"Command: {' '.join(self.cmd)}\n"
+            f"stderr:\n{self.stderr.strip()}"
+        )
+
+
+def find_binary(executable: str = "codex") -> str:
+    """Return the absolute path to the Codex CLI binary or raise if not found."""
+    path = shutil.which(executable)
+    if not path:
+        raise CodexNotFoundError(executable)
+    return path
+
+
+def run_exec(
+    prompt: str,
+    *,
+    model: str | None = None,
+    full_auto: bool = False,
+    cd: str | None = None,
+    timeout: float | None = None,
+    env: Mapping[str, str] | None = None,
+    executable: str = "codex",
+    extra_args: Iterable[str] | None = None,
+) -> str:
+    """
+    Run `codex exec` with the given prompt and return stdout as text.
+
+    - Raises CodexNotFoundError if the binary is unavailable.
+    - Raises CodexProcessError on non‑zero exit with captured stdout/stderr.
+    """
+    bin_path = find_binary(executable)
+
+    cmd: list[str] = [bin_path]
+
+    if cd:
+        cmd.extend(["--cd", cd])
+    if model:
+        cmd.extend(["-m", model])
+    if full_auto:
+        cmd.append("--full-auto")
+    if extra_args:
+        cmd.extend(list(extra_args))
+
+    cmd.extend(["exec", prompt])
+
+    completed = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        env={**os.environ, **(dict(env) if env else {})},
+        check=False,
+    )
+
+    stdout = completed.stdout or ""
+    stderr = completed.stderr or ""
+    if completed.returncode != 0:
+        raise CodexProcessError(
+            returncode=completed.returncode,
+            cmd=tuple(cmd),
+            stdout=stdout,
+            stderr=stderr,
+        )
+    return stdout
+
+
+@dataclass(slots=True)
+class CodexClient:
+    """Lightweight, synchronous client for the Codex CLI.
+
+    Provides defaults for repeated invocations and convenience helpers.
+    """
+
+    executable: str = "codex"
+    model: str | None = None
+    full_auto: bool = False
+    cd: str | None = None
+    env: Mapping[str, str] | None = None
+    extra_args: Sequence[str] | None = None
+
+    def ensure_available(self) -> str:
+        """Return the resolved binary path or raise CodexNotFoundError."""
+        return find_binary(self.executable)
+
+    def run(
+        self,
+        prompt: str,
+        *,
+        model: str | None = None,
+        full_auto: bool | None = None,
+        cd: str | None = None,
+        timeout: float | None = None,
+        env: Mapping[str, str] | None = None,
+        extra_args: Iterable[str] | None = None,
+    ) -> str:
+        """Execute `codex exec` and return stdout.
+
+        Explicit arguments override the client's defaults.
+        """
+        eff_model = model if model is not None else self.model
+        eff_full_auto = full_auto if full_auto is not None else self.full_auto
+        eff_cd = cd if cd is not None else self.cd
+
+        # Merge environment overlays; run_exec will merge with os.environ
+        merged_env: Mapping[str, str] | None
+        if self.env and env:
+            tmp = dict(self.env)
+            tmp.update(env)
+            merged_env = tmp
+        else:
+            merged_env = env or self.env
+
+        # Compose extra args
+        eff_extra: list[str] = []
+        if self.extra_args:
+            eff_extra.extend(self.extra_args)
+        if extra_args:
+            eff_extra.extend(list(extra_args))
+
+        return run_exec(
+            prompt,
+            model=eff_model,
+            full_auto=eff_full_auto,
+            cd=eff_cd,
+            timeout=timeout,
+            env=merged_env,
+            executable=self.executable,
+            extra_args=eff_extra,
+        )

codex/py.typed

@@ -0,0 +1 @@
+

codex_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: codex-python
+Version: 0.1.0
+Summary: A minimal Python library scaffold for codex-python
+Project-URL: Homepage, https://github.com/gersmann/codex-python
+Project-URL: Repository, https://github.com/gersmann/codex-python
+Project-URL: Issues, https://github.com/gersmann/codex-python/issues
+License: MIT License
+        
+        Copyright (c) 2025 gersmann
+        
+        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
+Keywords: codex,library,scaffold
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# codex-python
+
+A minimal Python library scaffold using `uv` with Python 3.13+.
+
+## Quickstart
+
+- Requires Python 3.13+.
+- Package import name: `codex`.
+- Distribution name (PyPI): `codex-python`.
+
+### Repo
+
+- Git: `git@github.com:gersmann/codex-python.git`
+- URL: https://github.com/gersmann/codex-python
+
+## Usage
+
+Basic non-interactive execution via Codex CLI:
+
+```
+from codex import run_exec
+
+out = run_exec("explain this repo")
+print(out)
+```
+
+Options:
+
+- Choose model: `run_exec("...", model="gpt-4.1")`
+- Full auto: `run_exec("scaffold a cli", full_auto=True)`
+- Run in another dir: `run_exec("...", cd="/path/to/project")`
+
+Using a client with defaults:
+
+```
+from codex import CodexClient
+
+client = CodexClient(model="gpt-4.1", full_auto=True)
+print(client.run("explain this repo"))
+```
+
+### Install uv
+
+- macOS (Homebrew): `brew install uv`
+- Or via install script:
+  - Unix/macOS: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+  - Windows (PowerShell): `iwr https://astral.sh/uv/install.ps1 -UseBasicParsing | iex`
+
+See: https://docs.astral.sh/uv/
+
+### Create a virtual env (optional)
+
+```
+uv python install 3.13
+uv venv --python 3.13
+. .venv/bin/activate  # or .venv\Scripts\activate on Windows
+```
+
+### Build
+
+```
+uv build
+```
+
+Artifacts appear in `dist/` (`.whl` and `.tar.gz`).
+
+### Publish to PyPI
+
+- Manual:
+
+```
+export PYPI_API_TOKEN="pypi-XXXX"  # create at https://pypi.org/manage/account/token/
+uv publish --token "$PYPI_API_TOKEN"
+```
+
+- GitHub Actions: add a repository secret `PYPI_API_TOKEN` and push a tag like `v0.1.0`.
+  The workflow at `.github/workflows/publish.yml` builds and publishes with `uv` on `v*` tags.
+
+### Dev tooling
+
+- Lint: `make lint` (ruff + mypy)
+- Tests: `make test` (pytest)
+- Format: `make fmt` (ruff formatter)
+ - Pre-commit: `uvx pre-commit install && uvx pre-commit run --all-files`
+
+## Project Layout
+
+```
+.
+├── codex/              # package root (import name: codex)
+│   └── __init__.py     # version lives here
+├── pyproject.toml      # PEP 621 metadata, hatchling build backend
+├── README.md
+└── .gitignore
+```
+
+## Versioning
+
+Version is managed via `codex/__init__.py` and exposed as `__version__`. The build uses Hatch’s version source.
+
+## Python Compatibility
+
+- Requires Python `>=3.13`.

codex_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+codex/__init__.py,sha256=E7HRcKV0xN5jhgmzYsAkQ2lm1KngmQgiH1T1LbQQ1mU,514
+codex/api.py,sha256=aP1OcnMxSF-vJyxwVIllbydmrFiUESsuePvCyYkBXxo,4614
+codex/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+codex_python-0.1.0.dist-info/METADATA,sha256=sVDPpdgXr-zFL0ege7Spc6ctWuPVE4-Sjnwb17Sls98,4246
+codex_python-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+codex_python-0.1.0.dist-info/licenses/LICENSE,sha256=ZhGahTKhsCbPWNmZ7ugZ14LVewMo4Gh1OeIOlQabyrI,1066
+codex_python-0.1.0.dist-info/RECORD,,

codex_python-0.1.0.dist-info/WHEEL

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

codex_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 gersmann
+
+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.
+