thrustlab 0.1.0__tar.gz

thrustlab-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+.tox/

thrustlab-0.1.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to the `thrustlab` Python SDK are documented here. The
+project follows [semantic versioning](https://semver.org/) independent of the
+ThrustLab API version (which is permanently `/v1/`).
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-27
+
+Initial public beta release of the official ThrustLab Python SDK.
+
+### Added
+
+- Full coverage of the `/v1/` API surface across **12 resource modules**:
+  `api_keys`, `users`, `projects`, `simulations`, `sweeps`, `components`,
+  `submissions`, `starred_components`, `geometry`, `credits`,
+  `subscriptions`, `webhook_endpoints`.
+- Sync transport (`httpx.Client`) with bearer-token authentication.
+- Auto-generated `Idempotency-Key` header on every mutating request (override
+  via `idempotency_key=` keyword argument).
+- Exponential backoff + jitter retry on 429, 5xx, and transient network
+  errors (`max_retries=3` default, configurable per client instance).
+- `CursorPager[T]` lazy iterator for cursor-paginated list endpoints;
+  transparent multi-page iteration.
+- `wait()` helpers on `simulations` and `sweeps` for polling async resources
+  to terminal state (`succeeded` / `failed` / `cancelled` / `timed_out`).
+- `Webhook.verify()` for HMAC SHA256 webhook signature verification with
+  configurable timestamp tolerance (default 300 s).
+- Stripe-style typed exception hierarchy:
+  `ThrustlabError` → `APIError` → `AuthenticationError`, `PermissionError`,
+  `NotFoundError`, `ValidationError`, `ConflictError`, `RateLimitError`,
+  `APIServerError`; plus `NetworkError`, `SignatureVerificationError`,
+  `ConfigurationError`.
+- Pydantic v2 models generated from `openapi.json` via
+  `openapi-python-client`; used internally for request/response shaping.
+- Configuration via constructor kwargs (`api_key`, `base_url`, `timeout`,
+  `max_retries`) or env vars (`THRUSTLAB_API_KEY`, `THRUSTLAB_BASE_URL`).
+- 103 unit + integration tests (pytest).
+
+### Out of scope (deferred)
+
+- Async transport (`httpx.AsyncClient`). Planned for v0.2.
+- Streaming response support.
+- Python 3.9 compatibility.
+- CLI tool (`thrustlab` command).
+- SDKs in other languages.
+
+## Pre-release rehearsal procedure
+
+Before tagging v0.1.0, rehearse with:
+
+1. Create a short-lived release-rehearsal branch from master.
+2. Tag `sdk-py-v0.0.1-rc1` and push it.
+3. The CI workflow runs build + TestPyPI publish only (gate step enforces
+   ancestry before either publish step fires).
+4. Delete the rehearsal tag + branch after validation.
+5. Tag `sdk-py-v0.1.0` from the actual master-merge commit for production publish.

thrustlab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ThrustLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

thrustlab-0.1.0/Makefile

@@ -0,0 +1,24 @@
+.PHONY: codegen test test-unit test-integration build publish clean check
+
+codegen:
+	python scripts/regen_models.py
+
+test: test-unit test-integration
+
+test-unit:
+	pytest tests/ -m "not integration" -q
+
+test-integration:
+	pytest tests/integration/ -q
+
+build:
+	python -m build
+
+check:
+	twine check dist/*
+
+publish:
+	twine upload dist/*
+
+clean:
+	rm -rf dist build *.egg-info

thrustlab-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: thrustlab
+Version: 0.1.0
+Summary: Official Python SDK for the ThrustLab API
+Project-URL: Homepage, https://thrustlab.com
+Project-URL: Documentation, https://thrustlab.com/docs
+Project-URL: Repository, https://github.com/<owner>/thrustlab
+Project-URL: Changelog, https://thrustlab.com/docs/changelog
+Author-email: ThrustLab <support@thrustlab.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: attrs>=23.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: python-dateutil>=2.8
+Provides-Extra: dev
+Requires-Dist: openapi-python-client>=0.21; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# thrustlab — official Python SDK for the ThrustLab API
+
+[![PyPI](https://img.shields.io/pypi/v/thrustlab.svg)](https://pypi.org/project/thrustlab/)
+[![Python](https://img.shields.io/pypi/pyversions/thrustlab.svg)](https://pypi.org/project/thrustlab/)
+[![License](https://img.shields.io/pypi/l/thrustlab.svg)](https://github.com/kylebedrich/thrustlab/blob/master/backend/sdks/python/LICENSE)
+
+## Install
+
+```bash
+pip install thrustlab
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+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:
+
+```python
+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
+
+```python
+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](https://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:
+
+```python
+# 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:
+
+```python
+sweep = client.sweeps.create(...)
+result = client.sweeps.wait(sweep["id"], timeout=600, poll_interval=2.0)
+if result["status"] == "succeeded":
+    print(result["outputs"])
+```
+
+## Webhooks
+
+```python
+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:
+
+```python
+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

thrustlab-0.1.0/README.md

@@ -0,0 +1,159 @@
+# thrustlab — official Python SDK for the ThrustLab API
+
+[![PyPI](https://img.shields.io/pypi/v/thrustlab.svg)](https://pypi.org/project/thrustlab/)
+[![Python](https://img.shields.io/pypi/pyversions/thrustlab.svg)](https://pypi.org/project/thrustlab/)
+[![License](https://img.shields.io/pypi/l/thrustlab.svg)](https://github.com/kylebedrich/thrustlab/blob/master/backend/sdks/python/LICENSE)
+
+## Install
+
+```bash
+pip install thrustlab
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+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:
+
+```python
+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
+
+```python
+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](https://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:
+
+```python
+# 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:
+
+```python
+sweep = client.sweeps.create(...)
+result = client.sweeps.wait(sweep["id"], timeout=600, poll_interval=2.0)
+if result["status"] == "succeeded":
+    print(result["outputs"])
+```
+
+## Webhooks
+
+```python
+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:
+
+```python
+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

thrustlab-0.1.0/examples/projects/create.py

@@ -0,0 +1,5 @@
+from thrustlab import Client
+
+client = Client()
+project = client.projects.create(name="my new project")
+print(project)

thrustlab-0.1.0/examples/projects/list.py

@@ -0,0 +1,7 @@
+from thrustlab import Client
+
+client = Client()
+
+# Auto-iterate through all projects
+for project in client.projects.list():
+    print(f"{project['id']} — {project['name']}")

thrustlab-0.1.0/examples/projects/retrieve.py

@@ -0,0 +1,5 @@
+from thrustlab import Client
+
+client = Client()
+project = client.projects.retrieve("proj_xxx")
+print(project)

thrustlab-0.1.0/examples/quickstart.py

@@ -0,0 +1,15 @@
+"""Quickstart: install thrustlab, set $THRUSTLAB_API_KEY, run this file."""
+
+from itertools import islice
+
+from thrustlab import Client
+
+client = Client()  # reads $THRUSTLAB_API_KEY
+
+project = client.projects.create(name="my first project")
+print(f"created project {project['id']}")
+
+print("first 5 motors:")
+for component in islice(client.components.list(type="motor"), 5):
+    brand = component["spec_json"].get("brand", "?")
+    print(f"  {component['id']} — {brand} {component['name']}")

thrustlab-0.1.0/examples/simulations/run_sync.py

@@ -0,0 +1,25 @@
+from thrustlab import Client
+
+client = Client()
+
+sim = client.simulations.create(
+    project_id="proj_xxx",
+    battery_component_id="comp_batt_xxx",
+    airspeed_m_s=0.0,
+    density_kg_m3=1.225,
+    battery_charge_pct=100,
+    rotor_groups=[
+        {
+            "label": "main",
+            "count": 4,
+            "motor_component_id": "comp_motor_xxx",
+            "propeller_component_id": "comp_prop_xxx",
+            "throttle_pct": 70,
+            "esc_resistance_mohm": 0,
+            "esc_motor_wire_resistance_mohm": 0,
+        }
+    ],
+)
+print(f"created {sim['id']}, status={sim['status']}")
+result = client.simulations.wait(sim["id"], timeout=300)
+print(f"final status: {result['status']}")

thrustlab-0.1.0/examples/simulations/wait.py

@@ -0,0 +1,8 @@
+from thrustlab import Client
+
+client = Client()
+
+# Assuming simulation is already running
+sim_id = "sim_xxx"
+result = client.simulations.wait(sim_id, timeout=300, poll_interval=2.0)
+print(f"simulation {sim_id} reached terminal state: {result['status']}")

thrustlab-0.1.0/examples/sweeps/run_and_poll.py

@@ -0,0 +1,30 @@
+from thrustlab import Client
+
+client = Client()
+
+sweep = client.sweeps.create(
+    project_id="proj_xxx",
+    battery_component_id="comp_batt_xxx",
+    airspeed_m_s=0.0,
+    density_kg_m3=1.225,
+    battery_charge_pct=100,
+    rotor_groups=[
+        {
+            "label": "main",
+            "count": 4,
+            "motor_component_id": "comp_motor_xxx",
+            "propeller_component_id": "comp_prop_xxx",
+            "throttle_pct": 70,
+            "esc_resistance_mohm": 0,
+            "esc_motor_wire_resistance_mohm": 0,
+        }
+    ],
+    sweep={
+        "rotor_sweep_mask": [True],
+        "throttle": {"mode": "range", "start": 10, "stop": 100, "steps": 10},
+    },
+)
+print(f"created {sweep['id']}")
+result = client.sweeps.wait(sweep["id"], timeout=600)
+points = list(client.sweeps.list_points(sweep["id"]))
+print(f"sweep done with {len(points)} points; status={result['status']}")

thrustlab-0.1.0/examples/webhooks/verify_handler.py

@@ -0,0 +1,24 @@
+"""Example FastAPI webhook handler verifying incoming events."""
+import os
+from fastapi import FastAPI, Request, HTTPException
+from thrustlab import Webhook
+from thrustlab.exceptions import SignatureVerificationError
+
+app = FastAPI()
+WEBHOOK_SECRET = os.environ["THRUSTLAB_WEBHOOK_SECRET"]
+
+
+@app.post("/webhooks/thrustlab")
+async def thrustlab_webhook(request: Request):
+    payload = await request.body()
+    sig = request.headers.get("Thrustlab-Signature", "")
+    try:
+        event = Webhook.verify(payload, sig, WEBHOOK_SECRET)
+    except SignatureVerificationError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+    if event.type == "simulation.succeeded":
+        sim_id = event.data["id"]
+        # ... do work ...
+
+    return {"received": True}

thrustlab-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "thrustlab"
+dynamic = ["version"]
+description = "Official Python SDK for the ThrustLab API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "ThrustLab", email = "support@thrustlab.com" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "httpx>=0.27,<1.0",
+  "pydantic>=2.7,<3.0",
+  "attrs>=23.0",
+  "python-dateutil>=2.8",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "openapi-python-client>=0.21",
+]
+
+[project.urls]
+Homepage = "https://thrustlab.com"
+Documentation = "https://thrustlab.com/docs"
+Repository = "https://github.com/<owner>/thrustlab"
+Changelog = "https://thrustlab.com/docs/changelog"
+
+[tool.hatch.version]
+path = "thrustlab/_version.py"