feat(client): add support for passing in a httpx client

Author: stainless-bot

README.md

@@ -1,14 +1,14 @@
-# OpenAI Python API Library
+# OpenAI Python API library
 
 [![PyPI version](https://img.shields.io/pypi/v/openai.svg)](https://pypi.org/project/openai/)
 
 The OpenAI Python library provides convenient access to the OpenAI REST API from any Python 3.7+
-application. It includes type definitions for all request params and response fields,
+application. The library includes type definitions for all request params and response fields,
 and offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).
 
 ## Documentation
 
-The API documentation can be found [here](https://platform.openai.com/docs).
+The API documentation can be found at [https://platform.openai.com/docs](https://platform.openai.com/docs).
 
 ## Installation
 
@@ -43,7 +43,7 @@ print(completion.choices)
 While you can provide an `api_key` keyword argument, we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/)
 and adding `OPENAI_API_KEY="my api key"` to your `.env` file so that your API Key is not stored in source control.
 
-## Async Usage
+## Async usage
 
 Simply import `AsyncOpenAI` instead of `OpenAI` and use `await` with each API call:
 
@@ -148,11 +148,11 @@ We recommend that you always instantiate a client (e.g., with `client = OpenAI()
 - It's harder to mock for testing purposes
 - It's not possible to control cleanup of network connections
 
-## Using Types
+## Using types
 
-Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Responses are [Pydantic models](https://docs.pydantic.dev), which provide helper methods for things like serializing back into json ([v1](https://docs.pydantic.dev/1.10/usage/models/), [v2](https://docs.pydantic.dev/latest/usage/serialization/)). To get a dictionary, you can call `dict(model)`.
+Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Responses are [Pydantic models](https://docs.pydantic.dev), which provide helper methods for things like serializing back into JSON ([v1](https://docs.pydantic.dev/1.10/usage/models/), [v2](https://docs.pydantic.dev/latest/usage/serialization/)). To get a dictionary, call `dict(model)`.
 
-This helps provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `"basic"`.
+Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`.
 
 ## Pagination
 
@@ -273,10 +273,10 @@ await client.files.create(
 
 ## Handling errors
 
-When the library is unable to connect to the API (e.g., due to network connection problems or a timeout), a subclass of `openai.APIConnectionError` is raised.
+When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `openai.APIConnectionError` is raised.
 
-When the API returns a non-success status code (i.e., 4xx or 5xx
-response), a subclass of `openai.APIStatusError` will be raised, containing `status_code` and `response` properties.
+When the API returns a non-success status code (that is, 4xx or 5xx
+response), a subclass of `openai.APIStatusError` is raised, containing `status_code` and `response` properties.
 
 All errors inherit from `openai.APIError`.
 
@@ -316,11 +316,11 @@ Error codes are as followed:
 
 ### Retries
 
-Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
+Certain errors are automatically retried 2 times by default, with a short exponential backoff.
 Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
-429 Rate Limit, and >=500 Internal errors will all be retried by default.
+429 Rate Limit, and >=500 Internal errors are all retried by default.
 
-You can use the `max_retries` option to configure or disable this:
+You can use the `max_retries` option to configure or disable retry settings:
 
 ```python
 from openai import OpenAI
@@ -345,8 +345,8 @@ client.with_options(max_retries=5).chat.completions.create(
 
 ### Timeouts
 
-Requests time out after 10 minutes by default. You can configure this with a `timeout` option,
-which accepts a float or an [`httpx.Timeout`](https://www.python-httpx.org/advanced/#fine-tuning-the-configuration):
+By default requests time out after 10 minutes. You can configure this with a `timeout` option,
+which accepts a float or an [`httpx.Timeout`](https://www.python-httpx.org/advanced/#fine-tuning-the-configuration) object:
 
 ```python
 from openai import OpenAI
@@ -376,13 +376,13 @@ client.with_options(timeout=5 * 1000).chat.completions.create(
 
 On timeout, an `APITimeoutError` is thrown.
 
-Note that requests which time out will be [retried twice by default](#retries).
+Note that requests that time out are [retried twice by default](#retries).
 
 ## Advanced
 
 ### How to tell whether `None` means `null` or missing
 
-In an API response, a field may be explicitly null, or missing entirely; in either case, its value is `None` in this library. You can differentiate the two cases with `.model_fields_set`:
+In an API response, a field may be explicitly `null`, or missing entirely; in either case, its value is `None` in this library. You can differentiate the two cases with `.model_fields_set`:
 
 ```py
 if response.my_field is None:
@@ -392,27 +392,30 @@ if response.my_field is None:
     print('Got json like {"my_field": null}.')
 ```
 
-### Configuring custom URLs, proxies, and transports
+### Configuring the HTTP client
 
-You can configure the following keyword arguments when instantiating the client:
+You can directly override the [httpx client](https://www.python-httpx.org/api/#client) to customize it for your use case, including:
+
+- Support for proxies
+- Custom transports
+- Additional [advanced](https://www.python-httpx.org/advanced/#client-instances) functionality
 
 ```python
 import httpx
 from openai import OpenAI
 
 client = OpenAI(
-    # Use a custom base URL
     base_url="http://my.test.server.example.com:8083",
-    proxies="http://my.test.proxy.example.com",
-    transport=httpx.HTTPTransport(local_address="0.0.0.0"),
+    http_client=httpx.Client(
+        proxies="http://my.test.proxy.example.com",
+        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
+    ),
 )
 ```
 
-See the httpx documentation for information about the [`proxies`](https://www.python-httpx.org/advanced/#http-proxying) and [`transport`](https://www.python-httpx.org/advanced/#custom-transports) keyword arguments.
-
 ### Managing HTTP resources
 
-By default we will close the underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__) is called but you can also manually close the client using the `.close()` method if desired, or with a context manager that closes when exiting.
+By default the library closes underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__). You can manually close the client using the `.close()` method if desired, or with a context manager that closes when exiting.
 
 ## Versioning
 

src/openai/__init__.py

@@ -88,7 +88,7 @@
 
 import httpx as _httpx
 
-from ._base_client import DEFAULT_LIMITS, DEFAULT_TIMEOUT, DEFAULT_MAX_RETRIES
+from ._base_client import DEFAULT_TIMEOUT, DEFAULT_MAX_RETRIES
 
 api_key: str | None = _os.environ.get("OPENAI_API_KEY")
 
@@ -104,14 +104,7 @@
 
 default_query: _t.Mapping[str, object] | None = None
 
-# See httpx documentation for [custom transports](https://www.python-httpx.org/advanced/#custom-transports)
-transport: Transport | None = None
-
-# See httpx documentation for [proxies](https://www.python-httpx.org/advanced/#http-proxying)
-proxies: ProxiesTypes | None = None
-
-# See httpx documentation for [limits](https://www.python-httpx.org/advanced/#pool-limit-configuration)
-connection_pool_limits: _httpx.Limits = DEFAULT_LIMITS
+http_client: _httpx.Client | None = None
 
 
 class _ModuleClient(OpenAI):
@@ -141,15 +134,13 @@ def organization(self, value: str | None) -> None:  # type: ignore
     @property
     def base_url(self) -> _httpx.URL:
         if base_url is not None:
-            # mypy doesn't use the type from the setter
-            self._client.base_url = base_url  # type: ignore[assignment]
+            return _httpx.URL(base_url)
 
-        return self._client.base_url
+        return super().base_url
 
     @base_url.setter
     def base_url(self, url: _httpx.URL | str) -> None:
-        # mypy doesn't use the type from the setter
-        self._client.base_url = url  # type: ignore[assignment]
+        super().base_url = url  # type: ignore[misc]
 
     @property  # type: ignore
     def timeout(self) -> float | Timeout | None:
@@ -191,6 +182,16 @@ def _custom_query(self, value: _t.Mapping[str, object] | None) -> None:  # type:
 
         default_query = value
 
+    @property  # type: ignore
+    def _client(self) -> _httpx.Client:
+        return http_client or super()._client
+
+    @_client.setter  # type: ignore
+    def _client(self, value: _httpx.Client) -> None:  # type: ignore
+        global http_client
+
+        http_client = value
+
     def __del__(self) -> None:
         try:
             super().__del__()
@@ -204,14 +205,7 @@ def __del__(self) -> None:
 def _load_client() -> OpenAI:  # type: ignore[reportUnusedFunction]
     global _client
 
-    if (
-        _client is None
-        # if these options have been changed then we need to rebuild
-        # the underlying http client
-        or _client._transport != transport
-        or _client._proxies != proxies
-        or _client._limits != connection_pool_limits
-    ):
+    if _client is None:
         _client = _ModuleClient(
             api_key=api_key,
             organization=organization,
@@ -220,9 +214,7 @@ def _load_client() -> OpenAI:  # type: ignore[reportUnusedFunction]
             max_retries=max_retries,
             default_headers=default_headers,
             default_query=default_query,
-            transport=transport,
-            proxies=proxies,
-            connection_pool_limits=connection_pool_limits,
+            http_client=http_client,
         )
         return _client