Skip to main content

Alien Python bindings

alienplatform gives async Python applications typed access to resources linked by Alien. Provider selection, short-lived credential refresh, error metadata, and cloud behavior stay in the shared Rust binding core.

The package is under development and is not published to a package registry yet.

Local development

Build an editable local-provider package from the repository root:

python -m venv .venv
source .venv/bin/activate
python -m pip install 'maturin>=1.9,<2' 'pytest>=8,<10' 'pytest-asyncio>=1,<2'
maturin develop --manifest-path crates/alien-bindings-python/Cargo.toml \
  --no-default-features --features local
pytest -q crates/alien-bindings-python/tests

The native extension uses Python's asyncio interface and runs Alien futures on its Tokio runtime. Resource factories are lazy: missing or malformed bindings fail when first used with a structured AlienError.

Resources

from alienplatform import ai, container, key, kv, postgres, queue, sandbox, storage, vault, worker
from sqlalchemy.ext.asyncio import create_async_engine

files = storage("files")
await files.put("reports/today.json", b"{}", condition="absent")
assert await files.get("reports/today.json") == b"{}"
assert await files.get_optional("reports/missing.json") is None

cache = kv("cache")
await cache.put("status", b"ready", condition="absent")

jobs = queue("jobs")
await jobs.send({"kind": "index"})

secrets = vault("secrets")
api_token = await secrets.get("api-token")

database = await postgres("database").connection()
engine = create_async_engine(**database.sqlalchemy_async_engine_kwargs())

service_url = await container("api").internal_url()

response = await worker("processor").invoke(
    method="POST", path="/jobs", body=b"{}", timeout_ms=30_000
)

ciphertext = await key("records").encrypt(b"private", {"tenant": "tenant-42"})

model = await ai("assistant").connection()
# OpenAI-compatible clients use model.openai_base_url. model.api_key is None
# for ambient Bedrock, Vertex, and Foundry resources because the embedded Rust
# gateway authenticates with the workload identity.

Do not log or render Postgres connection strings, passwords, vault values, or model credentials. Connection object representations redact credentials by default.

AI

ai(name).connection() returns a provider-neutral base URL. Managed Bedrock, Vertex, and Foundry resources start the same in-process Rust gateway used by the TypeScript SDK, so signing and short-lived credential refresh stay in the shared implementation. External OpenAI and Anthropic bindings return the projected key and provider endpoint. Pass openai_base_url to an OpenAI-compatible client.

Sandbox commands stream raw stdout and stderr frames with production-order sequence numbers:

runtime = sandbox("runtime")
instance = await runtime.create()
try:
    stream = await runtime.run_command(
        instance.sandbox_id,
        "python",
        ["-c", "print('hello')"],
        timeout_ms=30_000,
    )
    try:
        async for frame in stream:
            if frame.data is not None:
                print(frame.data.decode(errors="replace"), end="")
            if frame.exit_code is not None and frame.exit_code != 0:
                raise RuntimeError(f"command exited with {frame.exit_code}")
    finally:
        await stream.close()
finally:
    await runtime.terminate(instance.sandbox_id)

Long-running commands can use start_job, poll_job, and cancel_job. Call capabilities() for new sessions, or capabilities(sandbox_id) for an existing session, before optional file, job, pause/resume, or isolation behavior. Azure sessions retain the transport they were created with across image upgrades and rollbacks.

PostgreSQL TLS

Postgres.connection() returns the provider-neutral connection parameters, a wire-protocol URL, CA certificates, and SSL mode. sqlalchemy_async_engine_kwargs() translates the URL and supplies the verified TLS context together so create_async_engine() cannot omit provider CA certificates. Lower-level integrations can use sqlalchemy_async_url() and ssl_context() directly.

Errors

AlienError includes stable code, context, retryable, internal, http_status_code, and hint fields. Branch on code rather than parsing the message. Errors from object storage are intentionally mapped without object paths or provider response bodies so application logs do not leak customer data.

Remote KV

from alienplatform import Bindings

bindings = await Bindings.for_remote_customer(
    project=project, external_id=external_id, token=token
)
await bindings.kv("check-cache").put("status", b'{"ready":true}', ttl_seconds=86400)

Use a backend token with write access and enable remoteAccess on the KV resource before applying setup. Remote credentials refresh in the Rust core. AWS and Azure scope access to the selected table. Firestore access covers the project's documents because IAM cannot isolate collections in the shared default database. Raw value limits are 408,576 bytes for DynamoDB, 783,360 bytes for Firestore, and 24,576 bytes for Azure/local.

Worker queue batches

Install the optional alienplatform[worker] dependencies and configure the Worker's queue trigger with batch: {maxMessages: 10, maxWindowSeconds: 2}. Register handlers using the logical queue resource ID:

import asyncio
from alienplatform import QueueBatch, QueueOutcome, on_queue_batch, run_worker

async def process(batch: QueueBatch) -> list[QueueOutcome]:
    outcomes = []
    for delivery in batch.deliveries:
        # Persist the application's work before returning success.
        await persist(delivery.message.payload)
        outcomes.append(QueueOutcome(delivery.delivery_id, "success"))
    return outcomes

on_queue_batch("jobs", process)
asyncio.run(run_worker())

Return exactly one success or retry for each delivery ID. Missing, duplicate, unknown, or invalid outcomes reject the batch before acknowledging any item. An exception retries the batch. The runtime owns acknowledgment; do not also acknowledge these deliveries through a queue binding. on_queue_message continues to handle triggers without batch configuration. "*" matches any otherwise unregistered source.

Batching is an explicit deployment opt-in. Deploy a runtime and SDK that support batch handlers when adding batch to a queue trigger. A manager upgrade alone preserves legacy queue routes and concurrency settings. Removing batch restores single-message infrastructure settings; deploy a single-message handler with that change. On AWS, enabling batching checks queue visibility against six times the Worker timeout plus the collection window. Live queues are increased when needed; a derived visibility increase for setup-owned queues returns setup-required before Worker updates. Rerun setup and complete its normal handoff before enabling batching; the controller also verifies installed visibility before changing the Worker. Disabling batching never shortens an existing queue visibility timeout.

A batch may contain fewer than maxMessages. The collection window is a maximum wait, not a periodic schedule or a minimum batch size. Messages are unordered and may be delivered again, including after an uncertain acknowledgment. Make work idempotent. Distinct deliveries can share a provider message ID; use delivery_id when constructing outcomes. Python handlers execute sequentially within each application process; this does not provide a distributed lock.

For applications that explicitly receive through a queue binding, ack_batch(receipts) returns one result per receipt and is not atomic. renew_lease(receipt, duration_seconds) requires 1–600 seconds. AWS, GCP, and local queues reset the remaining lease, so a smaller value intentionally shortens it. Azure renews the queue's configured lock duration; the requested value is a validated hint, not an exact duration guarantee.

Storage notifications in queues

Parse a binding QueueMessage or a Worker's QueueEvent (including delivery.message inside a batch) with the typed helper:

from alienplatform import storage_event_from_message

event = storage_event_from_message(message)
print(event.bucket_name, event.object_key, event.timestamp, event.etag)

The helper validates the portable camelCase JSON payload and returns Python attributes in snake_case, including a timezone-aware UTC timestamp and optional object metadata. Invalid JSON or schema fields raise AlienError with code INVALID_STORAGE_EVENT_MESSAGE. Parsing does not acknowledge a message. Use normal queue-binding acknowledgment or Worker outcomes after processing succeeds. Notifications are at least once and unordered; make processing idempotent.

Metadata

Release files for alienplatform 3.3.60

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for alienplatform 3.3.60
File Actions
alienplatform-3.3.60-cp310-abi3-manylinux_2_28_aarch64.whl CPython 3.10 abi3 Linux glibc 2.28+ ARM64 Details for alienplatform-3.3.60-cp310-abi3-manylinux_2_28_aarch64.whl
alienplatform-3.3.60-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.10 abi3 Linux glibc 2.17+ x86-64 Details for alienplatform-3.3.60-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
alienplatform-3.3.60-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for alienplatform-3.3.60-cp310-abi3-macosx_11_0_arm64.whl
alienplatform-3.3.60-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for alienplatform-3.3.60-cp310-abi3-macosx_10_12_x86_64.whl

Total release size: 105.5 MB

Release files / alienplatform-3.3.60-cp310-abi3-manylinux_2_28_aarch64.whl

Download URL alienplatform-3.3.60-cp310-abi3-manylinux_2_28_aarch64.whl
Size 28.4 MB
Tags CPython 3.10 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
c3d562b5899eadf321d7c3adec94dafa9fe95a61569aace961ec9a3445334bfc
BLAKE2b-256 checksum
How to use checksums
ac809bd3a218ae6e5e298facaa4a27cb5031c3fd3698dfae96b9323a322022f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / alienplatform-3.3.60-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL alienplatform-3.3.60-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 27.4 MB
Tags CPython 3.10 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
81fee9676fec1f7d6c594bb8b6f454cb170a078d6753e5b67f8ed38ba4179e11
BLAKE2b-256 checksum
How to use checksums
cf843e3a6bb00936478af1e2657eef5d28787f5386a69afd93f0cfe8759b644f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / alienplatform-3.3.60-cp310-abi3-macosx_11_0_arm64.whl

Download URL alienplatform-3.3.60-cp310-abi3-macosx_11_0_arm64.whl
Size 24.6 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
8a7b01ba40c4785171b54b1b4dd359433b1ea3869b0b28bd1eb41155eac8ade0
BLAKE2b-256 checksum
How to use checksums
f3206fc02c16e45341ec9c2595d32fbc134883bad962bf2d18225bc78452afe4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / alienplatform-3.3.60-cp310-abi3-macosx_10_12_x86_64.whl

Download URL alienplatform-3.3.60-cp310-abi3-macosx_10_12_x86_64.whl
Size 25.1 MB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
8faa72699e16aa9671a1b9ef553370d7fa8f90f1fdaccb41d22f17d97ca4e2c8
BLAKE2b-256 checksum
How to use checksums
b8542fa570a76054766cad9bb74386ba6477b6bb2f9faec1d5e3a70b03e70e9c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for alienplatform 3.3.60

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 4 files in this release have been uploaded with provenance metadata.

Select from 4 files

Attestation for alienplatform-3.3.60-cp310-abi3-manylinux_2_28_aarch64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.3.60 This release

4 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page