python-arango-async 0.0.2__tar.gz → 0.0.3__tar.gz

{python_arango_async-0.0.2 → python_arango_async-0.0.3}/.github/workflows/pypi.yaml

@@ -9,7 +9,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          fetch-tags: true
 
       - uses: actions/setup-python@v4
         with:

{python_arango_async-0.0.2/python_arango_async.egg-info → python_arango_async-0.0.3}/PKG-INFO

@@ -1,45 +1,23 @@
 Metadata-Version: 2.4
 Name: python-arango-async
-Version: 0.0.2
+Version: 0.0.3
 Summary: Async Python Driver for ArangoDB
 Author-email: Alexandru Petenchea <alexandru.petenchea@arangodb.com>, Anthony Mahanna <anthony.mahanna@arangodb.com>
 Maintainer-email: Alexandru Petenchea <alexandru.petenchea@arangodb.com>, Anthony Mahanna <anthony.mahanna@arangodb.com>
-License: MIT License
-        
-        Copyright (c) 2024 ArangoDB
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
+License-Expression: MIT
 Project-URL: homepage, https://github.com/arangodb/python-arango-async
 Keywords: arangodb,python,driver,async
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Documentation :: Sphinx
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: packaging>=23.1
@@ -68,7 +46,7 @@ Dynamic: license-file
 [![Last commit](https://img.shields.io/github/last-commit/arangodb/python-arango-async)](https://github.com/arangodb/python-arango-async/commits/main)
 
 [![PyPI version badge](https://img.shields.io/pypi/v/python-arango-async?color=3775A9&style=for-the-badge&logo=pypi&logoColor=FFD43B)](https://pypi.org/project/python-arango-async/)
-[![Python versions badge](https://img.shields.io/badge/3.9%2B-3776AB?style=for-the-badge&logo=python&logoColor=FFD43B&label=Python)](https://pypi.org/project/python-arango-async/)
+[![Python versions badge](https://img.shields.io/badge/3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=FFD43B&label=Python)](https://pypi.org/project/python-arango-async/)
 
 [![License](https://img.shields.io/github/license/arangodb/python-arango?color=9E2165&style=for-the-badge)](https://github.com/arangodb/python-arango/blob/main/LICENSE)
 [![Code style: black](https://img.shields.io/static/v1?style=for-the-badge&label=code%20style&message=black&color=black)](https://github.com/psf/black)
@@ -80,7 +58,7 @@ Dynamic: license-file
 Python driver for [ArangoDB](https://www.arangodb.com), a scalable multi-model
 database natively supporting documents, graphs and search.
 
-This is the _asyncio_ alternative of the officially supported [python-arango](https://github.com/arangodb/python-arango)
+This is the _asyncio_ alternative of the [python-arango](https://github.com/arangodb/python-arango)
 driver.
 
 **Note: This project is still in active development, features might be added or removed.**
@@ -88,7 +66,7 @@ driver.
 ## Requirements
 
 - ArangoDB version 3.11+
-- Python version 3.9+
+- Python version 3.10+
 
 ## Installation
 

{python_arango_async-0.0.2 → python_arango_async-0.0.3}/README.md

@@ -5,7 +5,7 @@
 [![Last commit](https://img.shields.io/github/last-commit/arangodb/python-arango-async)](https://github.com/arangodb/python-arango-async/commits/main)
 
 [![PyPI version badge](https://img.shields.io/pypi/v/python-arango-async?color=3775A9&style=for-the-badge&logo=pypi&logoColor=FFD43B)](https://pypi.org/project/python-arango-async/)
-[![Python versions badge](https://img.shields.io/badge/3.9%2B-3776AB?style=for-the-badge&logo=python&logoColor=FFD43B&label=Python)](https://pypi.org/project/python-arango-async/)
+[![Python versions badge](https://img.shields.io/badge/3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=FFD43B&label=Python)](https://pypi.org/project/python-arango-async/)
 
 [![License](https://img.shields.io/github/license/arangodb/python-arango?color=9E2165&style=for-the-badge)](https://github.com/arangodb/python-arango/blob/main/LICENSE)
 [![Code style: black](https://img.shields.io/static/v1?style=for-the-badge&label=code%20style&message=black&color=black)](https://github.com/psf/black)
@@ -17,7 +17,7 @@
 Python driver for [ArangoDB](https://www.arangodb.com), a scalable multi-model
 database natively supporting documents, graphs and search.
 
-This is the _asyncio_ alternative of the officially supported [python-arango](https://github.com/arangodb/python-arango)
+This is the _asyncio_ alternative of the [python-arango](https://github.com/arangodb/python-arango)
 driver.
 
 **Note: This project is still in active development, features might be added or removed.**
@@ -25,7 +25,7 @@ driver.
 ## Requirements
 
 - ArangoDB version 3.11+
-- Python version 3.9+
+- Python version 3.10+
 
 ## Installation
 

{python_arango_async-0.0.2 → python_arango_async-0.0.3}/arangoasync/aql.py

@@ -238,6 +238,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."""

{python_arango_async-0.0.2 → python_arango_async-0.0.3}/arangoasync/client.py

@@ -139,7 +139,9 @@ 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,

{python_arango_async-0.0.2 → python_arango_async-0.0.3}/arangoasync/collection.py

@@ -251,6 +251,15 @@ class Collection(Generic[T, U, V]):
         """
         return self._name
 
+    @property
+    def context(self) -> str:
+        """Return the context of the collection.
+
+        Returns:
+            str: Context.
+        """
+        return self._executor.context
+
     @property
     def db_name(self) -> str:
         """Return the name of the current database.
@@ -270,9 +279,17 @@ class Collection(Generic[T, U, V]):
         """Return the deserializer."""
         return self._executor.deserializer
 
-    async def indexes(self) -> Result[List[IndexProperties]]:
+    async def indexes(
+        self,
+        with_stats: Optional[bool] = None,
+        with_hidden: Optional[bool] = None,
+    ) -> Result[List[IndexProperties]]:
         """Fetch all index descriptions for the given collection.
 
+        Args:
+            with_stats (bool | None): Whether to include figures and estimates in the result.
+            with_hidden (bool | None): Whether to include hidden indexes in the result.
+
         Returns:
             list: List of index properties.
 
@@ -282,10 +299,16 @@ class Collection(Generic[T, U, V]):
         References:
             - `list-all-indexes-of-a-collection <https://docs.arangodb.com/stable/develop/http-api/indexes/#list-all-indexes-of-a-collection>`__
         """  # noqa: E501
+        params: Params = dict(collection=self._name)
+        if with_stats is not None:
+            params["withStats"] = with_stats
+        if with_hidden is not None:
+            params["withHidden"] = with_hidden
+
         request = Request(
             method=Method.GET,
             endpoint="/_api/index",
-            params=dict(collection=self._name),
+            params=params,
         )
 
         def response_handler(resp: Response) -> List[IndexProperties]:
@@ -564,6 +587,7 @@ class StandardCollection(Collection[T, U, V]):
         Raises:
             DocumentRevisionError: If the revision is incorrect.
             DocumentGetError: If retrieval fails.
+            DocumentParseError: If the document is malformed.
 
         References:
             - `get-a-document <https://docs.arangodb.com/stable/develop/http-api/documents/#get-a-document>`__
@@ -707,6 +731,7 @@ class StandardCollection(Collection[T, U, V]):
 
         Raises:
             DocumentInsertError: If insertion fails.
+            DocumentParseError: If the document is malformed.
 
         References:
             - `create-a-document <https://docs.arangodb.com/stable/develop/http-api/documents/#create-a-document>`__

{python_arango_async-0.0.2 → python_arango_async-0.0.3}/arangoasync/connection.py

@@ -177,6 +177,9 @@ class BaseConnection(ABC):
         host_index = self._host_resolver.get_host_index()
         for tries in range(self._host_resolver.max_tries):
             try:
+                logger.debug(
+                    f"Sending request to host {host_index} ({tries}): {request}"
+                )
                 resp = await self._http_client.send_request(
                     self._sessions[host_index], request
                 )

{python_arango_async-0.0.2 → python_arango_async-0.0.3}/arangoasync/database.py

@@ -596,7 +596,6 @@ class Database:
         )
 
         def response_handler(resp: Response) -> StandardCollection[T, U, V]:
-            nonlocal doc_serializer, doc_deserializer
             if not resp.is_success:
                 raise CollectionCreateError(resp, request)
             if doc_serializer is None:
@@ -648,7 +647,6 @@ class Database:
         )
 
         def response_handler(resp: Response) -> bool:
-            nonlocal ignore_missing
             if resp.is_success:
                 return True
             if resp.status_code == HTTP_NOT_FOUND and ignore_missing:
@@ -1001,7 +999,6 @@ class Database:
         )
 
         def response_handler(resp: Response) -> bool:
-            nonlocal ignore_failure
             if resp.is_success:
                 return True
             if ignore_failure:
@@ -1046,7 +1043,6 @@ class Database:
         )
 
         def response_handler(resp: Response) -> bool:
-            nonlocal ignore_failure
             if resp.is_success:
                 return True
             if ignore_failure:

{python_arango_async-0.0.2 → python_arango_async-0.0.3}/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 @@ class HTTPClient(ABC):  # pragma: no cover
         """
         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 @@ class AioHTTPClient(HTTPClient):
             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,

python_arango_async-0.0.3/arangoasync/version.py

@@ -0,0 +1 @@
+__version__ = "0.0.3"

python_arango_async-0.0.3/docs/aql.rst

@@ -0,0 +1,171 @@
+AQL
+----
+
+**ArangoDB Query Language (AQL)** is used to read and write data. It is similar
+to SQL for relational databases, but without the support for data definition
+operations such as creating or deleting :doc:`databases <database>`,
+:doc:`collections <collection>` or :doc:`indexes <indexes>`. For more
+information, refer to `ArangoDB Manual`_.
+
+.. _ArangoDB Manual: https://docs.arangodb.com
+
+AQL Queries
+===========
+
+AQL queries are invoked from AQL wrapper. Executing queries returns
+:doc:`cursors <cursor>`.
+
+**Example:**
+
+.. code-block:: python
+
+    from arangoasync import ArangoClient, AQLQueryKillError
+    from arangoasync.auth import Auth
+
+    # Initialize the client for ArangoDB.
+    async with ArangoClient(hosts="http://localhost:8529") as client:
+        auth = Auth(username="root", password="passwd")
+
+        # Connect to "test" database as root user.
+        db = await client.db("test", auth=auth)
+
+        # Get the API wrapper for "students" collection.
+        students = db.collection("students")
+
+        # Insert some test documents into "students" collection.
+        await students.insert_many([
+            {"_key": "Abby", "age": 22},
+            {"_key": "John", "age": 18},
+            {"_key": "Mary", "age": 21}
+        ])
+
+        # Get the AQL API wrapper.
+        aql = db.aql
+
+        # Retrieve the execution plan without running the query.
+        plan = await aql.explain("FOR doc IN students RETURN doc")
+
+        # Validate the query without executing it.
+        validate = await aql.validate("FOR doc IN students RETURN doc")
+
+        # Execute the query
+        cursor = await db.aql.execute(
+          "FOR doc IN students FILTER doc.age < @value RETURN doc",
+          bind_vars={"value": 19}
+        )
+
+        # Iterate through the result cursor
+        student_keys = []
+        async for doc in cursor:
+            student_keys.append(doc)
+
+        # List currently running queries.
+        queries = await aql.queries()
+
+        # List any slow queries.
+        slow_queries = await aql.slow_queries()
+
+        # Clear slow AQL queries if any.
+        await aql.clear_slow_queries()
+
+        # Retrieve AQL query tracking properties.
+        await aql.tracking()
+
+        # Configure AQL query tracking properties.
+        await aql.set_tracking(
+            max_slow_queries=10,
+            track_bind_vars=True,
+            track_slow_queries=True
+        )
+
+        # Kill a running query (this should fail due to invalid ID).
+        try:
+            await aql.kill("some_query_id")
+        except AQLQueryKillError as err:
+            assert err.http_code == 404
+
+See :class:`arangoasync.aql.AQL` for API specification.
+
+
+AQL User Functions
+==================
+
+**AQL User Functions** are custom functions you define in Javascript to extend
+AQL functionality. They are somewhat similar to SQL procedures.
+
+**Example:**
+
+.. code-block:: python
+
+    from arangoasync import ArangoClient
+    from arangoasync.auth import Auth
+
+    # Initialize the client for ArangoDB.
+    async with ArangoClient(hosts="http://localhost:8529") as client:
+        auth = Auth(username="root", password="passwd")
+
+        # Connect to "test" database as root user.
+        db = await client.db("test", auth=auth)
+
+        # Get the AQL API wrapper.
+        aql = db.aql
+
+        # Create a new AQL user function.
+        await aql.create_function(
+            # Grouping by name prefix is supported.
+            name="functions::temperature::converter",
+            code="function (celsius) { return celsius * 1.8 + 32; }"
+        )
+
+        # List AQL user functions.
+        functions = await aql.functions()
+
+        # Delete an existing AQL user function.
+        await aql.delete_function("functions::temperature::converter")
+
+See :class:`arangoasync.aql.AQL` for API specification.
+
+
+AQL Query Cache
+===============
+
+**AQL Query Cache** is used to minimize redundant calculation of the same query
+results. It is useful when read queries are issued frequently and write queries
+are not.
+
+**Example:**
+
+.. code-block:: python
+
+    from arangoasync import ArangoClient
+    from arangoasync.auth import Auth
+
+    # Initialize the client for ArangoDB.
+    async with ArangoClient(hosts="http://localhost:8529") as client:
+        auth = Auth(username="root", password="passwd")
+
+        # Connect to "test" database as root user.
+        db = await client.db("test", auth=auth)
+
+        # Get the AQL API wrapper.
+        aql = db.aql
+
+        # Retrieve AQL query cache properties.
+        await aql.cache.properties()
+
+        # Configure AQL query cache properties.
+        await aql.cache.configure(mode="demand", max_results=10000)
+
+        # List results cache entries.
+        entries = await aql.cache.entries()
+
+        # List plan cache entries.
+        plan_entries = await aql.cache.plan_entries()
+
+        # Clear results in AQL query cache.
+        await aql.cache.clear()
+
+        # Clear results in AQL query plan cache.
+        await aql.cache.clear_plan()
+
+See :class:`arangoasync.aql.AQLQueryCache` for API specification.

python_arango_async-0.0.3/docs/async.rst

@@ -0,0 +1,148 @@
+Async API Execution
+-------------------
+
+In **asynchronous API executions**, the driver sends API requests to ArangoDB in
+fire-and-forget style. The server processes them in the background, and
+the results can be retrieved once available via :class:`arangoasync.job.AsyncJob` objects.
+
+**Example:**
+
+.. code-block:: python
+
+    import time
+    from arangoasync import ArangoClient
+    from arangoasync.auth import Auth
+    from arangoasync.errno import HTTP_BAD_PARAMETER
+    from arangoasync.exceptions import (
+        AQLQueryExecuteError,
+        AsyncJobCancelError,
+        AsyncJobClearError,
+    )
+
+    # Initialize the client for ArangoDB.
+    async with ArangoClient(hosts="http://localhost:8529") as client:
+        auth = Auth(username="root", password="passwd")
+
+        # Connect to "test" database as root user.
+        db = await client.db("test", auth=auth)
+
+        # Begin async execution. This returns an instance of AsyncDatabase, a
+        # database-level API wrapper tailored specifically for async execution.
+        async_db = db.begin_async_execution(return_result=True)
+
+        # Child wrappers are also tailored for async execution.
+        async_aql = async_db.aql
+        async_col = async_db.collection("students")
+
+        # API execution context is always set to "async".
+        assert async_db.context == "async"
+        assert async_aql.context == "async"
+        assert async_col.context == "async"
+
+        # On API execution, AsyncJob objects are returned instead of results.
+        job1 = await async_col.insert({"_key": "Neal"})
+        job2 = await async_col.insert({"_key": "Lily"})
+        job3 = await async_aql.execute("RETURN 100000")
+        job4 = await async_aql.execute("INVALID QUERY")  # Fails due to syntax error.
+
+        # Retrieve the status of each async job.
+        for job in [job1, job2, job3, job4]:
+            # Job status can be "pending" or "done".
+            assert await job.status() in {"pending", "done"}
+
+            # Let's wait until the jobs are finished.
+            while await job.status() != "done":
+                time.sleep(0.1)
+
+        # Retrieve the results of successful jobs.
+        metadata = await job1.result()
+        assert metadata["_id"] == "students/Neal"
+
+        metadata = await job2.result()
+        assert metadata["_id"] == "students/Lily"
+
+        cursor = await job3.result()
+        assert await cursor.next() == 100000
+
+        # If a job fails, the exception is propagated up during result retrieval.
+        try:
+            result = await job4.result()
+        except AQLQueryExecuteError as err:
+            assert err.http_code == HTTP_BAD_PARAMETER
+
+        # Cancel a job. Only pending jobs still in queue may be cancelled.
+        # Since job3 is done, there is nothing to cancel and an exception is raised.
+        try:
+            await job3.cancel()
+        except AsyncJobCancelError as err:
+            print(err.message)
+
+        # Clear the result of a job from ArangoDB server to free up resources.
+        # Result of job4 was removed from the server automatically upon retrieval,
+        # so attempt to clear it raises an exception.
+        try:
+            await job4.clear()
+        except AsyncJobClearError as err:
+            print(err.message)
+
+        # List the IDs of the first 100 async jobs completed.
+        jobs_done = await db.async_jobs(status="done", count=100)
+
+        # List the IDs of the first 100 async jobs still pending.
+        jobs_pending = await db.async_jobs(status='pending', count=100)
+
+        # Clear all async jobs still sitting on the server.
+        await db.clear_async_jobs()
+
+Cursors returned from async API wrappers will no longer send async requests when they fetch more results, but behave
+like regular cursors instead. This makes sense, because the point of cursors is iteration, whereas async jobs are meant
+for one-shot requests. However, the first result retrieval is still async, and only then the cursor is returned, making
+async AQL requests effective for queries with a long execution time.
+
+**Example:**
+
+.. code-block:: python
+
+    from arangoasync import ArangoClient
+    from arangoasync.auth import Auth
+
+    # Initialize the client for ArangoDB.
+    async with ArangoClient(hosts="http://localhost:8529") as client:
+        auth = Auth(username="root", password="passwd")
+
+        # Connect to "test" database as root user.
+        db = await client.db("test", auth=auth)
+
+        # Get the API wrapper for "students" collection.
+        students = db.collection("students")
+
+        # Insert some documents into the collection.
+        await students.insert_many([{"_key": "Neal"}, {"_key": "Lily"}])
+
+        # Begin async execution.
+        async_db = db.begin_async_execution(return_result=True)
+
+        aql = async_db.aql
+        job = await aql.execute(
+            f"FOR d IN {students.name} SORT d._key RETURN d",
+            count=True,
+            batch_size=1,
+            ttl=1000,
+        )
+        await job.wait()
+
+        # Iterate through the cursor.
+        # Although the request to fetch the cursor is async, its underlying executor is no longer async.
+        # Next batches will be fetched in real-time.
+        doc_cnt = 0
+        cursor = await job.result()
+        async with cursor as ctx:
+            async for _ in ctx:
+                doc_cnt += 1
+        assert doc_cnt == 2
+
+.. note::
+    Be mindful of server-side memory capacity when issuing a large number of
+    async requests in small time interval.
+
+See :class:`arangoasync.database.AsyncDatabase` and :class:`arangoasync.job.AsyncJob` for API specification.