Aerospike Python Async Client

Async I/O Python bindings for the Aerospike Rust client core. Built with PyO3; ships pre-built wheels for Linux (x86_64, aarch64), macOS (x86_64, arm64), and Windows (x86_64) on Python 3.10–3.14, including free-threaded builds (cp313t / cp314t).

Status: Public preview (alpha). Not yet production-ready; feedback welcome via GitHub Issues.

Not officially supported as a standalone client; APIs at this layer are undocumented and may change between releases without notice. This package is the low-level primitive layer underneath the Aerospike Python SDK. The reference sections below exist for SDK users who need to drop down to low-level configuration (TLS, multi-record transactions, strong-consistency read modes, wire compression) and for client contributors.

Resources

• PyPI:https://pypi.org/project/aerospike-async/
• Source:https://github.com/aerospike/aerospike-client-python-async
• Issues:https://github.com/aerospike/aerospike-client-python-async/issues
• Releases:https://github.com/aerospike/aerospike-client-python-async/releases

Installation

pip install aerospike-async

Pin to a specific release if you need reproducible builds:

pip install aerospike-async==0.6.0a1 # latest on PyPI as of this writing

Pre-built wheels are published for every supported platform/Python combination on regular CPython (3.10 – 3.14, ABI tags cp310–cp314) and on the free-threaded builds (cp313t / cp314t), so no Rust toolchain is required for ordinary use. If pip resolves to an sdist on your platform, see Building from source below.

Quick start

importasynciofromaerospike_asyncimport (
ClientPolicy,
Key,
ReadPolicy,
WritePolicy,
new_client,
)
asyncdefmain():
client=awaitnew_client(ClientPolicy(), "localhost:3000")
key=Key("test", "demo", "user1")
# Write a record (bins are plain dicts)awaitclient.put(key, {"name": "Alice", "age": 28})
# Read it backrecord=awaitclient.get(key)
print(record.bins) # {'name': 'Alice', 'age': 28}# Read specific bins onlyrecord=awaitclient.get(key, ["name"])
print(record.bins) # {'name': 'Alice'}# Delete the recordawaitclient.delete(key)
awaitclient.close()
asyncio.run(main())

TLS configuration

The client supports TLS for secure connections and PKI (certificate-based) authentication.

Basic TLS

fromaerospike_asyncimportClientPolicy, TlsConfig, new_clientpolicy=ClientPolicy()
policy.tls_config=TlsConfig("path/to/ca-certificate.pem")
client=awaitnew_client(policy, "tls-host:4333")

TLS with client authentication

policy=ClientPolicy()
policy.tls_config=TlsConfig.with_client_auth(
"ca.pem", # CA certificate"client.pem", # Client certificate"client.key", # Client private key
)
client=awaitnew_client(policy, "tls-host:4333")

PKI authentication

PKI mode uses client certificates for authentication (no username/password required):

fromaerospike_asyncimportAuthModepolicy=ClientPolicy()
policy.tls_config=TlsConfig.with_client_auth("ca.pem", "client.pem", "client.key")
policy.set_pki_auth() # or: policy.set_auth_mode(AuthMode.PKI)client=awaitnew_client(policy, "tls-host:4333")

TLS name in host strings

When the server certificate name differs from the connection hostname, specify the TLS name:

# Format: hostname:tls_name:port# Example: connect to IP but validate certificate against "server.example.com"client=awaitnew_client(policy, "192.168.1.100:server.example.com:4333")

Authentication modes

The client supports multiple authentication modes via AuthMode:

• AuthMode.NONE — no authentication
• AuthMode.INTERNAL — internal authentication (username/password)
• AuthMode.EXTERNAL — external authentication (LDAP, etc.)
• AuthMode.PKI — certificate-based authentication (requires TLS + client cert)

fromaerospike_asyncimportAuthModepolicy=ClientPolicy()
policy.set_auth_mode(AuthMode.INTERNAL, user="admin", password="secret")
# orpolicy.set_auth_mode(AuthMode.PKI) # No user/password needed

Multi-record transactions (MRT)

Multi-record transactions require a strong-consistency namespace on the server (Aerospike 8.0+). Group operations into a single atomic transaction by attaching a Txn to each policy, then commit or abort:

fromaerospike_asyncimportCommitStatus, Txnfromaerospike_async.exceptionsimportCommitFailedErrortxn=Txn()
write=WritePolicy()
write.set_txn(txn)
read=ReadPolicy()
read.set_txn(txn)
try:
awaitclient.put(key_a, {"balance": 100}, policy=write)
awaitclient.put(key_b, {"balance": 200}, policy=write)
status=awaitclient.commit(txn)
assertstatus==CommitStatus.OK_VERIFIEDexceptCommitFailedError:
awaitclient.abort(txn)

MRT-specific failure result codes are exposed on ResultCode: MRT_BLOCKED, MRT_VERSION_MISMATCH, MRT_EXPIRED, MRT_TOO_MANY_WRITES, MRT_COMMITTED, MRT_ABORTED, MRT_ALREADY_LOCKED, MRT_MONITOR_EXISTS.

Strong consistency read modes

Every read-capable policy exposes read_mode_ap and read_mode_sc for tuning consistency on AP and SC namespaces respectively:

fromaerospike_asyncimportReadModeAP, ReadModeSCpolicy=ReadPolicy()
policy.set_read_mode_ap(ReadModeAP.One) # AP namespacepolicy.set_read_mode_sc(ReadModeSC.Linearize) # SC namespace

Wire-protocol compression

Every policy exposes a use_compression flag (off by default) to enable compression of request/response payloads on the wire:

policy=WritePolicy()
policy.set_use_compression(True)

Versioning

PAC follows SemVer. Pre-releases use the MAJOR.MINOR.PATCH-{alpha,beta,rc}.N form (e.g. 0.4.0-alpha.1). PyPI normalizes these on upload to the equivalent PEP 440 spelling (0.4.0a1).

Cargo.toml is the single source of truth; pyproject.toml does not duplicate the version. maturin reads it from Cargo.toml when it builds the wheel, so the two are guaranteed to match.

See the Development section for the bump procedure.

License

Apache License 2.0. See LICENSE for details.

---

Development / Contributing

The sections below are for client contributors. Downstream users do not need any of this — pip install aerospike-async is sufficient to use the package.

Prerequisites

This project uses PyO3 to build a Rust extension for Python. You will need:

• Python 3.10 - 3.14, or 3.14t (free-threaded) for high-throughput / PSDK AsyncPool work. Recommended installer: uv (uv python install 3.14.5+freethreaded) or pyenv with a dedicated environment.
• Rust toolchain (rustc + cargo) — always required when building from source
• Aerospike server — required for integration tests

If Rust is not already installed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source$HOME/.cargo/env
# Verify
rustc --version
cargo --version

Building from source

Install Python build/test dependencies (any virtualenv works; pyenv is recommended):

pip install -r requirements.txt

Build & test in one step (Rust build, stub regeneration, full test suite):

make dev-test

Or build only — produces a development wheel and installs it into the active virtualenv:

make dev

Regenerate Python stubs (only needed after modifying Rust code):

make stubs

Configuration

Edit aerospike.env to match your Aerospike database node configuration:

export AEROSPIKE_HOST=localhost:3000

For local-only overrides (e.g. TLS certificate paths), create an aerospike.env.local file in the repo root. It is gitignored and automatically sourced by aerospike.env.

Running tests

make test# unit + integration
make test-unit # unit tests only (no server required)
make test-int # integration tests only (requires running Aerospike server)

macOS file descriptor limit. On macOS, you may encounter ConnectionError: Failed to connect to host(s) errors when running the full test suite. The default file descriptor limit (256) can be exceeded by the async client's concurrent connections.

ulimit -n 4096 # current shell session
make test

To make this permanent, add ulimit -n 4096 to your shell profile (~/.zshrc or ~/.bash_profile).

Bumping the version

Bumps are manual and happen in PRs against dev. Promotion workflows (dev → stage → main) do not mutate the version.

# 1. Edit Cargo.toml [package] version field, then refresh Cargo.lock:# e.g. 0.6.0-alpha.1 → 0.6.0-alpha.2
cargo check # or: cargo update -p aerospike_async --precise 0.6.0-alpha.2# 2. Confirm:
bin/get-version # prints 0.6.0-alpha.2# 3. Open a PR against dev with just this change.

Reading the version programmatically

Anywhere a build script, CI step, or release tool needs the version:

bin/get-version # → 0.6.0-alpha.1

The script parses the first version field inside the [package] table of Cargo.toml. It has no Python or cargo runtime dependencies — usable from any shell, container, or CI environment.