mirror of https://github.com/openai/codex.git synced 2026-05-03 10:56:37 +00:00

Files

Steve Coffey 0f40261e86 Publish Python SDK with Codex-pinned versioning (#18996 )

**note**: a large chunk of this diff comes from regenerating Python
types after app-server schema changes on `main`.

This is PR 3 of 3 for the Python SDK PyPI publishing split. PR #18862
refreshed the generated SDK surface, and PR #18865 made the runtime
package publishable as `openai-codex-cli-bin`; this final PR makes the
SDK package publishable as `openai-codex-app-server-sdk` and pins both
packages to the same Codex runtime version.

The key idea is that the published SDK version is the Codex runtime
version. That one version now drives the SDK package version, the exact
runtime dependency, the client version reported by the SDK, and the
bootstrap runtime pin. This keeps release-time versioning in one lane
instead of scattering checked-in literals through the package.

## What changed

- Rename the SDK distribution from `codex-app-server-sdk` to
`openai-codex-app-server-sdk` for conflict-free PyPI publishing.
- Use `stage-sdk --codex-version ...` with one Codex version for both
the SDK package version and exact `openai-codex-cli-bin` dependency.
- Preserve hidden legacy `--runtime-version` / `--sdk-version` args only
to reject mismatched versions during staging.
- Map PEP 440 package versions back to Codex release tags for runtime
setup downloads, e.g. `0.116.0a1` -> `rust-v0.116.0-alpha.1`.
- Derive `codex_app_server.__version__`, the default
`AppServerConfig.client_version`, and
`_runtime_setup.pinned_runtime_version()` from the SDK package/project
version instead of hardcoding duplicate version strings.
- Carry the current generated SDK refresh from `main` so
`generate-types` stays clean after recent app-server schema changes.
- Update `sdk/python/uv.lock` for the renamed editable package.

## Validation

- `uv run --extra dev pytest` in `sdk/python` -> 59 passed, 37 skipped.
- Targeted `uv run ruff check` for the touched SDK files.
- `git diff --check`.
- Staged runtime with `--codex-version rust-v0.116.0-alpha.1
--platform-tag macosx_11_0_arm64`.
- Staged SDK with `--codex-version rust-v0.116.0-alpha.1`.
- Built runtime wheel, SDK wheel, and SDK sdist.
- `twine check /tmp/codex-python-pr3-build/dist/*` -> passed.
- Clean venv smoke installed `openai-codex-app-server-sdk==0.116.0a1`
from local dist and pulled `openai-codex-cli-bin==0.116.0a1`.
- Smoke imports passed for `Codex` and `bundled_codex_path()`.

2026-04-27 14:28:46 -07:00

2.7 KiB

Raw Blame History

Python SDK Examples

Each example folder contains runnable versions:

sync.py (public sync surface: Codex)
async.py (public async surface: AsyncCodex)

All examples intentionally use only public SDK exports from codex_app_server.

Prerequisites

Python >=3.10
Install SDK dependencies for the same Python interpreter you will use to run examples

Recommended setup (from sdk/python):

uv sync
source .venv/bin/activate

When running examples from this repo checkout, the SDK source uses the local tree and does not bundle a runtime binary. The helper in examples/_bootstrap.py uses the installed openai-codex-cli-bin runtime package.

If the pinned openai-codex-cli-bin runtime is not already installed, the bootstrap will download the matching GitHub release artifact, stage a temporary local openai-codex-cli-bin package, install it into your active interpreter, and clean up the temporary files afterward.

The pinned runtime version comes from the SDK package version.

Run examples

From sdk/python:

python examples/<example-folder>/sync.py
python examples/<example-folder>/async.py

The examples bootstrap local imports from sdk/python/src automatically, so no SDK wheel install is required. You only need the Python dependencies for your active interpreter and an installed openai-codex-cli-bin runtime package (either already present or automatically provisioned by the bootstrap).

Recommended first run

python examples/01_quickstart_constructor/sync.py
python examples/01_quickstart_constructor/async.py

Index

01_quickstart_constructor/
- first run / sanity check
02_turn_run/
- inspect full turn output fields
03_turn_stream_events/
- stream a turn with a small curated event view
04_models_and_metadata/
- discover visible models for the connected runtime
05_existing_thread/
- resume a real existing thread (created in-script)
06_thread_lifecycle_and_controls/
- thread lifecycle + control calls
07_image_and_text/
- remote image URL + text multimodal turn
08_local_image_and_text/
- local image + text multimodal turn using a generated temporary sample image
09_async_parity/
- parity-style sync flow (see async parity in other examples)
10_error_handling_and_retry/
- overload retry pattern + typed error handling structure
11_cli_mini_app/
- interactive chat loop
12_turn_params_kitchen_sink/
- structured output with a curated advanced turn(...) configuration
13_model_select_and_turn_params/
- list models, pick highest model + highest supported reasoning effort, run turns, print message and usage
14_turn_controls/
- separate best-effort steer() and interrupt() demos with concise summaries

2.7 KiB Raw Blame History