aerospike-py 0.0.1a4

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/

Drop-in Replacement

Just change the import — your existing code works as-is:

- import aerospike
+ import aerospike_py as aerospike

config = {'hosts': [('localhost', 3000)]}
client = aerospike.client(config).connect()

key = ('test', 'demo', 'key1')
client.put(key, {'name': 'Alice', 'age': 30})
_, _, bins = client.get(key)
client.close()

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

For AI Agents

This project supports the llms.txt standard. Use the following prompt to give your AI agent full context about aerospike-py:

Fetch and read https://kimsoungryoul.github.io/aerospike-py/llms-full.txt to understand the aerospike-py Python client API, then write code based on that documentation.

• llms.txt — Documentation index for AI agents
• llms-full.txt — Complete documentation in a single file

Contributing

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

License

Apache License 2.0 — see LICENSE for details.