Coming from python-arango

Generally, migrating from python-arango should be a smooth transition. For the most part, the API is similar, but there are a few things to note.

Helpers

The current driver comes with Helper Types, because we want to:

Facilitate better type hinting and auto-completion in IDEs.
Ensure an easier 1-to-1 mapping of the ArangoDB API.

For example, coming from the synchronous driver, creating a new user looks like this:

sys_db.create_user(
    username="johndoe@gmail.com",
    password="first_password",
    active=True,
    extra={"team": "backend", "title": "engineer"}
)

In the asynchronous driver, it looks like this:

from arangoasync.typings import UserInfo

user_info = UserInfo(
    username="johndoe@gmail.com",
    password="first_password",
    active=True,
    extra={"team": "backend", "title": "engineer"}
)
await sys_db.create_user(user_info)

CamelCase vs. snake_case

Upon returning results, for the most part, the synchronous driver mostly tries to stick to snake case. Unfortunately, this is not always consistent.

status = db.status()
assert "host" in status
assert "operation_mode" in status

The asynchronous driver, however, tries to stick to a simple rule:

If the API returns a camel case key, it will be returned as is. The response is returned from the server as is.
Parameters passed from client to server use the snake case equivalent of the camel case keys required by the API (e.g. userName becomes user_name). This is done to ensure PEP8 compatibility.

from arangoasync.typings import ServerStatusInformation

status: ServerStatusInformation = await db.status()
assert "host" in status
assert "operationMode" in status
print(status.host)
print(status.operation_mode)

You can use the arangoasync.typings.JsonWrapper.format() method to gain more control over the formatting of keys.

Serialization

Check out the Serialization section to learn more about how to implement your own serializer/deserializer. The current driver makes use of generic types and allows for a higher degree of customization.

Replication

Although a minimal replication API is available for observability purposes, its use is not recommended. Most of these are internal APIs that are not meant to be used by the end user. If you need to make any changes to replication, please do so from the cluster web interface.

Mixing sync and async

Sometimes you may need to mix the two. This is not recommended, but it takes time to migrate everything. If you need to do this, you can use the asyncio.to_thread() function to run a synchronous function in separate thread, without compromising the async event loop.

# Use a python-arango synchronous client
sys_db = await asyncio.to_thread(
    client.db,
    "_system",
    username="root",
    password="passwd"
)