codex/sdk/python/examples
Ahmed Ibrahim eb1cc3824c
[codex] Prepare Python SDK beta documentation and package metadata (#24836)
## Why

The initial public `openai-codex` beta should read and install like a
normal published Python package before a release tag is created. This
follows merged PR #24828, which establishes the independent SDK beta
release plumbing and exact runtime dependency.

## What changed

- Rewrote `sdk/python/README.md` as a compact PyPI-facing beta package
page: published installation, one quickstart, short login examples,
built-in help, and links to deeper guides.
- Updated the getting-started guide, API reference, FAQ, and examples
index to present the published beta consistently without repeating
onboarding in the package landing page or reference page.
- Made `pip install openai-codex` the primary install path while beta
releases are the only published SDK releases, with `--pre` documented
for opting into prereleases after a stable release exists.
- Added curated `help()` / `pydoc` docstrings across the public API and
generated public convenience methods through
`scripts/update_sdk_artifacts.py`.
- Declared the repository `Apache-2.0` license expression and
Documentation URL in package metadata, without introducing a duplicated
SDK-local license file.
- Kept the source distribution focused on installable package material
(`src/openai_codex`, `README.md`, and `pyproject.toml`); the repository
docs and runnable examples remain linked from the PyPI README.
- Built release artifacts in an Alpine container on the Ubuntu runner,
matching Python SDK CI and allowing type generation to install the
published `musllinux` runtime wheel.
- Added `twine check --strict` to the release workflow so malformed PyPI
metadata or rendered README content fails before publishing.
- Added focused SDK assertions for beta metadata, the exact runtime pin,
source distribution contents, and the built-in Python documentation
surface.

## Validation

- Ran `uv run --frozen --extra dev ruff check
scripts/update_sdk_artifacts.py src/openai_codex
tests/test_public_api_signatures.py
tests/test_artifact_workflow_and_binaries.py` before the final
README-only reductions and review-fix follow-ups.
- Built `openai_codex-0.1.0b1-py3-none-any.whl` and
`openai_codex-0.1.0b1.tar.gz` before the final README-only reductions
and review-fix follow-ups.
- Ran `python -m twine check --strict` on both built artifacts before
the final README-only reductions and review-fix follow-ups.
- Verified artifact metadata reports `Apache-2.0` without a duplicated
SDK-local license file.
- Verified `inspect.getdoc(...)` resolves documentation for the package,
`Codex`, `CodexConfig`, and key generated thread methods.
- Rebased the documentation/readiness change onto merged PR #24828
without changing the intended SDK or workflow file contents.
- Final verification is delegated to online CI for this PR.
History 2026-05-27 18:29:05 -07:00
..
01_quickstart_constructor [8/8] Add Python SDK Ruff formatting (#22021) 2026-05-12 01:10:29 +03:00
02_turn_run [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
03_turn_stream_events [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
04_models_and_metadata [codex] Return TurnResult from Python turn handles (#23151) 2026-05-17 06:17:22 -07:00
05_existing_thread [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
06_thread_lifecycle_and_controls [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
07_image_and_text [codex] Return TurnResult from Python turn handles (#23151) 2026-05-17 06:17:22 -07:00
08_local_image_and_text [codex] Return TurnResult from Python turn handles (#23151) 2026-05-17 06:17:22 -07:00
09_async_parity [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
10_error_handling_and_retry [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
11_cli_mini_app [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
12_turn_params_kitchen_sink [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
13_model_select_and_turn_params [codex] Add friendly Python SDK sandbox presets (#24772) 2026-05-27 11:11:04 -07:00
14_turn_controls [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
15_login_and_account sdk/python: add first-class login support (#23093) 2026-05-16 19:49:28 -07:00
_bootstrap.py [codex] Rename Python SDK AppServerConfig to CodexConfig (#24800) 2026-05-27 16:10:15 -07:00
README.md [codex] Prepare Python SDK beta documentation and package metadata (#24836) 2026-05-27 18:29:05 -07:00

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 openai_codex and openai_codex.types.

Examples use plain strings for text-only turns and typed input objects for multimodal or structured input lists.

Prerequisites

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

Install the published beta:

python -m pip install openai-codex

The SDK installs its pinned openai-codex-cli-bin runtime dependency. The pinned runtime version comes from the SDK package dependency.

Run From A Checkout

Contributors using these checked-in scripts should install development dependencies from sdk/python:

uv sync --extra dev
source .venv/bin/activate

The examples bootstrap local SDK imports from sdk/python/src. If the pinned runtime is not already installed, the bootstrap installs the matching runtime package for the active interpreter and cleans up temporary files afterward.

Run examples

From sdk/python:

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

The checked-in examples use the local SDK source tree automatically.

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 steer() and interrupt() demos with concise summaries
  • 15_login_and_account/
    • browser-login handle lifecycle, cancellation, and account inspection