codex-python 1.0.1__tar.gz → 1.114.1__tar.gz

codex_python-1.114.1/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: codex-python
+Version: 1.114.1
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+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,<3
+Requires-Dist: websockets>=15.0.1,<16 ; extra == 'websocket'
+Provides-Extra: websocket
+License-File: LICENSE
+Summary: Python SDK for Codex CLI with bundled platform binaries
+Keywords: codex,sdk,cli,automation
+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: Issues, https://github.com/gersmann/codex-python/issues
+Project-URL: Repository, https://github.com/gersmann/codex-python
+
+# codex-python
+
+Python SDK for Codex with bundled `codex` binaries inside platform wheels.
+
+This package exposes two supported APIs:
+
+- `Codex`: a simple, local convenience interface backed by a private stdio app-server session
+- `AppServerClient`: a richer app-server client for thread management, streaming events, approvals, and typed protocol access
+
+Canonical import paths:
+
+- use `from codex import ...` for the high-level `Codex` facade
+- use `from codex.app_server import ...` for the raw app-server client and app-server option types
+
+## Install
+
+```bash
+pip install codex-python
+```
+
+## Which API should I use?
+
+### `Codex`
+
+Use `Codex` when you want the smallest surface area for local automation:
+
+- one private local app-server session per `Codex` instance
+- stateless `run*()` convenience (fresh internal thread per call)
+- stateful thread workflows when needed via `start_thread()` / `resume_thread()`
+- simple request/response usage
+- optional streaming over the exec event stream
+- structured output via `TurnOptions(output_schema=...)`
+
+### `AppServerClient`
+
+Use `AppServerClient` when you want a deeper integration:
+
+- persistent app-server connection
+- thread objects and turn streams
+- protocol-native notifications
+- server-driven requests such as tool callbacks and approvals
+- typed protocol models and raw JSON-RPC access when needed
+
+## Quickstart: `Codex`
+
+```python
+from codex import Codex
+
+client = Codex()
+summary = client.run_text("Diagnose the failing tests and propose a fix")
+print(summary)
+```
+
+More `Codex` examples: [docs/exec_api.md](docs/exec_api.md)
+
+## Quickstart: `AppServerClient`
+
+```python
+from codex.app_server import AppServerClient, AppServerClientInfo, AppServerInitializeOptions
+
+initialize_options = AppServerInitializeOptions(
+    client_info=AppServerClientInfo(
+        name="my_integration",
+        title="My Integration",
+        version="0.1.0",
+    )
+)
+
+with AppServerClient.connect_stdio(initialize_options=initialize_options) as client:
+    thread = client.start_thread()
+    summary = thread.run_text("Briefly summarize this repository's purpose.")
+    print(summary)
+```
+
+More app-server examples: [docs/app_server.md](docs/app_server.md)
+For websocket transport, install the optional extra: `pip install "codex-python[websocket]"`.
+
+## Structured output
+
+### `Codex`
+
+```python
+from codex import Codex, TurnOptions
+
+schema = {
+    "type": "object",
+    "properties": {"summary": {"type": "string"}},
+    "required": ["summary"],
+    "additionalProperties": False,
+}
+
+client = Codex()
+payload = client.run_json("Summarize repository status", TurnOptions(output_schema=schema))
+print(payload["summary"])
+```
+
+### `AppServerClient`
+
+```python
+from pydantic import BaseModel
+
+from codex.app_server import AppServerClient, AppServerTurnOptions
+
+
+class Summary(BaseModel):
+    summary: str
+
+
+with AppServerClient.connect_stdio() as client:
+    thread = client.start_thread()
+    result = thread.run_model(
+        "Summarize repository status",
+        Summary,
+    )
+    print(result.summary)
+```
+
+`run_model()` uses `Summary` both as the validation model and, by default, as the output schema sent
+to Codex. If you want JSON back without validation, you can also pass the model class directly to
+`output_schema`, for example `thread.run_json(..., AppServerTurnOptions(output_schema=Summary))`.
+
+## Streaming
+
+### `Codex` stream
+
+```python
+from codex import Codex
+from codex.protocol import types as protocol
+
+client = Codex()
+stream = client.run("Investigate this bug")
+for event in stream:
+    if isinstance(event, protocol.ItemAgentMessageDeltaNotification):
+        print(event.params.delta, end="", flush=True)
+
+print()
+```
+
+`Codex.run*()` starts a fresh internal thread for each call. Use
+`start_thread()` or `resume_thread()` when you want later runs to share context.
+
+High-level `Codex` helpers raise `ThreadRunError` on failed or interrupted terminal turns and
+preserve the final turn metadata on the exception for debugging and UI handling.
+
+### App-server stream
+
+```python
+from codex.app_server import AppServerClient
+from codex.protocol import types as protocol
+
+with AppServerClient.connect_stdio() as client:
+    thread = client.start_thread()
+    stream = thread.run("Investigate this bug")
+
+    for event in stream:
+        if isinstance(event, protocol.ItemAgentMessageDeltaNotification):
+            print(event.params.delta, end="", flush=True)
+
+    print()
+```
+
+Advanced app-server usage, including typed stable RPC domains such as `client.models` and the raw `client.rpc` fallback: [docs/app_server_advanced.md](docs/app_server_advanced.md)
+
+## Examples
+
+- [examples/basic_conversation.py](examples/basic_conversation.py): minimal `Codex` flow
+- [examples/app_server_conversation.py](examples/app_server_conversation.py): minimal app-server flow
+- [examples/app_server_websocket_conversation.py](examples/app_server_websocket_conversation.py): minimal websocket app-server flow
+- [examples/app_server_stream_events.py](examples/app_server_stream_events.py): protocol-native app-server streaming
+- [examples/app_server_tool_handler.py](examples/app_server_tool_handler.py): typed app-server request handling
+
+## Bundled binary behavior
+
+By default, the SDK resolves the bundled binary at:
+
+`codex/vendor/<target-triple>/codex/{codex|codex.exe}`
+
+If the bundled binary is not present, for example in a source checkout, the SDK falls back to
+`codex` on `PATH`.
+
+You can override the executable path with:
+
+- `CodexOptions(codex_path_override=...)`
+- `codex.app_server.AppServerProcessOptions(codex_path_override=...)`
+
+## Development
+
+```bash
+make lint
+make test
+```
+
+`make test` emits a terminal coverage report, writes `coverage.xml`, and enforces the repository
+coverage gate.
+
+If you want to test vendored-binary behavior locally, fetch binaries into `codex/vendor`:
+
+```bash
+python scripts/fetch_codex_binary.py --target-triple x86_64-unknown-linux-musl
+```
+

codex_python-1.114.1/README.md

@@ -0,0 +1,200 @@
+# codex-python
+
+Python SDK for Codex with bundled `codex` binaries inside platform wheels.
+
+This package exposes two supported APIs:
+
+- `Codex`: a simple, local convenience interface backed by a private stdio app-server session
+- `AppServerClient`: a richer app-server client for thread management, streaming events, approvals, and typed protocol access
+
+Canonical import paths:
+
+- use `from codex import ...` for the high-level `Codex` facade
+- use `from codex.app_server import ...` for the raw app-server client and app-server option types
+
+## Install
+
+```bash
+pip install codex-python
+```
+
+## Which API should I use?
+
+### `Codex`
+
+Use `Codex` when you want the smallest surface area for local automation:
+
+- one private local app-server session per `Codex` instance
+- stateless `run*()` convenience (fresh internal thread per call)
+- stateful thread workflows when needed via `start_thread()` / `resume_thread()`
+- simple request/response usage
+- optional streaming over the exec event stream
+- structured output via `TurnOptions(output_schema=...)`
+
+### `AppServerClient`
+
+Use `AppServerClient` when you want a deeper integration:
+
+- persistent app-server connection
+- thread objects and turn streams
+- protocol-native notifications
+- server-driven requests such as tool callbacks and approvals
+- typed protocol models and raw JSON-RPC access when needed
+
+## Quickstart: `Codex`
+
+```python
+from codex import Codex
+
+client = Codex()
+summary = client.run_text("Diagnose the failing tests and propose a fix")
+print(summary)
+```
+
+More `Codex` examples: [docs/exec_api.md](docs/exec_api.md)
+
+## Quickstart: `AppServerClient`
+
+```python
+from codex.app_server import AppServerClient, AppServerClientInfo, AppServerInitializeOptions
+
+initialize_options = AppServerInitializeOptions(
+    client_info=AppServerClientInfo(
+        name="my_integration",
+        title="My Integration",
+        version="0.1.0",
+    )
+)
+
+with AppServerClient.connect_stdio(initialize_options=initialize_options) as client:
+    thread = client.start_thread()
+    summary = thread.run_text("Briefly summarize this repository's purpose.")
+    print(summary)
+```
+
+More app-server examples: [docs/app_server.md](docs/app_server.md)
+For websocket transport, install the optional extra: `pip install "codex-python[websocket]"`.
+
+## Structured output
+
+### `Codex`
+
+```python
+from codex import Codex, TurnOptions
+
+schema = {
+    "type": "object",
+    "properties": {"summary": {"type": "string"}},
+    "required": ["summary"],
+    "additionalProperties": False,
+}
+
+client = Codex()
+payload = client.run_json("Summarize repository status", TurnOptions(output_schema=schema))
+print(payload["summary"])
+```
+
+### `AppServerClient`
+
+```python
+from pydantic import BaseModel
+
+from codex.app_server import AppServerClient, AppServerTurnOptions
+
+
+class Summary(BaseModel):
+    summary: str
+
+
+with AppServerClient.connect_stdio() as client:
+    thread = client.start_thread()
+    result = thread.run_model(
+        "Summarize repository status",
+        Summary,
+    )
+    print(result.summary)
+```
+
+`run_model()` uses `Summary` both as the validation model and, by default, as the output schema sent
+to Codex. If you want JSON back without validation, you can also pass the model class directly to
+`output_schema`, for example `thread.run_json(..., AppServerTurnOptions(output_schema=Summary))`.
+
+## Streaming
+
+### `Codex` stream
+
+```python
+from codex import Codex
+from codex.protocol import types as protocol
+
+client = Codex()
+stream = client.run("Investigate this bug")
+for event in stream:
+    if isinstance(event, protocol.ItemAgentMessageDeltaNotification):
+        print(event.params.delta, end="", flush=True)
+
+print()
+```
+
+`Codex.run*()` starts a fresh internal thread for each call. Use
+`start_thread()` or `resume_thread()` when you want later runs to share context.
+
+High-level `Codex` helpers raise `ThreadRunError` on failed or interrupted terminal turns and
+preserve the final turn metadata on the exception for debugging and UI handling.
+
+### App-server stream
+
+```python
+from codex.app_server import AppServerClient
+from codex.protocol import types as protocol
+
+with AppServerClient.connect_stdio() as client:
+    thread = client.start_thread()
+    stream = thread.run("Investigate this bug")
+
+    for event in stream:
+        if isinstance(event, protocol.ItemAgentMessageDeltaNotification):
+            print(event.params.delta, end="", flush=True)
+
+    print()
+```
+
+Advanced app-server usage, including typed stable RPC domains such as `client.models` and the raw `client.rpc` fallback: [docs/app_server_advanced.md](docs/app_server_advanced.md)
+
+## Examples
+
+- [examples/basic_conversation.py](examples/basic_conversation.py): minimal `Codex` flow
+- [examples/app_server_conversation.py](examples/app_server_conversation.py): minimal app-server flow
+- [examples/app_server_websocket_conversation.py](examples/app_server_websocket_conversation.py): minimal websocket app-server flow
+- [examples/app_server_stream_events.py](examples/app_server_stream_events.py): protocol-native app-server streaming
+- [examples/app_server_tool_handler.py](examples/app_server_tool_handler.py): typed app-server request handling
+
+## Bundled binary behavior
+
+By default, the SDK resolves the bundled binary at:
+
+`codex/vendor/<target-triple>/codex/{codex|codex.exe}`
+
+If the bundled binary is not present, for example in a source checkout, the SDK falls back to
+`codex` on `PATH`.
+
+You can override the executable path with:
+
+- `CodexOptions(codex_path_override=...)`
+- `codex.app_server.AppServerProcessOptions(codex_path_override=...)`
+
+## Development
+
+```bash
+make lint
+make test
+```
+
+`make test` emits a terminal coverage report, writes `coverage.xml`, and enforces the repository
+coverage gate.
+
+If you want to test vendored-binary behavior locally, fetch binaries into `codex/vendor`:
+
+```bash
+python scripts/fetch_codex_binary.py --target-triple x86_64-unknown-linux-musl
+```

codex_python-1.114.1/codex/__init__.py

@@ -0,0 +1,32 @@
+"""Python SDK for embedding Codex via the bundled CLI binary."""
+
+from __future__ import annotations
+
+from codex.codex import Codex
+from codex.errors import CodexError, CodexExecError, CodexParseError, ThreadRunError
+from codex.options import (
+    CancelSignal,
+    CodexConfigObject,
+    CodexConfigValue,
+    CodexOptions,
+    ThreadResumeOptions,
+    ThreadStartOptions,
+    TurnOptions,
+)
+
+__version__ = "1.114.1"
+
+__all__ = [
+    "Codex",
+    "CodexError",
+    "CodexExecError",
+    "CodexParseError",
+    "ThreadRunError",
+    "CodexOptions",
+    "ThreadStartOptions",
+    "ThreadResumeOptions",
+    "TurnOptions",
+    "CodexConfigValue",
+    "CodexConfigObject",
+    "CancelSignal",
+]

{codex_python-1.0.1 → codex_python-1.114.1}/codex/_binary.py

@@ -6,6 +6,10 @@ from pathlib import Path
 from codex.errors import CodexExecError
 
 
+class BundledCodexNotFoundError(CodexExecError):
+    """The platform wheel does not contain a bundled Codex binary."""
+
+
 def resolve_target_triple(system_name: str | None = None, machine_name: str | None = None) -> str:
     system = (system_name or platform.system()).lower()
     machine = (machine_name or platform.machine()).lower()
@@ -35,7 +39,7 @@ def bundled_codex_path(target_triple: str | None = None) -> Path:
     binary_name = "codex.exe" if "windows" in triple else "codex"
     binary_path = package_root / "vendor" / triple / "codex" / binary_name
     if not binary_path.exists():
-        raise CodexExecError(
+        raise BundledCodexNotFoundError(
             "Bundled codex binary not found at "
             f"{binary_path}. Install a platform wheel or provide codex_path_override."
         )

codex_python-1.114.1/codex/_config_types.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+type CodexConfigValue = (
+    str | int | float | bool | list["CodexConfigValue"] | dict[str, "CodexConfigValue"]
+)
+type CodexConfigObject = dict[str, CodexConfigValue]

codex_python-1.114.1/codex/_file_utils.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def atomic_write_text(path: Path, text: str, *, encoding: str = "utf-8") -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_path_str = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temp_path = Path(temp_path_str)
+    try:
+        with os.fdopen(fd, "w", encoding=encoding) as handle:
+            handle.write(text)
+        temp_path.replace(path)
+    except Exception:
+        temp_path.unlink(missing_ok=True)
+        raise

codex_python-1.114.1/codex/_runtime.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+from codex._binary import BundledCodexNotFoundError
+from codex._config_types import CodexConfigObject, CodexConfigValue
+
+INTERNAL_ORIGINATOR_ENV = "CODEX_INTERNAL_ORIGINATOR_OVERRIDE"
+PYTHON_SDK_ORIGINATOR = "codex_sdk_py"
+TOML_BARE_KEY = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def build_child_env(
+    env_override: Mapping[str, str] | None,
+    *,
+    base_url: str | None = None,
+    api_key: str | None = None,
+) -> dict[str, str]:
+    env = {} if env_override is None else dict(env_override)
+    if INTERNAL_ORIGINATOR_ENV not in env:
+        env[INTERNAL_ORIGINATOR_ENV] = PYTHON_SDK_ORIGINATOR
+    if base_url is not None:
+        env["OPENAI_BASE_URL"] = base_url
+    if api_key is not None:
+        env["CODEX_API_KEY"] = api_key
+    return env
+
+
+def resolve_codex_path(
+    executable_path: str | None,
+    *,
+    bundled_path: Callable[[], Path],
+    which: Callable[[str], str | None],
+    error_type: type[Exception],
+) -> str:
+    if executable_path is not None:
+        return str(Path(executable_path))
+    try:
+        return str(bundled_path())
+    except BundledCodexNotFoundError as bundled_error:
+        system_codex = which("codex")
+        if system_codex is None:
+            raise error_type(
+                f"{bundled_error} Also failed to find `codex` on PATH."
+            ) from bundled_error
+        return system_codex
+
+
+def serialize_config_overrides(config_overrides: CodexConfigObject) -> list[str]:
+    overrides: list[str] = []
+    _flatten_config_overrides(config_overrides, "", overrides)
+    return overrides
+
+
+def _flatten_config_overrides(
+    value: CodexConfigValue | CodexConfigObject,
+    prefix: str,
+    overrides: list[str],
+) -> None:
+    if not isinstance(value, dict):
+        if prefix == "":
+            raise ValueError("Codex config overrides must be a plain object")
+        overrides.append(f"{prefix}={_to_toml_value(value, prefix)}")
+        return
+
+    entries = list(value.items())
+    if prefix == "" and not entries:
+        return
+    if prefix != "" and not entries:
+        overrides.append(f"{prefix}={{}}")
+        return
+
+    for key, child in entries:
+        if not isinstance(key, str) or key == "":
+            raise ValueError("Codex config override keys must be non-empty strings")
+        path = f"{prefix}.{key}" if prefix else key
+        if isinstance(child, dict):
+            _flatten_config_overrides(child, path, overrides)
+        else:
+            overrides.append(f"{path}={_to_toml_value(child, path)}")
+
+
+def _to_toml_value(value: CodexConfigValue, path: str) -> str:
+    if isinstance(value, str):
+        return json.dumps(value)
+    if isinstance(value, bool):
+        return format_toml_bool(value)
+    if isinstance(value, int):
+        return f"{value}"
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ValueError(f"Codex config override at {path} must be a finite number")
+        return f"{value}"
+    if isinstance(value, list):
+        rendered_items = [
+            _to_toml_value(item, f"{path}[{index}]") for index, item in enumerate(value)
+        ]
+        return f"[{', '.join(rendered_items)}]"
+    if isinstance(value, dict):
+        parts: list[str] = []
+        for key, child in value.items():
+            if not isinstance(key, str) or key == "":
+                raise ValueError("Codex config override keys must be non-empty strings")
+            parts.append(f"{format_toml_key(key)} = {_to_toml_value(child, f'{path}.{key}')}")
+        return f"{{{', '.join(parts)}}}"
+    if value is None:
+        raise ValueError(f"Codex config override at {path} cannot be null")
+    raise ValueError(f"Unsupported Codex config override value at {path}: {type(value).__name__}")
+
+
+def format_toml_key(key: str) -> str:
+    if TOML_BARE_KEY.match(key):
+        return key
+    return json.dumps(key)
+
+
+def format_toml_bool(value: bool) -> str:
+    return "true" if value else "false"

codex_python-1.114.1/codex/_turn_options.py

@@ -0,0 +1,28 @@
+"""Shared turn-option helpers for structured-output runs."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from codex.app_server.options import AppServerTurnOptions
+from codex.output_schema import resolve_model_output_schema
+
+
+def with_model_output_schema(
+    options: AppServerTurnOptions | None,
+    model_type: type[BaseModel],
+    *,
+    owner: str,
+    option_model: type[AppServerTurnOptions] = AppServerTurnOptions,
+) -> AppServerTurnOptions:
+    if options is None:
+        return option_model(output_schema=model_type)
+    return options.model_copy(
+        update={
+            "output_schema": resolve_model_output_schema(
+                options.output_schema,
+                model_type,
+                owner=owner,
+            )
+        }
+    )