thrustlab 0.1.1

Official Python SDK for the ThrustLab API

thrustlab — official Python SDK for the ThrustLab API

Install

pip install thrustlab

Requires Python 3.10+.

Quickstart

from thrustlab import Client

client = Client(api_key="key_...")  # or set $THRUSTLAB_API_KEY

# Create a project
project = client.projects.create(name="my project")

# Run a simulation and wait for the result
sim = client.simulations.create(
    project_id=project["id"],
    motor="comp_motor_xxx",
    propeller="comp_prop_xxx",
    battery="comp_batt_xxx",
    throttle=0.7,
)
result = client.simulations.wait(sim["id"], timeout=300)
print(result)

Configuration

Setting	Constructor arg	Env var	Default
API key	api_key=	THRUSTLAB_API_KEY	(required)
Base URL	base_url=	THRUSTLAB_BASE_URL	https://thrustlab.com
Timeout	timeout=	—	30 (seconds)
Max retries	max_retries=	—	3

Resources

Every /v1/ route family is exposed as an attribute on the client:

client.api_keys
client.users
client.projects
client.simulations
client.sweeps
client.components
client.submissions
client.starred_components
client.geometry
client.credits
client.subscriptions
client.webhook_endpoints

Error handling

from thrustlab import Client
from thrustlab.exceptions import (
    AuthenticationError,
    ValidationError,
    RateLimitError,
    NotFoundError,
)

client = Client()
try:
    client.simulations.create(project_id="proj_xxx", motor="comp_xxx", ...)
except ValidationError as exc:
    print(f"bad request: {exc.code} ({exc.param}): {exc.message}")
except RateLimitError as exc:
    print(f"rate limited; retry after {exc.retry_after}s")
except NotFoundError as exc:
    print(f"not found: {exc.message}")
except AuthenticationError as exc:
    print(f"auth failed: {exc.message}")

Every error carries .code, .type, .request_id, .http_status, and .message. ValidationError additionally exposes .param. See thrustlab.com/docs/guides/errors for the full code reference.

Pagination

List endpoints return a CursorPager — a lazy iterator that fetches the next page only when needed:

# Iterate all pages automatically
for project in client.projects.list():
    print(project["id"])

# Materialise the first page only
first_page = list(client.projects.list(limit=20))

Async polling

simulations.wait() and sweeps.wait() block until the resource reaches a terminal state (succeeded, failed, or cancelled) or the timeout fires:

sweep = client.sweeps.create(...)
result = client.sweeps.wait(sweep["id"], timeout=600, poll_interval=2.0)
if result["status"] == "succeeded":
    print(result["outputs"])

Webhooks

from thrustlab import Webhook
from thrustlab.exceptions import SignatureVerificationError

WEBHOOK_SECRET = "whsec_..."

@app.post("/webhooks/thrustlab")
async def handle(request):
    payload = await request.body()
    sig    = request.headers["Thrustlab-Signature"]
    try:
        event = Webhook.verify(payload, sig, WEBHOOK_SECRET)
    except SignatureVerificationError:
        return Response(status_code=400)
    if event.type == "simulation.succeeded":
        print(event.data)

Retries

The client automatically retries on 429 (rate limit) and 5xx responses using exponential backoff with jitter. Set max_retries=0 to disable:

client = Client(max_retries=0)

Links

• Documentation: https://thrustlab.com/docs
• API reference: https://thrustlab.com/docs/reference
• SDK guide: https://thrustlab.com/docs/sdk/python
• Changelog: https://thrustlab.com/docs/changelog
• Issue tracker: https://github.com/kylebedrich/thrustlab/issues

License

MIT