aioorient 1.0.0

Async-native Python client for the OrientDB binary protocol

aioorient

Async-native Python client for the OrientDB binary protocol. Typed, tested, pooled, and dependency-free. Targets OrientDB 3.0+ (v37/v38 wire protocol) on Python 3.13+.

Quickstart

import asyncio
from aioorient import Client

async def main() -> None:
    async with await Client.connect(
        "localhost", 2424, user="root", password="rootpw"
    ) as client:
        async with client.database("demo", user="admin", password="adminpw") as db:
            rows = await db.query("SELECT FROM Person WHERE age > :min", params={"min": 18})
            for row in rows:
                print(row["name"], row.rid)

asyncio.run(main())

Install

pip install aioorient

Zero runtime dependencies. An optional C extension accelerates record decoding and ships in the binary wheels; without it, a pure-Python decoder is used transparently.

Features

• Async-only. Everything is await-ed; no sync wrapper, no blocking I/O.
• Typed. mypy --strict clean, ships py.typed; dict[str, Any] only where OrientDB values are genuinely polymorphic.
• Pooled by default. One Client → a server-level pool plus per-database query and batch pools, with health checks and back-pressure. No socket wrangling.
• v38 transactions. async with db.transaction() as tx: with MVCC-enforced expected_version.
• Streaming queries. async for row in db.query_stream(sql): pages under the hood without leaking server-side cursors.
• Live queries. async with db.live_query(sql) as sub: with a bounded buffer and clean three-way teardown.
• Binary v37 codec. Full document encode/decode with varint + zigzag primitives and an optional C fast path.
• Object-graph mapper. Declarative vertices/edges, property descriptors, a chainable query DSL, atomic batches, and per-class brokers.

Documentation

Full guides live in docs/:

• Getting started
• Connections & pooling
• Queries · Transactions · Live queries
• Object-graph mapper
• Records & types · Exceptions
• TinkerPop / Gremlin
• Evaluation — benchmarks vs. other OrientDB Python clients

Object-graph mapper at a glance

from aioorient.ogm import Graph, declarative_node, String, Integer

Node = declarative_node()

class Person(Node):
    element_type = "Person"
    name = String()
    age = Integer()

async with Graph(db, bases=[Node]) as g:
    await g.init_schema()
    alice = await g.create_vertex(Person, name="Alice", age=30)
    adults = await g.query(Person).where(Person.age >= 18).order_by(Person.name).all()

See the OGM guide for the query DSL, batches, brokers, and traversals.

Gremlin traversals at a glance

OrientDB can execute TinkerPop 3 Gremlin traversals server-side; aioorient sends them over the same binary connection via db.script(language="gremlin"). The server binds g = graph.traversal(), so you write standard Gremlin directly (needs the orientdb:3.2-tp3 image):

rows = await db.script(
    "g.V().hasLabel('Person').has('age', gte(18)).valueMap('name', 'age')",
    language="gremlin",
    params={},
)
for row in rows:
    print(row.fields)

Gremlin support is experimental. See the Gremlin guide for prerequisites, result shapes, and caveats.

Development

uv sync
uv run ruff check . && uv run ruff format --check .
uv run mypy src/aioorient tests
uv run pytest -m "not integration"          # unit tier

Integration tests require Docker (the suite starts/stops OrientDB itself):

uv run pytest -m integration

See CONTRIBUTING.md for the commit conventions that drive automated releases.

License

MIT