HTTP docs

Author: apetenchea

arangoasync/client.py

@@ -139,7 +139,9 @@ def version(self) -> str:
 
     async def close(self) -> None:
         """Close HTTP sessions."""
-        await asyncio.gather(*(session.close() for session in self._sessions))
+        await asyncio.gather(
+            *(self._http_client.close_session(session) for session in self._sessions)
+        )
 
     async def db(
         self,

arangoasync/http.py

@@ -33,6 +33,8 @@ class HTTPClient(ABC):  # pragma: no cover
             class MyCustomHTTPClient(HTTPClient):
                 def create_session(self, host):
                     pass
+                async def close_session(self, session):
+                    pass
                 async def send_request(self, session, request):
                     pass
     """
@@ -52,6 +54,18 @@ def create_session(self, host: str) -> Any:
         """
         raise NotImplementedError
 
+    @abstractmethod
+    async def close_session(self, session: Any) -> None:
+        """Close the session.
+
+        Note:
+            This method must be overridden by the user.
+
+        Args:
+            session (Any): Client session object.
+        """
+        raise NotImplementedError
+
     @abstractmethod
     async def send_request(
         self,
@@ -129,6 +143,14 @@ def create_session(self, host: str) -> ClientSession:
             read_bufsize=self._read_bufsize,
         )
 
+    async def close_session(self, session: ClientSession) -> None:
+        """Close the session.
+
+        Args:
+            session (Any): Client session object.
+        """
+        await session.close()
+
     async def send_request(
         self,
         session: ClientSession,

docs/http.rst

@@ -2,3 +2,135 @@
 
 HTTP
 ----
+
+You can define your own HTTP client for sending requests to
+ArangoDB server. The default implementation uses the aiohttp_ library.
+
+Your HTTP client must inherit :class:`arangoasync.http.HTTPClient` and implement the
+following abstract methods:
+
+* :func:`arangoasync.http.HTTPClient.create_session`
+* :func:`arangoasync.http.HTTPClient.close_session`
+* :func:`arangoasync.http.HTTPClient.send_request`
+
+Let's take for example, the default implementation of :class:`arangoasync.http.AioHTTPClient`:
+
+* The **create_session** method returns a :class:`aiohttp.ClientSession` instance per
+  connected host (coordinator). The session objects are stored in the client.
+* The **close_session** method performs the necessary cleanup for a :class:`aiohttp.ClientSession` instance.
+  This is usually called only by the client.
+* The **send_request** method must uses the session to send an HTTP request, and
+  returns a fully populated instance of :class:`arangoasync.response.Response`.
+
+**Example:**
+
+Suppose you're working on a project that uses httpx_ as a dependency and you want your
+own HTTP client implementation on top of :class:`httpx.AsyncClient`. Your ``HttpxHTTPClient``
+class might look something like this:
+
+.. code-block:: python
+
+    import httpx
+    import ssl
+    from typing import Any, Optional
+    from arangoasync.exceptions import ClientConnectionError
+    from arangoasync.http import  HTTPClient
+    from arangoasync.request import Request
+    from arangoasync.response import  Response
+
+    class HttpxHTTPClient(HTTPClient):
+        """HTTP client implementation on top of httpx.AsyncClient.
+
+        Args:
+            limits (httpx.Limits | None): Connection pool limits.n
+            timeout (httpx.Timeout | float | None): Request timeout settings.
+            ssl_context (ssl.SSLContext | bool): SSL validation mode.
+                `True` (default) uses httpx’s default validation (system CAs).
+                `False` disables SSL checks.
+                Or pass a custom `ssl.SSLContext`.
+        """
+
+        def __init__(
+            self,
+            limits: Optional[httpx.Limits] = None,
+            timeout: Optional[httpx.Timeout | float] = None,
+            ssl_context: bool | ssl.SSLContext = True,
+        ) -> None:
+            self._limits = limits or httpx.Limits(
+                max_connections=100,
+                max_keepalive_connections=20
+            )
+            self._timeout = timeout or httpx.Timeout(300.0, connect=60.0)
+            if ssl_context is True:
+                self._verify: bool | ssl.SSLContext = True
+            elif ssl_context is False:
+                self._verify = False
+            else:
+                self._verify = ssl_context
+
+        def create_session(self, host: str) -> httpx.AsyncClient:
+            return httpx.AsyncClient(
+                base_url=host,
+                limits=self._limits,
+                timeout=self._timeout,
+                verify=self._verify,
+            )
+
+        async def close_session(self, session: httpx.AsyncClient) -> None:
+            await session.aclose()
+
+        async def send_request(
+            self,
+            session: httpx.AsyncClient,
+            request: Request,
+        ) -> Response:
+            auth: Any = None
+            if request.auth is not None:
+                auth = httpx.BasicAuth(
+                    username=request.auth.username,
+                    password=request.auth.password,
+                )
+
+            try:
+                resp = await session.request(
+                    method=request.method.name,
+                    url=request.endpoint,
+                    headers=request.normalized_headers(),
+                    params=request.normalized_params(),
+                    content=request.data,
+                    auth=auth,
+                )
+                raw_body = resp.content
+                return Response(
+                    method=request.method,
+                    url=str(resp.url),
+                    headers=resp.headers,
+                    status_code=resp.status_code,
+                    status_text=resp.reason_phrase,
+                    raw_body=raw_body,
+                )
+            except httpx.HTTPError as e:
+                raise ClientConnectionError(str(e)) from e
+
+Then you would inject your client as follows:
+
+.. code-block:: python
+
+    from arangoasync import ArangoClient
+    from arangoasync.auth import Auth
+
+    # Initialize the client for ArangoDB.
+    async with ArangoClient(
+            hosts="http://localhost:8529",
+            http_client=HttpxHTTPClient(),
+    ) as client:
+        auth = Auth(username="root", password="passwd")
+
+        # Connect to "test" database as root user.
+        db = await client.db("test", auth=auth, verify=True)
+
+        # List all collections.
+        cols = await db.collections()
+
+.. _aiohttp: https://docs.aiohttp.org/en/stable/
+.. _httpx: https://www.python-httpx.org/