ApertureDB Python SDK
The ApertureDB Python SDK provides a seamless interface for interacting with ApertureDB, the purpose-built database for storing, managing, and querying visual data (images, videos) alongside metadata, embeddings, and annotations.
This SDK includes comprehensive utilities to efficiently ingest and retrieve data, manage graph-based metadata, perform similarity searches on embeddings, and seamlessly integrate with the broader ML/AI ecosystem.
🚀 Integrations & Capabilities
The SDK is designed for modern ML workflows and offers seamless integrations with (some require additional dependencies):
- Deep Learning Frameworks: Seamless conversion of ApertureDB queries into
PyTorch(PyTorchDataset.ApertureDBDataset) andTensorFlow(ApertureDBTensorFlowDataset) data loaders for immediate model training. - Vector Search & Embeddings: First-class support for storing and retrieving high-dimensional descriptors, including native embedding extraction utilizing
CLIP(requiresopenai-clip) andFacenet. - Distributed Data Processing: Integration with
Daskto handle parallelized data loading and large-scale query execution. - Cloud Storage Integrations: Easy handling of assets stored remotely using
Boto3(AWS S3) and Google Cloud Storage. - ML Croissant: Native parsing and handling of datasets aligned with the ML Croissant metadata format (requires
mlcroissant). - Knowledge Graphs: Ability to execute and map SPARQL queries natively into the database (requires
rdflib).
📦 Installation
To install the SDK in a standard virtual environment with all core integrations (such as PyTorch and TensorFlow support):
pip install "aperturedb[complete]"
To install just the base client without optional deep learning extras:
pip install aperturedb
📚 Documentation & Examples
- Getting Started Guide
- Python SDK Reference
- Simple Examples and Concepts
- Advanced ML Usage Examples
- Sample Applications
🛠 Development Setup
The recommended way to contribute is to clone this repository and perform an editable installation:
git clone https://github.com/aperture-data/aperturedb-python.git
cd aperturedb-python
pip install -e '.[dev]'
🧪 Running Tests
The tests are located inside the test/ directory. They are designed to run within an isolated Linux container network composed of aperturedb, lenz, nginx, ca, and webui.
If you'd like to bring up the environment manually, ensure your working directory is test/ and run:
docker compose up -d
Development Environment Adjustments
To connect to the local test environment natively from your host, edit test/dbinfo.py to match the exposed ports (you can find the ephemeral ports by running docker compose port lenz 55551 and docker compose port nginx 443):
DB_TCP_HOST = 'localhost'
DB_REST_HOST = 'localhost'
DB_TCP_PORT = 0 # Replace with the mapped host port for lenz
DB_REST_PORT = 0 # Replace with the mapped host port for nginx 443
# VERIFY_HOSTNAME = False # Optional: Only required if connecting via IP instead of localhost
Executing Tests
To run the entire test suite, export the necessary credentials and execute the test runner script:
export GCP_SERVICE_ACCOUNT_KEY=<content of a GCP SERVICE ACCOUNT JSON file>
bash run_test.sh
To run a specific test file natively via pytest:
PROJECT=aperturedata KAGGLE_username=ci KAGGLE_key=dummy coverage run -m pytest test_Session.py -v -s --log-cli-level=DEBUG
(Note: The test suite assumes a Linux x86_64 environment. Adjustments may be required for macOS or Windows.)
⚙️ Runtime Configuration Variables
The following environment variables can modify the runtime behavior of the SDK, which is particularly useful for debugging:
| Variable | Type | Description | Default Value |
|---|---|---|---|
ADB_DEBUGGABLE |
flag |
If set (to any value), allows the application to register a fault handler that dumps a trace when SIGUSR1 is sent to the process. |
Not set |
LOG_FILE_LEVEL |
string |
The threshold for emitting log messages into the error<timestamp>.log file. |
WARN |
LOG_CONSOLE_LEVEL |
string |
The threshold for emitting log messages to stdout. |
ERROR |
ADB_LOG_FILE |
string |
Custom file path for the log output. | Not set |
🐞 Bug Reports & Contributing
- Bugs: Please report any issues regarding functionality, documentation, or tests by creating a GitHub Issue.
- Contributing: We welcome Pull Requests! When submitting a PR, include a brief description of the problem and the implemented fix.
- Coding Standards: Our CI enforces coding style guidelines using
autopep8and trailing whitespace checks. If a PR encounters failures, review the CI logs for details on the offending lines.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file aperturedb-0.4.61.tar.gz.
File metadata
- Download URL: aperturedb-0.4.61.tar.gz
- Upload date:
- Size: 163.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.10.21
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
11d4729534808b350d587075b02161182c0e2e2bb4a5edbb526d301f1a6c3454
|
|
| MD5 |
e0f9990a3498b70d79d95b9701eed6e6
|
|
| BLAKE2b-256 |
1ba1f7c8138b9f7bd077a1fbd5afcceb42eafe650e7c6f5fcc1662de0fc923bb
|
File details
Details for the file aperturedb-0.4.61-py3-none-any.whl.
File metadata
- Download URL: aperturedb-0.4.61-py3-none-any.whl
- Upload date:
- Size: 164.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.10.21
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3c99ac6c633411b79e9e1aa9f941ac03bf865fbb448ccf619485e4311e740370
|
|
| MD5 |
fb25f90a81bc5d7352e6a629fa492709
|
|
| BLAKE2b-256 |
29a41111845a137f383eefa1f5efbf18c8f06dab61f6526f846573e8975e98e4
|
