mirror of
https://github.com/openai/codex.git
synced 2026-05-20 19:23:21 +00:00
4c89772314
## Why The Python SDK can already create threads and run turns, but authentication still has to be arranged outside the SDK. App-server already exposes account login, account inspection, logout, and `account/login/completed` notifications, so SDK users currently have to work around a missing public client layer for a core setup step. This change makes authentication a normal SDK workflow while preserving the backend flow shape: API-key login completes immediately, and interactive ChatGPT flows return live handles that complete later through app-server notifications. ## What changed - Added public sync and async auth methods on `Codex` / `AsyncCodex`: - `login_api_key(...)` - `login_chatgpt()` - `login_chatgpt_device_code()` - `account(...)` - `logout()` - Added public browser-login and device-code handle types with attempt-local `wait()` and `cancel()` helpers. Cancellation stays on the handle instead of a root-level SDK method. - Extended the Python app-server client and notification router so login completion events are routed by `login_id` without consuming unrelated global notifications. - Kept login request/handle logic in a focused internal `_login.py` module so `api.py` remains the public facade instead of absorbing more auth plumbing. - Exported the new handle types plus curated account/login response types from the SDK surfaces. - Updated SDK docs, added sync/async login walkthrough examples, and added a notebook login walkthrough cell. ## Verification Added SDK coverage for: - API-key login, account readback, and logout through the app-server harness in both sync and async clients. - Browser login cancellation plus `handle.wait()` completion through the real app-server boundary used by the Python SDK harness. - Waiter routing that stays scoped across replaced interactive login attempts, plus async handle cancellation coverage. - Login notification demuxing, replay of early completion events, and async client delegation. - Public export/signature assertions. - Real integration-suite smoke coverage for the new examples and notebook login cell.
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.
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 dependency.
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
- structured output with a curated advanced
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()andinterrupt()demos with concise summaries
- separate best-effort
15_login_and_account/- browser-login handle lifecycle, cancellation, and account inspection