aerospike-py

aerospike-py

High-performance Python client for Aerospike, built with Rust and PyO3 on top of the Aerospike Rust Client v2.

Features

• Sync and async (AsyncClient) APIs
• CRUD, batch, query, UDF, admin, index, and truncate operations
• List and map CDT operations and expression filters
• NumPy v2 structured-array results for batch reads, without per-record Python objects in analytical pipelines
• Full type stubs (.pyi) for IDE autocompletion

Documentation — API reference, usage guides, integration examples

Quickstart

pip install aerospike-py

Before running the examples, make sure an Aerospike server is available at 127.0.0.1:3000, or replace the host and port with a seed address for your cluster.

Sync Client

import aerospike_py as aerospike

with aerospike.client({
    "hosts": [("127.0.0.1", 3000)],
}).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)],
    }) 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

Sync is on par with the official C client. Async is 2.2-2.4x faster via native Tokio async/await.

Claude Code Skills & Agents

This project has Claude Code automation configured.

Ecosystem Plugin Installation

Install aerospike-ce-ecosystem-plugins to access the full ecosystem skill set, including the aerospike-py API reference and deployment guides.

From GitHub (recommended)

Add the repository as a marketplace, then install:

# Step 1: Add as marketplace
claude plugin marketplace add aerospike-ce-ecosystem/aerospike-ce-ecosystem-plugins

# Step 2: Install the plugin
claude plugin install aerospike-ce-ecosystem

Project-scoped install

To install only for the current project:

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

Verify installation

claude plugin list
# Should show: aerospike-ce-ecosystem@aerospike-ce-ecosystem ✔ enabled

Contributing

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

Repository Automation

This repository runs several automations on commits, pull requests, pushes, and schedules. The following sections explain when each check runs and why it may block an action.

Pre-commit hooks — .pre-commit-config.yaml

These hooks run on every git commit. Install them once with make pre-commit-install.

Claude Code hook — .claude/hooks/

Active when developing through Claude Code with the project plugin enabled.

• pr-perf-gate.sh — PreToolUse hook on gh pr create. If the PR diff touches any path in .claude/perf-hot-paths.txt and the conversation transcript has no perf-impact: verdict (from the perf-impact-reviewer agent) or benchmark run, the PR creation is blocked. Forces measurement on hot-path changes.

GitHub Actions — .github/workflows/

Build · release · docs

Skill & docs follow-up notifications

Both notify workflows reuse the GH_AW_GITHUB_TOKEN PAT for cross-repo writes — rotate together.

License

Apache License 2.0 — see LICENSE for details.