feat: accept a user-supplied httpx or httpx2 client (#146)

Author: tharropoulos

README.md

@@ -42,6 +42,33 @@ if __name__ == "__main__":
 
 See `examples/async_collection_operations.py` for a fuller async walkthrough.
 
+## Using httpx2
+
+The client sends requests with [httpx](https://www.python-httpx.org/) by default. On Python 3.10+ you can pass an [httpx2](https://github.com/pydantic/httpx2) client instead. httpx2 is Pydantic's maintained continuation of httpx, and it fixes a connection pool leak in httpcore ([encode/httpcore#1093](https://github.com/encode/httpcore/issues/1093)) that can leave an `AsyncClient` failing every request with `PoolTimeout` under load.
+
+```
+$ pip install "typesense[httpx2]"
+```
+
+```python
+import httpx2
+import typesense
+
+http_client = httpx2.AsyncClient(
+    timeout=httpx2.Timeout(2.0),
+    limits=httpx2.Limits(max_connections=100, max_keepalive_connections=20),
+)
+client = typesense.AsyncClient(
+    {
+        "api_key": "abcd",
+        "nodes": [{"host": "localhost", "port": "8108", "protocol": "http"}],
+    },
+    http_client=http_client,
+)
+```
+
+`typesense.Client` takes an `httpx2.Client` the same way. The connection pool settings in the config (`pool_timeout_seconds`, `max_connections`, `max_keepalive_connections`) only apply to the default client, so set them on your own client instead. The Typesense client does not close a client you pass in.
+
 ## Compatibility
 
 | Typesense Server | typesense-python |

pyproject.toml

@@ -27,6 +27,10 @@ dependencies = [
 ]
 dynamic = ["version"]
 
+[project.optional-dependencies]
+# Maintained continuation of httpx; fixes the httpcore pool leak in encode/httpcore#1093.
+httpx2 = ["httpx2>=2.6.0; python_version >= '3.10'"]
+
 [project.urls]
 Documentation = "https://typesense.org/"
 Source = "https://github.com/typesense/typesense-python"

src/typesense/async_/api_call.py

@@ -51,6 +51,7 @@
     ServiceUnavailable,
     TypesenseClientError,
 )
+from typesense.http_backend import ASYNC_CLIENT_TYPES, AsyncClientType, backend_errors
 from typesense.node_manager import NodeManager
 from typesense.request_handler import RequestHandler
 
@@ -116,38 +117,23 @@ class SessionFunctionKwargs(typing.Generic[TParams, TBody], typing.TypedDict):
     },
 )
 
-_SERVER_ERRORS: typing.Final[
-    typing.Tuple[
-        typing.Type[httpx.TimeoutException],
-        typing.Type[httpx.ConnectError],
-        typing.Type[httpx.HTTPError],
-        typing.Type[httpx.RequestError],
-        typing.Type[HTTPStatus0Error],
-        typing.Type[ServerError],
-        typing.Type[ServiceUnavailable],
-    ]
-] = (
-    httpx.TimeoutException,
-    httpx.ConnectError,
-    httpx.HTTPError,
-    httpx.RequestError,
+_SERVER_ERRORS: typing.Final[typing.Tuple[typing.Type[Exception], ...]] = (
+    *backend_errors("TimeoutException"),
+    *backend_errors("ConnectError"),
+    *backend_errors("HTTPError"),
+    *backend_errors("RequestError"),
     HTTPStatus0Error,
     ServerError,
     ServiceUnavailable,
 )
 
-_CLIENT_ERRORS: typing.Final[
-    typing.Tuple[
-        typing.Type[httpx.PoolTimeout],
-        typing.Type[httpx.LocalProtocolError],
-        typing.Type[httpx.DecodingError],
-        typing.Type[httpx.TooManyRedirects],
-    ]
-] = (
-    httpx.PoolTimeout,
-    httpx.LocalProtocolError,
-    httpx.DecodingError,
-    httpx.TooManyRedirects,
+# Raised by httpx inside the client, so they say nothing about the node's
+# health. They subclass entries of _SERVER_ERRORS and must be caught first.
+_CLIENT_ERRORS: typing.Final[typing.Tuple[typing.Type[Exception], ...]] = (
+    *backend_errors("PoolTimeout"),
+    *backend_errors("LocalProtocolError"),
+    *backend_errors("DecodingError"),
+    *backend_errors("TooManyRedirects"),
 )
 
 
@@ -161,19 +147,42 @@ class AsyncApiCall:
     Attributes:
         config (Configuration): The configuration object for the Typesense client.
         node_manager (NodeManager): Manages the nodes in the Typesense cluster.
-        _client (httpx.AsyncClient): The httpx async client for making requests.
+        _client (httpx.AsyncClient | httpx2.AsyncClient): The async client for
+            making requests.
     """
 
-    def __init__(self, config: Configuration):
+    def __init__(
+        self,
+        config: Configuration,
+        http_client: typing.Optional[AsyncClientType] = None,
+    ):
         """
         Initialize the AsyncApiCall instance.
 
         Args:
             config (Configuration): The configuration object for the Typesense client.
+            http_client (httpx.AsyncClient | httpx2.AsyncClient, optional): A client
+                to send requests with instead of the default httpx client. The
+                connection pool settings in ``config`` are not applied to it, and it
+                is not closed by ``aclose``.
+
+        Raises:
+            TypeError: If ``http_client`` is not an httpx or httpx2 async client.
         """
         self.config = config
         self.node_manager = NodeManager(config)
         self.request_handler = RequestHandler(config)
+        self._concurrency_limit = AsyncConcurrencyLimit(
+            config.max_concurrent_requests,
+        )
+        self._owns_client = http_client is None
+        if http_client is not None:
+            if not isinstance(http_client, ASYNC_CLIENT_TYPES):
+                raise TypeError(
+                    "`http_client` must be an httpx.AsyncClient or httpx2.AsyncClient.",
+                )
+            self._client: AsyncClientType = http_client
+            return
         self._client = httpx.AsyncClient(
             timeout=httpx.Timeout(
                 config.connection_timeout_seconds,
@@ -184,9 +193,6 @@ def __init__(self, config: Configuration):
                 max_keepalive_connections=config.max_keepalive_connections,
             ),
         )
-        self._concurrency_limit = AsyncConcurrencyLimit(
-            config.max_concurrent_requests,
-        )
 
     async def __aenter__(self) -> "AsyncApiCall":
         """Async context manager entry."""
@@ -199,11 +205,12 @@ async def __aexit__(
         exc_tb: typing.Optional[TracebackType],
     ) -> None:
         """Async context manager exit."""
-        await self._client.aclose()
+        await self.aclose()
 
     async def aclose(self) -> None:
-        """Close the httpx client."""
-        await self._client.aclose()
+        """Close the httpx client, unless it was passed in by the caller."""
+        if self._owns_client:
+            await self._client.aclose()
 
     @typing.overload
     async def get(

src/typesense/async_/client.py

@@ -55,6 +55,7 @@
 from .stopwords import AsyncStopwords
 from .synonym_sets import AsyncSynonymSets
 from typesense.configuration import ConfigDict, Configuration
+from typesense.http_backend import AsyncClientType
 
 TDoc = typing.TypeVar("TDoc", bound=DocumentSchema)
 
@@ -86,14 +87,24 @@ class AsyncClient:
         conversations_models (ConversationsModels): Instance for managing conversation models.
     """
 
-    def __init__(self, config_dict: ConfigDict) -> None:
+    def __init__(
+        self,
+        config_dict: ConfigDict,
+        http_client: typing.Optional[AsyncClientType] = None,
+    ) -> None:
         """
         Initialize the Client instance.
 
         Args:
             config_dict (ConfigDict):
                 A dictionary containing the configuration for the Typesense client.
 
+            http_client (httpx.AsyncClient | httpx2.AsyncClient, optional):
+                A client to send requests with instead of the default httpx client,
+                e.g. an ``httpx2.AsyncClient`` (``pip install typesense[httpx2]``).
+                The connection pool settings in ``config_dict`` are not applied to
+                it, and the Typesense client does not close it.
+
         Example:
             >>> config = {
             ...     "api_key": "your_api_key",
@@ -105,7 +116,7 @@ def __init__(self, config_dict: ConfigDict) -> None:
             >>> client = Client(config)
         """
         self.config = Configuration(config_dict)
-        self.api_call = AsyncApiCall(self.config)
+        self.api_call = AsyncApiCall(self.config, http_client)
         self.collections: AsyncCollections[DocumentSchema] = AsyncCollections(
             self.api_call
         )

src/typesense/http_backend.py

@@ -0,0 +1,77 @@
+"""
+HTTP backends the Typesense client can send requests with.
+
+The client builds an ``httpx`` client by default. Users can pass their own client
+instead, either from ``httpx`` or from ``httpx2`` (install ``typesense[httpx2]``,
+Python 3.10+). ``httpx2`` is Pydantic's maintained continuation of ``httpx``. It
+fixes a connection pool leak in ``httpcore`` (encode/httpcore#1093) that can leave
+an async client failing every request with ``PoolTimeout``.
+
+``httpx2`` has the same API as ``httpx`` but its own classes, so every
+``isinstance`` check and ``except`` clause has to cover both packages. This module
+builds those type tuples once, including ``httpx2`` only when it is installed.
+"""
+
+import importlib
+import sys
+from types import ModuleType
+
+import httpx
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+if typing.TYPE_CHECKING:
+    import httpx2  # noqa: F401 (used in the string annotations in this module)
+
+
+def _import_httpx2() -> typing.Optional[ModuleType]:
+    """Return the ``httpx2`` module, or ``None`` when it is not installed."""
+    # ``import_module`` is typed as returning a module whether or not httpx2 is
+    # installed; a plain ``import`` is ``Any`` to mypy when it is missing (Python 3.9).
+    try:
+        return importlib.import_module("httpx2")
+    except ImportError:
+        return None
+
+
+_httpx2 = _import_httpx2()
+
+_BACKENDS: typing.Final[typing.Tuple[ModuleType, ...]] = tuple(
+    backend for backend in (httpx, _httpx2) if backend is not None
+)
+
+SyncClientType = typing.Union[httpx.Client, "httpx2.Client"]
+AsyncClientType = typing.Union[httpx.AsyncClient, "httpx2.AsyncClient"]
+ResponseType = typing.Union[httpx.Response, "httpx2.Response"]
+
+
+def backend_errors(name: str) -> typing.Tuple[typing.Type[Exception], ...]:
+    """
+    Return the exception class called ``name`` from every installed backend.
+
+    Args:
+        name (str): The exception name shared by ``httpx`` and ``httpx2``.
+
+    Returns:
+        Tuple[Type[Exception], ...]: The matching classes, for ``except`` clauses.
+    """
+    return tuple(getattr(backend, name) for backend in _BACKENDS)
+
+
+# Declared precisely for type checkers so ``isinstance`` narrows to the client
+# unions above; at runtime they only contain the backends that are installed.
+if typing.TYPE_CHECKING:
+    CLIENT_TYPES: typing.Tuple[
+        typing.Type[httpx.Client],
+        typing.Type["httpx2.Client"],
+    ]
+    ASYNC_CLIENT_TYPES: typing.Tuple[
+        typing.Type[httpx.AsyncClient],
+        typing.Type["httpx2.AsyncClient"],
+    ]
+else:
+    CLIENT_TYPES = tuple(backend.Client for backend in _BACKENDS)
+    ASYNC_CLIENT_TYPES = tuple(backend.AsyncClient for backend in _BACKENDS)