Nearly every Python developer who has touched an AI product has typed the same two lines: import the openai package and instantiate a client. What few of them have considered is what those two lines actually invoke. The openai-python repository is Apache 2.0 licensed, targets Python 3.10 and up, and — this is the part that surprises people — most of it is not written by hand at all. The resource classes, the typed parameter objects, and the method signatures are generated from OpenAI’s OpenAPI specification by an internal generator called Castiron, with human-written code confined to the genuinely hard parts: the transport core, the response machinery, and the streaming layer. The result is the most widely used AI SDK on the planet, and its README is refreshingly current, showing the Responses API as the primary surface with a model string of gpt-5.5 in its examples.

That division of labor makes the repository a fascinating read for a second reason: it is a case study in how to hand-write only what matters. The generated surface guarantees that every API parameter is typed and documented the moment the REST API changes. The hand-written core then has to deliver retries that respect Retry-After headers, automatic idempotency keys, pydantic model hydration, server-sent event decoding, pagination, and alternate gateways for Azure and AWS Bedrock — all in sync and async flavors. Reading it is a masterclass in SDK design that applies to any API wrapper you will ever build. As always in this series, what follows is an educational tour of published source code.

OpenAI Python library overview: the exported clients sit on a transport core, expose generated resources like Responses and Chat Completions, hydrate responses through a runtime of models, streaming, and pagination, with Azure and Bedrock gateways beside them.

Reading the overview from left to right:

• the package init — generated exports of clients, exceptions, and helpers, annotated as written by Castiron.
• the client module — OpenAI and AsyncOpenAI with one property per API resource.
• the transport core — retries, idempotency, timeouts, and response processing for both sync and async.
• the Responses resource — the primary API surface, at 4,463 generated lines.
• the Chat Completions resource — the previous standard, supported indefinitely.
• the typed sentinels — NotGiven and omit markers that make every parameter explicitly optional.
• the model base — the pydantic-flavored BaseModel every response hydrates into.
• the Azure gateway — AzureOpenAI, sitting beside Bedrock and tool-runner helpers in the lib package.

Why You Need This

The first reason is practical literacy. If you call AI APIs from Python, this library is the interface you use daily, and knowing its internals changes how you debug it. Why does the client sometimes wait so long before failing? Because the transport core retries with exponential backoff, honoring the Retry-After header and a pair of maximum delay constants. Why is a POST safe to repeat after a network blip? Because the sync client automatically attaches an idempotency key to every non-GET request and reuses it across retries. Once you can point at the code responsible, production incidents become reading exercises instead of guesswork.

The second reason is design study. The repository solves, cleanly, the problems every SDK author faces. Typed optionality comes from the NotGiven sentinel, which distinguishes “parameter not provided” from “parameter explicitly None” — a distinction REST APIs care about and naive defaults destroy. Response handling is layered: an APIResponse object carries headers and request IDs, its parse() method hydrates pydantic models, and a legacy response class handles binary payloads like audio bytes that never touch JSON. Streaming is a thin decoder over server-sent events. Pagination is a pair of page objects that turn has-more cursors into plain iteration. Each mechanism is small, readable, and generalizable to your own API clients.

The third reason is that the hand-written edges of the tree show where the platform is heading. The lib package now contains a 2,626-line tool runner that executes agent tool calls against the Responses API until the model stops asking, computer-use and browser automation helpers, a Bedrock gateway for teams whose compliance departments live in AWS, and workload-identity authentication that swaps long-lived API keys for short-lived Kubernetes, Azure, and GCP tokens. Reading these files is effectively reading a changelog of where AI application infrastructure is going, months before it reaches the tutorials.

The detailed view: clients and transports on the left, the generated resource family in the middle, the response runtime below, and the gateways plus agent tooling on the right.

Start at the front door. _client.py (1,925 lines) defines OpenAI at line 127 and AsyncOpenAI at line 893. The constructor’s credential dance is worth reading: an explicit api_key argument wins, then the OPENAI_API_KEY environment variable is consulted at line 255, and if nothing is found you get the library’s famously clear error naming every option it tried, including OPENAI_ADMIN_KEY for administrative clients. From there the class is mostly composition: a property per resource — responses, chat, embeddings, images, videos, files, batches, moderations, and more — each constructed over the shared transport. The mirror classes beginning at line 1671, OpenAIWithRawResponse and its streamed sibling at line 2035, expose the same resources but return untouched HTTP responses for developers who want the wire truth. _client.py also hosts the modern credential path: a workload_identity parameter that accepts short-lived token providers from the auth package, whose _workload.py implements Kubernetes service-account, x509, and cloud identity providers.

The transport core is the best-engineered file in the tree. _base_client.py (2,011 lines) defines BaseClient at line 444, with SyncAPIClient at 964 and AsyncAPIClient at 1588 inheriting a complete request lifecycle. The retry logic lives in _should_retry at line 885 and _calculate_retry_timeout at line 861, bounded by MAX_RETRY_DELAY and MAX_RETRY_AFTER_DELAY constants, and it inspects both status codes and headers before deciding to try again. The idempotency machinery at line 1114 attaches a generated key to any non-GET request so retries reuse it. Around the request path sit the unglamorous essentials: a querystring encoder (_qs.py, 129 lines) that serializes nested parameters deterministically, a multipart helper (_files.py, 121 lines) that turns paths and tuples into upload payloads, and pydantic compatibility shims (_compat.py, 177 lines) that let one codebase span several pydantic versions. Errors surface through _exceptions.py (144 lines), a typed hierarchy from APIStatusError down to RateLimitError, AuthenticationError, and application-specific cases like ContentFilterFinishReasonError and InvalidWebhookSignatureError.

The response runtime is where JSON becomes Python. _models.py (826 lines) provides BaseModel, a pydantic-derived base with construct-mode parsing, cached properties, and helpers for attaching nested API objects without re-validation. _response.py (657 lines) wraps every call in APIResponse, carrying the request ID and headers, and its parse() materializes pydantic models — while _legacy_response.py (386 lines) keeps HttpxBinaryResponseContent for audio and image bytes. Streaming comes from _streaming.py (387 lines), where Stream and AsyncStream decode server-sent events into typed chunks, feeding _event_handler.py’s dispatcher for helper APIs that expose callbacks instead of loops. List endpoints get pagination.py (235 lines), cursor-aware page objects that integrate with page metadata defined alongside the transport. And underneath everything, the constants module fixes the defaults — timeout, retry count, connection limits — that most users never think to override.

The generated half deserves equal attention, because it teaches the other half of SDK economics. resources/responses/responses.py runs to 4,463 lines and chat completions to 2,895, all of it methodical, typed, and regenerable the moment the OpenAPI spec moves. The resource family now stretches past the classics: audio, containers, conversations, evals, fine-tuning, realtime, vector stores, webhooks, an admin namespace for organizations, and newer surfaces like skills, safety, and content provenance checks. lib/responses_tool_runner.py (2,626 lines) turns the Responses API into an agent loop, with a decisions-oriented sibling at 508 lines, computer.py (922 lines) and browser.py (1,683 lines) supplying desktop and web tool surfaces. AzureOpenAI in lib/azure.py (781 lines) subclasses the standard client to handle endpoint remapping and token flows, lib/bedrock.py (812 lines) routes through AWS credentials, and providers/bedrock.py plugs that capability into the transport. Even the examples directory reads like a roadmap: browser automation, computer desktop control, live voice, realtime websockets, and responses patterns.

From Install to a First Response

One install and six lines get you a response from the primary API:

# pip install openai
from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY from the environment

response = client.responses.create(
    model="gpt-5.5",
    input="Explain what a retry budget is in one sentence.",
)
print(response.output_text)

The README recommends keeping the key in a .env file loaded by python-dotenv rather than source control, and shows the same shape for Chat Completions for codebases that predate the Responses API. For automated infrastructure, pass a workload_identity instead of a key and let the short-lived token providers handle rotation. Streamed responses change the create call into create(stream=True), yielding typed event objects you can iterate; the streaming helpers add callback style for longer agent runs. A module-level client mirror and raw-response wrappers round out the ergonomics for teams with unusual integration needs.

Honest limits: roughly speaking there are two codebases in one directory, and knowing which half you are reading matters — the generated files are meant to be boring and should rarely be edited by hand, since the generator will overwrite them; the dependency surface has grown more opinionated with the move to the httpx2 transport, which occasionally surfaces as friction in environments that pin the older library; and the SDK’s rapid expansion — websockets, live sessions, webhooks, agent tooling — means its surface area now rewards a map before you start walking. None of that diminishes the achievement: this is both the front door to the most-used AI platform on Earth and a durable reference for how to build an API client that people never have to think about.

Enjoyed this post? Never miss out on future posts by following us