codex-python 0.2.0__tar.gz → 0.2.7__tar.gz

codex_python-0.2.7/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: codex-python
+Version: 0.2.7
+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.7/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.0 → codex_python-0.2.7}/codex/__init__.py

@@ -30,5 +30,5 @@ __all__ = [
     "CodexConfig",
 ]
 
-# Managed by Hatch via pyproject.toml [tool.hatch.version]
-__version__ = "0.2.0"
+# Package version. Kept in sync with Cargo.toml via CI before builds.
+__version__ = "0.2.7"

{codex_python-0.2.0 → codex_python-0.2.7}/codex/protocol/types.py

@@ -698,30 +698,6 @@ class WebSearchEndEvent(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-class AskForApproval_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class AskForApproval_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class AskForApproval_Variant3(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class AskForApproval_Variant4(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class AuthMode_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class AuthMode_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
 class ClientRequest_NewConversation(BaseModel):
     method: Literal["newConversation"]
     id: RequestId
@@ -1200,14 +1176,6 @@ class EventMsg_ConversationHistory(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-class ExecOutputStream_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class ExecOutputStream_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
 class FileChange_Variant1(BaseModel):
     add: dict[str, Any]
 
@@ -1247,30 +1215,6 @@ class InputItem_LocalImage(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-class InputMessageKind_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class InputMessageKind_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class InputMessageKind_Variant3(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class LocalShellStatus_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class LocalShellStatus_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class LocalShellStatus_Variant3(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
 class ParsedCommand_Read(BaseModel):
     type: Literal["read"]
     cmd: str
@@ -1303,22 +1247,6 @@ class ParsedCommand_Unknown(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-class ReasoningEffort_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class ReasoningEffort_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class ReasoningEffort_Variant3(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class ReasoningEffort_Variant4(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
 class ReasoningItemContent_ReasoningText(BaseModel):
     type: Literal["reasoning_text"]
     text: str
@@ -1333,30 +1261,6 @@ class ReasoningItemContent_Text(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-class ReasoningSummary_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class ReasoningSummary_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class ReasoningSummary_Variant3(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class ReasoningSummary_Variant4(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class RequestId_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class RequestId_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
 class ResponseItem_Message(BaseModel):
     type: Literal["message"]
     id: str | None = None
@@ -1434,42 +1338,6 @@ class ResponseItem_Other(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-class ReviewDecision_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class ReviewDecision_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class ReviewDecision_Variant3(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class ReviewDecision_Variant4(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class Role_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class Role_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class SandboxMode_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class SandboxMode_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class SandboxMode_Variant3(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
 class SandboxPolicy_Variant1(BaseModel):
     mode: Literal["danger-full-access"]
 
@@ -1521,38 +1389,6 @@ class ServerRequest_ExecCommandApproval(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-class StepStatus_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class StepStatus_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class StepStatus_Variant3(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class TurnAbortReason_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class TurnAbortReason_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class Verbosity_Variant1(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class Verbosity_Variant2(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class Verbosity_Variant3(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
 class WebSearchAction_Search(BaseModel):
     type: Literal["search"]
     query: str
@@ -1594,13 +1430,6 @@ class SendUserTurnResponse(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-AskForApproval = (
-    AskForApproval_Variant1
-    | AskForApproval_Variant2
-    | AskForApproval_Variant3
-    | AskForApproval_Variant4
-)
-AuthMode = AuthMode_Variant1 | AuthMode_Variant2
 ClientRequest = (
     ClientRequest_NewConversation
     | ClientRequest_ListConversations
@@ -1665,28 +1494,12 @@ EventMsg = (
     | EventMsg_ShutdownComplete
     | EventMsg_ConversationHistory
 )
-ExecOutputStream = ExecOutputStream_Variant1 | ExecOutputStream_Variant2
 FileChange = FileChange_Variant1 | FileChange_Variant2 | FileChange_Variant3
 InputItem = InputItem_Text | InputItem_Image | InputItem_LocalImage
-InputMessageKind = InputMessageKind_Variant1 | InputMessageKind_Variant2 | InputMessageKind_Variant3
-LocalShellStatus = LocalShellStatus_Variant1 | LocalShellStatus_Variant2 | LocalShellStatus_Variant3
 ParsedCommand = (
     ParsedCommand_Read | ParsedCommand_ListFiles | ParsedCommand_Search | ParsedCommand_Unknown
 )
-ReasoningEffort = (
-    ReasoningEffort_Variant1
-    | ReasoningEffort_Variant2
-    | ReasoningEffort_Variant3
-    | ReasoningEffort_Variant4
-)
 ReasoningItemContent = ReasoningItemContent_ReasoningText | ReasoningItemContent_Text
-ReasoningSummary = (
-    ReasoningSummary_Variant1
-    | ReasoningSummary_Variant2
-    | ReasoningSummary_Variant3
-    | ReasoningSummary_Variant4
-)
-RequestId = RequestId_Variant1 | RequestId_Variant2
 ResponseItem = (
     ResponseItem_Message
     | ResponseItem_Reasoning
@@ -1698,22 +1511,29 @@ ResponseItem = (
     | ResponseItem_WebSearchCall
     | ResponseItem_Other
 )
-ReviewDecision = (
-    ReviewDecision_Variant1
-    | ReviewDecision_Variant2
-    | ReviewDecision_Variant3
-    | ReviewDecision_Variant4
-)
-Role = Role_Variant1 | Role_Variant2
-SandboxMode = SandboxMode_Variant1 | SandboxMode_Variant2 | SandboxMode_Variant3
 SandboxPolicy = SandboxPolicy_Variant1 | SandboxPolicy_Variant2 | SandboxPolicy_Variant3
 ServerNotification = ServerNotification_AuthStatusChange | ServerNotification_LoginChatGptComplete
 ServerRequest = ServerRequest_ApplyPatchApproval | ServerRequest_ExecCommandApproval
-StepStatus = StepStatus_Variant1 | StepStatus_Variant2 | StepStatus_Variant3
-TurnAbortReason = TurnAbortReason_Variant1 | TurnAbortReason_Variant2
-Verbosity = Verbosity_Variant1 | Verbosity_Variant2 | Verbosity_Variant3
 WebSearchAction = WebSearchAction_Search | WebSearchAction_Other
 
+AskForApproval = (
+    Literal["never"] | Literal["on-failure"] | Literal["on-request"] | Literal["untrusted"]
+)
+AuthMode = Literal["apikey"] | Literal["chatgpt"]
+ExecOutputStream = Literal["stderr"] | Literal["stdout"]
+InputMessageKind = Literal["environment_context"] | Literal["plain"] | Literal["user_instructions"]
+LocalShellStatus = Literal["completed"] | Literal["in_progress"] | Literal["incomplete"]
+ReasoningEffort = Literal["high"] | Literal["low"] | Literal["medium"] | Literal["minimal"]
+ReasoningSummary = Literal["auto"] | Literal["concise"] | Literal["detailed"] | Literal["none"]
+RequestId = int | str
+ReviewDecision = (
+    Literal["abort"] | Literal["approved"] | Literal["approved_for_session"] | Literal["denied"]
+)
+Role = Literal["assistant"] | Literal["user"]
+SandboxMode = Literal["danger-full-access"] | Literal["read-only"] | Literal["workspace-write"]
+StepStatus = Literal["completed"] | Literal["in_progress"] | Literal["pending"]
+TurnAbortReason = Literal["interrupted"] | Literal["replaced"]
+Verbosity = Literal["high"] | Literal["low"] | Literal["medium"]
 ConversationId = str
 GitSha = str
 JsonValue = Any