HttpClient first version

Author: apetenchea

arangoasync/http.py

@@ -1,114 +1,121 @@
-# TODO __all__ = []
+__all__ = [
+    "HTTPClient",
+    "AioHTTPClient",
+    "DefaultHTTPClient",
+]
 
 from abc import ABC, abstractmethod
-from typing import Optional
+from typing import Any, Optional
 
-from aiohttp import BaseConnector, BasicAuth, ClientSession, ClientTimeout
+from aiohttp import BaseConnector, BasicAuth, ClientSession, ClientTimeout, TcpConnector
 from request import Request
 from response import Response
 
 
-class Session(ABC):  # pragma: no cover
-    """Abstract base class for HTTP sessions."""
-
-    @abstractmethod
-    async def request(self, request: Request) -> Response:
-        """Send an HTTP request.
-
-        This method must be overridden by the user.
-
-        :param request: HTTP request.
-        :type request: arangoasync.request.Request
-        :returns: HTTP response.
-        :rtype: arangoasync.response.Response
-        """
-        raise NotImplementedError
-
-    @abstractmethod
-    async def close(self) -> None:
-        """Close the session.
-
-        This method must be overridden by the user.
-        """
-        raise NotImplementedError
-
-
 class HTTPClient(ABC):  # pragma: no cover
-    """Abstract base class for HTTP clients."""
+    """Abstract base class for HTTP clients.
+    Custom HTTP clients should inherit from this class.
+    """
 
     @abstractmethod
-    def create_session(self, host: str) -> Session:
-        """Return a new requests session given the host URL.
+    def create_session(self, host: str) -> Any:
+        """Return a new session given the base host URL.
 
         This method must be overridden by the user.
 
         :param host: ArangoDB host URL.
         :type host: str
         :returns: Requests session object.
-        :rtype: arangoasync.http.Session
+        :rtype: Any
         """
         raise NotImplementedError
 
     @abstractmethod
     async def send_request(
         self,
-        session: Session,
-        url: str,
+        session: Any,
         request: Request,
     ) -> Response:
         """Send an HTTP request.
 
         This method must be overridden by the user.
 
         :param session: Session object.
-        :type session: arangoasync.http.Session
-        :param url: Request URL.
-        :type url: str
+        :type session: Any
         :param request: HTTP request.
         :type request: arangoasync.request.Request
         :returns: HTTP response.
-        :rtype: arango.response.Response
+        :rtype: arangoasync.response.Response
         """
         raise NotImplementedError
 
 
-class DefaultSession(Session):
-    """Wrapper on top of an aiohttp.ClientSession."""
+class AioHTTPClient(HTTPClient):
+    """HTTP client implemented on top of [aiohttp](https://docs.aiohttp.org/en/stable/).
+
+    :param connector: Supports connection pooling.
+        By default, 100 simultaneous connections are supported, with a 60-second timeout
+        for connection reusing after release.
+    :type connector: aiohttp.BaseConnector | None
+    :param timeout: Timeout settings.
+        300s total timeout by default for a complete request/response operation.
+    :type timeout: aiohttp.ClientTimeout | None
+    :param read_bufsize: Size of read buffer (64KB default).
+    :type read_bufsize: int
+    :param auth: HTTP authentication helper.
+        Should be used for specifying authorization data in client API.
+    :type auth: aiohttp.BasicAuth | None
+    :param compression_threshold: Will compress requests to the server if
+        the size of the request body (in bytes) is at least the value of this
+        option.
+    :type compression_threshold: int
+    """
 
     def __init__(
         self,
-        host: str,
-        connector: BaseConnector,
-        timeout: ClientTimeout,
+        connector: Optional[BaseConnector] = None,
+        timeout: Optional[ClientTimeout] = None,
         read_bufsize: int = 2**16,
         auth: Optional[BasicAuth] = None,
+        compression_threshold: int = 1024,
     ) -> None:
-        """Initialize the session.
+        self._connector = connector or TcpConnector(
+            keepalive_timeout=60,  # timeout for connection reusing after releasing
+            limit=100,  # total number simultaneous connections
+        )
+        self._timeout = timeout or ClientTimeout(
+            total=300,  # total number of seconds for the whole request
+            connect=60,  # max number of seconds for acquiring a pool connection
+        )
+        self._read_bufsize = read_bufsize
+        self._auth = auth
+        self._compression_threshold = compression_threshold
 
-        :param host: ArangoDB coordinator URL (eg http://localhost:8530).
+    def create_session(self, host: str) -> ClientSession:
+        """Return a new session given the base host URL.
+
+        :param host: ArangoDB host URL. Typically the address and port of a coordinator,
+            for example "http://127.0.0.1:8529".
         :type host: str
-        :param connector: Supports connection pooling.
-        :type connector: aiohttp.BaseConnector
-        :param timeout: Request timeout settings.
-        :type timeout: aiohttp.ClientTimeout
-        :param read_bufsize: Size of read buffer. 64 Kib by default.
-        :type read_bufsize: int
-        :param auth: HTTP Authorization.
-        :type auth: aiohttp.BasicAuth | None
+        :returns: Session object.
+        :rtype: aiohttp.ClientSession
         """
-        self._session = ClientSession(
-            base_url=host,
-            connector=connector,
-            timeout=timeout,
-            auth=auth,
-            read_bufsize=read_bufsize,
-            connector_owner=False,
-            auto_decompress=True,
+        return ClientSession(
+            connector=self._connector,
+            timeout=self._timeout,
+            auth=self._auth,
+            read_bufsize=self._read_bufsize,
         )
 
-    async def request(self, request: Request) -> Response:
+    async def send_request(
+        self,
+        session: ClientSession,
+        request: Request,
+    ) -> Response:
         """Send an HTTP request.
 
+        :param session: Session object.
+        :type session: aiohttp.ClientSession
         :param request: HTTP request.
         :type request: arangoasync.request.Request
         :returns: HTTP response.
@@ -119,13 +126,15 @@ async def request(self, request: Request) -> Response:
         headers = request.headers
         params = request.params
         data = request.data
+        compress = len(data) >= self._compression_threshold
 
-        async with self._session.request(
+        async with session.request(
             method.name,
             endpoint,
             headers=headers,
             params=params,
             data=data,
+            compress=compress,
         ) as response:
             raw_body = await response.read()
             return Response(
@@ -137,9 +146,5 @@ async def request(self, request: Request) -> Response:
                 raw_body=raw_body,
             )
 
-    async def close(self) -> None:
-        """Close the session."""
-        await self._session.close()
-
 
-# TODO implement DefaultHTTPClient
+DefaultHTTPClient = AioHTTPClient

arangoasync/request.py

@@ -7,7 +7,7 @@
 from typing import Generic, Optional, TypeVar
 
 from typings import Headers, Params
-from version import __version__ as driver_version
+from version import __version__
 
 T = TypeVar("T")
 
@@ -33,7 +33,7 @@ class Request(Generic[T]):
     :type endpoint: str
     :param headers: Request headers.
     :type headers: dict | None
-    :param params: URL (query) parameters.
+    :param params: URL parameters.
     :type params: dict | None
     :param data: Request payload.
     :type data: Any
@@ -42,7 +42,7 @@ class Request(Generic[T]):
 
     :ivar method: HTTP method.
     :vartype method: request.Method
-    :ivar endpoint: API endpoint.
+    :ivar endpoint: API endpoint, for example "_api/version".
     :vartype endpoint: str
     :ivar headers: Request headers.
     :vartype headers: dict | None
@@ -88,7 +88,7 @@ def _normalize_headers(headers: Optional[Headers]) -> Headers:
         :returns: Normalized request headers.
         :rtype: dict
         """
-        driver_header = f"arangoasync/{driver_version}"
+        driver_header = f"arangoasync/{__version__}"
         normalized_headers: Headers = {
             "charset": "utf-8",
             "content-type": "application/json",
@@ -103,11 +103,11 @@ def _normalize_headers(headers: Optional[Headers]) -> Headers:
 
     @staticmethod
     def _normalize_params(params: Optional[Params]) -> Params:
-        """Normalize URL (query) parameters.
+        """Normalize URL parameters.
 
-        :param params: URL (query) parameters.
+        :param params: URL parameters.
         :type params: dict | None
-        :returns: Normalized URL (query) parameters.
+        :returns: Normalized URL parameters.
         :rtype: dict
         """
         normalized_params: Params = {}

arangoasync/response.py

@@ -1,3 +1,7 @@
+__all__ = [
+    "Response",
+]
+
 from typing import Generic, Optional, TypeVar
 
 from request import Method

pyproject.toml

@@ -40,6 +40,7 @@ dependencies = [
     "packaging>=23.1",
     "setuptools>=42",
     "aiohttp>=3.9",
+    "multidict>=6.0",
 ]
 
 [tool.setuptools.dynamic]