clone/codex
1
0
Fork 0
mirror of https://github.com/openai/codex.git synced 2026-05-18 02:02:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
## 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. #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. #22014 `[7/8]` Add Python SDK app-server integration harness
8. 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.

---------

Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
Ahmed Ibrahim
2026-05-12 01:10:29 +03:00
committed by GitHub
parent 3e10e09e24
commit aa9e8f0262
51 changed files with 660 additions and 1163 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
sdk/python/tests/app_server_harness.py
View File

@@ -12,7 +12,6 @@ from typing import Any
from openai_codex import AppServerConfig
Json = dict[str, Any]

1
sdk/python/tests/app_server_helpers.py
View File

@@ -11,6 +11,7 @@ from app_server_harness import (
ev_response_created,
sse,
)
from openai_codex.generated.v2_all import (
AgentMessageDeltaNotification,
ItemCompletedNotification,

3
sdk/python/tests/test_app_server_approvals.py
View File

@@ -3,9 +3,10 @@ from __future__ import annotations
import asyncio
from app_server_harness import AppServerHarness
from app_server_helpers import response_approval_policy
from openai_codex import ApprovalMode, AsyncCodex, Codex
from openai_codex.generated.v2_all import AskForApprovalValue, ThreadResumeParams
from app_server_helpers import response_approval_policy
def test_thread_resume_inherits_deny_all_approval_mode(tmp_path) -> None:

17
sdk/python/tests/test_app_server_inputs.py
View File

@@ -1,9 +1,10 @@
from __future__ import annotations
from app_server_harness import AppServerHarness
from openai_codex import Codex, ImageInput, LocalImageInput, SkillInput, TextInput
from app_server_helpers import TINY_PNG_BYTES
from openai_codex import Codex, ImageInput, LocalImageInput, SkillInput, TextInput
def test_remote_image_input_reaches_responses_api(
tmp_path,
@@ -28,8 +29,7 @@ def test_remote_image_input_reaches_responses_api(
assert {
"final_response": result.final_response,
"contains_user_prompt": "Describe the remote image."
in request.message_input_texts("user"),
"contains_user_prompt": "Describe the remote image." in request.message_input_texts("user"),
"image_urls": request.message_image_urls("user"),
} == {
"final_response": "remote image received",
@@ -62,8 +62,7 @@ def test_local_image_input_reaches_responses_api(
assert {
"final_response": result.final_response,
"contains_user_prompt": "Describe the local image."
in request.message_input_texts("user"),
"contains_user_prompt": "Describe the local image." in request.message_input_texts("user"),
"image_url_is_png_data_url": request.message_image_urls("user")[-1].startswith(
"data:image/png;base64,"
),
@@ -81,9 +80,7 @@ def test_skill_input_injects_loaded_skill_body(tmp_path) -> None:
with AppServerHarness(tmp_path) as harness:
skill_file = harness.workspace / ".agents" / "skills" / "demo" / "SKILL.md"
skill_file.parent.mkdir(parents=True)
skill_file.write_text(
f"---\nname: demo\ndescription: demo skill\n---\n\n{skill_body}\n"
)
skill_file.write_text(f"---\nname: demo\ndescription: demo skill\n---\n\n{skill_body}\n")
skill_path = skill_file.resolve()
harness.responses.enqueue_assistant_message(
"skill received",
@@ -100,9 +97,7 @@ def test_skill_input_injects_loaded_skill_body(tmp_path) -> None:
request = harness.responses.single_request()
skill_blocks = [
text
for text in request.message_input_texts("user")
if text.startswith("<skill>")
text for text in request.message_input_texts("user") if text.startswith("<skill>")
]
assert {
"final_response": result.final_response,

7
sdk/python/tests/test_app_server_lifecycle.py
View File

@@ -3,9 +3,10 @@ from __future__ import annotations
import asyncio
from app_server_harness import AppServerHarness
from openai_codex import AsyncCodex, Codex
from app_server_helpers import request_kind
from openai_codex import AsyncCodex, Codex
def _thread_message_summary(read_response) -> list[tuple[str, str]]:
"""Return persisted user/agent messages from a thread read response."""
@@ -58,9 +59,7 @@ def test_thread_list_filters_archived_threads(tmp_path) -> None:
expected_ids = {active_thread.id, archived_thread.id}
assert {
"active_ids": sorted(
thread.id for thread in active_list.data if thread.id in expected_ids
),
"active_ids": sorted(thread.id for thread in active_list.data if thread.id in expected_ids),
"archived_ids": sorted(
thread.id for thread in archived_list.data if thread.id in expected_ids
),

14
sdk/python/tests/test_app_server_run.py
View File

@@ -3,7 +3,6 @@ from __future__ import annotations
import asyncio
import pytest
from app_server_harness import (
AppServerHarness,
ev_assistant_message,
@@ -13,13 +12,14 @@ from app_server_harness import (
ev_response_created,
sse,
)
from openai_codex import AsyncCodex, Codex
from openai_codex.generated.v2_all import MessagePhase
from app_server_helpers import (
agent_message_texts_from_items,
assistant_message_with_phase,
)
from openai_codex import AsyncCodex, Codex
from openai_codex.generated.v2_all import MessagePhase
def test_sync_thread_run_uses_mock_responses(
tmp_path,
@@ -250,9 +250,7 @@ def test_async_run_result_uses_last_unknown_phase_message(tmp_path) -> None:
)
async with AsyncCodex(config=harness.app_server_config()) as codex:
result = await (await codex.thread_start()).run(
"case: async last unknown phase"
)
result = await (await codex.thread_start()).run("case: async last unknown phase")
assert {
"final_response": result.final_response,
@@ -288,9 +286,7 @@ def test_async_run_result_does_not_promote_commentary_only_to_final(
)
async with AsyncCodex(config=harness.app_server_config()) as codex:
result = await (await codex.thread_start()).run(
"case: async commentary only"
)
result = await (await codex.thread_start()).run("case: async commentary only")
assert {
"final_response": result.final_response,

19
sdk/python/tests/test_app_server_streaming.py
View File

@@ -3,12 +3,6 @@ from __future__ import annotations
import asyncio
from app_server_harness import AppServerHarness
from openai_codex import AsyncCodex, Codex, TextInput
from openai_codex.generated.v2_all import (
AgentMessageDeltaNotification,
TurnCompletedNotification,
TurnStatus,
)
from app_server_helpers import (
agent_message_texts,
next_async_delta,
@@ -16,13 +10,18 @@ from app_server_helpers import (
streaming_response,
)
from openai_codex import AsyncCodex, Codex, TextInput
from openai_codex.generated.v2_all import (
AgentMessageDeltaNotification,
TurnCompletedNotification,
TurnStatus,
)
def test_sync_stream_routes_text_deltas_and_completion(tmp_path) -> None:
"""A sync turn stream should expose deltas, completed items, and completion."""
with AppServerHarness(tmp_path) as harness:
harness.responses.enqueue_sse(
streaming_response("stream-1", "msg-stream-1", ["hel", "lo"])
)
harness.responses.enqueue_sse(streaming_response("stream-1", "msg-stream-1", ["he", "llo"]))
with Codex(config=harness.app_server_config()) as codex:
thread = codex.thread_start()
@@ -42,7 +41,7 @@ def test_sync_stream_routes_text_deltas_and_completion(tmp_path) -> None:
if isinstance(event.payload, TurnCompletedNotification)
],
} == {
"deltas": ["hel", "lo"],
"deltas": ["he", "llo"],
"agent_messages": ["hello"],
"completed_statuses": [TurnStatus.completed],
}

7
sdk/python/tests/test_app_server_turn_controls.py
View File

@@ -1,9 +1,10 @@
from __future__ import annotations
from app_server_harness import AppServerHarness
from app_server_helpers import agent_message_texts, streaming_response
from openai_codex import Codex, TextInput
from openai_codex.generated.v2_all import TurnStatus
from app_server_helpers import agent_message_texts, streaming_response
def test_turn_steer_adds_follow_up_input(tmp_path) -> None:
@@ -30,9 +31,7 @@ def test_turn_steer_adds_follow_up_input(tmp_path) -> None:
"steered_turn_id": steer.turn_id,
"turn_id": turn.id,
"agent_messages": agent_message_texts(events),
"last_user_texts": [
request.message_input_texts("user")[-1] for request in requests
],
"last_user_texts": [request.message_input_texts("user")[-1] for request in requests],
} == {
"steered_turn_id": turn.id,
"turn_id": turn.id,

86
sdk/python/tests/test_artifact_workflow_and_binaries.py
View File

@@ -5,12 +5,12 @@ import importlib.util
import io
import json
import sys
import tomllib
import urllib.error
from pathlib import Path
from typing import Sequence
import pytest
import tomllib
ROOT = Path(__file__).resolve().parents[1]
@@ -32,9 +32,7 @@ def _load_runtime_setup_module():
runtime_setup_path = ROOT / "_runtime_setup.py"
spec = importlib.util.spec_from_file_location("_runtime_setup", runtime_setup_path)
if spec is None or spec.loader is None:
raise AssertionError(
f"Failed to load runtime setup module: {runtime_setup_path}"
)
raise AssertionError(f"Failed to load runtime setup module: {runtime_setup_path}")
module = importlib.util.module_from_spec(spec)
sys.modules[spec.name] = module
spec.loader.exec_module(module)
@@ -47,6 +45,40 @@ def test_generation_has_single_maintenance_entrypoint_script() -> None:
assert scripts == ["update_sdk_artifacts.py"]
def test_root_fmt_recipe_formats_rust_and_python_sdk() -> None:
"""The repo fmt command should work from Rust and Python SDK directories."""
justfile = ROOT.parents[1] / "justfile"
lines = justfile.read_text().splitlines()
fmt_index = lines.index("fmt:")
next_recipe_index = next(
index
for index in range(fmt_index + 1, len(lines))
if lines[index] and not lines[index].startswith((" ", "\t", "#"))
)
fmt_recipe = lines[fmt_index:next_recipe_index]
actual = {
"working_directory": lines[0],
"previous_attribute": lines[fmt_index - 1],
"commands": [line.strip() for line in fmt_recipe[1:] if line.strip()],
}
expected = {
"working_directory": 'set working-directory := "codex-rs"',
"previous_attribute": "# Format Rust and Python SDK code.",
"commands": [
"cargo fmt -- --config imports_granularity=Item 2>/dev/null",
"uv run --project ../sdk/python --extra dev ruff check --fix --fix-only ../sdk/python",
"uv run --project ../sdk/python --extra dev ruff format ../sdk/python",
],
}
assert actual == expected, (
"The root `just fmt` recipe must run Rust fmt and Python SDK Ruff. "
"Fix the `fmt` recipe in `justfile`, then run `just fmt`.\n"
f"Expected: {json.dumps(expected, indent=2)}\n"
f"Actual: {json.dumps(actual, indent=2)}"
)
def test_generate_types_wires_all_generation_steps() -> None:
"""The type generation command should refresh every schema-derived artifact."""
source = (ROOT / "scripts" / "update_sdk_artifacts.py").read_text()
@@ -56,8 +88,7 @@ def test_generate_types_wires_all_generation_steps() -> None:
(
node
for node in tree.body
if isinstance(node, ast.FunctionDef)
and node.name == "generate_types_from_schema_dir"
if isinstance(node, ast.FunctionDef) and node.name == "generate_types_from_schema_dir"
),
None,
)
@@ -94,8 +125,7 @@ def test_schema_normalization_only_flattens_string_literal_oneofs(
flattened = [
name
for name, definition in definitions.items()
if isinstance(definition, dict)
and script._flatten_string_enum_one_of(definition.copy())
if isinstance(definition, dict) and script._flatten_string_enum_one_of(definition.copy())
]
assert flattened == [
@@ -172,8 +202,7 @@ def test_examples_readme_points_to_runtime_version_source_of_truth() -> None:
def test_runtime_distribution_name_is_consistent() -> None:
script = _load_update_script_module()
runtime_setup = _load_runtime_setup_module()
from openai_codex import client as client_module
from openai_codex import _version
from openai_codex import _version, client as client_module
assert script.SDK_DISTRIBUTION_NAME == "openai-codex"
assert runtime_setup.SDK_PACKAGE_NAME == "openai-codex"
@@ -232,22 +261,6 @@ def test_release_metadata_retries_without_invalid_auth(
assert authorizations == ["Bearer invalid-token", None]
def test_source_sdk_package_pins_published_runtime() -> None:
"""The source package metadata should pin the runtime wheel that ships schemas."""
pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text())
assert {
"sdk_version": pyproject["project"]["version"],
"dependencies": pyproject["project"]["dependencies"],
} == {
"sdk_version": "0.131.0a4",
"dependencies": [
"pydantic>=2.12",
"openai-codex-cli-bin==0.131.0a4",
],
}
def test_runtime_setup_uses_pep440_package_version_and_codex_release_tags() -> None:
"""The SDK uses PEP 440 package pins and converts only when fetching releases."""
runtime_setup = _load_runtime_setup_module()
@@ -259,17 +272,12 @@ def test_runtime_setup_uses_pep440_package_version_and_codex_release_tags() -> N
f"{runtime_setup.PACKAGE_NAME}=={pyproject['project']['version']}"
in pyproject["project"]["dependencies"]
)
assert (
runtime_setup._normalized_package_version("rust-v0.116.0-alpha.1")
== "0.116.0a1"
)
assert runtime_setup._normalized_package_version("rust-v0.116.0-alpha.1") == "0.116.0a1"
assert runtime_setup._release_tag("0.116.0a1") == "rust-v0.116.0-alpha.1"
def test_runtime_package_is_wheel_only_and_builds_platform_specific_wheels() -> None:
pyproject = tomllib.loads(
(ROOT.parent / "python-runtime" / "pyproject.toml").read_text()
)
pyproject = tomllib.loads((ROOT.parent / "python-runtime" / "pyproject.toml").read_text())
hook_source = (ROOT.parent / "python-runtime" / "hatch_build.py").read_text()
hook_tree = ast.parse(hook_source)
initialize_fn = next(
@@ -411,9 +419,7 @@ def test_stage_runtime_release_copies_resource_binaries(tmp_path: Path) -> None:
)
assert {
path.relative_to(
staged / "src" / "codex_cli_bin" / "bin"
).as_posix(): path.read_text()
path.relative_to(staged / "src" / "codex_cli_bin" / "bin").as_posix(): path.read_text()
for path in (staged / "src" / "codex_cli_bin" / "bin").iterdir()
} == {
script.runtime_binary_name(): "fake codex\n",
@@ -502,9 +508,7 @@ def test_staged_sdk_and_runtime_versions_match(tmp_path: Path) -> None:
sdk_pyproject = tomllib.loads((sdk_stage / "pyproject.toml").read_text())
runtime_pyproject = tomllib.loads((runtime_stage / "pyproject.toml").read_text())
assert (
sdk_pyproject["project"]["version"] == runtime_pyproject["project"]["version"]
)
assert sdk_pyproject["project"]["version"] == runtime_pyproject["project"]["version"]
assert sdk_pyproject["project"]["dependencies"] == [
"pydantic>=2.12",
"openai-codex-cli-bin==0.116.0a1",
@@ -629,9 +633,7 @@ def test_stage_runtime_stages_binary_without_type_generation(tmp_path: Path) ->
script.run_command(args, ops)
assert calls == [
"stage_runtime:0.116.0a1:musllinux_1_1_x86_64:helper,fallback-helper"
]
assert calls == ["stage_runtime:0.116.0a1:musllinux_1_1_x86_64:helper,fallback-helper"]
def test_default_runtime_is_resolved_from_installed_runtime_package(

2
sdk/python/tests/test_async_client_behavior.py
View File

@@ -12,6 +12,7 @@ from openai_codex.models import Notification, UnknownNotification
def test_async_client_allows_concurrent_transport_calls() -> None:
"""Async wrappers should offload sync calls so concurrent awaits can overlap."""
async def scenario() -> int:
"""Run two blocking sync calls and report peak overlap."""
client = AsyncAppServerClient()
@@ -36,6 +37,7 @@ def test_async_client_allows_concurrent_transport_calls() -> None:
def test_async_client_turn_notification_methods_delegate_to_sync_client() -> None:
"""Async turn routing methods should preserve sync-client registration semantics."""
async def scenario() -> tuple[list[tuple[str, str]], Notification, str]:
"""Record the sync-client calls made by async turn notification wrappers."""
client = AsyncAppServerClient()

4
sdk/python/tests/test_client_rpc_methods.py
View File

@@ -111,9 +111,7 @@ def test_unknown_notifications_fall_back_to_unknown_payloads() -> None:
def test_invalid_notification_payload_falls_back_to_unknown() -> None:
client = AppServerClient()
event = client._coerce_notification(
"thread/tokenUsage/updated", {"threadId": "missing"}
)
event = client._coerce_notification("thread/tokenUsage/updated", {"threadId": "missing"})
assert event.method == "thread/tokenUsage/updated"
assert isinstance(event.payload, UnknownNotification)

5
sdk/python/tests/test_contract_generation.py
View File

@@ -31,10 +31,7 @@ def _snapshot_target(root: Path, rel_path: Path) -> dict[str, bytes] | bytes | N
def _snapshot_targets(root: Path) -> dict[str, dict[str, bytes] | bytes | None]:
"""Capture all checked-in generated artifacts before and after regeneration."""
return {
str(rel_path): _snapshot_target(root, rel_path)
for rel_path in GENERATED_TARGETS
}
return {str(rel_path): _snapshot_target(root, rel_path) for rel_path in GENERATED_TARGETS}
def test_generated_files_are_up_to_date():

8
sdk/python/tests/test_public_api_runtime_behavior.py
View File

@@ -7,13 +7,13 @@ from typing import Any
import pytest
import openai_codex.api as public_api_module
from openai_codex.generated.v2_all import TurnStartParams
from openai_codex.models import InitializeResponse
from openai_codex.api import (
ApprovalMode,
AsyncCodex,
Codex,
)
from openai_codex.generated.v2_all import TurnStartParams
from openai_codex.models import InitializeResponse
ROOT = Path(__file__).resolve().parents[1]
@@ -129,9 +129,7 @@ def test_async_codex_initializes_only_once_under_concurrency() -> None:
def _approval_mode_turn_params(approval_mode: ApprovalMode) -> TurnStartParams:
"""Build real generated turn params from one public approval mode."""
approval_policy, approvals_reviewer = public_api_module._approval_mode_settings(
approval_mode
)
approval_policy, approvals_reviewer = public_api_module._approval_mode_settings(approval_mode)
return TurnStartParams(
thread_id="thread-1",
input=[],

35
sdk/python/tests/test_public_api_signatures.py
View File

@@ -2,15 +2,16 @@ from __future__ import annotations
import importlib.resources as resources
import inspect
import tomllib
from pathlib import Path
from typing import Any
import tomllib
import openai_codex
import openai_codex.types as public_types
from openai_codex import (
AppServerConfig,
ApprovalMode,
AppServerConfig,
AsyncCodex,
AsyncThread,
Codex,
@@ -107,9 +108,7 @@ def _assert_no_any_annotations(fn: object) -> None:
signature = inspect.signature(fn)
for param in signature.parameters.values():
if param.annotation is Any:
raise AssertionError(
f"{fn} has public parameter typed as Any: {param.name}"
)
raise AssertionError(f"{fn} has public parameter typed as Any: {param.name}")
if signature.return_annotation is Any:
raise AssertionError(f"{fn} has public return annotation typed as Any")
@@ -150,9 +149,9 @@ def test_package_includes_py_typed_marker() -> None:
def test_package_root_exports_only_public_api() -> None:
"""The package root should expose the supported SDK surface, not internals."""
assert openai_codex.__all__ == EXPECTED_ROOT_EXPORTS
assert {name: hasattr(openai_codex, name) for name in EXPECTED_ROOT_EXPORTS} == {
name: True for name in EXPECTED_ROOT_EXPORTS
}
assert {name: hasattr(openai_codex, name) for name in EXPECTED_ROOT_EXPORTS} == dict.fromkeys(
EXPECTED_ROOT_EXPORTS, True
)
assert {
"AppServerClient": hasattr(openai_codex, "AppServerClient"),
"AsyncAppServerClient": hasattr(openai_codex, "AsyncAppServerClient"),
@@ -184,9 +183,9 @@ def test_package_star_import_matches_public_api() -> None:
def test_types_module_exports_curated_public_types() -> None:
"""The public type module should be the supported place for app-server models."""
assert public_types.__all__ == EXPECTED_TYPES_EXPORTS
assert {name: hasattr(public_types, name) for name in EXPECTED_TYPES_EXPORTS} == {
name: True for name in EXPECTED_TYPES_EXPORTS
}
assert {name: hasattr(public_types, name) for name in EXPECTED_TYPES_EXPORTS} == dict.fromkeys(
EXPECTED_TYPES_EXPORTS, True
)
def test_types_star_import_matches_public_types() -> None:
@@ -390,9 +389,9 @@ def test_new_thread_methods_default_to_auto_review() -> None:
AsyncCodex.thread_start,
]
assert {fn: _keyword_default(fn, "approval_mode") for fn in funcs} == {
fn: ApprovalMode.auto_review for fn in funcs
}
assert {fn: _keyword_default(fn, "approval_mode") for fn in funcs} == dict.fromkeys(
funcs, ApprovalMode.auto_review
)
def test_existing_thread_methods_default_to_preserving_approval_settings() -> None:
@@ -408,9 +407,7 @@ def test_existing_thread_methods_default_to_preserving_approval_settings() -> No
AsyncThread.run,
]
assert {fn: _keyword_default(fn, "approval_mode") for fn in funcs} == {
fn: None for fn in funcs
}
assert {fn: _keyword_default(fn, "approval_mode") for fn in funcs} == dict.fromkeys(funcs)
def test_lifecycle_methods_are_codex_scoped() -> None:
@@ -462,6 +459,4 @@ def test_initialize_metadata_requires_non_empty_information() -> None:
except RuntimeError as exc:
assert "missing required metadata" in str(exc)
else:
raise AssertionError(
"expected RuntimeError when initialize metadata is missing"
)
raise AssertionError("expected RuntimeError when initialize metadata is missing")

4
sdk/python/tests/test_real_app_server_integration.py
View File

@@ -539,7 +539,9 @@ def test_real_examples_run_and_assert(
assert "actions:" in out
assert "Items:" in out
elif folder == "13_model_select_and_turn_params":
assert "selected.model:" in out and "agent.message.params:" in out and "items.params:" in out
assert (
"selected.model:" in out and "agent.message.params:" in out and "items.params:" in out
)
elif folder == "14_turn_controls":
assert "steer.result:" in out and "steer.final.status:" in out
assert "interrupt.result:" in out and "interrupt.final.status:" in out