codex-python 0.2.3__tar.gz → 0.2.8__tar.gz

codex_python-0.2.8/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.
+

codex_python-0.2.8/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: codex-python
+Version: 0.2.8
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Typing :: Typed
+Classifier: Operating System :: OS Independent
+Requires-Dist: pydantic>=2.11.7
+License-File: LICENSE
+Summary: A minimal Python library scaffold for codex-python
+Keywords: codex,library,scaffold
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+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
+
+# codex-python
+
+Native Python bindings for Codex (in‑process execution). Ships as a single package (`codex-python`) with platform wheels that include the native extension.
+
+- Python: 3.12–3.13 (CI also attempts 3.14)
+- Import name: `codex`
+- PyPI: https://pypi.org/project/codex-python/
+
+## Install
+
+```
+pip install codex-python
+```
+
+If there’s no prebuilt wheel for your platform/Python, pip will build from source. You’ll need a Rust toolchain and maturin; see “Developing” below.
+
+## Quickstart
+
+Run a prompt and collect structured events (typed):
+
+```
+from codex.api import run_exec, CodexClient
+from codex.config import CodexConfig, ApprovalPolicy, SandboxMode
+
+cfg = CodexConfig(
+    model="gpt-5",
+    model_provider="openai",
+    approval_policy=ApprovalPolicy.ON_REQUEST,
+    sandbox_mode=SandboxMode.WORKSPACE_WRITE,
+)
+
+# One-shot
+events = run_exec("Explain this repo", config=cfg)
+
+# Conversation (streaming)
+client = CodexClient(config=cfg)
+for ev in client.start_conversation("Add a smoke test"):
+    print(ev.id, ev.msg)
+```
+
+Notes
+- `Event.msg` is typed as a union `EventMsg` (also available at `codex.EventMsg`).
+- For raw dict streaming from the native layer, use `codex.native.start_exec_stream`.
+
+## Configuration (Pydantic)
+
+Use `CodexConfig` to pass overrides mirrored from Rust `ConfigOverrides`.
+
+```
+from codex.config import CodexConfig, ApprovalPolicy, SandboxMode
+
+cfg = CodexConfig(
+    model="gpt-5",
+    model_provider="openai",
+    approval_policy=ApprovalPolicy.ON_REQUEST,
+    sandbox_mode=SandboxMode.WORKSPACE_WRITE,
+    cwd="/path/to/project",
+    include_apply_patch_tool=True,
+)
+```
+
+- `CodexConfig.to_dict()` emits only fields you set, with enums serialized to kebab‑case strings expected by the core.
+- For tests and introspection, `codex.native.preview_config(config_overrides=..., load_default_config=...)` returns a compact snapshot of the effective configuration.
+
+## Troubleshooting
+
+- “codex_native extension not installed”
+  - Install with `pip install codex-python` (wheel) or build locally (see below).
+- maturin develop fails without a virtualenv
+  - Use `python -m venv .venv && source .venv/bin/activate` (or conda), or run `make dev-native` which falls back to build+pip install when no venv is present.
+
+## Developing
+
+Prerequisites
+- Python 3.12/3.13
+- Rust toolchain (cargo)
+- maturin (for native builds)
+- uv (optional, for fast Python builds and dev tooling)
+
+Common tasks
+- Lint: `make lint` (ruff + mypy)
+- Test: `make test` (pytest)
+- Format: `make fmt`
+- Build native locally: `make dev-native`
+- Generate protocol types from upstream: `make gen-protocol`
+
+Protocol types
+- `make gen-protocol` generates TS types (via Codex or cargo) into `.generated/ts` and then writes Pydantic models to `codex/protocol/types.py`.
+- Generated models use `model_config = ConfigDict(extra='allow')` and place it at the end of each class.
+
+Releasing
+- Bump `codex/__init__.py` and `crates/codex_native/Cargo.toml` versions.
+- Update `CHANGELOG.md`.
+- Tag and push: `git tag -a vX.Y.Z -m "codex-python X.Y.Z" && git push origin vX.Y.Z`.
+- GitHub Actions (publish.yml) builds native wheels across platforms and an sdist, then publishes them via Trusted Publishing (OIDC).
+
+Project layout
+```
+.
+├── codex/                 # Python package
+├── crates/codex_native/   # PyO3 native extension
+├── scripts/               # generators and helpers
+├── .github/workflows/     # CI, publish, native wheels
+└── Makefile               # common tasks
+```
+
+Links
+- Codex repo: https://github.com/openai/codex
+- uv: https://docs.astral.sh/uv/
+- maturin: https://www.maturin.rs/
+

codex_python-0.2.8/README.md

@@ -0,0 +1,110 @@
+# codex-python
+
+Native Python bindings for Codex (in‑process execution). Ships as a single package (`codex-python`) with platform wheels that include the native extension.
+
+- Python: 3.12–3.13 (CI also attempts 3.14)
+- Import name: `codex`
+- PyPI: https://pypi.org/project/codex-python/
+
+## Install
+
+```
+pip install codex-python
+```
+
+If there’s no prebuilt wheel for your platform/Python, pip will build from source. You’ll need a Rust toolchain and maturin; see “Developing” below.
+
+## Quickstart
+
+Run a prompt and collect structured events (typed):
+
+```
+from codex.api import run_exec, CodexClient
+from codex.config import CodexConfig, ApprovalPolicy, SandboxMode
+
+cfg = CodexConfig(
+    model="gpt-5",
+    model_provider="openai",
+    approval_policy=ApprovalPolicy.ON_REQUEST,
+    sandbox_mode=SandboxMode.WORKSPACE_WRITE,
+)
+
+# One-shot
+events = run_exec("Explain this repo", config=cfg)
+
+# Conversation (streaming)
+client = CodexClient(config=cfg)
+for ev in client.start_conversation("Add a smoke test"):
+    print(ev.id, ev.msg)
+```
+
+Notes
+- `Event.msg` is typed as a union `EventMsg` (also available at `codex.EventMsg`).
+- For raw dict streaming from the native layer, use `codex.native.start_exec_stream`.
+
+## Configuration (Pydantic)
+
+Use `CodexConfig` to pass overrides mirrored from Rust `ConfigOverrides`.
+
+```
+from codex.config import CodexConfig, ApprovalPolicy, SandboxMode
+
+cfg = CodexConfig(
+    model="gpt-5",
+    model_provider="openai",
+    approval_policy=ApprovalPolicy.ON_REQUEST,
+    sandbox_mode=SandboxMode.WORKSPACE_WRITE,
+    cwd="/path/to/project",
+    include_apply_patch_tool=True,
+)
+```
+
+- `CodexConfig.to_dict()` emits only fields you set, with enums serialized to kebab‑case strings expected by the core.
+- For tests and introspection, `codex.native.preview_config(config_overrides=..., load_default_config=...)` returns a compact snapshot of the effective configuration.
+
+## Troubleshooting
+
+- “codex_native extension not installed”
+  - Install with `pip install codex-python` (wheel) or build locally (see below).
+- maturin develop fails without a virtualenv
+  - Use `python -m venv .venv && source .venv/bin/activate` (or conda), or run `make dev-native` which falls back to build+pip install when no venv is present.
+
+## Developing
+
+Prerequisites
+- Python 3.12/3.13
+- Rust toolchain (cargo)
+- maturin (for native builds)
+- uv (optional, for fast Python builds and dev tooling)
+
+Common tasks
+- Lint: `make lint` (ruff + mypy)
+- Test: `make test` (pytest)
+- Format: `make fmt`
+- Build native locally: `make dev-native`
+- Generate protocol types from upstream: `make gen-protocol`
+
+Protocol types
+- `make gen-protocol` generates TS types (via Codex or cargo) into `.generated/ts` and then writes Pydantic models to `codex/protocol/types.py`.
+- Generated models use `model_config = ConfigDict(extra='allow')` and place it at the end of each class.
+
+Releasing
+- Bump `codex/__init__.py` and `crates/codex_native/Cargo.toml` versions.
+- Update `CHANGELOG.md`.
+- Tag and push: `git tag -a vX.Y.Z -m "codex-python X.Y.Z" && git push origin vX.Y.Z`.
+- GitHub Actions (publish.yml) builds native wheels across platforms and an sdist, then publishes them via Trusted Publishing (OIDC).
+
+Project layout
+```
+.
+├── codex/                 # Python package
+├── crates/codex_native/   # PyO3 native extension
+├── scripts/               # generators and helpers
+├── .github/workflows/     # CI, publish, native wheels
+└── Makefile               # common tasks
+```
+
+Links
+- Codex repo: https://github.com/openai/codex
+- uv: https://docs.astral.sh/uv/
+- maturin: https://www.maturin.rs/

codex_python-0.2.8/codex/__init__.py

@@ -0,0 +1,34 @@
+"""codex
+
+Python interface for the Codex CLI.
+
+Usage:
+    from codex import run_exec
+    events = run_exec("explain this codebase to me")
+"""
+
+from .api import (
+    CodexClient,
+    CodexError,
+    CodexNativeError,
+    Conversation,
+    run_exec,
+)
+from .config import CodexConfig
+from .event import Event
+from .protocol.types import EventMsg
+
+__all__ = [
+    "__version__",
+    "CodexError",
+    "CodexNativeError",
+    "CodexClient",
+    "Conversation",
+    "run_exec",
+    "Event",
+    "EventMsg",
+    "CodexConfig",
+]
+
+# Package version. Kept in sync with Cargo.toml via CI before builds.
+__version__ = "0.2.7"

codex_python-0.2.8/codex/api.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from dataclasses import dataclass
+
+from .config import CodexConfig
+from .event import Event
+from .native import run_exec_collect as native_run_exec_collect
+from .native import start_exec_stream as native_start_exec_stream
+
+
+class CodexError(Exception):
+    """Base exception for codex-python."""
+
+
+class CodexNativeError(CodexError):
+    """Raised when the native extension is not available or fails."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "codex_native extension not installed or failed to run. "
+            "Run `make dev-native` or ensure native wheels are installed."
+        )
+
+
+@dataclass(slots=True)
+class Conversation:
+    """A stateful conversation with Codex, streaming events natively."""
+
+    _stream: Iterable[dict]
+
+    def __iter__(self) -> Iterator[Event]:
+        """Yield `Event` objects from the native stream."""
+        for item in self._stream:
+            yield Event.model_validate(item)
+
+
+@dataclass(slots=True)
+class CodexClient:
+    """Lightweight, synchronous client for the native Codex core.
+
+    Provides defaults for repeated invocations and conversation management.
+    """
+
+    config: CodexConfig | None = None
+    load_default_config: bool = True
+    env: Mapping[str, str] | None = None
+    extra_args: Sequence[str] | None = None
+
+    def start_conversation(
+        self,
+        prompt: str,
+        *,
+        config: CodexConfig | None = None,
+        load_default_config: bool | None = None,
+    ) -> Conversation:
+        """Start a new conversation and return a streaming iterator over events."""
+        eff_config = config if config is not None else self.config
+        eff_load_default_config = (
+            load_default_config if load_default_config is not None else self.load_default_config
+        )
+
+        try:
+            stream = native_start_exec_stream(
+                prompt,
+                config_overrides=eff_config.to_dict() if eff_config else None,
+                load_default_config=eff_load_default_config,
+            )
+            return Conversation(_stream=stream)
+        except RuntimeError as e:
+            raise CodexNativeError() from e
+
+
+def run_exec(
+    prompt: str,
+    *,
+    config: CodexConfig | None = None,
+    load_default_config: bool = True,
+) -> list[Event]:
+    """
+    Run a prompt through the native Codex engine and return a list of events.
+
+    - Raises CodexNativeError if the native extension is unavailable or fails.
+    """
+    try:
+        events = native_run_exec_collect(
+            prompt,
+            config_overrides=config.to_dict() if config else None,
+            load_default_config=load_default_config,
+        )
+        return [Event.model_validate(e) for e in events]
+    except RuntimeError as e:
+        raise CodexNativeError() from e

codex_python-0.2.8/codex/config.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ApprovalPolicy(str, Enum):
+    """Approval policy for executing shell commands.
+
+    Matches Rust enum `AskForApproval` (serde kebab-case):
+    - "untrusted": auto-approve safe read-only commands, ask otherwise
+    - "on-failure": sandbox by default; ask only if the sandboxed run fails
+    - "on-request": model decides (default)
+    - "never": never ask the user
+    """
+
+    UNTRUSTED = "untrusted"
+    ON_FAILURE = "on-failure"
+    ON_REQUEST = "on-request"
+    NEVER = "never"
+
+
+class SandboxMode(str, Enum):
+    """High-level sandbox mode override.
+
+    Matches Rust enum `SandboxMode` (serde kebab-case):
+    - "read-only"
+    - "workspace-write"
+    - "danger-full-access"
+    """
+
+    READ_ONLY = "read-only"
+    WORKSPACE_WRITE = "workspace-write"
+    DANGER_FULL_ACCESS = "danger-full-access"
+
+
+class CodexConfig(BaseModel):
+    """Configuration overrides for Codex.
+
+    This mirrors `codex_core::config::ConfigOverrides` and is intentionally
+    conservative: only values present (not None) are passed to the native core.
+    """
+
+    # Model selection
+    model: str | None = Field(default=None, description="Model slug, e.g. 'gpt-5' or 'o3'.")
+    model_provider: str | None = Field(
+        default=None, description="Provider key from config, e.g. 'openai'."
+    )
+
+    # Safety/Execution
+    approval_policy: ApprovalPolicy | None = Field(default=None)
+    sandbox_mode: SandboxMode | None = Field(default=None)
+
+    # Environment
+    cwd: str | None = Field(default=None, description="Working directory for the session.")
+    config_profile: str | None = Field(
+        default=None, description="Config profile key to use (from profiles.*)."
+    )
+    codex_linux_sandbox_exe: str | None = Field(
+        default=None, description="Absolute path to codex-linux-sandbox (Linux only)."
+    )
+
+    # UX / features
+    base_instructions: str | None = Field(default=None, description="Override base instructions.")
+    include_plan_tool: bool | None = Field(default=None)
+    include_apply_patch_tool: bool | None = Field(default=None)
+    include_view_image_tool: bool | None = Field(default=None)
+    show_raw_agent_reasoning: bool | None = Field(default=None)
+    tools_web_search_request: bool | None = Field(default=None)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return overrides as a plain dict with None values removed.
+
+        Enum fields are emitted as their string values.
+        """
+        return cast(dict[str, Any], self.model_dump(exclude_none=True))
+
+    # Pydantic v2 config. `use_enum_values=True` ensures enums dump as strings.
+    # Place at end of class, extra='allow' per style.
+    model_config = ConfigDict(extra="allow", validate_assignment=True, use_enum_values=True)

codex_python-0.2.8/codex/event.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+from pydantic.config import ConfigDict
+
+from .protocol.types import EventMsg
+
+
+class Event(BaseModel):
+    """Protocol event envelope with typed `msg` (union of EventMsg_*)."""
+
+    id: str
+    msg: EventMsg
+
+    # Allow forward compatibility with additional envelope fields
+    model_config = ConfigDict(extra="allow")

codex_python-0.2.8/codex/native.py

@@ -0,0 +1,35 @@
+from typing import Any, cast
+
+from codex_native import preview_config as _preview_config
+from codex_native import run_exec_collect as _run_exec_collect
+from codex_native import start_exec_stream as _start_exec_stream
+
+
+def run_exec_collect(
+    prompt: str,
+    *,
+    config_overrides: dict[str, Any] | None = None,
+    load_default_config: bool = True,
+) -> list[dict]:
+    """Run Codex natively (in‑process) and return a list of events as dicts."""
+    return cast(list[dict], _run_exec_collect(prompt, config_overrides, load_default_config))
+
+
+def start_exec_stream(
+    prompt: str,
+    *,
+    config_overrides: dict[str, Any] | None = None,
+    load_default_config: bool = True,
+) -> Any:
+    """Return a native streaming iterator over Codex events (dicts)."""
+    return _start_exec_stream(prompt, config_overrides, load_default_config)
+
+
+def preview_config(
+    *, config_overrides: dict[str, Any] | None = None, load_default_config: bool = True
+) -> dict:
+    """Return an effective config snapshot (selected fields) from native.
+
+    Useful for tests to validate override mapping without running Codex.
+    """
+    return cast(dict, _preview_config(config_overrides, load_default_config))