supabase-orm 0.0.0__tar.gz

supabase_orm-0.0.0/.gitignore

@@ -0,0 +1,114 @@
+# Generated by hatch-vcs
+src/supabase_orm/_version.py
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv / poetry / pdm / uv
+Pipfile.lock
+poetry.lock
+pdm.lock
+.pdm.toml
+.pdm-python
+.pdm-build/
+__pypackages__/
+
+# Environments
+.env
+.env.*
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy / pyright / ruff
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

supabase_orm-0.0.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: supabase-orm
+Version: 0.0.0
+Summary: Lightweight async ORM on top of supabase-py with Pydantic validation.
+Author-email: Adnan Ahmad <viperadnan@gmail.com>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: supabase>=2.30.0
+Description-Content-Type: text/markdown
+
+# supabase-orm
+
+Lightweight async ORM on top of `supabase-py` with Pydantic validation.
+
+```python
+from uuid import UUID
+from typing import Annotated
+from supabase_orm import SupabaseModel, Relation, lifespan
+
+
+class User(SupabaseModel, table="users"):
+    id: UUID
+    name: str
+
+
+class Pet(SupabaseModel, table="pets"):
+    id: UUID
+    name: str
+    species: str
+    adopted: bool
+
+
+class PetWithOwner(SupabaseModel, table="pets"):
+    id: UUID
+    name: str
+    species: str
+    owner: Annotated[User, Relation(join="inner")]
+
+
+# In FastAPI lifespan:
+async with lifespan(SUPABASE_URL, SUPABASE_KEY):
+    # Read
+    rows = await Pet.query.eq("species", "cat").order_by("-created_at").limit(10).all()
+    one  = await PetWithOwner.get(some_id)
+
+    # Write
+    p = await Pet.create(name="Whiskers", species="cat", adopted=False)
+    p.name = "Mr. Whiskers"
+    await p.save()
+
+    # Bulk
+    await Pet.query.eq("adopted", False).update(adopted=True)
+    await Pet.query.eq("species", "fish").lt("created_at", cutoff).delete()
+```
+
+## Status
+
+In-repo workspace package. Will be lifted to its own repo and published to
+PyPI later. Until then, depend on it via `uv` workspace.

supabase_orm-0.0.0/README.md

@@ -0,0 +1,49 @@
+# supabase-orm
+
+Lightweight async ORM on top of `supabase-py` with Pydantic validation.
+
+```python
+from uuid import UUID
+from typing import Annotated
+from supabase_orm import SupabaseModel, Relation, lifespan
+
+
+class User(SupabaseModel, table="users"):
+    id: UUID
+    name: str
+
+
+class Pet(SupabaseModel, table="pets"):
+    id: UUID
+    name: str
+    species: str
+    adopted: bool
+
+
+class PetWithOwner(SupabaseModel, table="pets"):
+    id: UUID
+    name: str
+    species: str
+    owner: Annotated[User, Relation(join="inner")]
+
+
+# In FastAPI lifespan:
+async with lifespan(SUPABASE_URL, SUPABASE_KEY):
+    # Read
+    rows = await Pet.query.eq("species", "cat").order_by("-created_at").limit(10).all()
+    one  = await PetWithOwner.get(some_id)
+
+    # Write
+    p = await Pet.create(name="Whiskers", species="cat", adopted=False)
+    p.name = "Mr. Whiskers"
+    await p.save()
+
+    # Bulk
+    await Pet.query.eq("adopted", False).update(adopted=True)
+    await Pet.query.eq("species", "fish").lt("created_at", cutoff).delete()
+```
+
+## Status
+
+In-repo workspace package. Will be lifted to its own repo and published to
+PyPI later. Until then, depend on it via `uv` workspace.

supabase_orm-0.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "supabase-orm"
+description = "Lightweight async ORM on top of supabase-py with Pydantic validation."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Adnan Ahmad", email = "viperadnan@gmail.com" }]
+license = { text = "MIT" }
+dynamic = ["version"]
+dependencies = [
+    "pydantic>=2.13.4",
+    "supabase>=2.30.0",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "0.0.0"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/supabase_orm/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/supabase_orm"]

supabase_orm-0.0.0/src/supabase_orm/__init__.py

@@ -0,0 +1,48 @@
+"""ORM public API.
+
+    from supabase_orm import SupabaseModel, Relation, lifespan, rpc
+
+    class Pet(SupabaseModel, table="pets"):
+        id: UUID
+        name: str
+        species: str
+        adopted: bool
+
+Internals live in underscore-prefixed modules; only names re-exported here
+are part of the supported surface.
+"""
+
+from ._base import SupabaseModel
+from ._client import get_client, lifespan, set_client
+from ._embed import Relation
+from ._exceptions import (
+    SupabaseORMUsageError,
+    SupabaseORMDoesNotExist,
+    SupabaseORMError,
+    SupabaseORMMultipleObjectsReturned,
+)
+from ._filters import register_op
+from ._query import QueryBuilder
+from ._rpc import rpc, rpc_maybe_one, rpc_one, rpc_scalar
+from ._serializers import register_serializer
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    "SupabaseModel",
+    "Relation",
+    "QueryBuilder",
+    "lifespan",
+    "get_client",
+    "set_client",
+    "rpc",
+    "rpc_one",
+    "rpc_maybe_one",
+    "rpc_scalar",
+    "register_op",
+    "register_serializer",
+    "SupabaseORMError",
+    "SupabaseORMDoesNotExist",
+    "SupabaseORMMultipleObjectsReturned",
+    "SupabaseORMUsageError",
+]

supabase_orm-0.0.0/src/supabase_orm/_base.py

@@ -0,0 +1,264 @@
+"""SupabaseModel — Pydantic + PostgREST ORM base.
+
+Subclass with ``table=``:
+
+    class Pet(SupabaseModel, table="pets"):
+        id: UUID
+        name: str
+        species: str
+        adopted: bool
+
+Then chain queries off ``Model.query``:
+
+    rows = await Pet.query.eq("species", "cat").order_by("-created_at").limit(10).all()
+    one  = await Pet.get(id)
+    p    = await Pet.create(name="Whiskers", species="cat", adopted=False)
+    p.name = "Mr. Whiskers"; await p.save()
+    await p.delete()
+    await Pet.query.eq("adopted", False).delete()                 # bulk
+    await Pet.query.eq("adopted", False).update(adopted=True)     # bulk
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Self, TypeVar
+
+from pydantic import BaseModel, ConfigDict, TypeAdapter
+
+from ._client import get_client
+from ._embed import Relation, build_select, collect_relations
+from ._exceptions import SupabaseORMUsageError, SupabaseORMDoesNotExist
+from ._query import QueryBuilder
+from ._serializers import serialize
+
+_TABLE_REGISTRY: dict[str, list[type["SupabaseModel"]]] = {}
+
+_T = TypeVar("_T", bound="SupabaseModel")
+
+
+class _QueryDescriptor:
+    """Returns a fresh ``QueryBuilder[Owner]`` per access.
+
+    Typed via the ``owner`` parameter, so ``Pet.query`` is inferred as
+    ``QueryBuilder[Pet]`` by static checkers — every operator on the chain
+    has a real signature and works with autocomplete.
+    """
+
+    def __get__(
+        self, instance: Any, owner: type[_T]
+    ) -> "QueryBuilder[_T]":
+        if not owner.__table__:
+            raise SupabaseORMUsageError(
+                f"{owner.__name__} has no __table__. Declare with "
+                f'`class {owner.__name__}(SupabaseModel, table="..."):`'
+            )
+        return QueryBuilder(owner)
+
+
+class SupabaseModel(BaseModel):
+    """Base class for tables. Configure per-subclass via class kwargs.
+
+    Class kwargs:
+        table:  PostgREST table / view name. Required on concrete subclasses.
+        pk:     Primary key field name. Default ``"id"``.
+        select: Override the auto-derived select string (escape hatch).
+    """
+
+    model_config = ConfigDict(
+        validate_assignment=True,
+        extra="ignore",
+    )
+
+    __table__: ClassVar[str] = ""
+    __pk__: ClassVar[str] = "id"
+    __select__: ClassVar[str] = ""
+    __select_override__: ClassVar[str | None] = None
+    # Populated by ``__pydantic_init_subclass__`` so hot paths don't reflect
+    # over ``model_fields`` on every query.
+    __relations__: ClassVar[dict[str, tuple[type, bool, Relation]]] = {}
+    __list_adapter__: ClassVar[TypeAdapter | None] = None
+
+    query: ClassVar[_QueryDescriptor] = _QueryDescriptor()
+
+    def __init_subclass__(
+        cls,
+        *,
+        table: str | None = None,
+        pk: str = "id",
+        select: str | None = None,
+        **kw: Any,
+    ) -> None:
+        # Pydantic populates model_fields AFTER this hook runs, so we just
+        # capture the table-level kwargs here. ``__pydantic_init_subclass__``
+        # below builds the cached metadata once fields are available.
+        super().__init_subclass__(**kw)
+        if table is None:
+            return
+        cls.__table__ = table
+        cls.__pk__ = pk
+        cls.__select_override__ = select
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kw: Any) -> None:
+        if not cls.__table__:
+            return
+        cls.__select__ = (
+            cls.__select_override__
+            if cls.__select_override__ is not None
+            else build_select(cls)
+        )
+        cls.__relations__ = collect_relations(cls)
+        cls.__list_adapter__ = TypeAdapter(list[cls])
+        _TABLE_REGISTRY.setdefault(cls.__table__, []).append(cls)
+
+    # ─── Builder entry point ───────────────────────────────────────────────
+
+    @classmethod
+    def _validate_column(cls, name: str) -> None:
+        """Surface typos at call time. Allows scalar fields and any
+        ``relation.column`` form (PostgREST embed-filter syntax)."""
+        head, _, _ = name.partition(".")
+        if head in cls.model_fields:
+            return
+        raise AttributeError(
+            f"{cls.__name__} has no column {head!r}. "
+            f"Known: {sorted(cls.model_fields)}"
+        )
+
+    # ─── PK shortcuts ──────────────────────────────────────────────────────
+
+    @classmethod
+    async def get(cls, pk_value: Any) -> Self:
+        """Fetch by primary key. Raises ``SupabaseORMDoesNotExist`` on miss."""
+        row = await cls.query.eq(cls.__pk__, pk_value).maybe_one()
+        if row is None:
+            raise SupabaseORMDoesNotExist(
+                f"{cls.__name__}({cls.__pk__}={pk_value!r}) not found"
+            )
+        return row
+
+    @classmethod
+    async def find(cls, pk_value: Any) -> Self | None:
+        """Fetch by primary key. Returns ``None`` on miss."""
+        return await cls.query.eq(cls.__pk__, pk_value).maybe_one()
+
+    # ─── Writes ────────────────────────────────────────────────────────────
+
+    @classmethod
+    async def create(cls, **values: Any) -> Self:
+        """Insert a row in a single round-trip.
+
+        Uses postgrest's ``insert(...).execute()`` which returns the inserted
+        row. For models with relations we still need a second round-trip to
+        fetch embeds, since ``insert`` only returns columns from the
+        inserted table.
+        """
+        payload = {k: serialize(v) for k, v in values.items()}
+        client = get_client()
+        ins = await client.table(cls.__table__).insert(payload).execute()
+        if not ins.data:
+            raise ValueError(f"{cls.__name__}.create returned no rows")
+        if cls.__relations__:
+            return await cls.get(ins.data[0][cls.__pk__])
+        return cls.model_validate(ins.data[0])
+
+    @classmethod
+    async def bulk_create(cls, rows: list[dict[str, Any]]) -> list[Self]:
+        if not rows:
+            return []
+        payload = [{k: serialize(v) for k, v in r.items()} for r in rows]
+        client = get_client()
+        ins = await client.table(cls.__table__).insert(payload).execute()
+        data = ins.data or []
+        if not data:
+            return []
+        if cls.__relations__:
+            ids = [r[cls.__pk__] for r in data]
+            return await cls.query.in_(cls.__pk__, ids).all()
+        adapter = cls.__list_adapter__
+        return (
+            adapter.validate_python(data)
+            if adapter
+            else [cls.model_validate(r) for r in data]
+        )
+
+    async def update(self, **values: Any) -> Self:
+        """Assign the given fields and persist in one call.
+
+        Equivalent to setting each attribute and calling :meth:`save`. Reads
+        more naturally for short updates::
+
+            await user.update(email="new@example.com", name="New Name")
+
+        Each assignment runs through Pydantic's validator (because
+        ``validate_assignment=True`` is set on ``SupabaseModel``), so
+        type errors surface before the round-trip. Raises
+        ``SupabaseORMUsageError`` if no values are passed.
+        """
+        if not values:
+            raise SupabaseORMUsageError(
+                "instance.update() requires at least one key=value."
+            )
+        cls = type(self)
+        for k in values:
+            if k == cls.__pk__:
+                raise SupabaseORMUsageError(
+                    f"Cannot update primary key {cls.__pk__!r} via .update()."
+                )
+            if k in cls.__relations__:
+                raise SupabaseORMUsageError(
+                    f"{k!r} is a relation, not a column on {cls.__table__!r}."
+                )
+        for k, v in values.items():
+            setattr(self, k, v)
+        return await self.save()
+
+    async def save(self) -> Self:
+        """Persist dirty fields and refresh local state in one round-trip.
+
+        For flat models the UPDATE returns the new row directly. For models
+        with relations we still need a follow-up GET to populate embeds.
+        """
+        cls = type(self)
+        dirty = self.__pydantic_fields_set__ - {cls.__pk__} - cls.__relations__.keys()
+        if not dirty:
+            return self
+        payload = {f: serialize(getattr(self, f)) for f in dirty}
+        client = get_client()
+        pk_val = serialize(getattr(self, cls.__pk__))
+        resp = await (
+            client.table(cls.__table__)
+            .update(payload)
+            .eq(cls.__pk__, pk_val)
+            .execute()
+        )
+        if not resp.data:
+            raise SupabaseORMDoesNotExist(
+                f"{cls.__name__}({cls.__pk__}={getattr(self, cls.__pk__)!r}) "
+                "not found during save"
+            )
+        if cls.__relations__:
+            fresh = await cls.get(getattr(self, cls.__pk__))
+        else:
+            fresh = cls.model_validate(resp.data[0])
+        self.__dict__.update(fresh.__dict__)
+        object.__setattr__(self, "__pydantic_fields_set__", set())
+        return self
+
+    async def delete(self) -> None:
+        """Delete this single row by primary key."""
+        cls = type(self)
+        client = get_client()
+        await (
+            client.table(cls.__table__)
+            .delete()
+            .eq(cls.__pk__, serialize(getattr(self, cls.__pk__)))
+            .execute()
+        )
+
+    async def refresh(self) -> Self:
+        cls = type(self)
+        fresh = await cls.get(getattr(self, cls.__pk__))
+        self.__dict__.update(fresh.__dict__)
+        object.__setattr__(self, "__pydantic_fields_set__", set())
+        return self

supabase_orm-0.0.0/src/supabase_orm/_client.py

@@ -0,0 +1,78 @@
+"""AsyncClient lifecycle.
+
+This module is framework-agnostic. It owns a single ``AsyncClient`` reference
+that models read via ``get_client()``. Wiring into a web framework (FastAPI's
+lifespan, Starlette events, a CLI entrypoint, a test fixture, ...) is the
+caller's job.
+
+Typical FastAPI use::
+
+    from contextlib import asynccontextmanager
+    from src.lib import orm
+
+    @asynccontextmanager
+    async def lifespan(app):
+        async with orm.lifespan(SUPABASE_URL, SUPABASE_KEY):
+            yield
+
+    app = FastAPI(lifespan=lifespan)
+
+Tests / scripts::
+
+    orm.set_client(await acreate_client(url, key))
+    ...
+    orm.set_client(None)
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+from supabase import AsyncClient, acreate_client
+
+from ._exceptions import SupabaseORMUsageError
+
+_client: AsyncClient | None = None
+
+
+def get_client() -> AsyncClient:
+    if _client is None:
+        raise SupabaseORMUsageError(
+            "Supabase AsyncClient not initialized. "
+            "Wrap your app startup in `async with orm.lifespan(url, key):` "
+            "or call `orm.set_client(client)` directly."
+        )
+    return _client
+
+
+def set_client(client: AsyncClient | None) -> None:
+    global _client
+    _client = client
+
+
+@asynccontextmanager
+async def lifespan(url: str, key: str) -> AsyncIterator[AsyncClient]:
+    """Async context manager that owns one AsyncClient for its lifetime.
+
+    Yields the client so callers can stash it on app state if they want;
+    most code should just import ``get_client`` from inside request handlers.
+    """
+    client = await acreate_client(url, key)
+    set_client(client)
+    try:
+        yield client
+    finally:
+        set_client(None)
+        # Best-effort teardown of the underlying httpx pools. supabase-py's
+        # AsyncClient doesn't expose a top-level close as of 2.x; we close
+        # each subclient that does so connection pools drain cleanly on
+        # graceful shutdown.
+        for sub in ("postgrest", "auth", "storage", "functions"):
+            obj = getattr(client, sub, None)
+            close = getattr(obj, "aclose", None)
+            if close is not None:
+                try:
+                    await close()
+                except Exception:  # noqa: BLE001 — shutdown is best-effort
+                    pass