mirror of
https://github.com/pchuan98/codex.git
synced 2026-07-01 00:31:56 +08:00
Ahmed Ibrahim
b1cbf622ad
## Why
The Python SDK currently exposes sandbox selection differently depending
on where it is used: thread lifecycle methods accept `SandboxMode`,
while turns accept the lower-level `SandboxPolicy` shape. For the common
case of choosing an access level, that leaks app-server wire details
into otherwise straightforward SDK usage.
This makes the common path explicit and discoverable: callers choose a
named sandbox preset once, using the same keyword on threads and turns.
The preset name `workspace_write` also makes the granted capability
clear at the callsite.
## What changed
- Added a root-level `Sandbox` enum with documented presets:
- `Sandbox.read_only`: read files without allowing writes.
- `Sandbox.workspace_write`: the normal default for projects with a
recorded trust decision; read files and write inside the workspace and
configured writable roots.
- `Sandbox.full_access`: run without filesystem access restrictions.
- Documented that omitting `sandbox=` delegates to app-server's
configured default, while explicit turn overrides remain sticky for
subsequent turns.
- Updated sync and async thread lifecycle and turn APIs to consistently
accept `sandbox=Sandbox...`, translating to the existing app-server
thread and turn representations internally.
- Updated the public API artifact generator so regenerated SDK wrappers
retain the friendly enum shape.
- Replaced low-level policy construction in Python docs, examples, and
the walkthrough notebook with the preset API.
- Added focused coverage for root exports, method signatures,
preset-to-wire mapping, and rejection of raw string sandbox inputs.
## API impact
High-level turn calls now use `sandbox=` instead of `sandbox_policy=`:
```python
from openai_codex import Codex, Sandbox
with Codex() as codex:
thread = codex.thread_start(sandbox=Sandbox.workspace_write)
result = thread.run("Review the diff only.", sandbox=Sandbox.read_only)
```
`thread_start(...)` already defaults to `ApprovalMode.auto_review`, so
normal writable usage is concise:
```python
with Codex() as codex:
thread = codex.thread_start(sandbox=Sandbox.workspace_write)
thread.run("Update the files in this workspace.")
```
With that combination, edits inside `cwd` and configured writable roots
run within the workspace-write sandbox. Operations that require
approval, such as edits outside those roots, are routed through auto
review. When `sandbox=` is omitted, app-server resolves its configured
default. A sandbox supplied to `run(...)` or `turn(...)` applies to that
turn and subsequent turns.
## Test coverage
- `sdk/python/tests/test_public_api_signatures.py` covers the public
export and parameter names, including the default approval mode.
- `sdk/python/tests/test_public_api_runtime_behavior.py` covers preset
mappings to the existing wire types and raw string rejection.
b1cbf622ad
ยท
2026-05-27 11:11:04 -07:00
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 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 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
steer()andinterrupt()demos with concise summaries
- separate
15_login_and_account/- browser-login handle lifecycle, cancellation, and account inspection