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

arangoasync/exceptions.py

@@ -0,0 +1,379 @@
+from typing import Optional
+
+from arangoasync.request import Request
+from arangoasync.response import Response
+
+
+class ArangoError(Exception):
+    """Base class for all exceptions in python-arango-async."""
+
+
+class ArangoClientError(ArangoError):
+    """Base class for all client-related exceptions.
+
+    Args:
+        msg (str): Error message.
+
+    Attributes:
+        source (str): Source of the error (always set to "client")
+        message (str): Error message.
+    """
+
+    source = "client"
+
+    def __init__(self, msg: str) -> None:
+        super().__init__(msg)
+        self.message = msg
+
+
+class ArangoServerError(ArangoError):
+    """Base class for all server-related exceptions.
+
+    Args:
+        resp (Response): HTTP response object.
+        request (Request): HTTP request object.
+        msg (str | None): Error message.
+
+    Attributes:
+        source (str): Source of the error (always set to "server")
+        message (str): Error message.
+        url (str): URL of the request.
+        response (Response): HTTP response object.
+        request (Request): HTTP request object.
+        http_method (str): HTTP method of the request.
+        http_code (int): HTTP status code of the response.
+        http_headers (dict): HTTP headers of the response.
+    """
+
+    source = "server"
+
+    def __init__(
+        self, resp: Response, request: Request, msg: Optional[str] = None
+    ) -> None:
+        if msg is None:
+            msg = resp.error_message or resp.status_text
+        else:
+            msg = f"{msg} ({resp.error_message or resp.status_text})"
+        self.error_message = resp.error_message
+        self.error_code = resp.error_code
+        if self.error_code is not None:
+            msg = f"[HTTP {resp.status_code}][ERR {self.error_code}] {msg}"
+        else:
+            msg = f"[HTTP {resp.status_code}] {msg}"
+            self.error_code = resp.status_code
+        super().__init__(msg)
+        self.message = msg
+        self.url = resp.url
+        self.response = resp
+        self.request = request
+        self.http_method = resp.method.name
+        self.http_code = resp.status_code
+        self.http_headers = resp.headers
+
+
+class AQLCacheClearError(ArangoServerError):
+    """Failed to clear the query cache."""
+
+
+class AQLCacheConfigureError(ArangoServerError):
+    """Failed to configure query cache properties."""
+
+
+class AQLCacheEntriesError(ArangoServerError):
+    """Failed to retrieve AQL cache entries."""
+
+
+class AQLCachePropertiesError(ArangoServerError):
+    """Failed to retrieve query cache properties."""
+
+
+class AQLFunctionCreateError(ArangoServerError):
+    """Failed to create AQL user function."""
+
+
+class AQLFunctionDeleteError(ArangoServerError):
+    """Failed to delete AQL user function."""
+
+
+class AQLFunctionListError(ArangoServerError):
+    """Failed to retrieve AQL user functions."""
+
+
+class AQLQueryClearError(ArangoServerError):
+    """Failed to clear slow AQL queries."""
+
+
+class AQLQueryExecuteError(ArangoServerError):
+    """Failed to execute query."""
+
+
+class AQLQueryExplainError(ArangoServerError):
+    """Failed to parse and explain query."""
+
+
+class AQLQueryKillError(ArangoServerError):
+    """Failed to kill the query."""
+
+
+class AQLQueryListError(ArangoServerError):
+    """Failed to retrieve running AQL queries."""
+
+
+class AQLQueryRulesGetError(ArangoServerError):
+    """Failed to retrieve AQL query rules."""
+
+
+class AQLQueryTrackingGetError(ArangoServerError):
+    """Failed to retrieve AQL tracking properties."""
+
+
+class AQLQueryTrackingSetError(ArangoServerError):
+    """Failed to configure AQL tracking properties."""
+
+
+class AQLQueryValidateError(ArangoServerError):
+    """Failed to parse and validate query."""
+
+
+class AsyncExecuteError(ArangoServerError):
+    """Failed to execute async API request."""
+
+
+class AsyncJobCancelError(ArangoServerError):
+    """Failed to cancel async job."""
+
+
+class AsyncJobClearError(ArangoServerError):
+    """Failed to clear async job results."""
+
+
+class AsyncJobListError(ArangoServerError):
+    """Failed to retrieve async jobs."""
+
+
+class AsyncJobResultError(ArangoServerError):
+    """Failed to retrieve async job result."""
+
+
+class AsyncJobStatusError(ArangoServerError):
+    """Failed to retrieve async job status."""
+
+
+class AuthHeaderError(ArangoClientError):
+    """The authentication header could not be determined."""
+
+
+class CollectionCreateError(ArangoServerError):
+    """Failed to create collection."""
+
+
+class CollectionDeleteError(ArangoServerError):
+    """Failed to delete collection."""
+
+
+class CollectionListError(ArangoServerError):
+    """Failed to retrieve collections."""
+
+
+class CollectionPropertiesError(ArangoServerError):
+    """Failed to retrieve collection properties."""
+
+
+class ClientConnectionAbortedError(ArangoClientError):
+    """The connection was aborted."""
+
+
+class ClientConnectionError(ArangoClientError):
+    """The request was unable to reach the server."""
+
+
+class CollectionTruncateError(ArangoServerError):
+    """Failed to truncate collection."""
+
+
+class CursorCloseError(ArangoServerError):
+    """Failed to delete the cursor result from server."""
+
+
+class CursorCountError(ArangoClientError, TypeError):
+    """The cursor count was not enabled."""
+
+
+class CursorEmptyError(ArangoClientError):
+    """The current batch in cursor was empty."""
+
+
+class CursorNextError(ArangoServerError):
+    """Failed to retrieve the next result batch from server."""
+
+
+class CursorStateError(ArangoClientError):
+    """The cursor object was in a bad state."""
+
+
+class DatabaseCreateError(ArangoServerError):
+    """Failed to create database."""
+
+
+class DatabaseDeleteError(ArangoServerError):
+    """Failed to delete database."""
+
+
+class DatabaseListError(ArangoServerError):
+    """Failed to retrieve databases."""
+
+
+class DatabasePropertiesError(ArangoServerError):
+    """Failed to retrieve database properties."""
+
+
+class DeserializationError(ArangoClientError):
+    """Failed to deserialize the server response."""
+
+
+class DocumentCountError(ArangoServerError):
+    """Failed to retrieve document count."""
+
+
+class DocumentDeleteError(ArangoServerError):
+    """Failed to delete document."""
+
+
+class DocumentGetError(ArangoServerError):
+    """Failed to retrieve document."""
+
+
+class DocumentInsertError(ArangoServerError):
+    """Failed to insert document."""
+
+
+class DocumentParseError(ArangoClientError):
+    """Failed to parse document input."""
+
+
+class DocumentReplaceError(ArangoServerError):
+    """Failed to replace document."""
+
+
+class DocumentRevisionError(ArangoServerError):
+    """The expected and actual document revisions mismatched."""
+
+
+class DocumentUpdateError(ArangoServerError):
+    """Failed to update document."""
+
+
+class IndexCreateError(ArangoServerError):
+    """Failed to create collection index."""
+
+
+class IndexDeleteError(ArangoServerError):
+    """Failed to delete collection index."""
+
+
+class IndexGetError(ArangoServerError):
+    """Failed to retrieve collection index."""
+
+
+class IndexListError(ArangoServerError):
+    """Failed to retrieve collection indexes."""
+
+
+class IndexLoadError(ArangoServerError):
+    """Failed to load indexes into memory."""
+
+
+class JWTRefreshError(ArangoClientError):
+    """Failed to refresh the JWT token."""
+
+
+class JWTSecretListError(ArangoServerError):
+    """Failed to retrieve information on currently loaded JWT secrets."""
+
+
+class JWTSecretReloadError(ArangoServerError):
+    """Failed to reload JWT secrets."""
+
+
+class PermissionGetError(ArangoServerError):
+    """Failed to retrieve user permission."""
+
+
+class PermissionListError(ArangoServerError):
+    """Failed to list user permissions."""
+
+
+class PermissionResetError(ArangoServerError):
+    """Failed to reset user permission."""
+
+
+class PermissionUpdateError(ArangoServerError):
+    """Failed to update user permission."""
+
+
+class SerializationError(ArangoClientError):
+    """Failed to serialize the request."""
+
+
+class ServerConnectionError(ArangoServerError):
+    """Failed to connect to ArangoDB server."""
+
+
+class ServerStatusError(ArangoServerError):
+    """Failed to retrieve server status."""
+
+
+class ServerVersionError(ArangoServerError):
+    """Failed to retrieve server version."""
+
+
+class SortValidationError(ArangoClientError):
+    """Invalid sort parameters."""
+
+
+class TransactionAbortError(ArangoServerError):
+    """Failed to abort transaction."""
+
+
+class TransactionCommitError(ArangoServerError):
+    """Failed to commit transaction."""
+
+
+class TransactionExecuteError(ArangoServerError):
+    """Failed to execute JavaScript transaction."""
+
+
+class TransactionInitError(ArangoServerError):
+    """Failed to initialize transaction."""
+
+
+class TransactionListError(ArangoServerError):
+    """Failed to retrieve transactions."""
+
+
+class TransactionStatusError(ArangoServerError):
+    """Failed to retrieve transaction status."""
+
+
+class UserCreateError(ArangoServerError):
+    """Failed to create user."""
+
+
+class UserDeleteError(ArangoServerError):
+    """Failed to delete user."""
+
+
+class UserGetError(ArangoServerError):
+    """Failed to retrieve user details."""
+
+
+class UserListError(ArangoServerError):
+    """Failed to retrieve users."""
+
+
+class UserReplaceError(ArangoServerError):
+    """Failed to replace user."""
+
+
+class UserUpdateError(ArangoServerError):
+    """Failed to update user."""

arangoasync/executor.py

@@ -0,0 +1,168 @@
+__all__ = [
+    "ApiExecutor",
+    "DefaultApiExecutor",
+    "NonAsyncExecutor",
+    "TransactionApiExecutor",
+    "AsyncApiExecutor",
+]
+
+from typing import Callable, Optional, TypeVar
+
+from arangoasync.connection import Connection
+from arangoasync.exceptions import AsyncExecuteError
+from arangoasync.job import AsyncJob
+from arangoasync.request import Request
+from arangoasync.response import Response
+from arangoasync.serialization import Deserializer, Serializer
+from arangoasync.typings import Json, Jsons
+
+T = TypeVar("T")
+
+
+class ExecutorContext:
+    """Base class for API executors.
+
+    Not to be exported publicly.
+
+    Args:
+        connection: HTTP connection.
+    """
+
+    def __init__(self, connection: Connection) -> None:
+        self._conn = connection
+
+    @property
+    def connection(self) -> Connection:
+        return self._conn
+
+    @property
+    def db_name(self) -> str:
+        return self._conn.db_name
+
+    @property
+    def serializer(self) -> Serializer[Json]:
+        return self._conn.serializer
+
+    @property
+    def deserializer(self) -> Deserializer[Json, Jsons]:
+        return self._conn.deserializer
+
+    def serialize(self, data: Json) -> str:
+        return self.serializer.dumps(data)
+
+    def deserialize(self, data: bytes) -> Json:
+        return self.deserializer.loads(data)
+
+
+class DefaultApiExecutor(ExecutorContext):
+    """Default API executor.
+
+    Responsible for executing requests and handling responses.
+
+    Args:
+        connection: HTTP connection.
+    """
+
+    def __init__(self, connection: Connection) -> None:
+        super().__init__(connection)
+
+    @property
+    def context(self) -> str:
+        return "default"
+
+    async def execute(
+        self, request: Request, response_handler: Callable[[Response], T]
+    ) -> T:
+        """Execute the request and handle the response.
+
+        Args:
+            request: HTTP request.
+            response_handler: HTTP response handler.
+        """
+        response = await self._conn.send_request(request)
+        return response_handler(response)
+
+
+class TransactionApiExecutor(ExecutorContext):
+    """Executes transaction API requests.
+
+    Args:
+        connection: HTTP connection.
+        transaction_id: str: Transaction ID generated by the server.
+    """
+
+    def __init__(self, connection: Connection, transaction_id: str) -> None:
+        super().__init__(connection)
+        self._id = transaction_id
+
+    @property
+    def context(self) -> str:
+        return "transaction"
+
+    @property
+    def id(self) -> str:
+        """Return the transaction ID."""
+        return self._id
+
+    async def execute(
+        self, request: Request, response_handler: Callable[[Response], T]
+    ) -> T:
+        """Execute the request and handle the response.
+
+        Args:
+            request: HTTP request.
+            response_handler: HTTP response handler.
+        """
+        request.headers["x-arango-trx-id"] = self.id
+        response = await self._conn.send_request(request)
+        return response_handler(response)
+
+
+class AsyncApiExecutor(ExecutorContext):
+    """Executes asynchronous API requests (jobs).
+
+    Args:
+        connection: HTTP connection.
+        return_result: If set to `True`, API executions return instances of
+        :class:`arangoasync.job.AsyncJob` and results can be retrieved from server
+        once available. If set to `False`, API executions return `None` and no
+        results are stored on server.
+    """
+
+    def __init__(self, connection: Connection, return_result: bool) -> None:
+        super().__init__(connection)
+        self._return_result = return_result
+
+    @property
+    def context(self) -> str:
+        return "async"
+
+    async def execute(
+        self, request: Request, response_handler: Callable[[Response], T]
+    ) -> Optional[AsyncJob[T]]:
+        """Execute an API request asynchronously.
+
+        Args:
+            request: HTTP request.
+            response_handler: HTTP response handler.
+
+        Returns: `AsyncJob` job or `None` if **return_result** parameter was set to
+            `False` during initialization.
+        """
+        if self._return_result:
+            request.headers["x-arango-async"] = "store"
+        else:
+            request.headers["x-arango-async"] = "true"
+
+        response = await self._conn.send_request(request)
+        if not response.is_success:
+            raise AsyncExecuteError(response, request)
+        if not self._return_result:
+            return None
+
+        job_id = response.headers["x-arango-async-id"]
+        return AsyncJob(self._conn, job_id, response_handler)
+
+
+ApiExecutor = DefaultApiExecutor | TransactionApiExecutor | AsyncApiExecutor
+NonAsyncExecutor = DefaultApiExecutor | TransactionApiExecutor