React

The official OpenAI Python SDK that provides a typed, async-capable HTTP client for interacting with all OpenAI API services including chat completions, audio transcription/speech, image generation, file uploads, assistants, realtime WebSocket APIs, and video generation with Sora. It supports both OpenAI and Azure OpenAI endpoints with comprehensive streaming, retry logic, and Pydantic-based request/response validation.

Tech Stack

React

Key Features

Sync/Async HTTP Client
Chat Completions with Streaming
Realtime WebSocket API
Audio Processing
Azure OpenAI Support
Structured Output Parsing
Assistants & Threads API
CLI Tool

Entry Points

Start here when working with this codebase

Package Initialization

src/openai/__init__.py

Public API exposure, module-level client management, exports all public classes and functions

Start here when adding new public exports, understanding what's exposed to users, or modifying package-level configuration

Main Client Implementation

src/openai/_client.py

Main OpenAI and AsyncOpenAI client classes with resource accessors and configuration

Start here when adding new API resource accessors, modifying client initialization, or changing authentication handling

Base Client Infrastructure

src/openai/_base_client.py

Core HTTP client base class with request execution, retries, response processing, and error handling

Start here when modifying HTTP behavior, retry logic, streaming infrastructure, or error handling patterns

CLI Entry Point

src/openai/__main__.py

Execute CLI when package is invoked as module (python -m openai)

Start here when understanding CLI invocation or adding module-level CLI behavior

Test Configuration

tests/conftest.py

Centralized pytest fixtures and test configuration

Start here when adding new test fixtures, understanding test setup, or modifying test infrastructure

How to Make Changes

Common modification patterns for this codebase

Add a new API resource endpoint

src/openai/types/

Create type definitions for request params and response models. Create a new file like src/openai/types/your_resource.py

Pattern: Follow src/openai/types/completion.py for response types and src/openai/types/completion_create_params.py for request params using TypedDict

src/openai/types/__init__.py

Export your new types from the types module

Pattern: Follow existing exports pattern: from .your_resource import YourResourceResponse

src/openai/resources/

Create resource class file like src/openai/resources/your_resource.py with sync and async classes

Pattern: Follow src/openai/resources/completions.py - create YourResource(SyncAPIResource) and AsyncYourResource(AsyncAPIResource) classes with create/list/retrieve methods

src/openai/resources/__init__.py

Export your resource classes and add to __all__

Pattern: Follow existing pattern: from .your_resource import YourResource, AsyncYourResource

src/openai/_client.py

Add resource accessor property to OpenAI and AsyncOpenAI classes

Pattern: Follow existing pattern like @cached_property def completions(self) -> Completions: return Completions(self)

tests/api_resources/

Create test file tests/api_resources/test_your_resource.py

Pattern: Follow tests/api_resources/test_completions.py - use parametrize for sync/async, mock responses with respx

Conventions to follow:

All resource classes must have both sync (SyncAPIResource) and async (AsyncAPIResource) variantsType definitions use TypedDict for params and Pydantic BaseModel for responsesResource methods use self._post(), self._get() etc from base classInclude with_raw_response and with_streaming_response variants for applicable methods

Add a new beta API resource

src/openai/types/beta/

Create type definitions in src/openai/types/beta/your_beta_resource.py

Pattern: Follow src/openai/types/beta/assistant.py for response models and src/openai/types/beta/assistant_create_params.py for request params

src/openai/types/beta/__init__.py

Export your beta types

Pattern: Follow existing exports in the file

src/openai/resources/beta/

Create resource class in src/openai/resources/beta/your_beta_resource.py

Pattern: Follow src/openai/resources/beta/assistants.py - include polling methods if needed using _poll_until_done pattern

src/openai/resources/beta/__init__.py

Export your beta resource classes

Pattern: Follow existing pattern in the file

src/openai/_client.py

Ensure beta accessor exists (it should), your resource will be accessed via client.beta.your_resource

Pattern: Beta resources are nested under the Beta resource class

Conventions to follow:

Beta resources live under src/openai/resources/beta/ and src/openai/types/beta/Beta resources may include polling helpers for async operations (see assistants.py)Beta APIs may change - document instability in docstrings

Add a new library helper utility

src/openai/lib/

Create helper module like src/openai/lib/your_helper.py

Pattern: Follow src/openai/lib/_parsing.py for tool parsing helpers or src/openai/lib/streaming/_assistants.py for streaming utilities

src/openai/lib/__init__.py

Export your helper if it should be public

Pattern: Follow existing exports - only export user-facing utilities

src/openai/__init__.py

If helper should be top-level accessible, add export here

Pattern: Follow how parse_chat_completion is exported

tests/lib/

Create test file tests/lib/test_your_helper.py

Pattern: Follow tests/lib/test_azure.py or tests/lib/test_parsing.py

Conventions to follow:

Internal helpers use underscore prefix (_parsing.py)Public helpers are exported from src/openai/lib/__init__.pyStreaming helpers go in src/openai/lib/streaming/ subdirectoryAzure-specific helpers go in src/openai/lib/_azure.py

Add a new CLI command

src/openai/cli/

Add command implementation in appropriate CLI module under src/openai/cli/

Pattern: Examine existing CLI structure in src/openai/cli/ directory

src/openai/cli/__init__.py

Pattern: Follow existing command registration patterns

tests/

Add CLI tests if applicable

Pattern: Test CLI commands by invoking them programmatically

Conventions to follow:

CLI commands should have clear help textUse argparse patterns consistent with existing commandsCLI is invoked via python -m openai or openai command

Add a new example

examples/

Create example file like examples/your_example.py

Pattern: Follow examples/demo.py for basic patterns or examples/realtime/realtime.py for async patterns

examples/your_example.py

Include proper imports, client initialization, and clear comments

Pattern: Follow examples/audio.py for multi-function examples or examples/picture.py for single-purpose examples

Conventions to follow:

Examples should be self-contained and runnableInclude comments explaining what the example demonstratesUse if __name__ == '__main__': pattern for runnable examplesRealtime/async examples go in examples/realtime/ subdirectory

Add internal utility functions

src/openai/_utils/

Add utility to appropriate module in src/openai/_utils/ or create new module

Pattern: Follow src/openai/_utils/_transform.py for data transformation utilities or src/openai/_utils/_streams.py for streaming utilities

src/openai/_utils/__init__.py

Export your utility if it needs to be used across modules

Pattern: Follow existing exports in the file

tests/

Add tests for your utility

Pattern: Follow tests/test_utils.py patterns

Conventions to follow:

Internal utilities use underscore prefix in module namesUtilities should be pure functions when possibleSync/async helpers go in src/openai/_utils/_sync.py

Add support for optional dependency

src/openai/_extras/

Create proxy module like src/openai/_extras/your_dep_proxy.py

Pattern: Follow src/openai/_extras/numpy_proxy.py or src/openai/_extras/pandas_proxy.py - use lazy import with helpful error message

src/openai/_extras/__init__.py

Export your proxy

Pattern: Follow existing exports pattern

Conventions to follow:

Optional dependencies must fail gracefully with clear install instructionsUse lazy imports to avoid import-time failuresProxy modules provide the same interface as the real dependency

Modify HTTP client behavior

src/openai/_base_client.py

Modify base client methods for request/response handling

Pattern: Study existing methods like _request(), _retry_request(), _process_response()

src/openai/_client.py

If changes affect client initialization or configuration, modify here

Pattern: Follow existing __init__ patterns for OpenAI and AsyncOpenAI classes

tests/test_client.py

Add tests for your HTTP behavior changes

Pattern: Follow existing tests in tests/test_client.py - use respx for mocking HTTP

Conventions to follow:

Base client handles all HTTP concerns (retries, timeouts, streaming)Use httpx for HTTP operationsMaintain both sync and async code pathsError handling uses custom exception classes from src/openai/_exceptions.py

Coding Conventions

Standards and patterns used in this codebase

naming

File naming uses: kebab-case

azure_ad.py, responses_input_tokens.py, detect-breaking-changes.py, conftest.py, test_client.py

examples/azure_ad.pyexamples/responses_input_tokens.pyscripts/detect-breaking-changes.py

utilities

Shared utilities are in utils/ directory

Utility files: scripts/utils/ruffen-docs.py, src/openai/helpers/local_audio_player.py

scripts/utils/ruffen-docs.pysrc/openai/helpers/local_audio_player.pysrc/openai/lib/__init__.py

file-organization

Standard project structure

Code is organized by feature/module

examples/azure_ad.pyexamples/responses_input_tokens.pyscripts/detect-breaking-changes.py