aerospike-py 0.0.1a3

Aerospike Python Client - PyO3 + Rust binding

aerospike-py

Aerospike Python Client built with PyO3 + Rust. Drop-in replacement for aerospike-client-python powered by the Aerospike Rust Client v2.

Features

• Sync and Async (AsyncClient) API
• CRUD, Batch, Query/Scan, UDF, Admin, Index, Truncate
• CDT List/Map Operations, Expression Filters
• Full type stubs (.pyi) for IDE autocompletion

API details: docs/api/ | Usage guides: docs/guides/

Quickstart

pip install aerospike-py

Sync Client

import aerospike_py as aerospike

with aerospike.client({
    "hosts": [("127.0.0.1", 3000)],
    "cluster_name": "docker",
}).connect() as client:

    key = ("test", "demo", "user1")
    client.put(key, {"name": "Alice", "age": 30})

    _, meta, bins = client.get(key)
    print(bins)  # {'name': 'Alice', 'age': 30}

    client.increment(key, "age", 1)
    client.remove(key)

Async Client

import asyncio
from aerospike_py import AsyncClient

async def main():
    async with AsyncClient({
        "hosts": [("127.0.0.1", 3000)],
        "cluster_name": "docker",
    }) as client:
        await client.connect()

        key = ("test", "demo", "user1")
        await client.put(key, {"name": "Bob", "age": 25})
        _, _, bins = await client.get(key)
        print(bins)

        # Concurrent operations
        tasks = [client.put(("test", "demo", f"item_{i}"), {"idx": i}) for i in range(10)]
        await asyncio.gather(*tasks)

asyncio.run(main())

Performance

Benchmark: 5,000 ops x 100 rounds, Aerospike CE (Docker), Apple M4 Pro

Operation	aerospike-py sync	official C client	aerospike-py async	Async vs C
put (ms)	0.140	0.139	0.058	2.4x faster
get (ms)	0.141	0.141	0.063	2.2x faster

Sync performance is on par with the official C client. Async throughput is 2.2-2.4x faster — the official C client has no Python async/await support (attempted and removed).

Why async matters

The official C client supports async I/O internally (libev/libuv/libevent), but its Python bindings cannot expose async/await — the attempt was abandoned and removed in PR #462. The only concurrency option with the C client is asyncio.run_in_executor() (thread pool, not true async).

aerospike-py provides native async/await via Tokio + PyO3, enabling asyncio.gather() for true concurrent I/O — critical for modern Python web frameworks (FastAPI, Starlette, etc).

Full benchmark details: benchmark/ | Run: make run-benchmark

Contributing

See CONTRIBUTING.md for development setup, running tests, and making changes.

License

Apache License 2.0 — see LICENSE for details.