clone/codex
1
0
Fork 0
mirror of https://github.com/openai/codex.git synced 2026-05-14 16:22:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

[4/8] Define Python SDK public API surface (#21896)

Browse Source 
## Why

The SDK package root should be the ergonomic public client API, not a
dump of every generated app-server schema type. Generated models still
need a supported import path, but callers should be able to tell which
names are high-level SDK entrypoints and which names are protocol value
models.

## What

- Define a curated root `__all__` for clients, handles, input helpers,
retry helpers, config, and public errors.
- Add a `types` module as the supported home for generated app-server
response, event, enum, and helper models.
- Update docs and examples to import protocol/value models from the type
module.
- Add tests that lock root exports, type-module exports, star-import
behavior, and example import hygiene.

## Stack

1. #21891 `[1/8]` Pin Python SDK runtime dependency
2. #21893 `[2/8]` Generate Python SDK types from pinned runtime
3. #21895 `[3/8]` Run Python SDK tests in CI
4. This PR `[4/8]` Define Python SDK public API surface
5. #21905 `[5/8]` Rename Python SDK package to `openai-codex`
6. #21910 `[6/8]` Add high-level Python SDK approval mode
7. #22014 `[7/8]` Add Python SDK app-server integration harness
8. #22021 `[8/8]` Add Python SDK Ruff formatting

## Verification

- Added public API signature tests for root exports, `types` exports,
and example imports.

---------

Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
Ahmed Ibrahim
2026-05-12 00:57:44 +03:00
committed by GitHub
parent 3e2936dd0e
commit b4bc02439f
16 changed files with 274 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
sdk/python/docs/api-reference.md
View File

@@ -15,7 +15,6 @@ from codex_app_server import (
AsyncThread,
TurnHandle,
AsyncTurnHandle,
InitializeResponse,
Input,
InputItem,
TextInput,
@@ -23,14 +22,18 @@ from codex_app_server import (
LocalImageInput,
SkillInput,
MentionInput,
)
from codex_app_server.types import (
InitializeResponse,
ThreadItem,
ThreadTokenUsage,
TurnStatus,
)
from codex_app_server.generated.v2_all import ThreadItem, ThreadTokenUsage
```
- Version: `codex_app_server.__version__`
- Requires Python >= 3.10
- Canonical generated app-server models live in `codex_app_server.generated.v2_all`
- Public app-server value and event types live in `codex_app_server.types`
## Codex (sync)
@@ -124,7 +127,7 @@ object with:
phase-less assistant message item.
Use `turn(...)` when you need low-level turn control (`stream()`, `steer()`,
`interrupt()`) or the canonical generated `Turn` from `TurnHandle.run()`.
`interrupt()`) or the public `Turn` model from `TurnHandle.run()`.
## TurnHandle / AsyncTurnHandle
@@ -133,7 +136,7 @@ Use `turn(...)` when you need low-level turn control (`stream()`, `steer()`,
- `steer(input: Input) -> TurnSteerResponse`
- `interrupt() -> TurnInterruptResponse`
- `stream() -> Iterator[Notification]`
- `run() -> codex_app_server.generated.v2_all.Turn`
- `run() -> codex_app_server.types.Turn`
Behavior notes:
@@ -145,7 +148,7 @@ Behavior notes:
- `steer(input: Input) -> Awaitable[TurnSteerResponse]`
- `interrupt() -> Awaitable[TurnInterruptResponse]`
- `stream() -> AsyncIterator[Notification]`
- `run() -> Awaitable[codex_app_server.generated.v2_all.Turn]`
- `run() -> Awaitable[codex_app_server.types.Turn]`
Behavior notes:
@@ -165,16 +168,15 @@ InputItem = TextInput | ImageInput | LocalImageInput | SkillInput | MentionInput
Input = list[InputItem] | InputItem
```
## Generated Models
## Public Types
The SDK wrappers return and accept canonical generated app-server models wherever possible:
The SDK wrappers return and accept public app-server models wherever possible:
```python
from codex_app_server.generated.v2_all import (
from codex_app_server.types import (
AskForApproval,
ThreadReadResponse,
Turn,
TurnStartParams,
TurnStatus,
)
```