Neo4j Aura SDK for Python

This SDK provides a thin, async client for the Neo4j Aura HTTP API.

Highlights in this branch

Support for both v1 and v2beta1 endpoints.
Client-level API versioning and guards so v2 endpoints can't be called by a v1-configured client.
Models and helper methods for import jobs and IP filters (v2beta1).

Installation

Install from PyPI (when published) or install locally for development:

Using pip:

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .
# install test/runtime deps
pip install pytest httpx pydantic

Using poetry:

poetry install

API versioning

The client defaults to the v1 API surface. To call v2 endpoints (v2beta1) you must construct the client with an API version that begins with v2.

Constructor option: pass api_version="v2beta1" to AuraClient.
Environment helper: AuraClient.from_env() will read AURA_API_VERSION (defaults to v1).

The client enforces a guard for v2 endpoints: calling a v2 method when the client is configured for v1 will raise a clear ValueError indicating the API version mismatch. This prevents accidental use of v2 endpoints when the client is not configured for them.

Examples

Default (v1) client — v2 methods will be blocked:

from neo4j_aura_sdk import AuraClient

async with AuraClient.from_env() as client:  # AURA_API_VERSION default is 'v1'
    tenants = await client.tenants()
    # The following will raise ValueError because the client is v1:
    # await client.list_organization_ip_filters("org-id")

Create a v2beta1 client (allows v2 calls):

from neo4j_aura_sdk import AuraClient

async with AuraClient("id", "secret", api_version="v2beta1") as client:
    # Calls to v2beta1 endpoints (IP filters, import jobs) are allowed
    filters = await client.list_organization_ip_filters("org-id")

You can also set the environment variable AURA_API_VERSION=v2beta1 before calling AuraClient.from_env().

Usage

Minimal example (uses environment variables for credentials):

from neo4j_aura_sdk import AuraClient
import asyncio

async def main():
    async with AuraClient.from_env() as client:
        tenants = await client.tenants()
        print(tenants)

if __name__ == "__main__":
    asyncio.run(main())

Development

Run tests

With poetry:

poetry run pytest -q

With pip/venv:

source .venv/bin/activate
pytest -q

Build/publish

poetry build
poetry publish

Contributing

Please see CONTRIBUTING.md for contributor guidelines.

Notes

The repository now exposes an api_version property on AuraClient and provides clear guards for attempting v2 calls on a v1-configured client.
Several v1 and v2 methods include concise docstrings describing inputs and return models.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

neo4j_aura_sdk-0.1.4.tar.gz (79.7 kB view details)

Uploaded Jul 16, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

neo4j_aura_sdk-0.1.4-py3-none-any.whl (83.5 kB view details)

Uploaded Jul 16, 2026 Python 3

File details

Details for the file neo4j_aura_sdk-0.1.4.tar.gz.

File metadata

Download URL: neo4j_aura_sdk-0.1.4.tar.gz
Upload date: Jul 16, 2026
Size: 79.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for neo4j_aura_sdk-0.1.4.tar.gz
Algorithm	Hash digest
SHA256	`0960a8d0bd6e201ac94df7fa05c225f0c02167e37e48c26f3d6cb6e29ad4589a`
MD5	`b4da637fc381a1e4017113193dd22408`
BLAKE2b-256	`5ccb9a4f23264b4a54b92fd79fa4edb8f97b54826c7b122ff00b6446621a7eb9`

See more details on using hashes here.

Provenance

The following attestation bundles were made for neo4j_aura_sdk-0.1.4.tar.gz:

Publisher: release.yaml on nodestream-proj/neo4j-aura-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: neo4j_aura_sdk-0.1.4.tar.gz
- Subject digest: 0960a8d0bd6e201ac94df7fa05c225f0c02167e37e48c26f3d6cb6e29ad4589a
- Sigstore transparency entry: 2187651581
- Sigstore integration time: Jul 16, 2026
Source repository:
- Permalink: nodestream-proj/neo4j-aura-sdk@16efbdd1c1a9aa203d6a1bd9a58341af695a1fa3
- Branch / Tag: refs/tags/0.1.4
- Owner: https://github.com/nodestream-proj
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yaml@16efbdd1c1a9aa203d6a1bd9a58341af695a1fa3
- Trigger Event: release