atlas-local-lib-py

Python library for managing MongoDB Atlas Local deployments. It wraps the atlas-local Rust library and requires a running Docker daemon.

Requirements

• Python >= 3.10
• Docker running locally

Installation

pip install atlas-local-lib-py

Usage

Create a deployment

from atlas_local import LocalDeployment

deployment = LocalDeployment.create(name="my-local-deployment")

print(deployment.container_id)
print(deployment.state)

When using a Voyage API key that needs a non-default gateway, pass the full HTTPS embeddings URL as embedding_provider_endpoint:

This option requires a non-empty voyage_api_key.

deployment = LocalDeployment.create(
    name="my-local-deployment",
    voyage_api_key="<key>",
    embedding_provider_endpoint="https://api.voyageai.com/v1/embeddings",
)

Use https://ai.mongodb.com/v1/embeddings for Atlas-issued production keys and https://api.voyageai.com/v1/embeddings for keys created directly with Voyage AI. For an Atlas staging key, provide its gateway, such as https://ai-stage.mongodb.com/v1/embeddings.

Get or create a deployment

Use get_or_create to reuse an existing deployment with matching options, or create a new one if it doesn't exist.

deployment = LocalDeployment.get_or_create(name="my-local-deployment")

Creation options such as voyage_api_key and embedding_provider_endpoint are also accepted by get_or_create. If a deployment with the same name already exists but was created with a different endpoint, get_or_create raises a ValueError instead of reusing it.

Get an existing deployment

deployment = LocalDeployment.get("my-local-deployment")

List deployments

for deployment in LocalDeployment.list():
    print(deployment.name, deployment.state)

Manage the deployment lifecycle

deployment.stop()
deployment.start()
deployment.pause()
deployment.unpause()
deployment.delete()

Each lifecycle method is also available as a static method that takes a container ID or name, for example LocalDeployment.stop_deployment("my-local-deployment").

Error handling

Operations raise exceptions rooted at atlas_local.AtlasLocalError, with more specific subclasses such as CreateDeploymentError, GetDeploymentError, DeleteDeploymentError, StartDeploymentError, StopDeploymentError, PauseDeploymentError, and UnpauseDeploymentError.

from atlas_local import AtlasLocalError, LocalDeployment

try:
    deployment = LocalDeployment.get("nonexistent-deployment")
except AtlasLocalError as error:
    print(f"Failed to get deployment: {error}")

Development

Build the extension in editable mode:

pip install maturin
maturin develop --extras test

Run the test suite:

pytest

Integration tests require a running Docker daemon and are opt-in:

pytest -m integration