Adding more documentation (#45)

* Adding more documentation

* Minor edit

* No longer using testcode

* Completed transactions documentation

* Completed async documentation

* Completed user documentation

* Completed overview documentation

* Completed overview documentation

* Completed cursor documentation

* Completed errno documentation

* Completed errors documentation

* Completed compression documentation

* Completed logging documentation

* Completed helpers documentation

* Fixing test and lint

* Added authentication documentation

* Minor fixes

* TLS docs

* HTTP docs

* Serialization docs

* Migration docs

Author: apetenchea

README.md

@@ -17,15 +17,15 @@
 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.**
 
 ## Requirements
 
 - ArangoDB version 3.11+
-- Python version 3.9+
+- Python version 3.10+
 
 ## Installation
 

arangoasync/aql.py

@@ -238,6 +238,11 @@ def name(self) -> str:
         """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."""

arangoasync/client.py

@@ -139,7 +139,9 @@ def version(self) -> str:
 
     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,

arangoasync/collection.py

@@ -251,6 +251,15 @@ def name(self) -> str:
         """
         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 @@ def deserializer(self) -> Deserializer[Json, Jsons]:
         """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 @@ async def indexes(self) -> Result[List[IndexProperties]]:
         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 @@ async def get(
         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 @@ async def insert(
 
         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>`__

arangoasync/connection.py

@@ -177,6 +177,9 @@ async def process_request(self, request: Request) -> Response:
         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
                 )

arangoasync/database.py

@@ -596,7 +596,6 @@ async def create_collection(
         )
 
         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 @@ async def delete_collection(
         )
 
         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 @@ async def update_permission(
         )
 
         def response_handler(resp: Response) -> bool:
-            nonlocal ignore_failure
             if resp.is_success:
                 return True
             if ignore_failure:
@@ -1046,7 +1043,6 @@ async def reset_permission(
         )
 
         def response_handler(resp: Response) -> bool:
-            nonlocal ignore_failure
             if resp.is_success:
                 return True
             if ignore_failure:

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 @@ def create_session(self, host: str) -> Any:
         """
         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 @@ def create_session(self, host: str) -> ClientSession:
             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,

docs/aql.rst

@@ -5,6 +5,167 @@ AQL
 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`_.
+information, refer to `ArangoDB Manual`_.
 
-.. _ArangoDB manual: https://docs.arangodb.com
+.. _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.