python-arango-async 0.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

arangoasync/aql.py

@@ -16,6 +16,7 @@ from arangoasync.exceptions import (
     AQLQueryClearError,
     AQLQueryExecuteError,
     AQLQueryExplainError,
+    AQLQueryHistoryError,
     AQLQueryKillError,
     AQLQueryListError,
     AQLQueryRulesGetError,
@@ -77,7 +78,7 @@ class AQLQueryCache:
             AQLCacheEntriesError: If retrieval fails.
 
         References:
-            - `list-the-entries-of-the-aql-query-results-cache <https://docs.arangodb.com/stable/develop/http-api/queries/aql-query-results-cache/#list-the-entries-of-the-aql-query-results-cache>`__
+            - `list-the-entries-of-the-aql-query-results-cache <https://docs.arango.ai/stable/develop/http-api/queries/aql-query-results-cache/#list-the-entries-of-the-aql-query-results-cache>`__
         """  # noqa: E501
         request = Request(method=Method.GET, endpoint="/_api/query-cache/entries")
 
@@ -98,7 +99,7 @@ class AQLQueryCache:
             AQLCacheEntriesError: If retrieval fails.
 
         References:
-            - `list-the-entries-of-the-aql-query-plan-cache <https://docs.arangodb.com/stable/develop/http-api/queries/aql-query-plan-cache/#list-the-entries-of-the-aql-query-plan-cache>`__
+            - `list-the-entries-of-the-aql-query-plan-cache <https://docs.arango.ai/stable/develop/http-api/queries/aql-query-plan-cache/#list-the-entries-of-the-aql-query-plan-cache>`__
         """  # noqa: E501
         request = Request(method=Method.GET, endpoint="/_api/query-plan-cache")
 
@@ -116,7 +117,7 @@ class AQLQueryCache:
             AQLCacheClearError: If clearing the cache fails.
 
         References:
-            - `clear-the-aql-query-results-cache <https://docs.arangodb.com/stable/develop/http-api/queries/aql-query-results-cache/#clear-the-aql-query-results-cache>`__
+            - `clear-the-aql-query-results-cache <https://docs.arango.ai/stable/develop/http-api/queries/aql-query-results-cache/#clear-the-aql-query-results-cache>`__
         """  # noqa: E501
         request = Request(method=Method.DELETE, endpoint="/_api/query-cache")
 
@@ -133,7 +134,7 @@ class AQLQueryCache:
             AQLCacheClearError: If clearing the cache fails.
 
         References:
-            - `clear-the-aql-query-plan-cache <https://docs.arangodb.com/stable/develop/http-api/queries/aql-query-plan-cache/#clear-the-aql-query-plan-cache>`__
+            - `clear-the-aql-query-plan-cache <https://docs.arango.ai/stable/develop/http-api/queries/aql-query-plan-cache/#clear-the-aql-query-plan-cache>`__
         """  # noqa: E501
         request = Request(method=Method.DELETE, endpoint="/_api/query-plan-cache")
 
@@ -153,7 +154,7 @@ class AQLQueryCache:
             AQLCachePropertiesError: If retrieval fails.
 
         References:
-            - `get-the-aql-query-results-cache-configuration <https://docs.arangodb.com/stable/develop/http-api/queries/aql-query-results-cache/#get-the-aql-query-results-cache-configuration>`__
+            - `get-the-aql-query-results-cache-configuration <https://docs.arango.ai/stable/develop/http-api/queries/aql-query-results-cache/#get-the-aql-query-results-cache-configuration>`__
         """  # noqa: E501
         request = Request(method=Method.GET, endpoint="/_api/query-cache/properties")
 
@@ -192,7 +193,7 @@ class AQLQueryCache:
             AQLCacheConfigureError: If setting the configuration fails.
 
         References:
-            - `set-the-aql-query-results-cache-configuration <https://docs.arangodb.com/stable/develop/http-api/queries/aql-query-results-cache/#set-the-aql-query-results-cache-configuration>`__
+            - `set-the-aql-query-results-cache-configuration <https://docs.arango.ai/stable/develop/http-api/queries/aql-query-results-cache/#set-the-aql-query-results-cache-configuration>`__
         """  # noqa: E501
         data: Json = dict()
         if mode is not None:
@@ -238,6 +239,11 @@ class AQL:
         """Return the name of the current database."""
         return self._executor.db_name
 
+    @property
+    def context(self) -> str:
+        """Return the current API execution context."""
+        return self._executor.context
+
     @property
     def serializer(self) -> Serializer[Json]:
         """Return the serializer."""
@@ -292,7 +298,7 @@ class AQL:
             Cursor: Result cursor.
 
         References:
-            - `create-a-cursor <https://docs.arangodb.com/stable/develop/http-api/queries/aql-queries/#create-a-cursor>`__
+            - `create-a-cursor <https://docs.arango.ai/stable/develop/http-api/queries/aql-queries/#create-a-cursor>`__
         """  # noqa: E501
         data: Json = dict(query=query)
         if count is not None:
@@ -347,7 +353,7 @@ class AQL:
             AQLQueryTrackingGetError: If retrieval fails.
 
         References:
-            - `get-the-aql-query-tracking-configuration <https://docs.arangodb.com/stable/develop/http-api/queries/aql-queries/#get-the-aql-query-tracking-configuration>`__
+            - `get-the-aql-query-tracking-configuration <https://docs.arango.ai/stable/develop/http-api/queries/aql-queries/#get-the-aql-query-tracking-configuration>`__
         """  # noqa: E501
         request = Request(method=Method.GET, endpoint="/_api/query/properties")
 
@@ -391,7 +397,7 @@ class AQL:
             AQLQueryTrackingSetError: If setting the configuration fails.
 
         References:
-            - `update-the-aql-query-tracking-configuration <https://docs.arangodb.com/stable/develop/http-api/queries/aql-queries/#update-the-aql-query-tracking-configuration>`__
+            - `update-the-aql-query-tracking-configuration <https://docs.arango.ai/stable/develop/http-api/queries/aql-queries/#update-the-aql-query-tracking-configuration>`__
         """  # noqa: E501
         data: Json = dict()
 
@@ -421,6 +427,25 @@ class AQL:
 
         return await self._executor.execute(request, response_handler)
 
+    async def history(self) -> Result[Json]:
+        """Return recently executed AQL queries (admin only).
+
+        Returns:
+            dict: AQL query history.
+
+        Raises:
+            AQLQueryHistoryError: If retrieval fails.
+        """
+        request = Request(method=Method.GET, endpoint="/_admin/server/aql-queries")
+
+        def response_handler(resp: Response) -> Json:
+            if not resp.is_success:
+                raise AQLQueryHistoryError(resp, request)
+            result: Json = self.deserializer.loads(resp.raw_body)
+            return cast(Json, result["result"])
+
+        return await self._executor.execute(request, response_handler)
+
     async def queries(self, all_queries: bool = False) -> Result[Jsons]:
         """Return a list of currently running queries.
 
@@ -437,7 +462,7 @@ class AQL:
             AQLQueryListError: If retrieval fails.
 
         References:
-            - `list-the-running-queries <https://docs.arangodb.com/stable/develop/http-api/queries/aql-queries/#list-the-running-queries>`__
+            - `list-the-running-queries <https://docs.arango.ai/stable/develop/http-api/queries/aql-queries/#list-the-running-queries>`__
         """  # noqa: E501
         request = Request(
             method=Method.GET,
@@ -468,7 +493,7 @@ class AQL:
             AQLQueryListError: If retrieval fails.
 
         References:
-            - `list-the-slow-aql-queries <https://docs.arangodb.com/stable/develop/http-api/queries/aql-queries/#list-the-slow-aql-queries>`__
+            - `list-the-slow-aql-queries <https://docs.arango.ai/stable/develop/http-api/queries/aql-queries/#list-the-slow-aql-queries>`__
         """  # noqa: E501
         request = Request(
             method=Method.GET,
@@ -498,7 +523,7 @@ class AQL:
             AQLQueryClearError: If retrieval fails.
 
         References:
-            - `clear-the-list-of-slow-aql-queries <https://docs.arangodb.com/stable/develop/http-api/queries/aql-queries/#clear-the-list-of-slow-aql-queries>`__
+            - `clear-the-list-of-slow-aql-queries <https://docs.arango.ai/stable/develop/http-api/queries/aql-queries/#clear-the-list-of-slow-aql-queries>`__
         """  # noqa: E501
         request = Request(
             method=Method.DELETE,
@@ -535,7 +560,7 @@ class AQL:
             AQLQueryKillError: If killing the query fails.
 
         References:
-            - `kill-a-running-aql-query <https://docs.arangodb.com/stable/develop/http-api/queries/aql-queries/#kill-a-running-aql-query>`__
+            - `kill-a-running-aql-query <https://docs.arango.ai/stable/develop/http-api/queries/aql-queries/#kill-a-running-aql-query>`__
         """  # noqa: E501
         request = Request(
             method=Method.DELETE,
@@ -573,7 +598,7 @@ class AQL:
             AQLQueryExplainError: If retrieval fails.
 
         References:
-            - `explain-an-aql-query <https://docs.arangodb.com/stable/develop/http-api/queries/aql-queries/#explain-an-aql-query>`__
+            - `explain-an-aql-query <https://docs.arango.ai/stable/develop/http-api/queries/aql-queries/#explain-an-aql-query>`__
         """  # noqa: E501
         data: Json = dict(query=query)
         if bind_vars is not None:
@@ -592,7 +617,7 @@ class AQL:
         def response_handler(resp: Response) -> Json:
             if not resp.is_success:
                 raise AQLQueryExplainError(resp, request)
-            return self.deserializer.loads(resp.raw_body)
+            return Response.format_body(self.deserializer.loads(resp.raw_body))
 
         return await self._executor.execute(request, response_handler)
 
@@ -609,7 +634,7 @@ class AQL:
             AQLQueryValidateError: If validation fails.
 
         References:
-            - `parse-an-aql-query <https://docs.arangodb.com/stable/develop/http-api/queries/aql-queries/#parse-an-aql-query>`__
+            - `parse-an-aql-query <https://docs.arango.ai/stable/develop/http-api/queries/aql-queries/#parse-an-aql-query>`__
         """  # noqa: E501
         request = Request(
             method=Method.POST,
@@ -620,7 +645,7 @@ class AQL:
         def response_handler(resp: Response) -> Json:
             if not resp.is_success:
                 raise AQLQueryValidateError(resp, request)
-            return self.deserializer.loads(resp.raw_body)
+            return Response.format_body(self.deserializer.loads(resp.raw_body))
 
         return await self._executor.execute(request, response_handler)
 
@@ -634,7 +659,7 @@ class AQL:
             AQLQueryRulesGetError: If retrieval fails.
 
         References:
-            - `list-all-aql-optimizer-rules <https://docs.arangodb.com/stable/develop/http-api/queries/aql-queries/#list-all-aql-optimizer-rules>`__
+            - `list-all-aql-optimizer-rules <https://docs.arango.ai/stable/develop/http-api/queries/aql-queries/#list-all-aql-optimizer-rules>`__
         """  # noqa: E501
         request = Request(method=Method.GET, endpoint="/_api/query/rules")
 
@@ -659,7 +684,7 @@ class AQL:
             AQLFunctionListError: If retrieval fails.
 
         References:
-            - `list-the-registered-user-defined-aql-functions <https://docs.arangodb.com/stable/develop/http-api/queries/user-defined-aql-functions/#list-the-registered-user-defined-aql-functions>`__
+            - `list-the-registered-user-defined-aql-functions <https://docs.arango.ai/stable/develop/http-api/queries/user-defined-aql-functions/#list-the-registered-user-defined-aql-functions>`__
         """  # noqa: E501
         params: Json = dict()
         if namespace is not None:
@@ -701,7 +726,7 @@ class AQL:
             AQLFunctionCreateError: If registration fails.
 
         References:
-            - `create-a-user-defined-aql-function <https://docs.arangodb.com/stable/develop/http-api/queries/user-defined-aql-functions/#create-a-user-defined-aql-function>`__
+            - `create-a-user-defined-aql-function <https://docs.arango.ai/stable/develop/http-api/queries/user-defined-aql-functions/#create-a-user-defined-aql-function>`__
         """  # noqa: E501
         request = Request(
             method=Method.POST,
@@ -714,7 +739,7 @@ class AQL:
         def response_handler(resp: Response) -> Json:
             if not resp.is_success:
                 raise AQLFunctionCreateError(resp, request)
-            return self.deserializer.loads(resp.raw_body)
+            return Response.format_body(self.deserializer.loads(resp.raw_body))
 
         return await self._executor.execute(request, response_handler)
 
@@ -740,7 +765,7 @@ class AQL:
             AQLFunctionDeleteError: If removal fails.
 
         References:
-            - `remove-a-user-defined-aql-function <https://docs.arangodb.com/stable/develop/http-api/queries/user-defined-aql-functions/#remove-a-user-defined-aql-function>`__
+            - `remove-a-user-defined-aql-function <https://docs.arango.ai/stable/develop/http-api/queries/user-defined-aql-functions/#remove-a-user-defined-aql-function>`__
         """  # noqa: E501
         params: Json = dict()
         if group is not None:
@@ -755,6 +780,6 @@ class AQL:
             if not resp.is_success:
                 if not (resp.status_code == HTTP_NOT_FOUND and ignore_missing):
                     raise AQLFunctionDeleteError(resp, request)
-            return self.deserializer.loads(resp.raw_body)
+            return Response.format_body(self.deserializer.loads(resp.raw_body))
 
         return await self._executor.execute(request, response_handler)

arangoasync/auth.py

@@ -20,8 +20,8 @@ class Auth:
         encoding (str): Encoding for the password (default: utf-8)
     """
 
-    username: str
-    password: str
+    username: str = ""
+    password: str = ""
     encoding: str = "utf-8"
 
 

arangoasync/backup.py

@@ -0,0 +1,295 @@
+__all__ = ["Backup"]
+
+from numbers import Number
+from typing import Optional, cast
+
+from arangoasync.exceptions import (
+    BackupCreateError,
+    BackupDeleteError,
+    BackupDownloadError,
+    BackupGetError,
+    BackupRestoreError,
+    BackupUploadError,
+)
+from arangoasync.executor import ApiExecutor
+from arangoasync.request import Method, Request
+from arangoasync.response import Response
+from arangoasync.result import Result
+from arangoasync.serialization import Deserializer, Serializer
+from arangoasync.typings import Json, Jsons
+
+
+class Backup:
+    """Backup API wrapper."""
+
+    def __init__(self, executor: ApiExecutor) -> None:
+        self._executor = executor
+
+    @property
+    def serializer(self) -> Serializer[Json]:
+        """Return the serializer."""
+        return self._executor.serializer
+
+    @property
+    def deserializer(self) -> Deserializer[Json, Jsons]:
+        """Return the deserializer."""
+        return self._executor.deserializer
+
+    async def get(self, backup_id: Optional[str] = None) -> Result[Json]:
+        """Return backup details.
+
+        Args:
+            backup_id (str | None): If set, the returned list is restricted to the
+                backup with the given id.
+
+        Returns:
+            dict: Backup details.
+
+        Raises:
+            BackupGetError: If the operation fails.
+
+        References:
+            - `list-backups <https://docs.arango.ai/stable/develop/http-api/hot-backups/#list-all-backups>`__
+        """  # noqa: E501
+        data: Json = {}
+        if backup_id is not None:
+            data["id"] = backup_id
+
+        request = Request(
+            method=Method.POST,
+            endpoint="/_admin/backup/list",
+            data=self.serializer.dumps(data) if data else None,
+            prefix_needed=False,
+        )
+
+        def response_handler(resp: Response) -> Json:
+            if not resp.is_success:
+                raise BackupGetError(resp, request)
+            result: Json = self.deserializer.loads(resp.raw_body)
+            return cast(Json, result["result"])
+
+        return await self._executor.execute(request, response_handler)
+
+    async def create(
+        self,
+        label: Optional[str] = None,
+        allow_inconsistent: Optional[bool] = None,
+        force: Optional[bool] = None,
+        timeout: Optional[Number] = None,
+    ) -> Result[Json]:
+        """Create a backup when the global write lock can be obtained.
+
+        Args:
+            label (str | None): Label for this backup. If not specified, a UUID is used.
+            allow_inconsistent (bool | None): Allow inconsistent backup when the global
+                transaction lock cannot be acquired before timeout.
+            force (bool | None): Forcefully abort all running transactions to ensure a
+                consistent backup when the global transaction lock cannot be
+                acquired before timeout. Default (and highly recommended) value
+                is `False`.
+            timeout (float | None): The time in seconds that the operation tries to
+                get a consistent snapshot.
+
+        Returns:
+            dict: Backup information.
+
+        Raises:
+            BackupCreateError: If the backup creation fails.
+
+        References:
+            - `create-backup <https://docs.arango.ai/stable/develop/http-api/hot-backups/#create-a-backup>`__
+        """  # noqa: E501
+        data: Json = {}
+        if label is not None:
+            data["label"] = label
+        if allow_inconsistent is not None:
+            data["allowInconsistent"] = allow_inconsistent
+        if force is not None:
+            data["force"] = force
+        if timeout is not None:
+            data["timeout"] = timeout
+
+        request = Request(
+            method=Method.POST,
+            endpoint="/_admin/backup/create",
+            data=self.serializer.dumps(data),
+            prefix_needed=False,
+        )
+
+        def response_handler(resp: Response) -> Json:
+            if not resp.is_success:
+                raise BackupCreateError(resp, request)
+            result: Json = self.deserializer.loads(resp.raw_body)
+            return cast(Json, result["result"])
+
+        return await self._executor.execute(request, response_handler)
+
+    async def restore(self, backup_id: str) -> Result[Json]:
+        """Restore a local backup.
+
+        Args:
+            backup_id (str): Backup ID.
+
+        Returns:
+            dict: Result of the restore operation.
+
+        Raises:
+            BackupRestoreError: If the restore operation fails.
+
+        References:
+            - `restore-backup <https://docs.arango.ai/stable/develop/http-api/hot-backups/#restore-a-backup>`__
+        """  # noqa: E501
+        data: Json = {"id": backup_id}
+        request = Request(
+            method=Method.POST,
+            endpoint="/_admin/backup/restore",
+            data=self.serializer.dumps(data),
+            prefix_needed=False,
+        )
+
+        def response_handler(resp: Response) -> Json:
+            if not resp.is_success:
+                raise BackupRestoreError(resp, request)
+            result: Json = self.deserializer.loads(resp.raw_body)
+            return cast(Json, result["result"])
+
+        return await self._executor.execute(request, response_handler)
+
+    async def delete(self, backup_id: str) -> None:
+        """Delete a backup.
+
+        Args:
+            backup_id (str): Backup ID.
+
+        Raises:
+            BackupDeleteError: If the delete operation fails.
+
+        References:
+            - `delete-backup <https://docs.arango.ai/stable/develop/http-api/hot-backups/#delete-a-backup>`__
+        """  # noqa: E501
+        data: Json = {"id": backup_id}
+        request = Request(
+            method=Method.POST,
+            endpoint="/_admin/backup/delete",
+            data=self.serializer.dumps(data),
+            prefix_needed=False,
+        )
+
+        def response_handler(resp: Response) -> None:
+            if not resp.is_success:
+                raise BackupDeleteError(resp, request)
+
+        await self._executor.execute(request, response_handler)
+
+    async def upload(
+        self,
+        backup_id: Optional[str] = None,
+        repository: Optional[str] = None,
+        abort: Optional[bool] = None,
+        config: Optional[Json] = None,
+        upload_id: Optional[str] = None,
+    ) -> Result[Json]:
+        """Manage backup uploads.
+
+        Args:
+            backup_id (str | None): Backup ID used for scheduling an upload. Mutually
+                exclusive with parameter **upload_id**.
+            repository (str | None): Remote repository URL(e.g. "local://tmp/backups").
+            abort (str | None): If set to `True`, running upload is aborted. Used with
+                parameter **upload_id**.
+            config (dict | None): Remote repository configuration. Required for scheduling
+                an upload and mutually exclusive with parameter **upload_id**.
+            upload_id (str | None): Upload ID. Mutually exclusive with parameters
+                **backup_id**, **repository**, and **config**.
+
+        Returns:
+            dict: Upload details.
+
+        Raises:
+            BackupUploadError: If upload operation fails.
+
+        References:
+            - `upload-a-backup-to-a-remote-repository <https://docs.arango.ai/stable/develop/http-api/hot-backups/#upload-a-backup-to-a-remote-repository>`__
+        """  # noqa: E501
+        data: Json = {}
+        if upload_id is not None:
+            data["uploadId"] = upload_id
+        if backup_id is not None:
+            data["id"] = backup_id
+        if repository is not None:
+            data["remoteRepository"] = repository
+        if abort is not None:
+            data["abort"] = abort
+        if config is not None:
+            data["config"] = config
+
+        request = Request(
+            method=Method.POST,
+            endpoint="/_admin/backup/upload",
+            data=self.serializer.dumps(data),
+            prefix_needed=False,
+        )
+
+        def response_handler(resp: Response) -> Json:
+            if not resp.is_success:
+                raise BackupUploadError(resp, request)
+            result: Json = self.deserializer.loads(resp.raw_body)
+            return cast(Json, result["result"])
+
+        return await self._executor.execute(request, response_handler)
+
+    async def download(
+        self,
+        backup_id: Optional[str] = None,
+        repository: Optional[str] = None,
+        abort: Optional[bool] = None,
+        config: Optional[Json] = None,
+        download_id: Optional[str] = None,
+    ) -> Result[Json]:
+        """Manage backup downloads.
+
+        Args:
+            backup_id (str | None): Backup ID used for scheduling a download. Mutually
+                exclusive with parameter **download_id**.
+            repository (str | None): Remote repository URL (e.g. "local://tmp/backups").
+            abort (bool | None): If set to `True`, running download is aborted.
+            config (dict | None): Remote repository configuration. Required for scheduling
+                a download and mutually exclusive with parameter **download_id**.
+            download_id (str | None): Download ID. Mutually exclusive with parameters
+                **backup_id**, **repository**, and **config**.
+
+        Returns:
+            dict: Download details.
+
+        Raises:
+            BackupDownloadError: If the download operation fails.
+
+        References:
+            - `download-a-backup-from-a-remote-repository <https://docs.arango.ai/stable/develop/http-api/hot-backups/#download-a-backup-from-a-remote-repository>`__
+        """  # noqa: E501
+        data: Json = {}
+        if download_id is not None:
+            data["downloadId"] = download_id
+        if backup_id is not None:
+            data["id"] = backup_id
+        if repository is not None:
+            data["remoteRepository"] = repository
+        if abort is not None:
+            data["abort"] = abort
+        if config is not None:
+            data["config"] = config
+
+        request = Request(
+            method=Method.POST,
+            endpoint="/_admin/backup/download",
+            data=self.serializer.dumps(data),
+            prefix_needed=False,
+        )
+
+        def response_handler(resp: Response) -> Json:
+            if not resp.is_success:
+                raise BackupDownloadError(resp, request)
+            result: Json = self.deserializer.loads(resp.raw_body)
+            return cast(Json, result["result"])
+
+        return await self._executor.execute(request, response_handler)

arangoasync/client.py

@@ -139,13 +139,15 @@ class ArangoClient:
 
     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,
         name: str,
         auth_method: str = "basic",
-        auth: Optional[Auth] = None,
+        auth: Optional[Auth | str] = None,
         token: Optional[JwtToken] = None,
         verify: bool = False,
         compression: Optional[CompressionManager] = None,
@@ -167,7 +169,8 @@ class ArangoClient:
                     and client are synchronized.
                 - "superuser": Superuser JWT authentication.
                     The `token` parameter is required. The `auth` parameter is ignored.
-            auth (Auth | None): Login information.
+            auth (Auth | None): Login information (username and password) or
+                access token.
             token (JwtToken | None): JWT token.
             verify (bool): Verify the connection by sending a test request.
             compression (CompressionManager | None): If set, supersedes the
@@ -186,6 +189,9 @@ class ArangoClient:
         """
         connection: Connection
 
+        if isinstance(auth, str):
+            auth = Auth(password=auth)
+
         if auth_method == "basic":
             if auth is None:
                 raise ValueError("Basic authentication requires the `auth` parameter")