supabase-orm 0.0.1.dev1__tar.gz → 0.1.1__tar.gz

supabase_orm-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,97 @@
+name: Publish to PyPI
+
+# Fires when a PEP 440 version tag is pushed (e.g. 0.1.0, 0.1.0a1, 0.1.0.dev0).
+# We tag without a ``v`` prefix so hatch-vcs reads the tag as the version directly.
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+*"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+# Single source of truth for the PyPI distribution name. Used in the
+# environment URL, the release-notes install snippet, and the PyPI link.
+env:
+  PACKAGE_NAME: supabase-orm
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+
+    # Requires a "pypi" environment with trusted-publishing configured.
+    # See https://docs.pypi.org/trusted-publishers/
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ env.PACKAGE_NAME }}
+
+    permissions:
+      id-token: write   # trusted publishing
+      contents: write   # create GitHub release
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0   # hatch-vcs needs full history to resolve the tag
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Run mock tests
+        run: uv run pytest
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          VERSION="${GITHUB_REF_NAME}"
+
+          # PEP 440 pre-release? aN / bN / rcN / .devN
+          PRERELEASE_FLAG=""
+          if [[ "${VERSION}" =~ (a|b|rc|\.dev)[0-9] ]]; then
+            PRERELEASE_FLAG="--prerelease"
+          fi
+
+          # Categorised notes from GitHub's native generator
+          # (driven by .github/release.yml if present).
+          AUTO_NOTES=$(gh api \
+            -X POST \
+            "repos/${GITHUB_REPOSITORY}/releases/generate-notes" \
+            -f tag_name="${VERSION}" \
+            --jq .body)
+
+          {
+            echo "## Install"
+            echo
+            echo '```bash'
+            echo "pip install '${PACKAGE_NAME}==${VERSION}'"
+            echo '```'
+            echo
+            echo "PyPI: https://pypi.org/project/${PACKAGE_NAME}/${VERSION}/"
+            echo
+            echo "${AUTO_NOTES}"
+          } > /tmp/release-notes.md
+
+          gh release create "${VERSION}" \
+            --title "${VERSION}" \
+            --notes-file /tmp/release-notes.md \
+            --verify-tag \
+            ${PRERELEASE_FLAG} \
+            dist/*

{supabase_orm-0.0.1.dev1 → supabase_orm-0.1.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: supabase-orm
-Version: 0.0.1.dev1
+Version: 0.1.1
 Summary: Lightweight async ORM on top of supabase-py with Pydantic validation.
-Project-URL: Homepage, https://github.com/viperadnan/supabase-orm
-Project-URL: Repository, https://github.com/viperadnan/supabase-orm
-Project-URL: Issues, https://github.com/viperadnan/supabase-orm/issues
-Project-URL: Documentation, https://github.com/viperadnan/supabase-orm#readme
+Project-URL: Homepage, https://github.com/viperadnan-git/supabase-orm
+Project-URL: Repository, https://github.com/viperadnan-git/supabase-orm
+Project-URL: Issues, https://github.com/viperadnan-git/supabase-orm/issues
+Project-URL: Documentation, https://github.com/viperadnan-git/supabase-orm#readme
 Author-email: Adnan Ahmad <viperadnan@gmail.com>
 License: Apache-2.0
 License-File: LICENSE
@@ -485,7 +485,7 @@ The integration suite needs a Supabase project with the test schema applied. See
 
 ## Contributing
 
-Issues and PRs welcome at [github.com/viperadnan/supabase-orm](https://github.com/viperadnan/supabase-orm). Run the test suite before sending a PR:
+Issues and PRs welcome at [github.com/viperadnan-git/supabase-orm](https://github.com/viperadnan-git/supabase-orm). Run the test suite before sending a PR:
 
 ```bash
 uv run pytest                       # mock suite (fast, no network)

{supabase_orm-0.0.1.dev1 → supabase_orm-0.1.1}/README.md

@@ -451,7 +451,7 @@ The integration suite needs a Supabase project with the test schema applied. See
 
 ## Contributing
 
-Issues and PRs welcome at [github.com/viperadnan/supabase-orm](https://github.com/viperadnan/supabase-orm). Run the test suite before sending a PR:
+Issues and PRs welcome at [github.com/viperadnan-git/supabase-orm](https://github.com/viperadnan-git/supabase-orm). Run the test suite before sending a PR:
 
 ```bash
 uv run pytest                       # mock suite (fast, no network)

{supabase_orm-0.0.1.dev1 → supabase_orm-0.1.1}/pyproject.toml

@@ -32,10 +32,10 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/viperadnan/supabase-orm"
-Repository = "https://github.com/viperadnan/supabase-orm"
-Issues = "https://github.com/viperadnan/supabase-orm/issues"
-Documentation = "https://github.com/viperadnan/supabase-orm#readme"
+Homepage = "https://github.com/viperadnan-git/supabase-orm"
+Repository = "https://github.com/viperadnan-git/supabase-orm"
+Issues = "https://github.com/viperadnan-git/supabase-orm/issues"
+Documentation = "https://github.com/viperadnan-git/supabase-orm#readme"
 
 [build-system]
 requires = ["hatchling", "hatch-vcs"]

{supabase_orm-0.0.1.dev1 → supabase_orm-0.1.1}/src/supabase_orm/__init__.py

@@ -22,6 +22,7 @@ from ._exceptions import (
     SupabaseORMUsageError,
 )
 from ._filters import register_op
+from ._predicates import Column, Predicate
 from ._query import QueryBuilder
 from ._rpc import rpc, rpc_maybe_one, rpc_one, rpc_scalar
 from ._serializers import register_serializer, serialize
@@ -32,6 +33,8 @@ __all__ = [
     "SupabaseModel",
     "Relation",
     "QueryBuilder",
+    "Column",
+    "Predicate",
     "lifespan",
     "get_client",
     "set_client",

{supabase_orm-0.0.1.dev1 → supabase_orm-0.1.1}/src/supabase_orm/_base.py

@@ -28,6 +28,7 @@ from pydantic import BaseModel, ConfigDict, TypeAdapter
 from ._client import get_client
 from ._embed import Relation, build_select, collect_relations
 from ._exceptions import SupabaseORMDoesNotExist, SupabaseORMUsageError
+from ._predicates import _FieldsAccess
 from ._query import QueryBuilder
 from ._serializers import serialize
 
@@ -77,6 +78,10 @@ class SupabaseModel(BaseModel):
     __list_adapter__: ClassVar[TypeAdapter | None] = None
 
     query: ClassVar[_QueryDescriptor] = _QueryDescriptor()
+    # Typed predicate namespace — ``Pet.f.age >= 5`` returns a Predicate.
+    # The actual ``_FieldsAccess`` instance is attached per subclass in
+    # ``__pydantic_init_subclass__``; declared here for type checkers.
+    f: ClassVar[_FieldsAccess]
 
     def __init_subclass__(
         cls,
@@ -107,6 +112,7 @@ class SupabaseModel(BaseModel):
         )
         cls.__relations__ = collect_relations(cls)
         cls.__list_adapter__ = TypeAdapter(list[cls])
+        cls.f = _FieldsAccess(cls)
         _TABLE_REGISTRY.setdefault(cls.__table__, []).append(cls)
 
     # ─── Builder entry point ───────────────────────────────────────────────

{supabase_orm-0.0.1.dev1 → supabase_orm-0.1.1}/src/supabase_orm/_filters.py

@@ -150,17 +150,36 @@ def _is(b, c, v):
     return b.is_(c, v)
 
 
-@register_op("contains")
+# PostgREST array/range ops have two quirks vs. simple operators:
+#  * URL-tree wire names are short (``cs`` / ``cd`` / ``ov``); the long
+#    Python names map to supabase-py builder methods only.
+#  * Array literals use Postgres ``{a,b}`` braces inside predicate strings
+#    (``in`` uses ``(a,b)`` parens — different shape, same idea).
+# Builder-side serialization is handled by supabase-py; we only need the
+# predicate-string form here.
+def _array_pred_value(val: Any) -> str:
+    val = serialize(val)
+    if isinstance(val, (list, tuple, set)):
+        return "{" + ",".join(_pred_value(v).strip('"') for v in val) + "}"
+    return _pred_value(val)
+
+
+def _array_pred(wire: str) -> PredicateCompiler:
+    """Factory for the three array/range ops — same shape, different wire."""
+    return lambda c, v: f"{c}.{wire}.{_array_pred_value(v)}"
+
+
+@register_op("contains", wire="cs", predicate=_array_pred("cs"))
 def _contains(b, c, v):
     return b.contains(c, serialize(v))
 
 
-@register_op("contained_by")
+@register_op("contained_by", wire="cd", predicate=_array_pred("cd"))
 def _contained_by(b, c, v):
     return b.contained_by(c, serialize(v))
 
 
-@register_op("overlaps")
+@register_op("overlaps", wire="ov", predicate=_array_pred("ov"))
 def _overlaps(b, c, v):
     return b.overlaps(c, serialize(v))
 

supabase_orm-0.1.1/src/supabase_orm/_predicates.py

@@ -0,0 +1,274 @@
+"""Typed predicate builder.
+
+Lets callers express filters as Python expressions instead of lambda
+callbacks::
+
+    await Pet.query.or_(
+        Pet.f.species == "cat",
+        (Pet.f.species == "dog") & (Pet.f.age >= 5),
+    ).all()
+
+Implementation:
+
+* :class:`Column` — exposes every PostgREST operator as a typed method,
+  with ``==`` / ``!=`` / ``<`` / ``<=`` / ``>`` / ``>=`` overloads that
+  return a :class:`Predicate` instead of ``bool``.
+* :class:`Predicate` — composable AST node. ``|`` builds an OR group,
+  ``&`` an AND group, ``~`` a NOT. Each node compiles to a single
+  PostgREST predicate string (``and(...)`` / ``or(...)`` / ``not.<x>``).
+* :class:`_FieldsAccess` — runtime namespace exposed as
+  ``Model.f``. ``Model.f.<column>`` resolves to a typed
+  :class:`Column`. Statically declared with ``__getattr__`` so type
+  checkers accept any field name without losing operator return
+  types.
+
+The ``_PredicateAtom``/``_PredicateAnd``/``_PredicateOr``/
+``_PredicateNot`` subclasses live in this module too. They're private
+to the compile pipeline — callers should only ever see :class:`Predicate`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from ._filters import compile_predicate
+
+if TYPE_CHECKING:
+    from ._base import SupabaseModel
+
+T = TypeVar("T")
+
+
+# ─── Predicate AST ────────────────────────────────────────────────────────
+
+
+class Predicate:
+    """Composable boolean expression that compiles to a PostgREST predicate.
+
+    Build with :class:`Column` operators (``==`` / ``>=`` / ``.in_()`` /
+    ``.like()`` / ...) and combine with ``|`` / ``&`` / ``~``::
+
+        (Pet.f.species == "cat") | (Pet.f.age >= 5)
+        ~(Pet.f.adopted == True)
+
+    Pass to :meth:`QueryBuilder.or_` or :meth:`QueryBuilder.not_`.
+    """
+
+    def _compile(self) -> str:
+        raise NotImplementedError  # pragma: no cover — abstract
+
+    def __or__(self, other: Predicate) -> Predicate:
+        if not isinstance(other, Predicate):
+            return NotImplemented
+        return _PredicateOr(
+            _flatten(self, _PredicateOr) + _flatten(other, _PredicateOr)
+        )
+
+    def __and__(self, other: Predicate) -> Predicate:
+        if not isinstance(other, Predicate):
+            return NotImplemented
+        return _PredicateAnd(
+            _flatten(self, _PredicateAnd) + _flatten(other, _PredicateAnd)
+        )
+
+    def __invert__(self) -> Predicate:
+        return _PredicateNot(self)
+
+    # Predicates aren't hashable and aren't booleans. ``bool(pred)`` would be
+    # a foot-gun (``if Pet.f.age >= 5:`` reads natural but never runs the
+    # query) — fail loudly instead.
+    def __bool__(self) -> bool:
+        raise TypeError(
+            "Predicate is not a bool. Pass it to .or_() / .not_() instead of "
+            "evaluating it directly."
+        )
+
+
+def _flatten(p: Predicate, kind: type[Predicate]) -> list[Predicate]:
+    """Flatten same-kind nesting so ``a | b | c`` compiles to
+    ``or(a,b,c)`` instead of ``or(or(a,b),c)``."""
+    if isinstance(p, kind):
+        # ``parts`` is set by the And/Or subclasses below; safe to read here.
+        return list(p.parts)  # type: ignore[attr-defined]
+    return [p]
+
+
+class _PredicateAtom(Predicate):
+    """Single ``column.op.value`` filter."""
+
+    __slots__ = ("op", "column", "value")
+
+    def __init__(self, op: str, column: str, value: Any) -> None:
+        self.op = op
+        self.column = column
+        self.value = value
+
+    def _compile(self) -> str:
+        return compile_predicate(self.op, self.column, self.value)
+
+
+class _PredicateGroupBase(Predicate):
+    """Shared body for ``and(...)`` / ``or(...)`` AST nodes — same shape,
+    different keyword. Subclasses set :attr:`_kw` to ``"and"`` or ``"or"``."""
+
+    __slots__ = ("parts",)
+    _kw: str = ""
+
+    def __init__(self, parts: list[Predicate]) -> None:
+        self.parts = parts
+
+    def _compile(self) -> str:
+        return f"{self._kw}(" + ",".join(p._compile() for p in self.parts) + ")"
+
+
+class _PredicateAnd(_PredicateGroupBase):
+    _kw = "and"
+
+
+class _PredicateOr(_PredicateGroupBase):
+    _kw = "or"
+
+
+class _PredicateNot(Predicate):
+    __slots__ = ("inner",)
+
+    def __init__(self, inner: Predicate) -> None:
+        self.inner = inner
+
+    def _compile(self) -> str:
+        # PostgREST logic trees accept ``not.and(...)`` / ``not.or(...)`` but
+        # *not* a bare ``not.col.op.val`` atom. Wrap atoms in a single-element
+        # ``and()`` so ``~(Pet.f.species == "cat")`` parses correctly inside
+        # ``or=(...)``.
+        if isinstance(self.inner, _PredicateAtom):
+            return "not.and(" + self.inner._compile() + ")"
+        return "not." + self.inner._compile()
+
+
+# ─── Column ───────────────────────────────────────────────────────────────
+
+
+class Column(Generic[T]):
+    """Typed column reference. Operators build :class:`Predicate` nodes.
+
+    Don't construct directly — access via ``Model.f.<column>``.
+    """
+
+    __slots__ = ("_name", "_model")
+
+    def __init__(self, name: str, model: type[SupabaseModel]) -> None:
+        self._name = name
+        self._model = model
+
+    def __repr__(self) -> str:
+        return f"<Column {self._model.__name__}.{self._name}>"
+
+    def _atom(self, op: str, value: Any) -> Predicate:
+        """Single source of truth for ``Column → Predicate`` construction."""
+        return _PredicateAtom(op, self._name, value)
+
+    # ─── Symbolic operators ────────────────────────────────────────────────
+
+    # ``__eq__`` / ``__ne__`` deliberately return Predicate, not bool — same
+    # trick SQLAlchemy uses. Type checkers want ``bool`` here, so we suppress
+    # the override warning per method.
+
+    def __eq__(self, other: T) -> Predicate:  # type: ignore[override]
+        return self._atom("eq", other)
+
+    def __ne__(self, other: T) -> Predicate:  # type: ignore[override]
+        return self._atom("neq", other)
+
+    def __lt__(self, other: T) -> Predicate:
+        return self._atom("lt", other)
+
+    def __le__(self, other: T) -> Predicate:
+        return self._atom("lte", other)
+
+    def __gt__(self, other: T) -> Predicate:
+        return self._atom("gt", other)
+
+    def __ge__(self, other: T) -> Predicate:
+        return self._atom("gte", other)
+
+    # Disable hashing — predicate-building objects mustn't be dict keys.
+    __hash__ = None  # type: ignore[assignment]
+
+    # ─── Method-form operators (no symbol available) ───────────────────────
+
+    def in_(self, values: Sequence[T]) -> Predicate:
+        return self._atom("in_", values)
+
+    def is_(self, value: bool | None) -> Predicate:
+        return self._atom("is_", value)
+
+    def is_null(self) -> Predicate:
+        """Sugar for ``col.is_(None)`` — checks ``IS NULL``."""
+        return self._atom("is_", None)
+
+    def like(self, pattern: str) -> Predicate:
+        return self._atom("like", pattern)
+
+    def ilike(self, pattern: str) -> Predicate:
+        return self._atom("ilike", pattern)
+
+    def contains(self, value: Any) -> Predicate:
+        return self._atom("contains", value)
+
+    def contained_by(self, value: Any) -> Predicate:
+        return self._atom("contained_by", value)
+
+    def overlaps(self, value: Any) -> Predicate:
+        return self._atom("overlaps", value)
+
+    def fts(self, query: str) -> Predicate:
+        return self._atom("fts", query)
+
+    def plfts(self, query: str) -> Predicate:
+        return self._atom("plfts", query)
+
+    def phfts(self, query: str) -> Predicate:
+        return self._atom("phfts", query)
+
+    def wfts(self, query: str) -> Predicate:
+        return self._atom("wfts", query)
+
+
+# ─── f namespace ──────────────────────────────────────────────────────────
+
+
+class _FieldsAccess:
+    """Runtime namespace exposing typed :class:`Column`\\s for a model.
+
+    Created once per :class:`SupabaseModel` subclass and attached as
+    ``Model.f``. Statically typed with ``__getattr__`` so callers can
+    use any column name without triggering "unknown attribute" errors
+    from type checkers — the operators on the returned ``Column[Any]``
+    are still fully typed, so ``Pet.f.age >= 5`` resolves to
+    :class:`Predicate`, never ``bool``.
+    """
+
+    __slots__ = ("_model", "_columns")
+
+    def __init__(self, model: type[SupabaseModel]) -> None:
+        self._model = model
+        self._columns: dict[str, Column[Any]] = {
+            name: Column(name, model) for name in model.model_fields
+        }
+
+    def __getattr__(self, name: str) -> Column[Any]:
+        try:
+            return self._columns[name]
+        except KeyError:
+            raise AttributeError(
+                f"{self._model.__name__} has no column {name!r}. "
+                f"Known: {sorted(self._columns)}"
+            ) from None
+
+    def __repr__(self) -> str:
+        return f"<{self._model.__name__}.f: {sorted(self._columns)}>"
+
+    # Help IDEs that walk ``dir()`` for autocomplete.
+    def __dir__(self) -> list[str]:
+        return list(self._columns)

{supabase_orm-0.0.1.dev1 → supabase_orm-0.1.1}/src/supabase_orm/_query.py

@@ -12,7 +12,7 @@ Don't reuse a builder after a terminal call; create a fresh one off ``Model.quer
 from __future__ import annotations
 
 from collections.abc import Sequence
-from typing import TYPE_CHECKING, Any, Callable, Generic, Self, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Callable, Generic, Self, TypeVar, cast, overload
 
 from ._client import get_client
 from ._exceptions import (
@@ -21,6 +21,7 @@ from ._exceptions import (
     SupabaseORMUsageError,
 )
 from ._filters import apply_op, compile_predicate
+from ._predicates import Predicate
 from ._serializers import serialize
 
 if TYPE_CHECKING:
@@ -105,19 +106,58 @@ class _Filterable:
 
     # ─── Compound predicates ───────────────────────────────────────────────
 
+    # Two ways to compose OR/NOT branches:
+    #
+    #   1. Predicate objects (preferred, since 0.2.0) ─ typed & composable::
+    #
+    #          Pet.query.or_(
+    #              Pet.f.species == "cat",
+    #              (Pet.f.species == "dog") & (Pet.f.age >= 5),
+    #          )
+    #
+    #   2. Lambda callbacks (legacy, kept for backward compat with 0.1.x)::
+    #
+    #          Pet.query.or_(lambda q: q.eq("species", "cat"))
+    #
+    # The two forms can't be mixed in a single call — we raise ``UsageError``
+    # rather than silently picking one. ``@overload`` gives type checkers
+    # the precise signature for each form.
+
+    @overload
+    def or_(self, *predicates: Predicate) -> Self: ...
+    @overload
     def or_(
-        self,
-        *branches: Callable[["_PredicateGroup"], "_PredicateGroup"],
-    ) -> Self:
-        compiled = _compile_branches(self._model, branches)
-        return self._apply_predicate_group(f"or({compiled})")
+        self, *branches: Callable[["_PredicateGroup"], "_PredicateGroup"]
+    ) -> Self: ...
+    def or_(self, *args: Any) -> Self:
+        if not args:
+            raise SupabaseORMUsageError("or_() requires at least one branch.")
+        is_pred = [isinstance(a, Predicate) for a in args]
+        if all(is_pred):
+            compiled = ",".join(cast(Predicate, a)._compile() for a in args)
+            return self._apply_predicate_group(f"or({compiled})")
+        if not any(is_pred):
+            compiled = _compile_branches(self._model, args)
+            return self._apply_predicate_group(f"or({compiled})")
+        raise SupabaseORMUsageError(
+            "or_() can't mix Predicate args with lambda branches in a single call."
+        )
 
+    @overload
+    def not_(self, predicate: Predicate) -> Self: ...
+    @overload
     def not_(
-        self,
-        branch: Callable[["_PredicateGroup"], "_PredicateGroup"],
-    ) -> Self:
+        self, branch: Callable[["_PredicateGroup"], "_PredicateGroup"]
+    ) -> Self: ...
+    def not_(self, arg: Any) -> Self:
+        if isinstance(arg, Predicate):
+            # Route through ``~`` (i.e. _PredicateNot._compile) so atoms get
+            # wrapped in ``not.and(...)`` — bare ``not.col.op.val`` doesn't
+            # parse inside PostgREST's logic tree.
+            return self._apply_predicate_group((~arg)._compile())
+        # Legacy lambda form.
         sub = _PredicateGroup(self._model)
-        branch(sub)
+        arg(sub)
         return self._apply_predicate_group(f"not.and({sub._compile()})")
 
 

{supabase_orm-0.0.1.dev1 → supabase_orm-0.1.1}/src/supabase_orm/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.1.dev1'
-__version_tuple__ = version_tuple = (0, 0, 1, 'dev1')
+__version__ = version = '0.1.1'
+__version_tuple__ = version_tuple = (0, 1, 1)
 
 __commit_id__ = commit_id = None

supabase_orm-0.1.1/tests/integration/test_predicates.py

@@ -0,0 +1,163 @@
+"""Predicate API round-trips against real PostgREST.
+
+The mock suite proves we emit the right predicate strings. These tests
+prove PostgREST parses and applies them correctly — including the
+``not.or(...)``, nested ``and(or(...))``, and atom-form negation cases
+that string-concatenation makes easy to get subtly wrong.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from .conftest import Owner, Pet
+
+
+async def _seed_pets(n: int = 3) -> list[Pet]:
+    owner = await Owner.create(email=f"o-{uuid4()}@x.test")
+    pets = []
+    for i in range(n):
+        pets.append(
+            await Pet.create(
+                owner_id=owner.id,
+                name=f"pet-{i}",
+                species="cat" if i % 2 == 0 else "dog",
+                adopted=i == 0,
+                tags=["a", "b"] if i == 0 else ["b"],
+                amount=float(i),
+            )
+        )
+    return pets
+
+
+# ─── Atomic predicates ────────────────────────────────────────────────────
+
+
+async def test_eq_predicate_via_or_single_branch(clean):
+    pets = await _seed_pets()
+    rows = await Pet.query.or_(Pet.f.species == "cat").all()
+    assert {p.id for p in rows} == {p.id for p in pets if p.species == "cat"}
+
+
+async def test_comparison_operators_round_trip(clean):
+    pets = await _seed_pets()
+    rows = await Pet.query.or_(Pet.f.amount >= 1).all()
+    assert {p.id for p in rows} == {p.id for p in pets if p.amount >= 1}
+
+    rows = await Pet.query.or_(Pet.f.amount < 2).all()
+    assert {p.id for p in rows} == {p.id for p in pets if p.amount < 2}
+
+
+async def test_in_predicate(clean):
+    pets = await _seed_pets()
+    ids = [pets[0].id, pets[2].id]
+    rows = await Pet.query.or_(Pet.f.id.in_(ids)).all()
+    assert {p.id for p in rows} == set(ids)
+
+
+async def test_like_predicate(clean):
+    await _seed_pets()
+    rows = await Pet.query.or_(Pet.f.name.like("pet-%")).all()
+    assert len(rows) == 3
+
+
+async def test_is_null_predicate(clean):
+    pets = await _seed_pets()
+    await pets[0].update(owner_id=None)
+    rows = await Pet.query.or_(Pet.f.owner_id.is_null()).all()
+    assert [p.id for p in rows] == [pets[0].id]
+
+
+async def test_contains_predicate(clean):
+    pets = await _seed_pets()
+    # Only pets[0] has tag "a".
+    rows = await Pet.query.or_(Pet.f.tags.contains(["a"])).all()
+    assert {p.id for p in rows} == {pets[0].id}
+
+
+# ─── Composition: |, &, ~ ────────────────────────────────────────────────
+
+
+async def test_or_composition_two_branches(clean):
+    pets = await _seed_pets()
+    rows = await Pet.query.or_(
+        Pet.f.name == pets[0].name,
+        Pet.f.name == pets[2].name,
+    ).all()
+    assert {p.id for p in rows} == {pets[0].id, pets[2].id}
+
+
+async def test_and_inside_or_branch(clean):
+    pets = await _seed_pets()
+    rows = await Pet.query.or_(
+        Pet.f.name == pets[1].name,
+        (Pet.f.species == "cat") & (Pet.f.amount >= 2),
+    ).all()
+    expected = {pets[1].id} | {
+        p.id for p in pets if p.species == "cat" and p.amount >= 2
+    }
+    assert {p.id for p in rows} == expected
+
+
+async def test_pipe_composition_flattens(clean):
+    """``a | b | c`` should match rows matching any of the three."""
+    pets = await _seed_pets()
+    p = (
+        (Pet.f.name == pets[0].name)
+        | (Pet.f.name == pets[1].name)
+        | (Pet.f.name == pets[2].name)
+    )
+    rows = await Pet.query.or_(p).all()
+    assert {p.id for p in rows} == {p.id for p in pets}
+
+
+async def test_not_of_atom(clean):
+    pets = await _seed_pets()
+    rows = await Pet.query.not_(Pet.f.species == "cat").all()
+    assert {p.id for p in rows} == {p.id for p in pets if p.species != "cat"}
+
+
+async def test_not_of_or_group(clean):
+    """``not.or(name=X, name=Y)`` must parse as "neither X nor Y"."""
+    pets = await _seed_pets()
+    rows = await Pet.query.not_(
+        (Pet.f.name == pets[0].name) | (Pet.f.name == pets[1].name)
+    ).all()
+    assert {p.id for p in rows} == {pets[2].id}
+
+
+async def test_not_of_and_group(clean):
+    pets = await _seed_pets()
+    rows = await Pet.query.not_((Pet.f.species == "cat") & (Pet.f.amount == 0)).all()
+    # Exclude pets[0] (cat, amount=0) only; pets[2] is cat amount=2,
+    # pets[1] is dog amount=1 → both retained.
+    assert {p.id for p in rows} == {pets[1].id, pets[2].id}
+
+
+# ─── Chain integration ───────────────────────────────────────────────────
+
+
+async def test_chain_eq_plus_predicate_or(clean):
+    """Chain handles AND; predicate args handle OR. They mix freely."""
+    pets = await _seed_pets()
+    rows = await (
+        Pet.query.eq("adopted", False)
+        .or_(Pet.f.name == pets[1].name, Pet.f.name == pets[2].name)
+        .all()
+    )
+    # pets[1] and pets[2] are both adopted=False (only pets[0] is adopted).
+    assert {p.id for p in rows} == {pets[1].id, pets[2].id}
+
+
+# ─── Backward compat — lambda form still works against the server ────────
+
+
+async def test_legacy_lambda_or_still_works(clean):
+    """The old ``or_(lambda q: q.eq(...))`` form must keep working
+    end-to-end so 0.1.x callers aren't broken by 0.2.0."""
+    pets = await _seed_pets()
+    rows = await Pet.query.or_(
+        lambda q: q.eq("name", pets[0].name),
+        lambda q: q.eq("name", pets[2].name),
+    ).all()
+    assert {p.id for p in rows} == {pets[0].id, pets[2].id}

supabase_orm-0.1.1/tests/test_predicates.py

@@ -0,0 +1,284 @@
+"""Typed predicate builder — Column[T], Predicate, Model.f."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from uuid import UUID, uuid4
+
+import pytest
+
+from supabase_orm import Column, Predicate, SupabaseModel
+from supabase_orm._predicates import (
+    _FieldsAccess,
+    _PredicateAnd,
+    _PredicateAtom,
+    _PredicateNot,
+    _PredicateOr,
+)
+
+from .conftest import FakeResponse
+
+
+class Row(SupabaseModel, table="rows_pred"):
+    id: UUID
+    name: str
+    age: int
+    is_active: bool = True
+    tags: list[str] = []
+    created_at: datetime | None = None
+
+
+# ─── Model.f namespace ────────────────────────────────────────────────────
+
+
+def test_f_namespace_is_attached_per_subclass():
+    assert isinstance(Row.f, _FieldsAccess)
+    # Two different models get their own namespaces.
+    assert Row.f is not SupabaseModel.__dict__.get("f")
+
+
+def test_f_returns_typed_column_per_field():
+    col = Row.f.age
+    assert isinstance(col, Column)
+    assert col._name == "age"
+    assert col._model is Row
+
+
+def test_f_returns_same_column_object_each_access():
+    # Cached at construction time — useful so identity comparisons work
+    # and we don't allocate per access in tight loops.
+    assert Row.f.age is Row.f.age
+
+
+def test_f_unknown_field_raises_attributeerror():
+    with pytest.raises(AttributeError, match="no column 'nope'"):
+        _ = Row.f.nope  # type: ignore[attr-defined]
+
+
+def test_f_dir_lists_columns_for_ide_autocomplete():
+    assert set(dir(Row.f)) == set(Row.model_fields)
+
+
+# ─── Atomic predicates ────────────────────────────────────────────────────
+
+
+def test_eq_builds_predicate_not_bool():
+    p = Row.f.name == "alice"
+    assert isinstance(p, Predicate)
+    assert isinstance(p, _PredicateAtom)
+    assert p._compile() == "name.eq.alice"
+
+
+def test_ne_builds_neq_predicate():
+    p = Row.f.name != "alice"
+    assert isinstance(p, Predicate)
+    assert p._compile() == "name.neq.alice"
+
+
+def test_comparison_operators():
+    assert (Row.f.age < 18)._compile() == "age.lt.18"
+    assert (Row.f.age <= 18)._compile() == "age.lte.18"
+    assert (Row.f.age > 18)._compile() == "age.gt.18"
+    assert (Row.f.age >= 18)._compile() == "age.gte.18"
+
+
+def test_method_form_operators():
+    assert Row.f.age.in_([1, 2, 3])._compile() == "age.in.(1,2,3)"
+    assert Row.f.name.like("a%")._compile() == "name.like.a%"
+    assert Row.f.name.ilike("A%")._compile() == "name.ilike.A%"
+    # PostgREST's URL-tree wire names are short (cs/cd/ov) and array
+    # literals use ``{}`` curly braces, not the ``()`` parens that ``in`` uses.
+    assert Row.f.tags.contains(["x"])._compile() == "tags.cs.{x}"
+    assert Row.f.tags.contained_by(["x"])._compile() == "tags.cd.{x}"
+    assert Row.f.tags.overlaps(["x"])._compile() == "tags.ov.{x}"
+
+
+def test_is_null_sugar():
+    assert Row.f.created_at.is_null()._compile() == "created_at.is.null"
+    assert Row.f.created_at.is_(None)._compile() == "created_at.is.null"
+    assert Row.f.is_active.is_(True)._compile() == "is_active.is.true"
+
+
+def test_text_search_operators():
+    assert Row.f.name.fts("cat")._compile() == "name.fts.cat"
+    assert Row.f.name.plfts("cat")._compile() == "name.plfts.cat"
+    assert Row.f.name.phfts("cat")._compile() == "name.phfts.cat"
+    assert Row.f.name.wfts("cat")._compile() == "name.wfts.cat"
+
+
+def test_predicate_serializes_values_via_filter_layer():
+    u = uuid4()
+    p = Row.f.id == u
+    assert p._compile() == f"id.eq.{u}"
+
+    dt = datetime(2024, 1, 2, 3, 4, 5, tzinfo=timezone.utc)
+    assert (Row.f.created_at == dt)._compile() == f"created_at.eq.{dt.isoformat()}"
+
+
+# ─── Composition: |, &, ~ ────────────────────────────────────────────────
+
+
+def test_or_composition():
+    p = (Row.f.name == "a") | (Row.f.name == "b")
+    assert isinstance(p, _PredicateOr)
+    assert p._compile() == "or(name.eq.a,name.eq.b)"
+
+
+def test_and_composition():
+    p = (Row.f.name == "a") & (Row.f.age > 5)
+    assert isinstance(p, _PredicateAnd)
+    assert p._compile() == "and(name.eq.a,age.gt.5)"
+
+
+def test_not_composition():
+    p = ~(Row.f.is_active == True)  # noqa: E712 (the orm cares about == not is)
+    assert isinstance(p, _PredicateNot)
+    # Atom-not wraps in single-element and() so it parses inside or=(...).
+    assert p._compile() == "not.and(is_active.eq.true)"
+
+
+def test_or_flattens_same_kind():
+    """``a | b | c`` should be ``or(a,b,c)`` not ``or(or(a,b),c)``."""
+    p = (Row.f.name == "a") | (Row.f.name == "b") | (Row.f.name == "c")
+    assert p._compile() == "or(name.eq.a,name.eq.b,name.eq.c)"
+
+
+def test_and_flattens_same_kind():
+    p = (Row.f.age > 1) & (Row.f.age < 10) & (Row.f.is_active == True)  # noqa: E712
+    assert p._compile() == "and(age.gt.1,age.lt.10,is_active.eq.true)"
+
+
+def test_mixed_and_or_keeps_nesting():
+    p = (Row.f.name == "a") | ((Row.f.age >= 5) & (Row.f.is_active == True))  # noqa: E712
+    assert p._compile() == "or(name.eq.a,and(age.gte.5,is_active.eq.true))"
+
+
+def test_not_of_compound_negates_whole_group():
+    p = ~((Row.f.name == "a") | (Row.f.name == "b"))
+    assert p._compile() == "not.or(name.eq.a,name.eq.b)"
+
+
+# ─── Foot-gun guards ──────────────────────────────────────────────────────
+
+
+def test_predicate_is_not_bool():
+    """Catches ``if Pet.f.age >= 5:`` mistakes at runtime."""
+    p = Row.f.age >= 5
+    with pytest.raises(TypeError, match="not a bool"):
+        bool(p)
+
+
+def test_or_with_non_predicate_returns_notimplemented():
+    p = Row.f.age >= 5
+    # ``__or__`` returning NotImplemented lets Python fall back to the
+    # other operand's ``__ror__`` (or raise TypeError if none exists).
+    assert p.__or__("x") is NotImplemented  # type: ignore[arg-type]
+    assert p.__and__("x") is NotImplemented  # type: ignore[arg-type]
+
+
+# ─── Integration with QueryBuilder.or_ / not_ ────────────────────────────
+
+
+async def test_or_accepts_predicate_args(fake_client):
+    fake_client.queue(FakeResponse(data=[]))
+    await Row.query.or_(
+        Row.f.name == "a",
+        Row.f.name == "b",
+    ).all()
+    or_call = next(c for c in fake_client.builders[0].calls if c[0] == "or_")
+    assert or_call[1] == ("name.eq.a,name.eq.b",)
+
+
+async def test_or_predicate_with_and_branch(fake_client):
+    fake_client.queue(FakeResponse(data=[]))
+    await Row.query.or_(
+        Row.f.name == "a",
+        (Row.f.name == "b") & (Row.f.age >= 5),
+    ).all()
+    or_call = next(c for c in fake_client.builders[0].calls if c[0] == "or_")
+    assert or_call[1] == ("name.eq.a,and(name.eq.b,age.gte.5)",)
+
+
+async def test_or_predicate_with_nested_or(fake_client):
+    fake_client.queue(FakeResponse(data=[]))
+    await Row.query.or_(
+        (Row.f.name == "a") | (Row.f.name == "b"),
+        Row.f.age >= 5,
+    ).all()
+    or_call = next(c for c in fake_client.builders[0].calls if c[0] == "or_")
+    # Inner ``or(...)`` stays a nested group — PostgREST accepts that.
+    assert or_call[1] == ("or(name.eq.a,name.eq.b),age.gte.5",)
+
+
+async def test_not_accepts_predicate(fake_client):
+    fake_client.queue(FakeResponse(data=[]))
+    await Row.query.not_(Row.f.is_active == True).all()  # noqa: E712
+    or_call = next(c for c in fake_client.builders[0].calls if c[0] == "or_")
+    assert or_call[1] == ("not.and(is_active.eq.true)",)
+
+
+async def test_not_of_or_group(fake_client):
+    fake_client.queue(FakeResponse(data=[]))
+    await Row.query.not_((Row.f.name == "a") | (Row.f.name == "b")).all()
+    or_call = next(c for c in fake_client.builders[0].calls if c[0] == "or_")
+    assert or_call[1] == ("not.or(name.eq.a,name.eq.b)",)
+
+
+async def test_or_requires_at_least_one_branch(fake_client):
+    from supabase_orm import SupabaseORMUsageError
+
+    with pytest.raises(SupabaseORMUsageError, match="at least one branch"):
+        Row.query.or_()
+
+
+async def test_or_rejects_mixed_predicate_and_lambda(fake_client):
+    from supabase_orm import SupabaseORMUsageError
+
+    with pytest.raises(SupabaseORMUsageError, match="can't mix"):
+        Row.query.or_(
+            Row.f.name == "a",
+            lambda q: q.eq("name", "b"),  # type: ignore[arg-type]
+        )
+
+
+# ─── Backward compat — lambda API still works ────────────────────────────
+
+
+async def test_or_legacy_lambda_path_still_works(fake_client):
+    fake_client.queue(FakeResponse(data=[]))
+    await Row.query.or_(
+        lambda q: q.eq("name", "a"),
+        lambda q: q.eq("name", "b"),
+    ).all()
+    or_call = next(c for c in fake_client.builders[0].calls if c[0] == "or_")
+    assert or_call[1] == ("name.eq.a,name.eq.b",)
+
+
+async def test_not_legacy_lambda_path_still_works(fake_client):
+    fake_client.queue(FakeResponse(data=[]))
+    await Row.query.not_(lambda q: q.eq("name", "a")).all()
+    or_call = next(c for c in fake_client.builders[0].calls if c[0] == "or_")
+    assert or_call[1] == ("not.and(name.eq.a)",)
+
+
+# ─── Chain integration ───────────────────────────────────────────────────
+
+
+async def test_predicate_or_composes_with_chain_filters(fake_client):
+    """Chain handles AND, predicate-or_ handles OR — they mix freely."""
+    fake_client.queue(FakeResponse(data=[]))
+    await (
+        Row.query.eq("is_active", True)
+        .or_(Row.f.name == "a", Row.f.name == "b")
+        .order_by("-age")
+        .limit(10)
+        .all()
+    )
+    b = fake_client.builders[0]
+    calls = [c for c in b.calls if c[0] != "select"]
+    assert calls == [
+        ("eq", ("is_active", True), {}),
+        ("or_", ("name.eq.a,name.eq.b",), {}),
+        ("order", ("age",), {"desc": True}),
+        ("limit", (10,), {}),
+    ]

{supabase_orm-0.0.1.dev1 → supabase_orm-0.1.1}/tests/test_wire.py

@@ -222,9 +222,9 @@ async def test_neq_lt_gte_serialize_values(fake_client):
         ("ilike", "name", "A%", "name.ilike.A%"),
         ("is_", "name", None, "name.is.null"),
         ("is_", "is_active", True, "is_active.is.true"),
-        ("contains", "tags", ["x"], "tags.contains.(x)"),
-        ("contained_by", "tags", ["x"], "tags.contained_by.(x)"),
-        ("overlaps", "tags", ["x"], "tags.overlaps.(x)"),
+        ("contains", "tags", ["x"], "tags.cs.{x}"),
+        ("contained_by", "tags", ["x"], "tags.cd.{x}"),
+        ("overlaps", "tags", ["x"], "tags.ov.{x}"),
         ("fts", "name", "cat", "name.fts.cat"),
         ("plfts", "name", "cat", "name.plfts.cat"),
         ("phfts", "name", "cat", "name.phfts.cat"),