supabase-orm 0.1.0__tar.gz → 0.1.2__tar.gz

{supabase_orm-0.1.0 → supabase_orm-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supabase-orm
-Version: 0.1.0
+Version: 0.1.2
 Summary: Lightweight async ORM on top of supabase-py with Pydantic validation.
 Project-URL: Homepage, https://github.com/viperadnan-git/supabase-orm
 Project-URL: Repository, https://github.com/viperadnan-git/supabase-orm
@@ -48,19 +48,23 @@ Description-Content-Type: text/markdown
 
 - **Type-safe query builder.** Every operator on `Model.query` is a real method with a real signature — autocomplete works, typos surface as `AttributeError` at call time, not as silent server-side errors.
 
+- **Typed predicate expressions.** `Pet.f.age >= 5` builds a composable `Predicate`. Combine with `|` / `&` / `~` and pass to `.or_()` / `.not_()`. Reads as boolean logic, type-checks as expressions.
+
+- **Keyset iteration that scales.** `async for pet in Pet.query.eq(...).iter():` paginates by PK with constant-time-per-batch and no offset cliff. Works on tables of any size; race-safe under concurrent inserts and deletes.
+
 - **Pydantic v2 throughout.** Your model *is* the row schema, the response schema, and the request body schema. No DTO layer.
 
 - **Async-first.** Built for `asyncio` and FastAPI — every terminal call is `await`-able, every chain is a fresh builder.
 
 - **PostgREST embeds, declared at the type level.** Mark a field as `Annotated[Owner, Relation(...)]` and the ORM builds the right `select=` string for you, including `!inner` / FK hints / per-relation filters.
 
-- **Per-request RLS via `ContextVar`.** Attach a JWT in a FastAPI middleware and Postgres row-level security sees the user. No client-per-request overhead, no leakage between concurrent requests.
+- **Per-request RLS via `ContextVar`.** Pair `use_client()` with a JWT-authenticated client in a FastAPI middleware — Postgres row-level security sees the user, with zero leakage between concurrent requests.
 
 - **Typed RPC helpers.** Call `setof` functions with row validation, get a single row, or coerce a scalar — all with one line.
 
 - **Opt-in foot-gun guards.** Unfiltered bulk `delete()` / `update()` raise unless you pass `allow_unfiltered=True`.
 
-- **Tested both ways.** 166 mock tests cover the wire contract (every operator, every serializer, every shorthand). 34 integration tests run against a real Supabase project to confirm PostgREST actually interprets those calls the way we expect.
+- **Tested both ways.** 230+ mock tests cover the wire contract (every operator, every serializer, every shorthand, predicate composition, keyset iteration). 60+ integration tests run against a real Supabase project to confirm PostgREST actually interprets those calls the way we expect.
 
 ---
 
@@ -105,10 +109,16 @@ class PetWithOwner(SupabaseModel, table="pets"):
 
 
 async with lifespan(SUPABASE_URL, SUPABASE_KEY):
-    # Read
+    # Read — chain style for sequential AND
     cats = await Pet.query.eq("species", "cat").order_by("-created_at").limit(10).all()
     one = await PetWithOwner.get(some_id)
 
+    # Read — typed predicates for OR / NOT / nested boolean logic
+    rescues = await Pet.query.or_(
+        Pet.f.species == "cat",
+        (Pet.f.species == "dog") & (Pet.f.adopted == False),
+    ).all()
+
     # Write
     p = await Pet.create(name="Whiskers", species="cat", adopted=False)
     p.name = "Mr. Whiskers"
@@ -135,11 +145,12 @@ class Pet(SupabaseModel, table="pets"):
 
 ### Class kwargs
 
-| Kwarg    | Default | What it does                                                    |
-|----------|---------|-----------------------------------------------------------------|
-| `table`  | —       | PostgREST table or view name. **Required.**                     |
-| `pk`     | `"id"`  | Primary-key field name. Used by `get()`, `save()`, `delete()`.  |
-| `select` | auto    | Override the auto-derived `select=` string. Escape hatch only.  |
+| Kwarg         | Default          | What it does                                                                |
+|---------------|------------------|-----------------------------------------------------------------------------|
+| `table`       | —                | PostgREST table or view name. **Required.**                                 |
+| `pk`          | `"id"`           | Primary-key field name. Used by `get()`, `save()`, `delete()`, `iter()`.    |
+| `select`      | auto             | Override the auto-derived `select=` string. Escape hatch only.              |
+| `query_class` | `QueryBuilder`   | Custom `QueryBuilder` subclass for `.query`. MRO-inherited via base models. |
 
 ### Relations
 
@@ -164,24 +175,58 @@ class PetWithOwner(SupabaseModel, table="pets"):
 
 ### Lean projections
 
-Two models can point at the same table for full-detail vs. trimmed views:
+Two models on the same table — full-detail vs. trimmed view. Just query the lean one directly when its fields are enough:
 
 ```python
 class Pet(SupabaseModel, table="pets"):
     id: UUID
     name: str
     species: str
+    bio: str           # heavy column you don't always need
     created_at: datetime
 
 class PetMini(SupabaseModel, table="pets"):
     id: UUID
     name: str
 
-# Build the full query, then rebind:
-mini_rows = await Pet.query.eq("adopted", False).as_(PetMini).all()
-# → list[PetMini]
+# Half the wire bytes, fewer Pydantic fields to validate:
+await PetMini.query.eq("species", "cat").all()
+```
+
+For huge result sets, pair with `.iter()` so the lean projection runs per batch:
+
+```python
+async for mini in PetMini.query.iter(batch_size=5000):
+    process(mini)
 ```
 
+### `.as_(target)` — rebind the response shape
+
+Use `.as_()` when you need to **filter on source columns the lean model doesn't expose**, or to switch the response shape conditionally without rebuilding the chain. Two modes:
+
+**Same-table SupabaseModel** — narrows the wire `select` AND validates against the target:
+
+```python
+# Wire: ?select=id,name  →  list[PetMini]
+await Pet.query.eq("adopted", False).as_(PetMini).all()
+```
+
+**Plain Pydantic BaseModel** — validation only, wire `select` unchanged. The chain keeps using the source model's columns and predicates:
+
+```python
+from pydantic import BaseModel
+
+class PetCard(BaseModel):
+    id: UUID
+    name: str
+
+# Filter on `bio` (only on Pet) but validate as PetCard:
+await Pet.query.fts("bio", "fluffy").as_(PetCard).all()
+# → list[PetCard], wire still selects all of Pet's columns
+```
+
+If a same-table SupabaseModel target works, prefer it — you get the wire-narrowing optimization. Reach for the plain BaseModel form only when the lean schema doesn't have all the columns you need to filter on.
+
 ---
 
 ## Querying
@@ -196,12 +241,13 @@ mini_rows = await Pet.query.eq("adopted", False).as_(PetMini).all()
 | `.maybe_one()`        | `T \| None`            | At most one row. Raises if >1.                                          |
 | `.count()`            | `int`                  | Head-only request with `count="exact"`.                                 |
 | `.all_with_count()`   | `tuple[list[T], int]`  | Rows + filtered total in one round-trip (for paginated endpoints).      |
+| `.iter(batch_size=)`  | `AsyncIterator[T]`     | Stream every matching row via PK keyset pagination. Scales to any size. |
 | `.values(*cols)`      | `list[dict]`           | Ad-hoc projection, raw dicts, no Pydantic validation.                   |
 | `.raw()`              | postgrest builder      | Escape hatch.                                                           |
 
 ### Filter operators
 
-Every operator below works as a method on `Model.query` **and** inside `or_()` / `not_()` predicate lambdas:
+Every operator below works as a method on `Model.query` (chain style) and as a method/operator on `Model.f.<column>` (predicate style):
 
 ```python
 Pet.query.eq("species", "cat")
@@ -216,34 +262,127 @@ Pet.query.overlaps("tags", ["indoor"])
 Pet.query.fts("description", "fluffy")          # plus plfts / phfts / wfts
 ```
 
-### Compound predicates
+### Typed predicates (`Pet.f`)
+
+For OR / NOT / nested boolean logic, use the `Model.f` namespace. Every column is a typed `Column[T]` with operator overloads — `==`, `!=`, `<`, `<=`, `>`, `>=` build atomic predicates, and `|` / `&` / `~` compose them.
+
+```python
+from supabase_orm import SupabaseModel
+
+class Pet(SupabaseModel, table="pets"):
+    id: UUID
+    name: str
+    species: str
+    age: int
+    adopted: bool
+    tags: list[str]
+
+# Atomic predicates — what `==`, `>=` etc. return:
+Pet.f.species == "cat"            # column.eq.value
+Pet.f.age >= 5
+Pet.f.name.like("Mr%")
+Pet.f.tags.contains(["indoor"])
+Pet.f.owner_id.is_null()
+```
+
+Compose with boolean operators:
+
+```python
+# OR
+await Pet.query.or_(
+    Pet.f.species == "cat",
+    Pet.f.species == "dog",
+).all()
+
+# OR with AND inside a branch
+await Pet.query.or_(
+    Pet.f.species == "cat",
+    (Pet.f.species == "dog") & (Pet.f.age >= 5),
+).all()
+
+# NOT — negates any predicate, atomic or compound
+await Pet.query.not_(Pet.f.adopted == True).all()
+await Pet.query.not_((Pet.f.species == "cat") | (Pet.f.species == "dog")).all()
+```
+
+The chain and predicates compose freely — chain handles sequential AND, predicates handle boolean logic:
+
+```python
+await (
+    Pet.query.eq("owner_id", uid)                       # chain: AND
+    .or_(Pet.f.species == "cat", Pet.f.species == "dog") # predicate: OR
+    .order_by("-created_at")
+    .limit(20)
+    .all()
+)
+```
+
+#### Foot-gun guards
+
+```python
+if Pet.f.age >= 5:           # TypeError: Predicate is not a bool
+    ...
+```
+
+A predicate is an expression that builds a query — it has no truth value at the call site. The runtime rejects `bool(predicate)` loudly so `if Pet.f.adopted == True:` mistakes fail at the first hit instead of always being truthy.
+
+#### Lambda form
 
 ```python
-# OR across branches:
 await Pet.query.or_(
     lambda q: q.eq("species", "cat"),
     lambda q: q.eq("species", "dog").gte("age", 5),
 ).all()
-
-# NOT:
-await Pet.query.not_(lambda q: q.eq("adopted", True)).all()
 ```
 
+Prefer the `Pet.f` form — it composes, reads as boolean logic, and gives operator-level type safety.
+
 ### `match()` — multi-column equality
 
 ```python
 await Pet.query.match({"species": "cat", "adopted": False}).all()
 ```
 
-PostgREST's `match` is multi-column by design and has no predicate-string form, so it isn't usable inside `or_()` / `not_()`.
+`match` is a `postgrest-py` convenience — it just expands to multiple `eq` filters on the wire, equivalent to chaining `.eq()` per pair or composing `(Pet.f.a == 1) & (Pet.f.b == 2)`. Use whichever reads best.
 
 ### Ordering & pagination
 
+`order_by()` accepts strings (`"-col"` for descending) or typed `Pet.f.<col>.asc()` / `.desc()`. The typed form unlocks `nulls="first"` / `"last"` and gets autocomplete + column-existence checks.
+
 ```python
+# String shorthand
 await Pet.query.order_by("-created_at", "name").limit(20).offset(40).all()
-await Pet.query.range(0, 9).all()       # PostgREST-style inclusive range
+await Pet.query.range(0, 9).all()                           # inclusive range
+
+# Typed form — autocomplete on Pet.f, nulls position support
+await Pet.query.order_by(Pet.f.created_at.desc()).all()
+await Pet.query.order_by(Pet.f.last_login.desc(nulls="last")).all()
+
+# Mix freely
+await Pet.query.order_by("species", Pet.f.amount.desc()).all()
 ```
 
+Typos in either form raise `AttributeError` at call time — never silent server errors.
+
+### Iteration over large result sets
+
+`.iter()` streams every matching row using **PK keyset pagination** — `WHERE pk > :cursor ORDER BY pk LIMIT :batch_size` per batch. Constant time per batch regardless of position; scales to billions of rows.
+
+```python
+async for pet in Pet.query.eq("species", "cat").iter():
+    process(pet)
+
+# Tune batch size for the memory / round-trip tradeoff:
+async for row in BigTable.query.iter(batch_size=5000):
+    ...
+
+# Compose with projections to narrow wire bytes per batch:
+async for mini in Pet.query.eq("species", "cat").as_(PetMini).iter():
+    ...
+```
+
+`.iter()` owns ordering and pagination — chaining `.order_by()` / `.limit()` / `.offset()` / `.range()` before it raises `SupabaseORMUsageError`. Race-safe under concurrent inserts (new rows with `pk > cursor` get picked up) and deletes (deleted rows simply don't appear).
+
 ### Pagination with total
 
 ```python
@@ -363,19 +502,24 @@ app = FastAPI(lifespan=lifespan)
 
 ### Per-request RLS via JWT
 
-The client is stored in a `ContextVar`, so each FastAPI request runs in its own copied context — `set_auth()` mutations are isolated to that request, even under concurrent load.
+The client is stored in a `ContextVar`, so each FastAPI request runs in its own copied context. Pair `use_client()` with a per-request authenticated client to isolate the JWT — and therefore the RLS identity — to that request only:
 
 ```python
-from supabase_orm import set_auth
+from supabase import acreate_client
+from supabase_orm import use_client
 
 @app.middleware("http")
-async def attach_jwt(request, call_next):
-    if (auth := request.headers.get("authorization")):
-        set_auth(auth.removeprefix("Bearer "))
-    try:
+async def per_request_client(request, call_next):
+    auth = request.headers.get("authorization")
+    if not auth:
+        return await call_next(request)
+
+    jwt = auth.removeprefix("Bearer ")
+    client = await acreate_client(SUPABASE_URL, SUPABASE_ANON_KEY)
+    client.postgrest.auth(jwt)
+
+    async with use_client(client):
         return await call_next(request)
-    finally:
-        set_auth(None)   # back to the anon/service-role key from lifespan
 ```
 
 Inside a handler, just call the ORM as usual — Postgres RLS sees the user:
@@ -386,6 +530,9 @@ async def my_pets():
     return await Pet.query.order_by("-created_at").all()
 ```
 
+> [!IMPORTANT]
+> Don't mutate the app-wide client's auth headers across requests (e.g. `get_client().postgrest.auth(jwt)` directly). The underlying postgrest sub-client is shared, so the mutation leaks across overlapping requests. `ContextVar` isolates *references*, not the objects they point at — `use_client()` with a per-request client is the only safe pattern.
+
 ### Per-request override with a dedicated client
 
 For background tasks, scripts, or any place outside the request lifecycle:
@@ -428,6 +575,40 @@ class Money:
 register_serializer(Money, lambda v: v.cents)
 ```
 
+### Custom `QueryBuilder` methods
+
+Subclass `QueryBuilder` to add your own chainable methods, then opt in either per-model or project-wide.
+
+```python
+from supabase_orm import QueryBuilder, SupabaseModel
+
+class PaginatedQB(QueryBuilder):
+    async def paginate(self, *, page: int, per_page: int):
+        return await self.range(
+            page * per_page, (page + 1) * per_page - 1
+        ).all_with_count()
+```
+
+**Project-wide** — define a base model once, every subclass inherits via MRO:
+
+```python
+class _AppModel(SupabaseModel):
+    __query_class__ = PaginatedQB
+
+class User(_AppModel, table="users"):  # gets PaginatedQB automatically
+    id: UUID
+    email: str
+
+rows, total = await User.query.eq("is_active", True).paginate(page=0, per_page=20)
+```
+
+**Per-model** — opt in inline, no base class needed:
+
+```python
+class Audit(SupabaseModel, table="audit_log", query_class=PaginatedQB):
+    ...
+```
+
 ---
 
 ## Error handling
@@ -456,7 +637,6 @@ from supabase_orm import (
 - Unfiltered bulk `delete()` / `update()` without `allow_unfiltered=True`.
 - `as_()` to a model on a different table.
 - `instance.update()` trying to change the primary key or a relation field.
-- `set_auth(None)` with no recorded default key.
 
 Map them to HTTP responses in one place: