Implementation:Openai Openai python HTTP Base Client

Knowledge Sources	Openai_Openai_python
Domains	SDK_Infrastructure, Python
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for core HTTP client infrastructure and pagination provided by the openai-python SDK.

Description

The _base_client.py module (2159 lines) implements the foundational HTTP client classes that power all API interactions. It provides:

PageInfo (line 120): Stores information needed to fetch the next page of results. Accepts one of url, params, or json to indicate how to request the subsequent page.

BasePage[_T] (line 171): A generic Pydantic model that defines the core pagination interface. Provides has_next_page() to check availability and next_page_info() to retrieve the PageInfo for the next request. Contains helper _info_to_options() to transform page info into request options.

BaseSyncPage[_T] (line 232) and BaseAsyncPage[_T] (line 320): Synchronous and asynchronous page implementations with __iter__ / __aiter__ support for iterating through all items across all pages, and iter_pages() / get_next_page() for page-level traversal.

BaseClient (line 365): Generic base class parameterized by [_HttpxClientT, _DefaultStreamT]. Handles URL preparation, header building (including retry count and timeout headers), request construction (JSON, multipart/form-data, file uploads), retry logic with exponential backoff and jitter, and response processing with type-safe casting.

SyncAPIClient (line 843): Synchronous client subclass wrapping httpx.Client. Implements _request() with synchronous retry logic, _retry_request() with sleep-based delay, and context manager support (__enter__/__exit__).

AsyncAPIClient (line 1440): Asynchronous client subclass wrapping httpx.AsyncClient. Mirrors SyncAPIClient with await-based operations and anyio.sleep for retry delays. Supports async context manager (__aenter__/__aexit__).

The module also defines AsyncPaginator (line 281) which is an awaitable helper that sets up pagination state and delegates to the async client. Default httpx client wrappers (DefaultHttpxClient, DefaultAsyncHttpxClient, DefaultAioHttpClient) are also exported.

Usage

These classes are internal infrastructure. End users interact with OpenAI and AsyncOpenAI (defined in _client.py) which inherit from SyncAPIClient and AsyncAPIClient respectively. Direct usage of base client classes is for SDK extension or custom client development.

Code Reference

Source Location

Repository: openai-python
File: src/openai/_base_client.py
Lines: 1-2159

Signature

class PageInfo:
    url: URL | NotGiven
    params: Query | NotGiven
    json: Body | NotGiven

    def __init__(
        self,
        *,
        url: URL | NotGiven = not_given,
        json: Body | NotGiven = not_given,
        params: Query | NotGiven = not_given,
    ) -> None: ...

class BasePage(GenericModel, Generic[_T]):
    def has_next_page(self) -> bool: ...
    def next_page_info(self) -> Optional[PageInfo]: ...

class BaseClient(Generic[_HttpxClientT, _DefaultStreamT]):
    def __init__(
        self,
        *,
        version: str,
        base_url: str | URL,
        _strict_response_validation: bool,
        max_retries: int = DEFAULT_MAX_RETRIES,
        timeout: float | Timeout | None = DEFAULT_TIMEOUT,
        custom_headers: Mapping[str, str] | None = None,
        custom_query: Mapping[str, object] | None = None,
    ) -> None: ...

class SyncAPIClient(BaseClient[httpx.Client, Stream[Any]]):
    def __init__(
        self,
        *,
        version: str,
        base_url: str | URL,
        max_retries: int = DEFAULT_MAX_RETRIES,
        timeout: float | Timeout | None | NotGiven = not_given,
        http_client: httpx.Client | None = None,
        custom_headers: Mapping[str, str] | None = None,
        custom_query: Mapping[str, object] | None = None,
        _strict_response_validation: bool,
    ) -> None: ...

class AsyncAPIClient(BaseClient[httpx.AsyncClient, AsyncStream[Any]]):
    def __init__(
        self,
        *,
        version: str,
        base_url: str | URL,
        _strict_response_validation: bool,
        max_retries: int = DEFAULT_MAX_RETRIES,
        timeout: float | Timeout | None | NotGiven = not_given,
        http_client: httpx.AsyncClient | None = None,
        custom_headers: Mapping[str, str] | None = None,
        custom_query: Mapping[str, object] | None = None,
    ) -> None: ...

Import

from openai._base_client import SyncAPIClient, AsyncAPIClient
from openai._base_client import DefaultHttpxClient, DefaultAsyncHttpxClient

I/O Contract

Inputs

Name	Type	Required	Description
version	str	Yes	SDK version string
base_url	str or URL	Yes	API base URL
_strict_response_validation	bool	Yes	If True, raise on non-JSON Content-Type
max_retries	int	No	Max retry attempts; defaults to `DEFAULT_MAX_RETRIES` (2)
timeout	float or Timeout or None	No	Request timeout; defaults to `DEFAULT_TIMEOUT` (600s)
http_client	httpx.Client or httpx.AsyncClient or None	No	Custom httpx client instance
custom_headers	Mapping[str, str] or None	No	Extra headers merged into every request
custom_query	Mapping[str, object] or None	No	Extra query params merged into every request

Outputs

Name	Type	Description
response	APIResponse[R] or AsyncAPIResponse[R]	Typed response wrapper from `_request()` calls
page	BaseSyncPage[_T] or BaseAsyncPage[_T]	Paginated result from `_request_api_list()`

Usage Examples

Pagination Iteration

from openai import OpenAI

client = OpenAI()

# Automatic iteration across all pages
for model in client.models.list():
    print(model.id)

Custom httpx Client

import httpx
from openai import OpenAI, DefaultHttpxClient

client = OpenAI(
    http_client=DefaultHttpxClient(
        proxies="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment