Python SDK
Upload files, query Ready data, and read Mesh files from Python
The Alloy Python SDK gives you a normal Python path into Mesh Storage. Use it from notebooks, scripts, backend jobs, CI checks, and internal tools that need to upload recordings or work with data that is already in Mesh.
Mesh still does the same work behind the scenes: files land in object storage, Alloy processes MCAPs into queryable tables, and Ready data becomes available through SQL, Replay, Inspect, and external tools.
The SDK is for Python code. If you want to browse files, replay MCAPs, or run ad-hoc SQL without writing code, use the Mesh Storage page and SQL Workbench instead.
What you can do
Quickstart
Install the SDK, upload a run, query rows, and download a file
Upload files
Upload MCAPs and metadata sidecars into uploads/sdk-uploads
Query Mesh data
Run hosted SQL and return rows, Arrow, pandas, Polars, or DuckDB
List and download files
Read Mesh keys and prefixes from Python
The public modules
The SDK currently has two customer-facing modules:
| Module | Use it for |
|---|---|
alloy.storage | Upload files, list Mesh files, and download Mesh files |
alloy.sql | Query Ready Mesh data through hosted SQL |
Keep imports explicit:
from alloy import storage, sqlKeep using the module names in application code. The package root keeps SQL convenience exports, but storage client names stay under alloy.storage so Client and AsyncClient do not collide.
How uploads fit Mesh Storage
SDK uploads land under:
uploads/sdk-uploads/<path>/You choose the <path> part:
from alloy import storage
with storage.connect() as store:
result = store.upload_folder("runs/run-001", path="flights/run-001")
print(result.prefix)
# uploads/sdk-uploads/flights/run-001/After upload, files show up in Mesh Storage like any other uploaded file. Replay and Inspect are available once the file lands. SQL is available after processing reaches Ready.
Sync and async
Both storage and hosted SQL have sync and async clients. Use sync for scripts and notebooks. Use async for services, workers, and tools that already run on an event loop.
from alloy import storage
with storage.connect() as store:
store.upload_file("run.mcap", path="flights/run-001")from alloy import storage
async with storage.async_connect() as store:
await store.upload_file("run.mcap", path="flights/run-001")