Completed helpers documentation

Author: apetenchea

docs/helpers.rst

@@ -0,0 +1,86 @@
+Helper Types
+------------
+
+The driver comes with a set of helper types and wrappers to make it easier to work with the ArangoDB API. These are
+designed to behave like dictionaries, but with some additional features and methods. See the :class:`arangoasync.typings.JsonWrapper` class for more details.
+
+**Example:**
+
+.. code-block:: python
+
+    from arangoasync import ArangoClient
+    from arangoasync.auth import Auth
+    from arangoasync.typings import QueryProperties
+
+    # 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)
+
+        properties = QueryProperties(
+            allow_dirty_reads=True,
+            allow_retry=False,
+            fail_on_warning=True,
+            fill_block_cache=False,
+            full_count=True,
+            intermediate_commit_count=1000,
+            intermediate_commit_size=1048576,
+            max_dnf_condition_members=10,
+            max_nodes_per_callstack=100,
+            max_number_of_plans=5,
+            max_runtime=60.0,
+            max_transaction_size=10485760,
+            max_warning_count=10,
+            optimizer={"rules": ["-all", "+use-indexes"]},
+            profile=1,
+            satellite_sync_wait=10.0,
+            skip_inaccessible_collections=True,
+            spill_over_threshold_memory_usage=10485760,
+            spill_over_threshold_num_rows=100000,
+            stream=True,
+            use_plan_cache=True,
+        )
+
+        # The types are fully serializable.
+        print(properties)
+
+        await db.aql.execute(
+            "FOR doc IN students RETURN doc",
+            batch_size=1,
+            options=properties,
+        )
+
+You can easily customize the data representation using formatters. By default, keys are in the format used by the ArangoDB
+API, but you can change them to snake_case if you prefer. See :func:`arangoasync.typings.JsonWrapper.format` for more details.
+
+**Example:**
+
+.. code-block:: python
+
+    from arangoasync.typings import Json, UserInfo
+
+    data = {
+        "user": "john",
+        "password": "secret",
+        "active": True,
+        "extra": {"role": "admin"},
+    }
+    user_info = UserInfo(**data)
+
+    def uppercase_formatter(data: Json) -> Json:
+        result: Json = {}
+        for key, value in data.items():
+            result[key.upper()] = value
+        return result
+
+    print(user_info.format(uppercase_formatter))
+
+Helpers
+=======
+
+Below are all the available helpers.
+
+.. automodule:: arangoasync.typings
+    :members:

docs/index.rst

@@ -68,6 +68,7 @@ Contents
     errors
     errno
     logging
+    helpers
 
 **Development**
 

docs/specs.rst

@@ -46,8 +46,5 @@ python-arango-async.
 .. automodule:: arangoasync.response
     :members:
 
-.. automodule:: arangoasync.typings
-    :members:
-
 .. automodule:: arangoasync.result
     :members: