refactor: migrate api_call from requests to httpx and add async support

- replace requests with httpx in api_call class
- add async_api_call class with httpx.asyncclient support
- migrate tests from requests_mock to respx

Author: tharropoulos

src/typesense/api_call.py

@@ -34,8 +34,12 @@
 
 import sys
 
-import requests
+import httpx
 
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
 from typesense.configuration import Configuration, Node
 from typesense.exceptions import (
     HTTPStatus0Error,
@@ -44,36 +48,138 @@
     TypesenseClientError,
 )
 from typesense.node_manager import NodeManager
-from typesense.request_handler import RequestHandler, SessionFunctionKwargs
+from typesense.request_handler import (
+    RequestHandler,
+)
+
+TEntityDict = typing.TypeVar("TEntityDict")
+TParams = typing.TypeVar("TParams", bound=typing.Dict[str, typing.Any])
+TBody = typing.TypeVar(
+    "TBody", bound=typing.Union[str, bytes, typing.Mapping[str, typing.Any]]
+)
+
+
+class SessionFunctionKwargs(typing.Generic[TParams, TBody], typing.TypedDict):
+    """
+    Type definition for keyword arguments used in request functions.
+
+    This is an internal abstraction that gets converted to httpx's request parameters.
+    The `data` field is converted to `content` when passed to httpx.
+
+    Note: `verify` and `timeout` are set on the httpx client, not in request kwargs.
+    However, we include them here for compatibility with the existing API.
+
+    Attributes:
+        params (Optional[Union[TParams, None]]): Query parameters for the request.
+            Passed as `params` to httpx.
+
+        data (Optional[Union[TBody, str, None]]): Body of the request.
+            Converted to `content` (JSON string) when passed to httpx.
+
+        headers (Optional[Dict[str, str]]): Headers for the request.
+            Passed as `headers` to httpx.
+
+        timeout (float): Timeout for the request in seconds.
+            Set on the httpx client, not in request kwargs.
+
+        verify (bool): Whether to verify SSL certificates.
+            Set on the httpx client, not in request kwargs.
+    """
+
+    params: typing.NotRequired[typing.Union[TParams, None]]
+    data: typing.NotRequired[
+        typing.Union[TBody, str, typing.Dict[str, typing.Any], None]
+    ]
+    content: typing.NotRequired[typing.Union[TBody, str, None]]
+    headers: typing.NotRequired[typing.Dict[str, str]]
+    timeout: typing.NotRequired[float]
+
 
 if sys.version_info >= (3, 11):
     import typing
 else:
     import typing_extensions as typing
 
-session = requests.sessions.Session()
-TParams = typing.TypeVar("TParams")
-TBody = typing.TypeVar("TBody")
-TEntityDict = typing.TypeVar("TEntityDict")
+
+class ApiCallProtocol(typing.Protocol):
+    """
+    Protocol defining the interface for API call classes.
+
+    This protocol ensures that both sync (ApiCall) and async (AsyncApiCall)
+    implementations provide the same interface, allowing resource classes
+    to work with either implementation.
+    """
+
+    config: Configuration
+    node_manager: NodeManager
+    request_handler: RequestHandler
+
+    def get(
+        self,
+        endpoint: str,
+        entity_type: typing.Type[TEntityDict],
+        as_json: typing.Union[typing.Literal[True], typing.Literal[False]] = True,
+        params: typing.Union[TParams, None] = None,
+    ) -> typing.Union[TEntityDict, str]:
+        """Execute a GET request to the Typesense API."""
+        ...
+
+    def post(
+        self,
+        endpoint: str,
+        entity_type: typing.Type[TEntityDict],
+        as_json: typing.Union[typing.Literal[True], typing.Literal[False]] = True,
+        params: typing.Union[TParams, None] = None,
+        body: typing.Union[TBody, None] = None,
+    ) -> typing.Union[str, TEntityDict]:
+        """Execute a POST request to the Typesense API."""
+        ...
+
+    def put(
+        self,
+        endpoint: str,
+        entity_type: typing.Type[TEntityDict],
+        body: TBody,
+        params: typing.Union[TParams, None] = None,
+    ) -> TEntityDict:
+        """Execute a PUT request to the Typesense API."""
+        ...
+
+    def patch(
+        self,
+        endpoint: str,
+        entity_type: typing.Type[TEntityDict],
+        body: TBody,
+        params: typing.Union[TParams, None] = None,
+    ) -> TEntityDict:
+        """Execute a PATCH request to the Typesense API."""
+        ...
+
+    def delete(
+        self,
+        endpoint: str,
+        entity_type: typing.Type[TEntityDict],
+        params: typing.Union[TParams, None] = None,
+    ) -> TEntityDict:
+        """Execute a DELETE request to the Typesense API."""
+        ...
 
 
 _SERVER_ERRORS: typing.Final[
     typing.Tuple[
-        typing.Type[requests.exceptions.Timeout],
-        typing.Type[requests.exceptions.ConnectionError],
-        typing.Type[requests.exceptions.HTTPError],
-        typing.Type[requests.exceptions.RequestException],
-        typing.Type[requests.exceptions.SSLError],
+        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],
     ]
 ] = (
-    requests.exceptions.Timeout,
-    requests.exceptions.ConnectionError,
-    requests.exceptions.HTTPError,
-    requests.exceptions.RequestException,
-    requests.exceptions.SSLError,
+    httpx.TimeoutException,
+    httpx.ConnectError,
+    httpx.HTTPError,
+    httpx.RequestError,
     HTTPStatus0Error,
     ServerError,
     ServiceUnavailable,
@@ -103,6 +209,10 @@ def __init__(self, config: Configuration):
         self.config = config
         self.node_manager = NodeManager(config)
         self.request_handler = RequestHandler(config)
+        self._client = httpx.Client(
+            timeout=config.connection_timeout_seconds,
+            verify=config.verify,
+        )
 
     @typing.overload
     def get(
@@ -166,7 +276,7 @@ def get(
             Union[TEntityDict, str]: The response, either as a JSON object or a string.
         """
         return self._execute_request(
-            session.get,
+            "GET",
             endpoint,
             entity_type,
             as_json,
@@ -238,7 +348,7 @@ def post(
             Union[TEntityDict, str]: The response, either as a JSON object or a string.
         """
         return self._execute_request(
-            session.post,
+            "POST",
             endpoint,
             entity_type,
             as_json,
@@ -265,7 +375,7 @@ def put(
             EntityDict: The response, as a JSON object.
         """
         return self._execute_request(
-            session.put,
+            "PUT",
             endpoint,
             entity_type,
             as_json=True,
@@ -292,7 +402,7 @@ def patch(
             EntityDict: The response, as a JSON object.
         """
         return self._execute_request(
-            session.patch,
+            "PATCH",
             endpoint,
             entity_type,
             as_json=True,
@@ -318,7 +428,7 @@ def delete(
             EntityDict: The response, as a JSON object.
         """
         return self._execute_request(
-            session.delete,
+            "DELETE",
             endpoint,
             entity_type,
             as_json=True,
@@ -328,13 +438,13 @@ def delete(
     @typing.overload
     def _execute_request(
         self,
-        fn: typing.Callable[..., requests.models.Response],
+        method: str,
         endpoint: str,
         entity_type: typing.Type[TEntityDict],
         as_json: typing.Literal[True],
         last_exception: typing.Union[None, Exception] = None,
         num_retries: int = 0,
-        **kwargs: SessionFunctionKwargs[TParams, TBody],
+        **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]],
     ) -> TEntityDict:
         """
         Execute a request to the Typesense API with retry logic.
@@ -367,13 +477,13 @@ def _execute_request(
     @typing.overload
     def _execute_request(
         self,
-        fn: typing.Callable[..., requests.models.Response],
+        method: str,
         endpoint: str,
         entity_type: typing.Type[TEntityDict],
         as_json: typing.Literal[False],
         last_exception: typing.Union[None, Exception] = None,
         num_retries: int = 0,
-        **kwargs: SessionFunctionKwargs[TParams, TBody],
+        **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]],
     ) -> str:
         """
         Execute a request to the Typesense API with retry logic.
@@ -405,13 +515,13 @@ def _execute_request(
 
     def _execute_request(
         self,
-        fn: typing.Callable[..., requests.models.Response],
+        method: str,
         endpoint: str,
         entity_type: typing.Type[TEntityDict],
         as_json: typing.Union[typing.Literal[True], typing.Literal[False]] = True,
         last_exception: typing.Union[None, Exception] = None,
         num_retries: int = 0,
-        **kwargs: SessionFunctionKwargs[TParams, TBody],
+        **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]],
     ) -> typing.Union[TEntityDict, str]:
         """
         Execute a request to the Typesense API with retry logic.
@@ -420,7 +530,7 @@ def _execute_request(
         node selection, error handling, and retries.
 
         Args:
-            fn (Callable): The HTTP method function to use (e.g., session.get).
+            method (str): The HTTP method to use (e.g., "GET", "POST").
 
             endpoint (str): The API endpoint to call.
 
@@ -449,7 +559,7 @@ def _execute_request(
 
         try:
             return self._make_request_and_process_response(
-                fn,
+                method,
                 url,
                 entity_type,
                 as_json,
@@ -458,7 +568,7 @@ def _execute_request(
         except _SERVER_ERRORS as server_error:
             self.node_manager.set_node_health(node, is_healthy=False)
             return self._execute_request(
-                fn,
+                method,
                 endpoint,
                 entity_type,
                 as_json,
@@ -469,18 +579,19 @@ def _execute_request(
 
     def _make_request_and_process_response(
         self,
-        fn: typing.Callable[..., requests.models.Response],
+        method: str,
         url: str,
         entity_type: typing.Type[TEntityDict],
         as_json: bool,
-        **kwargs: SessionFunctionKwargs[TParams, TBody],
+        **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]],
     ) -> typing.Union[TEntityDict, str]:
         """Make the API request and process the response."""
         request_response = self.request_handler.make_request(
-            fn=fn,
+            method=method,
             url=url,
             as_json=as_json,
             entity_type=entity_type,
+            client=self._client,
             **kwargs,
         )
         self.node_manager.set_node_health(self.node_manager.get_node(), is_healthy=True)
@@ -493,12 +604,23 @@ def _make_request_and_process_response(
     def _prepare_request_params(
         self,
         endpoint: str,
-        **kwargs: SessionFunctionKwargs[TParams, TBody],
+        **kwargs: typing.Unpack[SessionFunctionKwargs[TParams, TBody]],
     ) -> typing.Tuple[Node, str, SessionFunctionKwargs[TParams, TBody]]:
+        """
+        Prepare request parameters including node selection and URL construction.
+
+        Args:
+            endpoint: The API endpoint path.
+            **kwargs: Request parameters following SessionFunctionKwargs structure.
+
+        Returns:
+            Tuple of (node, full_url, kwargs_dict) where kwargs_dict contains
+            the request parameters as a regular dict for further processing.
+        """
         node = self.node_manager.get_node()
         url = node.url() + endpoint
 
-        if kwargs.get("params"):
-            self.request_handler.normalize_params(kwargs["params"])
+        if params := kwargs.get("params"):
+            self.request_handler.normalize_params(params)
 
         return node, url, kwargs