Metadata-Version: 2.5
Name: stitchdb
Version: 2.1.0
Summary: Official Python client for StitchDB: database, auth, storage, realtime and Edge Functions.
Project-URL: Homepage, https://stitchdb.com
Project-URL: Documentation, https://stitchdb.com/docs/sdk/python
Project-URL: Repository, https://github.com/stitchdb/stitchdb-python
Project-URL: Issues, https://github.com/stitchdb/stitchdb-python/issues
Author-email: StitchDB <support@stitchdb.com>
License-Expression: MIT
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES
Keywords: auth,database,postgres,realtime,stitchdb,storage
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: deprecation>=2.1.0
Requires-Dist: httpx[http2]<0.29,>=0.26
Requires-Dist: pydantic<3,>=2.11.7
Requires-Dist: pyjwt[crypto]>=2.12.0
Requires-Dist: strenum>=0.4.15
Requires-Dist: typing-extensions>=4.14.0
Requires-Dist: websockets<16,>=11
Requires-Dist: yarl>=1.22.0
Provides-Extra: iceberg
Requires-Dist: pyiceberg>=0.10.0; extra == 'iceberg'
Description-Content-Type: text/markdown

# stitchdb

The official Python client for [StitchDB](https://stitchdb.com): Postgres database, auth, storage, realtime and Edge Functions. Sync and async.

```bash
pip install stitchdb
```

Python 3.9+. To install the latest code from this repository instead: `pip install "git+https://github.com/stitchdb/stitchdb-python"`.

```python
import os
from stitchdb import create_client

stitchdb = create_client(os.environ["STITCHDB_URL"], os.environ["STITCHDB_KEY"])

# Database (respects Row Level Security)
rows = stitchdb.table("todos").select("id, task").eq("is_complete", False).limit(10).execute().data
stitchdb.table("todos").insert({"task": "Ship it"}).execute()
stitchdb.rpc("search_todos", {"term": "ship"}).execute()

# Auth
stitchdb.auth.sign_in_with_password({"email": "ada@example.com", "password": "..."})
user = stitchdb.auth.get_user()

# Storage
stitchdb.storage.from_("avatars").upload("user-1/avatar.png", open("avatar.png", "rb").read())
url = stitchdb.storage.from_("avatars").create_signed_url("user-1/avatar.png", 60)

# Edge Functions
stitchdb.functions.invoke("hello-world", {"body": {"name": "Ada"}})
```

Async: `from stitchdb import acreate_client` and `stitchdb = await acreate_client(url, key)`. Realtime needs the async client.

## App services

The same client reaches StitchDB's app services (turn each on in Studio first). Errors raise a
subclass of `stitchdb.StitchDBAppsError` (`.status`, `.code`, `.message`).

```python
stitchdb.flags.load(attributes={"app_version": "2.4.1"})
if stitchdb.flags.is_on("new-checkout"): ...

stitchdb.analytics.track("purchase", {"plan": "pro"}); stitchdb.analytics.flush()
stitchdb.crashes.start(release="2.4.1")          # reports uncaught exceptions
stitchdb.push.register({"platform": "android", "token": fcm_token})
stitchdb.purchases.has_entitlement("pro")
stitchdb.search("articles", "postgres backups", mode="hybrid")
stitchdb.orgs.create("Acme")
offline = stitchdb.offline(["todos"], path="todos.json"); offline.sync()

# Server side, with the service key
stitchdb.jobs.start("send-invoice", {"order": 42}, idempotency_key="order-42")
stitchdb.metering.record("api_calls", 1, customer="acme")
```

Also: `links` (deep links), `collab` (collaborative documents), `history` (realtime message
history and `replay`), `heartbeat` (job monitoring), `status_page`, `graphql()`, and in
`stitchdb.auth`: `sign_in_with_web3`, `passkey`, `oauth` (consent), `mfa.recovery_codes`.

Standalone helpers:

```python
from stitchdb import create_sql, verify_webhook, AgentClient

sql = create_sql(os.environ["STITCHDB_SQL_URL"])            # SQL over HTTP: https://<sql key>@<host>
rows = sql.query("select * from orders where id = $1", [42])

event = verify_webhook(request_body, request_headers, secret=WEBHOOK_SECRET)  # raises if not genuine

agent = AgentClient(os.environ["STITCHDB_AGENT_KEY"])        # sdb_agt_ keys for AI agents
agent.sql("select count(*) from orders", session="task-1")
```

Find your project URL and keys in the dashboard under **Settings → API keys**. Use the `service_role` key only on servers you control.

Documentation: https://stitchdb.com/docs/sdk/python
