Metadata-Version: 2.4
Name: instantdb
Version: 1.0.45
Summary: Server-side Python SDK for InstantDB — the Modern Firebase
Project-URL: Homepage, https://www.instantdb.com
Project-URL: Documentation, https://www.instantdb.com/docs
Project-URL: Repository, https://github.com/instantdb/instant
Project-URL: Issues, https://github.com/instantdb/instant/issues
Author: Instant
License-Expression: Apache-2.0
Keywords: admin,database,instant,instantdb,realtime
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
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
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: cryptography>=42
Requires-Dist: httpx-sse>=0.4
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://instantdb.com">
    <img alt="Shows the Instant logo" src="https://instantdb.com/img/icon/android-chrome-512x512.png" width="10%">
  </a>
  <h1 align="center">Python Admin SDK</h1>
</p>

<p align="center">
  <a
    href="https://discord.com/invite/VU53p7uQcE" >
    <img height=20 src="https://img.shields.io/discord/1031957483243188235" />
  </a>
  <img src="https://img.shields.io/github/stars/instantdb/instant" alt="stars">
</p>

<p align="center">
   <a href="https://www.instantdb.com/docs/start-python">Get Started</a> ·
   <a href="https://instantdb.com/examples">Examples</a> ·
   <a href="https://www.instantdb.com/docs/backend">Docs</a> ·
   <a href="https://discord.com/invite/VU53p7uQcE">Discord</a>
</p>

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-<your-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)
