python-arango-async 0.0.1__py3-none-any.whl

arangoasync/http.py

@@ -0,0 +1,182 @@
+__all__ = [
+    "HTTPClient",
+    "AioHTTPClient",
+    "DefaultHTTPClient",
+]
+
+from abc import ABC, abstractmethod
+from ssl import SSLContext, create_default_context
+from typing import Any, Optional
+
+from aiohttp import (
+    BaseConnector,
+    BasicAuth,
+    ClientSession,
+    ClientTimeout,
+    TCPConnector,
+    client_exceptions,
+)
+
+from arangoasync.exceptions import ClientConnectionError
+from arangoasync.request import Request
+from arangoasync.response import Response
+
+
+class HTTPClient(ABC):  # pragma: no cover
+    """Abstract base class for HTTP clients.
+
+    Custom HTTP clients should inherit from this class.
+
+    Example:
+        .. code-block:: python
+
+            class MyCustomHTTPClient(HTTPClient):
+                def create_session(self, host):
+                    pass
+                async def send_request(self, session, request):
+                    pass
+    """
+
+    @abstractmethod
+    def create_session(self, host: str) -> Any:
+        """Return a new session given the base host URL.
+
+        Note:
+            This method must be overridden by the user.
+
+        Args:
+            host (str): ArangoDB host URL.
+
+        Returns:
+            Requests session object.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def send_request(
+        self,
+        session: Any,
+        request: Request,
+    ) -> Response:
+        """Send an HTTP request.
+
+        Note:
+            This method must be overridden by the user.
+
+        Args:
+            session (Any): Client session object.
+            request (Request): HTTP request.
+
+        Returns:
+            Response: HTTP response.
+        """
+        raise NotImplementedError
+
+
+class AioHTTPClient(HTTPClient):
+    """HTTP client implemented on top of aiohttp_.
+
+    Args:
+        connector (aiohttp.BaseConnector | None): Supports connection pooling.
+            By default, 100 simultaneous connections are supported, with a 60-second
+            timeout for connection reusing after release.
+        timeout (aiohttp.ClientTimeout | None): Client timeout settings.
+            300s total timeout by default for a complete request/response operation.
+        read_bufsize (int): Size of read buffer (64KB default).
+        ssl_context (ssl.SSLContext | bool): SSL validation mode.
+            `True` for default SSL checks (see :func:`ssl.create_default_context`).
+            `False` disables SSL checks.
+            Additionally, you can pass a custom :class:`ssl.SSLContext`.
+
+    .. _aiohttp:
+        https://docs.aiohttp.org/en/stable/
+    """
+
+    def __init__(
+        self,
+        connector: Optional[BaseConnector] = None,
+        timeout: Optional[ClientTimeout] = None,
+        read_bufsize: int = 2**16,
+        ssl_context: bool | SSLContext = True,
+    ) -> None:
+        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._ssl_context = (
+            ssl_context if ssl_context is not True else create_default_context()
+        )
+
+    def create_session(self, host: str) -> ClientSession:
+        """Return a new session given the base host URL.
+
+        Args:
+            host (str): ArangoDB host URL. Must not include any paths. Typically, this
+                is the address and port of a coordinator (e.g. "http://127.0.0.1:8529").
+
+        Returns:
+            aiohttp.ClientSession: Session object, used to send future requests.
+        """
+        return ClientSession(
+            base_url=host,
+            connector=self._connector,
+            timeout=self._timeout,
+            read_bufsize=self._read_bufsize,
+        )
+
+    async def send_request(
+        self,
+        session: ClientSession,
+        request: Request,
+    ) -> Response:
+        """Send an HTTP request.
+
+        Args:
+            session (aiohttp.ClientSession): Session object used to make the request.
+            request (Request): HTTP request.
+
+        Returns:
+            Response: HTTP response.
+
+        Raises:
+            ClientConnectionError: If the request fails.
+        """
+
+        if request.auth is not None:
+            auth = BasicAuth(
+                login=request.auth.username,
+                password=request.auth.password,
+                encoding=request.auth.encoding,
+            )
+        else:
+            auth = None
+
+        try:
+            async with session.request(
+                request.method.name,
+                request.endpoint,
+                headers=request.normalized_headers(),
+                params=request.normalized_params(),
+                data=request.data,
+                auth=auth,
+                ssl=self._ssl_context,
+            ) as response:
+                raw_body = await response.read()
+                return Response(
+                    method=request.method,
+                    url=str(response.real_url),
+                    headers=response.headers,
+                    status_code=response.status,
+                    status_text=str(response.reason),
+                    raw_body=raw_body,
+                )
+        except client_exceptions.ClientConnectionError as e:
+            raise ClientConnectionError(str(e)) from e
+
+
+DefaultHTTPClient = AioHTTPClient

arangoasync/job.py

@@ -0,0 +1,214 @@
+__all__ = ["AsyncJob"]
+
+
+import asyncio
+from typing import Callable, Generic, Optional, TypeVar
+
+from arangoasync.connection import Connection
+from arangoasync.errno import HTTP_NOT_FOUND
+from arangoasync.exceptions import (
+    AsyncJobCancelError,
+    AsyncJobClearError,
+    AsyncJobResultError,
+    AsyncJobStatusError,
+)
+from arangoasync.request import Method, Request
+from arangoasync.response import Response
+
+T = TypeVar("T")
+
+
+class AsyncJob(Generic[T]):
+    """Job for tracking and retrieving result of an async API execution.
+
+    Args:
+        conn: HTTP connection.
+        job_id: Async job ID.
+        response_handler: HTTP response handler
+
+    References:
+        - `jobs <https://docs.arangodb.com/stable/develop/http-api/jobs/>`__
+    """  # noqa: E501
+
+    def __init__(
+        self,
+        conn: Connection,
+        job_id: str,
+        response_handler: Callable[[Response], T],
+    ) -> None:
+        self._conn = conn
+        self._id = job_id
+        self._response_handler = response_handler
+
+    def __repr__(self) -> str:
+        return f"<AsyncJob {self._id}>"
+
+    @property
+    def id(self) -> str:
+        """Return the async job ID.
+
+        Returns:
+            str: Async job ID.
+        """
+        return self._id
+
+    async def status(self) -> str:
+        """Return the async job status from server.
+
+        Once a job result is retrieved via func:`arangoasync.job.AsyncJob.result`
+        method, it is deleted from server and subsequent status queries will
+        fail.
+
+        Returns:
+            str: Async job status. Possible values are "pending" (job is still
+            in queue), "done" (job finished or raised an error).
+
+        Raises:
+            ArangoError: If there is a problem with the request.
+            AsyncJobStatusError: If retrieval fails or the job is not found.
+
+        References:
+            - `list-async-jobs-by-status-or-get-the-status-of-specific-job <https://docs.arangodb.com/stable/develop/http-api/jobs/#list-async-jobs-by-status-or-get-the-status-of-specific-job>`__
+        """  # noqa: E501
+        request = Request(method=Method.GET, endpoint=f"/_api/job/{self._id}")
+        response = await self._conn.send_request(request)
+
+        if response.is_success:
+            if response.status_code == 204:
+                return "pending"
+            else:
+                return "done"
+        if response.error_code == HTTP_NOT_FOUND:
+            error_message = f"job {self._id} not found"
+            raise AsyncJobStatusError(response, request, error_message)
+        raise AsyncJobStatusError(response, request)
+
+    async def result(self) -> T:
+        """Fetch the async job result from server.
+
+        If the job raised an exception, it is propagated up at this point.
+
+        Once job result is retrieved, it is deleted from server and subsequent
+        queries for result will fail.
+
+        Returns:
+            Async job result.
+
+        Raises:
+            ArangoError: If the job raised an exception or there was a problem with
+                the request.
+            AsyncJobResultError: If retrieval fails, because job no longer exists or
+                is still pending.
+
+        References:
+            - `get-the-results-of-an-async-job <https://docs.arangodb.com/stable/develop/http-api/jobs/#get-the-results-of-an-async-job>`__
+        """  # noqa: E501
+        request = Request(method=Method.PUT, endpoint=f"/_api/job/{self._id}")
+        response = await self._conn.send_request(request)
+
+        if (
+            "x-arango-async-id" in response.headers
+            or "X-Arango-Async-Id" in response.headers
+        ):
+            # The job result is available on the server
+            return self._response_handler(response)
+
+        if response.status_code == 204:
+            # The job is still in the pending queue or not yet finished.
+            raise AsyncJobResultError(response, request, self._not_done())
+        # The job is not known (anymore).
+        # We can tell the status from the HTTP status code.
+        if response.error_code == HTTP_NOT_FOUND:
+            raise AsyncJobResultError(response, request, self._not_found())
+        raise AsyncJobResultError(response, request)
+
+    async def cancel(self, ignore_missing: bool = False) -> bool:
+        """Cancel the async job.
+
+        An async job cannot be cancelled once it is taken out of the queue.
+
+        Note:
+            It still might take some time to actually cancel the running async job.
+
+        Args:
+            ignore_missing: Do not raise an exception if the job is not found.
+
+        Returns:
+            `True` if job was cancelled successfully, `False` if the job was not found
+            but **ignore_missing** was set to `True`.
+
+        Raises:
+            ArangoError: If there was a problem with the request.
+            AsyncJobCancelError: If cancellation fails.
+
+        References:
+            - `cancel-an-async-job <https://docs.arangodb.com/stable/develop/http-api/jobs/#cancel-an-async-job>`__
+        """  # noqa: E501
+        request = Request(method=Method.PUT, endpoint=f"/_api/job/{self._id}/cancel")
+        response = await self._conn.send_request(request)
+
+        if response.is_success:
+            return True
+        if response.error_code == HTTP_NOT_FOUND:
+            if ignore_missing:
+                return False
+            raise AsyncJobCancelError(response, request, self._not_found())
+        raise AsyncJobCancelError(response, request)
+
+    async def clear(
+        self,
+        ignore_missing: bool = False,
+    ) -> bool:
+        """Delete the job result from the server.
+
+        Args:
+            ignore_missing: Do not raise an exception if the job is not found.
+
+        Returns:
+            `True` if result was deleted successfully, `False` if the job was
+            not found but **ignore_missing** was set to `True`.
+
+        Raises:
+            ArangoError: If there was a problem with the request.
+            AsyncJobClearError: If deletion fails.
+
+        References:
+            - `delete-async-job-results <https://docs.arangodb.com/stable/develop/http-api/jobs/#delete-async-job-results>`__
+        """  # noqa: E501
+        request = Request(method=Method.DELETE, endpoint=f"/_api/job/{self._id}")
+        resp = await self._conn.send_request(request)
+
+        if resp.is_success:
+            return True
+        if resp.error_code == HTTP_NOT_FOUND:
+            if ignore_missing:
+                return False
+            raise AsyncJobClearError(resp, request, self._not_found())
+        raise AsyncJobClearError(resp, request)
+
+    async def wait(self, seconds: Optional[float] = None) -> bool:
+        """Wait for the async job to finish.
+
+        Args:
+            seconds: Number of seconds to wait between status checks. If not
+                provided, the method will wait indefinitely.
+
+        Returns:
+            `True` if the job is done, `False` if the job is still pending.
+        """
+        while True:
+            if await self.status() == "done":
+                return True
+            if seconds is None:
+                await asyncio.sleep(1)
+            else:
+                seconds -= 1
+                if seconds < 0:
+                    return False
+                await asyncio.sleep(1)
+
+    def _not_found(self) -> str:
+        return f"job {self._id} not found"
+
+    def _not_done(self) -> str:
+        return f"job {self._id} not done"

arangoasync/logger.py

@@ -0,0 +1,3 @@
+import logging
+
+logger = logging.getLogger("arangoasync")

arangoasync/request.py

@@ -0,0 +1,107 @@
+__all__ = [
+    "Method",
+    "Request",
+]
+
+from enum import Enum, auto
+from typing import Optional
+
+from arangoasync.auth import Auth
+from arangoasync.typings import Params, RequestHeaders
+from arangoasync.version import __version__
+
+
+class Method(Enum):
+    """HTTP methods enum: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"""
+
+    GET = auto()
+    POST = auto()
+    PUT = auto()
+    PATCH = auto()
+    DELETE = auto()
+    HEAD = auto()
+    OPTIONS = auto()
+
+
+class Request:
+    """HTTP request.
+
+    Args:
+        method (Method): HTTP method.
+        endpoint (str): API endpoint.
+        headers (dict | None): Request headers.
+        params (dict | None): URL parameters.
+        data (bytes | None): Request payload.
+        auth (Auth | None): Authentication.
+
+    Attributes:
+        method (Method): HTTP method.
+        endpoint (str): API endpoint.
+        headers (dict | None): Request headers.
+        params (dict | None): URL parameters.
+        data (bytes | None): Request payload.
+        auth (Auth | None): Authentication.
+    """
+
+    __slots__ = (
+        "method",
+        "endpoint",
+        "headers",
+        "params",
+        "data",
+        "auth",
+    )
+
+    def __init__(
+        self,
+        method: Method,
+        endpoint: str,
+        headers: Optional[RequestHeaders] = None,
+        params: Optional[Params] = None,
+        data: Optional[bytes | str] = None,
+        auth: Optional[Auth] = None,
+    ) -> None:
+        self.method: Method = method
+        self.endpoint: str = endpoint
+        self.headers: RequestHeaders = headers or dict()
+        self.params: Params = params or dict()
+        self.data: Optional[bytes | str] = data
+        self.auth: Optional[Auth] = auth
+
+    def normalized_headers(self) -> RequestHeaders:
+        """Normalize request headers.
+
+        Returns:
+            dict: Normalized request headers.
+        """
+        driver_header = f"arangoasync/{__version__}"
+        normalized_headers: RequestHeaders = {
+            "charset": "utf-8",
+            "content-type": "application/json",
+            "x-arango-driver": driver_header,
+        }
+
+        if self.headers is not None:
+            for key, value in self.headers.items():
+                normalized_headers[key.lower()] = value
+
+        return normalized_headers
+
+    def normalized_params(self) -> Params:
+        """Normalize URL parameters.
+
+        Returns:
+            dict: Normalized URL parameters.
+        """
+        normalized_params: Params = {}
+
+        if self.params is not None:
+            for key, value in self.params.items():
+                if isinstance(value, bool):
+                    value = int(value)
+                normalized_params[key] = str(value)
+
+        return normalized_params
+
+    def __repr__(self) -> str:
+        return f"<{self.method.name} {self.endpoint}>"

arangoasync/resolver.py

@@ -0,0 +1,119 @@
+__all__ = [
+    "HostResolver",
+    "SingleHostResolver",
+    "RoundRobinHostResolver",
+    "DefaultHostResolver",
+    "get_resolver",
+]
+
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+
+class HostResolver(ABC):
+    """Abstract base class for host resolvers.
+
+    Args:
+        host_count (int): Number of hosts.
+        max_tries (int | None): Maximum number of attempts to try a host.
+            Will default to 3 times the number of hosts if not provided.
+
+    Raises:
+        ValueError: If max_tries is less than host_count.
+    """
+
+    def __init__(self, host_count: int = 1, max_tries: Optional[int] = None) -> None:
+        max_tries = max_tries or host_count * 3
+        if max_tries < host_count:
+            raise ValueError(
+                "The maximum number of attempts cannot be "
+                "lower than the number of hosts."
+            )
+        self._host_count = host_count
+        self._max_tries = max_tries
+        self._index = 0
+
+    @abstractmethod
+    def get_host_index(self) -> int:  # pragma: no cover
+        """Return the index of the host to use.
+
+        Returns:
+            int: Index of the host.
+        """
+        raise NotImplementedError
+
+    def change_host(self) -> None:
+        """If there are multiple hosts available, switch to the next one."""
+        self._index = (self._index + 1) % self.host_count
+
+    @property
+    def host_count(self) -> int:
+        """Return the number of hosts."""
+        return self._host_count
+
+    @property
+    def max_tries(self) -> int:
+        """Return the maximum number of attempts."""
+        return self._max_tries
+
+
+class SingleHostResolver(HostResolver):
+    """Single host resolver.
+
+    Always returns the same host index, unless prompted to change.
+    """
+
+    def __init__(self, host_count: int, max_tries: Optional[int] = None) -> None:
+        super().__init__(host_count, max_tries)
+
+    def get_host_index(self) -> int:
+        return self._index
+
+
+class RoundRobinHostResolver(HostResolver):
+    """Round-robin host resolver. Changes host every time.
+
+    Useful for bulk inserts or updates.
+
+    Note:
+        Do not use this resolver for stream transactions.
+        Transaction IDs cannot be shared across different coordinators.
+    """
+
+    def __init__(self, host_count: int, max_tries: Optional[int] = None) -> None:
+        super().__init__(host_count, max_tries)
+        self._index = -1
+
+    def get_host_index(self, indexes_to_filter: Optional[List[int]] = None) -> int:
+        self.change_host()
+        return self._index
+
+
+DefaultHostResolver = SingleHostResolver
+
+
+def get_resolver(
+    strategy: str,
+    host_count: int,
+    max_tries: Optional[int] = None,
+) -> HostResolver:
+    """Return a host resolver based on the strategy.
+
+    Args:
+        strategy (str): Resolver strategy.
+        host_count (int): Number of hosts.
+        max_tries (int): Maximum number of attempts to try a host.
+
+    Returns:
+        HostResolver: Host resolver.
+
+    Raises:
+        ValueError: If the strategy is not supported.
+    """
+    if strategy == "roundrobin":
+        return RoundRobinHostResolver(host_count, max_tries)
+    if strategy == "single":
+        return SingleHostResolver(host_count, max_tries)
+    if strategy == "default":
+        return DefaultHostResolver(host_count, max_tries)
+    raise ValueError(f"Unsupported host resolver strategy: {strategy}")

arangoasync/response.py

@@ -0,0 +1,65 @@
+__all__ = [
+    "Response",
+]
+
+from typing import Optional
+
+from arangoasync.request import Method
+from arangoasync.typings import ResponseHeaders
+
+
+class Response:
+    """HTTP response.
+
+    Parameters:
+        method (Method): HTTP method.
+        url (str): API URL.
+        headers (dict): Response headers.
+        status_code (int): Response status code.
+        status_text (str): Response status text.
+        raw_body (bytes): Raw response body.
+
+    Attributes:
+        method (Method): HTTP method.
+        url (str): API URL.
+        headers (dict): Response headers.
+        status_code (int): Response status code.
+        status_text (str): Response status text.
+        raw_body (bytes): Raw response body.
+        error_code (int | None): Error code from ArangoDB server.
+        error_message (str | None): Error message from ArangoDB server.
+        is_success (bool | None): True if response status code was 2XX.
+    """
+
+    __slots__ = (
+        "method",
+        "url",
+        "headers",
+        "status_code",
+        "status_text",
+        "raw_body",
+        "error_code",
+        "error_message",
+        "is_success",
+    )
+
+    def __init__(
+        self,
+        method: Method,
+        url: str,
+        headers: ResponseHeaders,
+        status_code: int,
+        status_text: str,
+        raw_body: bytes,
+    ) -> None:
+        self.method: Method = method
+        self.url: str = url
+        self.headers: ResponseHeaders = headers
+        self.status_code: int = status_code
+        self.status_text: str = status_text
+        self.raw_body: bytes = raw_body
+
+        # Populated later
+        self.error_code: Optional[int] = None
+        self.error_message: Optional[str] = None
+        self.is_success: Optional[bool] = None

arangoasync/result.py

@@ -0,0 +1,9 @@
+__all__ = ["Result"]
+
+from typing import TypeVar, Union
+
+from arangoasync.job import AsyncJob
+
+# The Result definition has to be in a separate module because of circular imports.
+T = TypeVar("T")
+Result = Union[T, AsyncJob[T], None]