feat(api)!: migrate to HTTPX2

[apcha-oai]

Makes HTTPX2 the default HTTP client for the next major Python SDK release. See the HTTPX Migration Guide for complete customer-facing migration instructions.

Customer migration

• Default clients: OpenAI() and AsyncOpenAI() use HTTPX2 automatically; API calls, parsed responses, streaming, retries, authentication, and numeric timeouts retain their existing interfaces.
• Dependencies: pip install openai installs HTTPX2 instead of HTTPX. Applications importing httpx through the SDK's former transitive dependency must migrate to httpx2 or install httpx explicitly.
• TLS trust store: HTTPX2 uses the operating-system trust store instead of certifi. This can break certificate verification even with the default client; configure the system trust store, SSL_CERT_FILE, SSL_CERT_DIR, or a custom ssl.SSLContext as needed.
• Custom HTTP integrations: Migrate custom clients, transports, timeout objects, authentication handlers, hooks, request mocks, and instrumentation to their HTTPX2 equivalents. Raw requests, responses, and transport exceptions are now HTTPX2 objects.
• aiohttp: openai[aiohttp] and DefaultAioHttpClient() remain supported through an HTTPX2-native transport without installing HTTPX or httpx-aiohttp.
• Legacy escape hatch: Explicitly installed httpx.Client, httpx.AsyncClient, and httpx-aiohttp clients remain supported when passed through http_client. This compatibility is runtime-only; legacy clients are not supported by static type checkers such as mypy or Pyright. Legacy HTTPX support is provided as a migration aid and may be discontinued.

See httpx2.md for examples and detailed migration cases.

Implementation notes

• Replace the SDK’s default clients and HTTP-facing types with HTTPX2.
• Test legacy HTTPX and aiohttp compatibility separately, including a real request through the legacy aiohttp adapter.

Vendored dependencies
We've vendored a few dependencies in so that we can avoid installing httpx by default for both normal dependencies and dev dependencies. This was the fastest path to unblock migration; we are happy to upstream
these changes if it makes sense for those package's dependencies.

• Fork RESPX under tests/respx2 so existing request-mocking tests work without HTTPX.
  • This is for convenience so we can mechanically rewrite tests.
• Vendor the upstream HTTPX2 aiohttp adapter, including its original license and attribution.
  • This is to avoid aiohttp bringing in httpx by default for now.

Issues

• Consider migrating from httpx to httpx2 #3375

[openai-sdks]

OkTest Summary

❌ Failed for Python SDK PR #3594.

View OkTest run #31490970344

_{SDK merge (e050eb39c4db) · head (2e4a69261f6c) · base (ea17fda01d70) · OkTest (91635c6a2723)}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2e4a69261f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Map generic aiohttp connection failures as connect errors

When DefaultAioHttpClient encounters a refused connection, DNS failure, or proxy connection failure, aiohttp raises a ClientConnectorError, which first matches its ClientConnectionError base here and is mapped to ConnectTimeout. The later ConnectError/ProxyError mappings cannot replace it because those exception classes are siblings of ConnectTimeout, while the selection logic only replaces a mapping with a subclass. Consequently, the SDK reports ordinary connection failures as APITimeoutError rather than APIConnectionError; map the broad base to ConnectError or prioritize the most specific source exception.

Useful? React with 👍 / 👎.

[jbeckwith-oai]

The SDK implementation and package validation look clean, but two first-party rollout gates are still broken on this exact head:

1. Detect Agents SDK regressions fails with 38 mypy errors in openai-agents-python. The HTTPX2 type migration changes AsyncClient, URL, request, response, and SDK exception surfaces out from under that consumer. Please coordinate/update the Agents SDK (or otherwise stage the major-version rollout) so this regression gate is green before merging.
2. The linked OkTest run cannot start the Python bridge. Its image still installs a hard-coded legacy httpx dependency set, then installs this wheel with --no-deps, so httpx2 is absent at runtime and the bridge never becomes healthy. Please update the OkTest Python harness/dependency installation for this new default and rerun it successfully.

I audited the complete 165-file diff, surrounding transport/provider/error/response paths, generated surfaces, vendored attribution, security-sensitive TLS/proxy/auth behavior, and file-size thresholds. Locally, lint/mypy/import checks, wheel build, Python-policy validation, Bedrock-wheel validation, HTTPX2-only/aiohttp/isolated legacy-wheel validation, and 486 focused transport/client/provider tests all pass. No file crossed the 1k-line threshold. Once the two integration gates above are green, I did not find another blocker.