codex-python 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

codex/__init__.py

@@ -4,27 +4,31 @@ Python interface for the Codex CLI.
 
 Usage:
     from codex import run_exec
-    output = run_exec("explain this codebase to me")
+    events = run_exec("explain this codebase to me")
 """
 
 from .api import (
     CodexClient,
     CodexError,
-    CodexNotFoundError,
-    CodexProcessError,
-    find_binary,
+    CodexNativeError,
+    Conversation,
     run_exec,
 )
+from .config import CodexConfig
+from .event import Event
+from .protocol.types import EventMsg
 
 __all__ = [
     "__version__",
     "CodexError",
-    "CodexNotFoundError",
-    "CodexProcessError",
+    "CodexNativeError",
     "CodexClient",
-    "find_binary",
+    "Conversation",
     "run_exec",
+    "Event",
+    "EventMsg",
+    "CodexConfig",
 ]
 
 # Managed by Hatch via pyproject.toml [tool.hatch.version]
-__version__ = "0.1.1"
+__version__ = "0.2.0"

codex/api.py

@@ -1,165 +1,93 @@
 from __future__ import annotations
 
-import os
-import shutil
-import subprocess
-from collections.abc import Iterable, Mapping, Sequence
+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 CodexNotFoundError(CodexError):
-    """Raised when the 'codex' binary cannot be found or executed."""
+class CodexNativeError(CodexError):
+    """Raised when the native extension is not available or fails."""
 
-    def __init__(self, executable: str = "codex") -> None:
+    def __init__(self) -> None:
         super().__init__(
-            f"Codex CLI not found: '{executable}'.\n"
-            "Install from https://github.com/openai/codex or ensure it is on PATH."
+            "codex_native extension not installed or failed to run. "
+            "Run `make dev-native` or ensure native wheels are installed."
         )
-        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()}"
-        )
-
+class Conversation:
+    """A stateful conversation with Codex, streaming events natively."""
 
-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
+    _stream: Iterable[dict]
 
-
-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
+    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 Codex CLI.
+    """Lightweight, synchronous client for the native Codex core.
 
-    Provides defaults for repeated invocations and convenience helpers.
+    Provides defaults for repeated invocations and conversation management.
     """
 
-    executable: str = "codex"
-    model: str | None = None
-    full_auto: bool = False
-    cd: str | None = None
+    config: CodexConfig | None = None
+    load_default_config: bool = True
     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(
+    def start_conversation(
         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(
+        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,
-            model=eff_model,
-            full_auto=eff_full_auto,
-            cd=eff_cd,
-            timeout=timeout,
-            env=merged_env,
-            executable=self.executable,
-            extra_args=eff_extra,
+            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/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/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/native.py

@@ -0,0 +1,56 @@
+from typing import Any, cast
+
+try:
+    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
+except Exception as _e:  # pragma: no cover - optional native path
+    _run_exec_collect = None
+    _start_exec_stream = None
+    _preview_config = None
+
+
+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.
+
+    Requires the native extension to be built/installed (see `make dev-native`).
+    Falls back to raising if the extension is not available.
+    """
+    if _run_exec_collect is None:
+        raise RuntimeError(
+            "codex_native extension not installed. Run `make dev-native` or build wheels via maturin."
+        )
+    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)."""
+    if _start_exec_stream is None:
+        raise RuntimeError(
+            "codex_native extension not installed. Run `make dev-native` or build wheels via maturin."
+        )
+    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.
+    """
+    if _preview_config is None:  # pragma: no cover
+        raise RuntimeError(
+            "codex_native extension not installed. Run `make dev-native` or build wheels via maturin."
+        )
+    return cast(dict, _preview_config(config_overrides, load_default_config))