aerospike-py 0.5.0

High-performance Aerospike Python client with sync and async APIs, built with PyO3 and Rust

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, 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})

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

    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})
        record = await client.get(key)
        print(record.bins)  # {'name': 'Bob', 'age': 25}

        # 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

Claude Code Skills & Agents

이 프로젝트는 Claude Code 자동화가 설정되어 있습니다.

Ecosystem Plugin 설치

aerospike-ce-ecosystem-plugins를 설치하면 aerospike-py API 레퍼런스, 배포 가이드 등 ecosystem 전체 스킬을 사용할 수 있습니다.

claude plugin marketplace add aerospike-ce-ecosystem/aerospike-ce-ecosystem-plugins
claude plugin install aerospike-ce-ecosystem

Skills

/skill-name으로 호출합니다.

Skill	명령어	설명
run-tests	/run-tests [type]	빌드 → Aerospike 서버 보장 → 테스트 실행 (unit/integration/concurrency/compat/all/matrix)
release-check	/release-check	릴리스 전 검증 (lint, unit test, pyright, type stub 일관성, 버전 확인)
bench-compare	/bench-compare	aerospike-py vs 공식 C 클라이언트 벤치마크 비교
test-sample-fastapi	/test-sample-fastapi	aerospike-py 빌드 → sample-fastapi 설치 → 통합 테스트 실행
new-api	/new-api [method] [desc]	새 Client/AsyncClient API 메서드 추가 가이드 (Rust → Python 래퍼 → 타입 스텁 → 테스트)

Subagents

코드 리뷰/분석 시 자동으로 활용됩니다.

Agent	설명
pyo3-reviewer	PyO3 바인딩 리뷰 (GIL 관리, 타입 변환, async 안전성, 메모리 안전성)
type-stub-sync	__init__.pyi stub과 Rust 소스 간 일관성 검증

Hooks

파일 편집 시 자동 실행됩니다.

Hook	트리거	동작
Python auto-format	.py 편집 후	ruff format + ruff check --fix
Rust auto-format	.rs 편집 후	cargo fmt
Binary/lock 보호	.so, .dylib, .whl, uv.lock 편집 시	편집 차단

Contributing

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

Code stats

tokei 기반 (tokei.toml + .tokeignore).

코드 규모

레이어	파일 수	코드 라인	역할
aerospike-core (Rust)	100	19,635	Aerospike 프로토콜, 클러스터 관리, 명령 실행
rust/src (PyO3 바인딩)	32	9,582	Python ↔ Rust 변환, async/sync 클라이언트, 정책 파싱
src/aerospike_py (Python)	24	6,877	타입 스텁(.pyi), NamedTuple 래퍼, 헬퍼
합계	156	36,094	Rust 81% · Python 19%

타 DB 클라이언트 대비

클라이언트	구현 코드	비고
aerospike-py (Rust+Python)	~36K	프로토콜 자체 구현
aerospike-client-python (공식)	~15K	C client(100K+) 래핑, C 코드 별도
redis-rs (Rust)	~15K	프로토콜이 훨씬 단순 (텍스트 기반)
pymongo (Python)	~40-50K	순수 Python, 프로토콜 자체 구현
psycopg3 (Python)	~25-30K	libpq(C) 래핑

# 순수 구현 코드만 (tests, examples, benchmark 제외)
tokei

# aerospike-core 포함
tokei rust/src/ src/aerospike_py/

License

Apache License 2.0 — see LICENSE for details.