Shows the Instant logo

Python Admin SDK

stars

Get Started · Examples · Docs · Discord

Welcome to [Instant's](http://instantdb.com) Python Admin SDK. ## Quickstart ```bash uv add instantdb # or pip install instantdb ``` Requires Python 3.10+. `app_id` and `admin_token` can be passed explicitly or read from `INSTANT_APP_ID` / `INSTANT_APP_ADMIN_TOKEN` environment variables. ```python from instantdb import Instant, id db = Instant( app_id="YOUR_APP_ID", admin_token="YOUR_ADMIN_TOKEN", ) # Transact (InstaML) goal_id = id() db.transact(db.tx.goals[goal_id].update({"title": "Get fit"})) # Query (InstaQL) result = db.query({"goals": {"todos": {}}}) # Auth: magic codes, tokens, user management token = db.auth.create_token(email="alyssa@example.com") # Impersonate for permission-scoped queries scoped = db.as_user(guest=True) scoped_result = scoped.query({"goals": {}}) ``` The async client (`AsyncInstant`) ships the same surface plus `subscribe_query` (live SSE subscriptions) and `streams` (durable bidirectional byte streams). Use it from FastAPI handlers, agents, or anywhere you're already running an event loop: ```python import asyncio from instantdb import AsyncInstant adb = AsyncInstant() async def main(): async with adb.subscribe_query({"goals": {}}) as sub: async for payload in sub: process(payload) asyncio.run(main()) ``` Head on over to the [Python Docs](https://www.instantdb.com/docs/start-python) for more usage docs! ## Development ```bash cd client/packages/python uv sync make check # ruff + mypy strict + pytest make fmt ``` ### Editing the SDK source **Only edit `src/instantdb/_async/`.** The sync client at `src/instantdb/_sync/` is generated from the async tree via [`unasync`](https://github.com/python-trio/unasync) and is committed to the repo. After any change to `_async/`, regenerate: ```bash make unasync ``` This runs `scripts/run_unasync.py` (preprocesses + applies replacement rules) then ruff (import sort + format). Commit the generated `_sync/` tree alongside your async change. Some modules under `_async/` are intentionally async-only — they're listed in the `ASYNC_ONLY` set in `scripts/run_unasync.py` and each one explains its rationale in its own docstring (typically: relies on asyncio coordination primitives that don't survive unasync's token-rewrite). **Adding a new file under `_async/`**: - HTTP-shaped surface (request/response, no background tasks): just drop it in and re-run `make unasync` — it'll be picked up automatically. - Async-only surface (background tasks, asyncio coordination): drop it in, add its path to `ASYNC_ONLY` in `scripts/run_unasync.py`, and note the why in the module's docstring so the next person doesn't have to figure it out. If you add a method or import that should exist only on the async client (inside a file that _is_ unasynced), wrap it in marker comments and re-run `make unasync`: ```python # UNASYNC_REMOVE_START def new_async_only_method(self): ... # UNASYNC_REMOVE_END ``` Full mechanics — replacement rules, preprocessing details, what to avoid — live in the docstring of `scripts/run_unasync.py`. ### Testing changes We test in three layers, fastest to most realistic: 1. **Unit tests** (`make check`) — validation, header construction, error parsing, and pure-logic helpers (buffer-discard math, dispatch precedence, etc.). No network. This is the fast inner loop. 2. **Sandbox integration tests** — exercise the SDK against a real Instant server and assert on outcomes. Similar to how we test the JS admin SDK. 3. **End-to-end branch test** — scaffold a real consumer project that pulls the SDK from your branch, then run a script the way a user would. #### Sandbox (integration) The sandbox at `client/sandbox/admin-sdk-python/` is the integration layer. ```bash cd ../../sandbox/admin-sdk-python cp .env.example .env # fill in INSTANT_APP_ID + INSTANT_APP_ADMIN_TOKEN uv sync # uncomment a tester call inside main() in src/main.py uv run --env-file .env python -m src.main ``` Two entry points: `src/main.py` for the async client (everything, including subscribe + streams) and `src/main_sync.py` for the sync client (auth, query, transact, storage, rooms, webhooks). Tester calls are commented out at rest — uncomment the one you want, run it, re-comment before committing. Defaults to `http://localhost:8888`; set `INSTANT_API_URI` in `.env` to point elsewhere. #### End-to-end (a real project on your branch) To exercise a change the way a user would — scaffold a project, install the SDK, run a script — point a fresh `create-instant-app` project at your branch: 1. Push your branch to GitHub (e.g. `my-feature`). 2. Scaffold a project with the per-branch build of `create-instant-app` (the `@branch-` tag is published automatically per branch): ```bash cd /tmp pnpx create-instant-app@branch-my-feature --python my-app cd my-app ``` 3. The scaffold pulls `instantdb` from PyPI by default, which won't have your branch's changes. Point it at your branch by adding a `[tool.uv.sources]` entry to the scaffolded `pyproject.toml`: ```toml [tool.uv.sources] instantdb = { git = "https://github.com/instantdb/instant.git", branch = "my-feature", subdirectory = "client/packages/python" } ``` 4. Sync and run (the scaffolder already wrote a working `.env`): ```bash uv sync # clones the repo, builds the SDK from your branch, installs it uv run --env-file .env python main.py ``` If you already have the monorepo checked out and are iterating on the SDK, use a local editable path instead so source edits show up without re-syncing from git: ```toml [tool.uv.sources] instantdb = { path = "/absolute/path/to/client/packages/python", editable = true } ``` # Questions? If you have any questions, feel free to drop us a line on our [Discord](https://discord.com/invite/VU53p7uQcE)