[8/8] Add Python SDK Ruff formatting by aibrahim-oai · Pull Request #22021 · openai/codex

aibrahim-oai · 2026-05-10T12:40:05Z

Why

The Python SDK needs the same tight formatter/lint loop as the rest of the repo: a safe Ruff autofix pass, Ruff formatting, editor save behavior, and CI checks that catch drift. Without that loop, SDK changes can land with formatting or import ordering that differs from what reviewers and CI expect.

What

Add Ruff configuration to sdk/python/pyproject.toml, excluding generated protocol code and notebooks from the normal lint/format pass.
Update just fmt so it still formats Rust and also runs Python SDK Ruff autofix and formatting.
Add Python SDK CI steps for ruff check and ruff format --check before pytest.
Recommend the Ruff VS Code extension and enable Python format/fix/organize-on-save so Cmd+S uses the same tooling.
Apply the resulting Ruff formatting to SDK Python files, examples, and the checked-in generated v2_all.py output emitted by the pinned generator.
Add a guard test for the just fmt recipe so it keeps working from both Rust and Python SDK working directories.

Stack

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

Verification

Added test_root_fmt_recipe_formats_rust_and_python_sdk for the shared format recipe.
Ran just fmt after the recipe update.

aibrahim-oai · 2026-05-10T12:40:07Z

This change is part of the following stack:

[8/8] Add Python SDK Ruff formatting #22021 ◀

_{Change managed by git-spice.}

charliermarsh · 2026-05-10T19:22:42Z

 testpaths = ["tests"]

+[tool.ruff]
+target-version = "py310"


You should be able to omit this, it'll be inferred from the requires-python.

## Why The Python SDK depends on the app-server runtime package for the bundled `codex` binary and schema source of truth. That relationship should be explicit in package metadata instead of inferred from matching version numbers, so installers, lockfiles, and reviewers can see exactly which runtime the SDK expects. ## What - Declare `openai-codex-cli-bin==0.131.0a4` as a Python SDK dependency. - Update runtime setup helpers to resolve the runtime version from the declared dependency pin. - Refresh the SDK lockfile for the pinned runtime wheel. - Update package/runtime tests and docs that describe where the runtime version comes from. ## Stack 1. This PR `[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. #21896 `[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 coverage for the SDK runtime dependency pin and runtime distribution naming. --------- Co-authored-by: Codex <noreply@openai.com>

## Why Once the SDK declares its runtime package, generated Python artifacts should come from that pinned runtime rather than whatever app-server schema happens to be in the current checkout. That keeps the generated API and model surface aligned with the runtime users install. ## What - Teach `scripts/update_sdk_artifacts.py generate-types` to invoke the pinned runtime package for schema generation. - Regenerate `v2_all.py`, `notification_registry.py`, and generated public wrapper methods from that schema. - Add freshness coverage so regenerating from the pinned runtime must leave checked-in artifacts unchanged. ## Stack 1. #21891 `[1/8]` Pin Python SDK runtime dependency 2. This PR `[2/8]` Generate Python SDK types from pinned runtime 3. #21895 `[3/8]` Run Python SDK tests in CI 4. #21896 `[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 `test_generated_files_are_up_to_date` for pinned-runtime generation drift. - Added generator-structure tests for schema annotation and notification metadata generation. --------- Co-authored-by: Codex <noreply@openai.com>

## Why The Python SDK stack now depends on packaging metadata, pinned runtime wheels, generated artifacts, async behavior, and stream interleaving. Those checks need to run in CI so future changes cannot bypass the SDK test suite. ## What - Add a dedicated `python-sdk` job to `.github/workflows/sdk.yml`. - Run the job in `python:3.12-alpine` so dependency resolution exercises the pinned musl runtime wheel. - Keep the Python SDK test job parallel to the existing SDK job instead of serializing the full workflow. ## Stack 1. #21891 `[1/8]` Pin Python SDK runtime dependency 2. #21893 `[2/8]` Generate Python SDK types from pinned runtime 3. This PR `[3/8]` Run Python SDK tests in CI 4. #21896 `[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 - The added workflow job installs the SDK with `uv sync --extra dev --frozen` and runs the Python SDK pytest suite. --------- Co-authored-by: Codex <noreply@openai.com>

## 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>

## Why The SDK should publish under the reserved public distribution name `openai-codex`, and its import module should match that name in the Python style. Since package names can contain hyphens but import modules cannot, the public import path becomes `openai_codex`. Keeping the rename separate from the public API surface change makes the naming change easy to review and avoids mixing it with API curation. ## What - Rename the SDK distribution from `openai-codex-app-server-sdk` to `openai-codex`. - Rename the import package from `codex_app_server` to `openai_codex`. - Keep the runtime wheel as the separate `openai-codex-cli-bin` dependency. - Update docs, examples, notebooks, artifact scripts, lockfile metadata, and tests for the new distribution/module names. ## 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. #21896 `[4/8]` Define Python SDK public API surface 5. This PR `[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 - Updated package metadata and public API tests to assert the distribution and import names. Co-authored-by: Codex <noreply@openai.com>

## Why The high-level SDK should expose the approval behavior it actually supports instead of leaking generated app-server routing fields. New work should have two clear choices: default auto review, or explicitly deny escalated permission requests. Existing threads and subsequent turns should preserve their current approval behavior unless the caller passes an override. ## What - Add the public `ApprovalMode` enum with `auto_review` and `deny_all`. - Default new thread creation to `ApprovalMode.auto_review`. - Preserve existing approval settings by default for resume, fork, run, and turn helpers. - Remove raw `approval_policy` / `approvals_reviewer` kwargs from high-level SDK wrappers. - Update generated wrapper output, docs, examples, notebooks, and tests for the high-level approval mode API. ## 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. #21896 `[4/8]` Define Python SDK public API surface 5. #21905 `[5/8]` Rename Python SDK package to `openai-codex` 6. This PR `[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 approval-mode mapping/default tests for new threads, existing threads, forks, resumes, and subsequent turns. --------- Co-authored-by: Codex <noreply@openai.com>

## Why The SDK had behavioral tests that replaced SDK client internals. Those tests could catch wrapper mistakes, but they did not prove the pinned app-server runtime, generated notification models, request routing, and sync/async public clients worked together. This PR adds deterministic integration coverage that starts the pinned `codex app-server` process and mocks only the upstream Responses HTTP boundary. ## What - Add `AppServerHarness` and `MockResponsesServer` helpers for isolated `CODEX_HOME`, mock-provider config, queued SSE responses, and captured `/v1/responses` requests. - Add shared helpers for SSE construction, stream assertions, approval-policy inspection, and image fixtures. - Split integration coverage into focused modules for run behavior, inputs, streaming, turn controls, approvals, and thread lifecycle. - Cover sync and async `Thread.run`, `TurnHandle.stream`, interleaved streams, approval-mode persistence, lifecycle helpers, final-answer phase handling, image inputs, loaded skill input injection, steering, interruption, listing, history reads, run overrides, and token usage mapping. - Replace public-wrapper tests that duplicated integration-test behavior with lower-level client tests only where direct client behavior is the thing under test. ## 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. #21896 `[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. This PR `[7/8]` Add Python SDK app-server integration harness 8. #22021 `[8/8]` Add Python SDK Ruff formatting ## Verification - Added pinned app-server integration tests under `sdk/python/tests/test_app_server_*.py` and `test_real_app_server_integration.py`. --------- Co-authored-by: Codex <noreply@openai.com>

Co-authored-by: Codex <noreply@openai.com>

charliermarsh reviewed May 10, 2026

View reviewed changes

aibrahim-oai force-pushed the codex/python-sdk-mock-integration-tests branch from 5c7b278 to 81dccad Compare May 11, 2026 21:30

aibrahim-oai force-pushed the codex/python-sdk-format-lint branch from 3cc0805 to a886174 Compare May 11, 2026 21:30

aibrahim-oai mentioned this pull request May 11, 2026

Publish Linux runtime wheels with glibc-compatible tags #21812

Open

aibrahim-oai force-pushed the codex/python-sdk-mock-integration-tests branch from 81dccad to 175fc0a Compare May 11, 2026 21:49

aibrahim-oai force-pushed the codex/python-sdk-format-lint branch from a886174 to 22d7c19 Compare May 11, 2026 21:49

aibrahim-oai force-pushed the codex/python-sdk-mock-integration-tests branch from 175fc0a to 9a169a2 Compare May 11, 2026 21:51

aibrahim-oai force-pushed the codex/python-sdk-format-lint branch from 22d7c19 to 88c3acf Compare May 11, 2026 21:51

aibrahim-oai force-pushed the codex/python-sdk-mock-integration-tests branch from 9a169a2 to 46d29b5 Compare May 11, 2026 21:55

aibrahim-oai force-pushed the codex/python-sdk-format-lint branch from 88c3acf to 8ff3598 Compare May 11, 2026 21:55

aibrahim-oai force-pushed the codex/python-sdk-mock-integration-tests branch from 46d29b5 to 5ee8852 Compare May 11, 2026 21:56

aibrahim-oai force-pushed the codex/python-sdk-format-lint branch from 8ff3598 to 48f9823 Compare May 11, 2026 21:57

aibrahim-oai force-pushed the codex/python-sdk-mock-integration-tests branch from 5ee8852 to 810898d Compare May 11, 2026 21:58

aibrahim-oai force-pushed the codex/python-sdk-format-lint branch from 48f9823 to 66f4e95 Compare May 11, 2026 21:59

aibrahim-oai force-pushed the codex/python-sdk-mock-integration-tests branch from 810898d to 27366d0 Compare May 11, 2026 22:00

aibrahim-oai force-pushed the codex/python-sdk-format-lint branch from 66f4e95 to 94fd54b Compare May 11, 2026 22:00

aibrahim-oai force-pushed the codex/python-sdk-mock-integration-tests branch from 27366d0 to 70cc226 Compare May 11, 2026 22:06

aibrahim-oai force-pushed the codex/python-sdk-format-lint branch from 94fd54b to 53ff5bf Compare May 11, 2026 22:06

Base automatically changed from codex/python-sdk-mock-integration-tests to main May 11, 2026 22:06

aibrahim-oai and others added 7 commits May 12, 2026 01:07

Add Python SDK Ruff formatting

c0cc0cf

Co-authored-by: Codex <noreply@openai.com>

Update generated SDK formatting

a56e59d

Co-authored-by: Codex <noreply@openai.com>

Simplify SDK fmt recipe paths

a784759

Co-authored-by: Codex <noreply@openai.com>

Use default cwd for fmt recipe

8a8b15b

Co-authored-by: Codex <noreply@openai.com>

Guard Python SDK fmt recipe

4a256df

Co-authored-by: Codex <noreply@openai.com>

Clarify fmt recipe guard failure

d9cb529

Co-authored-by: Codex <noreply@openai.com>

Tighten fmt guard failure message

190ba8e

Co-authored-by: Codex <noreply@openai.com>

aibrahim-oai force-pushed the codex/python-sdk-format-lint branch from 53ff5bf to 190ba8e Compare May 11, 2026 22:07

aibrahim-oai and others added 2 commits May 12, 2026 01:08

Avoid codespell false positive in streaming test

7f45503

Co-authored-by: Codex <noreply@openai.com>

Format streaming test fixture

0adb952

Co-authored-by: Codex <noreply@openai.com>

aibrahim-oai merged commit aa9e8f0 into main May 11, 2026
25 of 26 checks passed

aibrahim-oai deleted the codex/python-sdk-format-lint branch May 11, 2026 22:10

github-actions Bot locked and limited conversation to collaborators May 11, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[8/8] Add Python SDK Ruff formatting#22021

[8/8] Add Python SDK Ruff formatting#22021
aibrahim-oai merged 9 commits into
mainfrom
codex/python-sdk-format-lint

aibrahim-oai commented May 10, 2026 •

edited

Loading

Uh oh!

aibrahim-oai commented May 10, 2026 •

edited

Loading

Uh oh!

charliermarsh May 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

aibrahim-oai commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What

Stack

Verification

Uh oh!

aibrahim-oai commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

charliermarsh May 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aibrahim-oai commented May 10, 2026 •

edited

Loading

aibrahim-oai commented May 10, 2026 •

edited

Loading