OpenAI: Migrating to HTTPX2

OpenAI's Python SDK has migrated to httpx2 for its HTTP client, a change detailed in a new migration guide. This technical shift is significant not just for its impact on TLS certificate handling and custom client configurations, but also due to the controversial backstory of the original httpx project. The httpx2 fork emerged to offer stability after the original httpx maintainer paused development and closed discussions due to concerns about community gender representation, adding an unexpected layer of drama to a routine SDK update.

Score

Comments

Highest Rank

17h

on Front Page

First Seen

Aug 28, 12:00 PM

Last Seen

Aug 29, 5:00 AM

Rank Over Time

The Lowdown

OpenAI has officially moved its Python SDK to use httpx2 for both synchronous and asynchronous HTTP clients, automatically installing it with the SDK. This migration guide outlines the necessary adjustments developers must make, emphasizing that while basic usage remains largely consistent, deeper integrations require attention.

The SDK now bundles httpx2, meaning developers who previously relied on the SDK for transitive httpx installation will need to add explicit httpx dependencies for their own projects.
A crucial change involves TLS certificate verification: httpx2 defaults to the operating system's trust store instead of certifi. This can break setups in minimal container images, corporate proxies, or custom certifi environments, necessitating explicit configuration.
Developers providing custom HTTP clients must transition to httpx2 objects and configuration patterns, though OpenAI provides helpers to maintain SDK defaults.
All httpx specific objects (e.g., httpx.Client, httpx.Timeout, httpx.URL) must be replaced with their httpx2 counterparts.
Authentication handlers, event hooks, and raw response handling will now interact with httpx2 request and response objects.
The aiohttp extra now utilizes an httpx2-native transport, streamlining asynchronous operations.
Testing and mocking setups will need to be updated to intercept httpx2 requests and return httpx2 responses.
A temporary 'escape hatch' exists for those needing to maintain legacy httpx compatibility, but it comes with caveats regarding type checking and is not a long-term solution.

The guide aims to provide a clear path for developers to adapt their existing applications to the new httpx2 foundation, highlighting potential breaking changes primarily around TLS and custom HTTP client integrations while ensuring a smoother transition for most default users.

The Gossip

The 'Why' Behind the Change (and the Drama)

Commenters quickly pointed out the larger context behind the switch to `httpx2`. The original `httpx` project's impending 1.0 release was expected to introduce significant breaking changes. Crucially, `httpx2` emerged as a fork specifically to maintain API stability, directly addressing community concerns. The discussion also surfaced a controversial decision by the original `httpx` maintainer to close GitHub discussions and issues due to "absurdly skewed gender representation," which prompted strong reactions and further explained the community's desire for an alternative like `httpx2`.

Upsides vs. Downsides Debated

While the document details *how* to migrate, some users questioned the *upsides* of the change, given the apparent complexities. The most immediate downside highlighted was the shift in TLS certificate handling to the operating system trust store, which was identified as a potential 'breaking change' for corporate environments or minimal container setups that relied on `certifi`.

Nerd Notes & Clarifications

Amidst the technical details, some minor clarifications were sought. One user asked about the meaning of 'nb' in a comment, which was politely clarified to mean 'nota bene' (note well) by the original poster.