feat: add Python interface to Codex CLI (run_exec) with robust errors; tests, docs

Author: gersmann

README.md

@@ -13,6 +13,23 @@ A minimal Python library scaffold using `uv` with Python 3.13+.
 - 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")`
+
 ### Install uv
 
 - macOS (Homebrew): `brew install uv`

codex/__init__.py

@@ -1,12 +1,22 @@
 """codex
 
-Minimal Python library package.
+Python interface for the Codex CLI.
 
-This package is intentionally lightweight; extend as needed.
+Usage:
+    from codex import run_exec
+    output = run_exec("explain this codebase to me")
 """
 
-__all__ = ["__version__"]
+from .api import CodexError, CodexNotFoundError, CodexProcessError, find_binary, run_exec
+
+__all__ = [
+    "__version__",
+    "CodexError",
+    "CodexNotFoundError",
+    "CodexProcessError",
+    "find_binary",
+    "run_exec",
+]
 
 # Managed by Hatch via pyproject.toml [tool.hatch.version]
 __version__ = "0.1.0"
-

codex/api.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Iterable, Mapping, Optional, Sequence
+
+
+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: Optional[str] = None,
+    full_auto: bool = False,
+    cd: Optional[str] = None,
+    timeout: Optional[float] = None,
+    env: Optional[Mapping[str, str]] = None,
+    executable: str = "codex",
+    extra_args: Optional[Iterable[str]] = 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
+

tests/test_api.py

@@ -0,0 +1,29 @@
+import os
+import stat
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from codex.api import CodexNotFoundError, run_exec
+
+
+def test_missing_binary_raises():
+    with pytest.raises(CodexNotFoundError):
+        run_exec("hello", executable="codex-does-not-exist-xyz")
+
+
+def test_runs_with_dummy_binary(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    # Create a dummy 'codex' executable that echoes args and succeeds
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    codex_path = bin_dir / "codex"
+    codex_path.write_text("""#!/bin/sh\necho \"[dummy] $@\"\n""")
+    codex_path.chmod(codex_path.stat().st_mode | stat.S_IXUSR)
+
+    # Prepend our dummy bin to PATH
+    monkeypatch.setenv("PATH", f"{bin_dir}{os.pathsep}" + os.environ.get("PATH", ""))
+
+    out = run_exec("hello world", executable="codex")
+    assert "[dummy] exec hello world" in out
+