fastapi-sqlalchemy-querykit 0.1.0__tar.gz → 0.2.0__tar.gz

{fastapi_sqlalchemy_querykit-0.1.0 → fastapi_sqlalchemy_querykit-0.2.0}/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.2.0] - 2026-06-13
+
+### Added
+- **Offset pagination** (`querybuilder.pagination`): the `Page[T]` / `PageMeta`
+  response envelope, the `PageParams` dependency (plus a `page_params(default=, max_=)`
+  factory), a turnkey `paginate(db, stmt, params)` runner, and `build_page_meta`
+  for bring-your-own-query endpoints.
+- **Query-config introspection** (`querybuilder.config`): `build_query_config(model)`
+  returns a `QueryConfig` / `FieldConfig` description of a `Queryable` model's
+  filterable fields (logical type, valid operators, enum values), derived from the
+  same `describe_path` / `allowed_operators_for` rules `build_query` enforces — so a
+  filter-builder UI can never drift from what the API actually accepts.
+- **Turnkey list runner** (`querybuilder.runner`): `list_and_paginate(...)`
+  (`build_query` → caller `scope` → eager `options` → `paginate`) and the `ScopeFn`
+  type alias for the caller-owned base scope.
+
+### Changed
+- `pydantic>=2` is now an explicit runtime dependency (already required transitively
+  by `fastapi`); the pagination and query-config models use it.
+
 ## [0.1.0] - 2026-06-02
 
 First public release. A deny-by-default query builder for FastAPI + SQLAlchemy 2.0,

{fastapi_sqlalchemy_querykit-0.1.0 → fastapi_sqlalchemy_querykit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-sqlalchemy-querykit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Deny-by-default declarative filtering, sorting, and searching for FastAPI + SQLAlchemy 2.0.
 Project-URL: Homepage, https://github.com/Rooler-ai/fastapi-sqlalchemy-querybuilder
 Project-URL: Repository, https://github.com/Rooler-ai/fastapi-sqlalchemy-querybuilder
@@ -24,6 +24,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: fastapi>=0.115
+Requires-Dist: pydantic>=2
 Requires-Dist: sqlalchemy>=2.0
 Provides-Extra: dev
 Requires-Dist: aiosqlite>=0.20; extra == 'dev'
@@ -105,6 +106,7 @@ stmt = build_query(User, params, allowed_filters={"status", "username"})
 - [Operator reference](docs/operators.md) — wire format, every operator, the per-type matrix
 - [Guide](docs/guide.md) — `Queryable`, relationships, search, sort, errors, limits, startup validation
 - [FastAPI integration](docs/integration.md)
+- [Pagination & query-config](docs/pagination.md) — the `Page` envelope, `list_and_paginate`, `build_query_config`
 
 Build the docs site locally: `pip install -e ".[docs]" && mkdocs serve`.
 

{fastapi_sqlalchemy_querykit-0.1.0 → fastapi_sqlalchemy_querykit-0.2.0}/README.md

@@ -71,6 +71,7 @@ stmt = build_query(User, params, allowed_filters={"status", "username"})
 - [Operator reference](docs/operators.md) — wire format, every operator, the per-type matrix
 - [Guide](docs/guide.md) — `Queryable`, relationships, search, sort, errors, limits, startup validation
 - [FastAPI integration](docs/integration.md)
+- [Pagination & query-config](docs/pagination.md) — the `Page` envelope, `list_and_paginate`, `build_query_config`
 
 Build the docs site locally: `pip install -e ".[docs]" && mkdocs serve`.
 

{fastapi_sqlalchemy_querykit-0.1.0 → fastapi_sqlalchemy_querykit-0.2.0}/docs/index.md

@@ -29,8 +29,8 @@ pip install fastapi-sqlalchemy-querykit
   an integer → 400). Enums match by value and are Postgres-safe.
 - **Caller-owned scope.** The builder is purely additive — it never adds or
   inspects your tenant / soft-delete / visibility `WHERE`.
-- **Tiny surface.** Runtime dependencies: `fastapi` + `sqlalchemy` only. Ships
-  `py.typed`.
+- **Tiny surface.** Runtime dependencies: `fastapi`, `sqlalchemy`, and `pydantic`
+  (which `fastapi` already requires). Ships `py.typed`.
 
 ## 60-second example
 

{fastapi_sqlalchemy_querykit-0.1.0 → fastapi_sqlalchemy_querykit-0.2.0}/docs/integration.md

@@ -39,17 +39,22 @@ GET /users?filters={"status":{"$eq":"active"}}&sort=created_at:desc&search=jdoe
 
 ## Pagination
 
-`build_query` returns a plain `Select`, so it composes with whatever pagination
-you already use — `.limit()/.offset()`, a `COUNT(*)` over the same statement, or a
-library such as `fastapi-pagination`:
+The library ships an offset-pagination envelope and a turnkey runner — see
+[Pagination & query-config](pagination.md):
 
 ```python
-from fastapi_pagination.ext.sqlalchemy import paginate
+from querybuilder import list_and_paginate
 
-stmt = build_query(User, params).where(User.is_deleted.is_(False))
-page = await paginate(db, stmt)
+rows, meta = await list_and_paginate(
+    db, User, params, page_params,
+    scope=lambda stmt: stmt.where(User.is_deleted.is_(False)),
+)
 ```
 
+Because `build_query` returns a plain `Select`, it also composes with whatever
+pagination you already use — `.limit()/.offset()`, a `COUNT(*)` over the same
+statement, or a library such as `fastapi-pagination`.
+
 Relationship filters/search are correlated `EXISTS`, so the count is correct
 (no fan-out duplicates).
 

fastapi_sqlalchemy_querykit-0.2.0/docs/pagination.md

@@ -0,0 +1,142 @@
+# Pagination & query-config
+
+Beyond building the `Select`, the library ships the two things every list endpoint
+also needs: a standard **offset-pagination** envelope, and a **query-config**
+introspection so a frontend filter-builder can render itself.
+
+## The response envelope
+
+Every list endpoint returns the same shape:
+
+```json
+{
+  "items": [ ... ],
+  "meta": { "total": 137, "page": 2, "limit": 25, "total_pages": 6, "has_next": true, "has_prev": true }
+}
+```
+
+`Page[T]` and `PageMeta` are the Pydantic models for it:
+
+```python
+from querybuilder import Page, PageMeta
+
+@router.get("/users", response_model=Page[UserRead])
+async def list_users(...):
+    rows, meta = await ...        # see below
+    return Page[UserRead](items=[UserRead.model_validate(r) for r in rows], meta=meta)
+```
+
+## Request params
+
+`PageParams` is a FastAPI dependency exposing `page` (1-based) and `limit`:
+
+```python
+from fastapi import Depends
+from querybuilder import PageParams
+
+@router.get("/users")
+async def list_users(p: PageParams = Depends(), ...):
+    ...
+```
+
+Defaults are `page=1`, `limit=25`, capped at `100`. For a different default/cap,
+build a variant with the `page_params` factory:
+
+```python
+from querybuilder import page_params
+
+p: PageParams = Depends(page_params(default=50, max_=200))
+```
+
+## Two ways to paginate
+
+### Turnkey — `list_and_paginate`
+
+The common case: build the query, apply your base scope, eager-load, and paginate
+in one call.
+
+```python
+from sqlalchemy.orm import selectinload
+from querybuilder import QueryParams, PageParams, list_and_paginate
+
+# data/query layer
+async def list_users(db, company_id: int, q: QueryParams, p: PageParams):
+    def scope(stmt):                                  # caller-owned base scope
+        return stmt.where(User.company_id == company_id, User.is_deleted.is_(False))
+
+    return await list_and_paginate(
+        db, User, q, p,
+        scope=scope,
+        options=[selectinload(User.posts)],           # to-many → selectinload
+    )
+```
+
+`list_and_paginate` runs `build_query` → your `scope` → eager `options` →
+`paginate`, and returns `(rows, meta)`.
+
+`scope` is a `ScopeFn` — a `Select -> Select` callable that applies your mandatory
+predicates. The builder is purely additive and **never** injects tenant / soft-delete
+/ visibility scope; that is always the caller's `scope`. For directly-scoped models
+it is a `.where(...)`; for indirectly-scoped models it can be a `.join(...).where(...)`
+chain.
+
+!!! warning "The scope must live inside the statement"
+    `paginate` counts with `select(func.count()).select_from(stmt.order_by(None).subquery())`.
+    The outer count statement has **no ORM mapper**, so any scope you rely on *outside*
+    the statement — e.g. a session-level scoping ORM event — will not fire on the count
+    path even if it fires on the fetch. Apply tenant/visibility predicates **inside**
+    `stmt` (which `scope` does) or the `total` is computed unscoped and leaks across
+    tenants.
+
+!!! note "Eager loading"
+    Use `selectinload` for to-many relations — it runs a separate query and is safe
+    under `LIMIT`. A `joinedload` of a collection truncates rows under `LIMIT`.
+
+### Bring-your-own query — `build_page_meta`
+
+When an endpoint keeps its own count/fetch logic (aggregates, raw SQL, a union)
+but should still emit the standard envelope:
+
+```python
+from querybuilder import build_page_meta
+
+total = await db.scalar(my_count_query)
+rows = (await db.execute(my_page_query)).scalars().all()
+meta = build_page_meta(total=total, page=p.page, limit=p.limit)
+return Page[UserRead](items=[...], meta=meta)
+```
+
+You can also call `paginate(db, stmt, p)` directly if you have a `Select` but don't
+need the `scope`/`options` plumbing of `list_and_paginate`.
+
+## Describing the query surface — `build_query_config`
+
+`build_query_config(model)` introspects a `Queryable` model's allowlists into a
+frontend-facing config: for each filterable field, its logical type, the operators
+valid for that type, and (for enums) the allowed values. It is derived from the same
+`describe_path` and `allowed_operators_for` rules `build_query` enforces, so the
+config can never drift from what the API actually accepts.
+
+```python
+from querybuilder import build_query_config, QueryConfig
+
+@router.get("/users/query-config", response_model=QueryConfig)
+async def users_query_config():
+    return build_query_config(User)
+```
+
+```json
+{
+  "filterable": {
+    "status":           { "type": "enum",    "operators": ["$eq","$ne","$in","$nin","$contains", ...], "values": ["active","inactive"] },
+    "age":              { "type": "integer", "operators": ["$eq","$ne","$gt","$gte","$lt","$lte","$in","$nin","$isnull","$isnotnull"], "values": null },
+    "organization.name":{ "type": "string",  "operators": ["$eq","$ne","$in","$nin","$contains", ...], "values": null }
+  },
+  "sortable": ["created_at", "username"],
+  "searchable": ["username", "organization.name"]
+}
+```
+
+Enum `values` are the member **values** (what you filter by), not the stored member
+names — consistent with how enum filtering works (see the
+[operator reference](operators.md)).

{fastapi_sqlalchemy_querykit-0.1.0 → fastapi_sqlalchemy_querykit-0.2.0}/mkdocs.yml

@@ -35,3 +35,4 @@ nav:
   - Operator reference: operators.md
   - Guide: guide.md
   - FastAPI integration: integration.md
+  - Pagination & query-config: pagination.md

{fastapi_sqlalchemy_querykit-0.1.0 → fastapi_sqlalchemy_querykit-0.2.0}/pyproject.toml

@@ -31,6 +31,7 @@ classifiers = [
 dependencies = [
     "fastapi>=0.115",
     "sqlalchemy>=2.0",
+    "pydantic>=2",
 ]
 
 [project.optional-dependencies]

{fastapi_sqlalchemy_querykit-0.1.0 → fastapi_sqlalchemy_querykit-0.2.0}/querybuilder/__init__.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 from .allowlist import validate_queryable, validate_queryables
 from .builder import build_query
+from .config import FieldConfig, QueryConfig, build_query_config
 from .errors import (
     FilterError,
     QueryBuilderError,
@@ -17,7 +18,16 @@ from .errors import (
     SortError,
 )
 from .mixin import Queryable
+from .pagination import (
+    Page,
+    PageMeta,
+    PageParams,
+    build_page_meta,
+    page_params,
+    paginate,
+)
 from .params import QueryParams
+from .runner import ScopeFn, list_and_paginate
 
 __all__ = [
     "build_query",
@@ -30,6 +40,20 @@ __all__ = [
     "SortError",
     "SearchError",
     "QueryConfigurationError",
+    # pagination
+    "Page",
+    "PageMeta",
+    "PageParams",
+    "page_params",
+    "paginate",
+    "build_page_meta",
+    # query-config introspection
+    "QueryConfig",
+    "FieldConfig",
+    "build_query_config",
+    # turnkey runner
+    "list_and_paginate",
+    "ScopeFn",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

fastapi_sqlalchemy_querykit-0.2.0/querybuilder/config.py

@@ -0,0 +1,129 @@
+"""Introspection of a model's ``Queryable`` policy into a frontend-facing config.
+
+Powers per-entity ``GET /<plural>/query-config`` endpoints: for each declared
+filterable field it returns the field type, the operators valid for that type, and
+(for enums) the allowed values — so a filter-builder UI can render itself.
+
+Everything is derived from the library's OWN rules — ``resolver.describe_path`` to
+resolve dotted paths to a leaf column, and ``validation.allowed_operators_for`` for
+the type→operator gate — so the config can never drift from what ``build_query``
+actually accepts.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from sqlalchemy import Uuid as _SAUuid
+
+from .columns import (
+    is_boolean_column,
+    is_datetime_like_column,
+    is_enum_column,
+    is_integer_column,
+    is_numeric_column,
+    is_string_column,
+)
+from .resolver import describe_path
+from .validation import allowed_operators_for
+
+try:  # postgresql-specific UUID type
+    from sqlalchemy.dialects.postgresql import UUID as _PGUuid
+except Exception:  # pragma: no cover - dialect import guard
+    _PGUuid = ()
+
+# Canonical display order for operators (a superset; only the applicable ones are
+# emitted per field). Keeps the UI stable instead of alphabetical noise.
+_OP_ORDER = [
+    "$eq", "$ne",
+    "$gt", "$gte", "$lt", "$lte",
+    "$in", "$nin",
+    "$contains", "$ncontains", "$startswith", "$endswith",
+    "$isnull", "$isnotnull",
+]
+
+
+class FieldConfig(BaseModel):
+    """How one filterable field may be queried."""
+
+    type: str = Field(..., description="Logical field type (string/enum/integer/number/boolean/datetime)")
+    operators: List[str] = Field(..., description="Operators valid for this field's type")
+    values: Optional[List[str]] = Field(None, description="Allowed values for enum fields")
+
+
+class QueryConfig(BaseModel):
+    """The filter/sort/search capabilities a list endpoint exposes for a model."""
+
+    filterable: Dict[str, FieldConfig] = Field(default_factory=dict)
+    sortable: List[str] = Field(default_factory=list)
+    searchable: List[str] = Field(default_factory=list)
+
+
+def _is_uuid_column(column: Any) -> bool:
+    col_type = getattr(column, "type", None)
+    if col_type is None:
+        return False
+    if isinstance(col_type, _SAUuid):  # generic SQLAlchemy 2.0 Uuid
+        return True
+    if _PGUuid and isinstance(col_type, _PGUuid):  # postgresql UUID
+        return True
+    return col_type.__class__.__name__.lower() == "uuid"
+
+
+def _type_label(column: Any) -> str:
+    # Enum first: an enum column is also string-like, but "enum" is the useful label.
+    if is_enum_column(column):
+        return "enum"
+    if is_boolean_column(column):
+        return "boolean"
+    if is_integer_column(column):
+        return "integer"
+    if is_numeric_column(column):
+        return "number"
+    if is_datetime_like_column(column):
+        return "datetime"
+    if _is_uuid_column(column):
+        # Equality/set comparison only (no substring/ordering) — see allowed_operators_for.
+        return "uuid"
+    if is_string_column(column):
+        return "string"
+    return "string"
+
+
+def _enum_values(column: Any) -> Optional[List[str]]:
+    if not is_enum_column(column):
+        return None
+    col_type = getattr(column, "type", None)
+    enum_class = getattr(col_type, "enum_class", None)
+    if enum_class is not None:
+        # Filtering matches by the enum member's VALUE (per docs/operators.md).
+        return [str(m.value) for m in enum_class]
+    # Raw Enum("a", "b") with no Python class.
+    return [str(v) for v in (getattr(col_type, "enums", None) or [])]
+
+
+def _ordered_ops(ops) -> List[str]:
+    present = set(ops)
+    ordered = [o for o in _OP_ORDER if o in present]
+    # Surface any operator not in the canonical list (forward-compat) at the end.
+    ordered.extend(sorted(present - set(ordered)))
+    return ordered
+
+
+def build_query_config(model: Any) -> QueryConfig:
+    """Build the :class:`QueryConfig` for a ``Queryable`` model from its allowlists."""
+    filterable: Dict[str, FieldConfig] = {}
+    for path in sorted(getattr(model, "__filterable__", frozenset())):
+        leaf, _has_to_many = describe_path(model, path.split("."))
+        filterable[path] = FieldConfig(
+            type=_type_label(leaf),
+            operators=_ordered_ops(allowed_operators_for(leaf)),
+            values=_enum_values(leaf),
+        )
+    return QueryConfig(
+        filterable=filterable,
+        sortable=sorted(getattr(model, "__sortable__", frozenset())),
+        searchable=sorted(getattr(model, "__searchable__", frozenset())),
+    )

fastapi_sqlalchemy_querykit-0.2.0/querybuilder/pagination.py

@@ -0,0 +1,135 @@
+"""Offset pagination: request params, response envelope, and a turnkey runner.
+
+Standard list shape::
+
+    { "items": [...], "meta": { total, page, limit, total_pages, has_next, has_prev } }
+
+Two modes: a turnkey :func:`paginate` (and :func:`querybuilder.runner.list_and_paginate`)
+that runs the count + page query for you, or :func:`build_page_meta` for endpoints
+that keep their own query logic but still want the standard envelope.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Generic, List, Sequence, Tuple, TypeVar
+
+from fastapi import Query
+from pydantic import BaseModel, Field
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.sql import Select
+
+T = TypeVar("T")
+
+DEFAULT_LIMIT = 25
+MAX_LIMIT = 100
+
+
+class PageMeta(BaseModel):
+    """Pagination metadata for a single page of results."""
+
+    total: int = Field(..., description="Total rows matching the query (all pages)")
+    page: int = Field(..., description="Current 1-based page number")
+    limit: int = Field(..., description="Page size used for this query")
+    total_pages: int = Field(..., description="Total number of pages")
+    has_next: bool = Field(..., description="Whether a next page exists")
+    has_prev: bool = Field(..., description="Whether a previous page exists")
+
+
+class Page(BaseModel, Generic[T]):
+    """Generic paginated response envelope: ``{items, meta}``."""
+
+    items: List[T] = Field(default_factory=list)
+    meta: PageMeta
+
+
+def build_page_meta(total: int, page: int, limit: int) -> PageMeta:
+    """Compute :class:`PageMeta` from raw counts (Mode 2: bring-your-own query).
+
+    Use when an endpoint keeps its own count/fetch logic but should still emit the
+    standard envelope.
+    """
+    limit = max(1, limit)
+    total_pages = math.ceil(total / limit) if total else 0
+    return PageMeta(
+        total=total,
+        page=page,
+        limit=limit,
+        total_pages=total_pages,
+        has_next=page < total_pages,
+        has_prev=page > 1,
+    )
+
+
+class PageParams:
+    """FastAPI dependency exposing ``page`` + ``limit`` query params (offset paging).
+
+    Use directly — ``p: PageParams = Depends()`` — or build a variant with a custom
+    default/max page size via :func:`page_params`.
+    """
+
+    def __init__(
+        self,
+        page: int = Query(1, ge=1, description="1-based page number"),
+        limit: int = Query(
+            DEFAULT_LIMIT, ge=1, le=MAX_LIMIT, description="Items per page"
+        ),
+    ):
+        self.page = page
+        self.limit = limit
+
+    @property
+    def offset(self) -> int:
+        return (self.page - 1) * self.limit
+
+
+def page_params(default: int = DEFAULT_LIMIT, max_: int = MAX_LIMIT):
+    """Factory for a :class:`PageParams` dependency with a custom default/max size.
+
+    Mirrors Spatie's configurable ``default_size`` / ``max_results``::
+
+        p: PageParams = Depends(page_params(default=50, max_=200))
+    """
+
+    def _dep(
+        page: int = Query(1, ge=1, description="1-based page number"),
+        limit: int = Query(default, ge=1, le=max_, description="Items per page"),
+    ) -> PageParams:
+        return PageParams(page=page, limit=limit)
+
+    return _dep
+
+
+async def paginate(
+    db: AsyncSession, stmt: Select, params: PageParams
+) -> Tuple[Sequence[Any], PageMeta]:
+    """Mode 1 (turnkey): run ``COUNT`` + ``LIMIT/OFFSET`` over ``stmt``.
+
+    Returns ``(rows, meta)``; the endpoint wraps ``rows`` in ``Page[Read]``.
+
+    SCOPE FOOTGUN: the count is built as
+    ``select(count()).select_from(stmt.order_by(None).subquery())``, whose outer
+    statement has no ORM mapper. Any scope you rely on *outside* ``stmt`` — e.g. a
+    session-level scoping ORM event — will NOT fire on this count path even if it
+    fires on the fetch. So tenant / soft-delete / visibility predicates MUST live
+    INSIDE ``stmt`` (via the ``scope`` callable in
+    :func:`querybuilder.runner.list_and_paginate`) to land in the count subquery
+    too — otherwise ``total`` is computed unscoped and leaks across tenants.
+
+    Eager-loading rule: to-many relations must use ``selectinload`` (a separate
+    query, safe under ``LIMIT``); ``joinedload`` of a collection truncates rows under
+    ``LIMIT``. ``.unique()`` defensively dedups joined to-one rows.
+    """
+    count_stmt = select(func.count()).select_from(stmt.order_by(None).subquery())
+    total = int((await db.execute(count_stmt)).scalar_one() or 0)
+    if total == 0:
+        return [], build_page_meta(0, params.page, params.limit)
+
+    rows = (
+        (await db.execute(stmt.limit(params.limit).offset(params.offset)))
+        .unique()
+        .scalars()
+        .all()
+    )
+    return rows, build_page_meta(total, params.page, params.limit)

fastapi_sqlalchemy_querykit-0.2.0/querybuilder/runner.py

@@ -0,0 +1,48 @@
+"""Turnkey list path: ``build_query`` → caller ``scope`` → eager ``options`` → paginate.
+
+A thin convenience over :func:`querybuilder.build_query` and
+:func:`querybuilder.pagination.paginate` for the common list-endpoint shape. The
+caller supplies the mandatory base scope (tenant / soft-delete / visibility) as a
+``Select -> Select`` callable; the builder never adds it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Iterable, Optional, Sequence, Tuple
+
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.sql import Select
+
+from .builder import build_query
+from .pagination import PageMeta, PageParams, paginate
+from .params import QueryParams
+
+# A scope callable receives the built Select and returns it with the caller's
+# mandatory predicates applied (tenant / company, soft-delete, visibility). For
+# directly-scoped models this is a ``.where(...)``; for indirectly-scoped models it
+# is a ``.join(...).where(...)`` chain. It is REQUIRED for correct tenant isolation
+# — the builder never adds it, and it must be applied here (inside ``stmt``) so it
+# also constrains the pagination count. See :func:`querybuilder.pagination.paginate`.
+ScopeFn = Callable[[Select], Select]
+
+
+async def list_and_paginate(
+    db: AsyncSession,
+    model: Any,
+    q: QueryParams,
+    p: PageParams,
+    *,
+    scope: Optional[ScopeFn] = None,
+    options: Optional[Iterable[Any]] = None,
+) -> Tuple[Sequence[Any], PageMeta]:
+    """Turnkey list path: ``build_query`` → caller ``scope`` → eager ``options`` → paginate.
+
+    Returns ``(rows, meta)``. ``options`` should use ``selectinload`` for to-many
+    relations (see :func:`querybuilder.pagination.paginate`).
+    """
+    stmt = build_query(model, q)
+    if scope is not None:
+        stmt = scope(stmt)
+    if options:
+        stmt = stmt.options(*options)
+    return await paginate(db, stmt, p)

fastapi_sqlalchemy_querykit-0.2.0/tests/test_config.py

@@ -0,0 +1,64 @@
+"""build_query_config introspection over a model's Queryable allowlists."""
+
+from querybuilder import build_query_config
+
+from models import User
+
+
+def test_filterable_keys_match_declaration():
+    cfg = build_query_config(User)
+    assert set(cfg.filterable) == set(User.__filterable__)
+
+
+def test_sortable_and_searchable_are_sorted_declared_sets():
+    cfg = build_query_config(User)
+    assert cfg.sortable == sorted(User.__sortable__)
+    assert cfg.searchable == sorted(User.__searchable__)
+
+
+def test_enum_field_reports_values_by_value_not_name():
+    cfg = build_query_config(User)
+    stage = cfg.filterable["stage"]
+    assert stage.type == "enum"
+    # Stage.ACCOUNT_SETUP.value == "accountsetup" (name != value) — surfaced by VALUE.
+    assert stage.values == ["accountsetup", "profilesetup"]
+    assert "$contains" in stage.operators  # enums get substring ops
+    assert "$gt" not in stage.operators     # but not ordering
+
+
+def test_integer_field_gets_ordering_not_substring():
+    cfg = build_query_config(User)
+    age = cfg.filterable["age"]
+    assert age.type == "integer"
+    assert age.values is None
+    assert "$gt" in age.operators
+    assert "$contains" not in age.operators
+
+
+def test_boolean_field_equality_and_null_only():
+    cfg = build_query_config(User)
+    v = cfg.filterable["is_verified"]
+    assert v.type == "boolean"
+    assert set(v.operators) == {"$eq", "$ne", "$isnull", "$isnotnull"}
+
+
+def test_datetime_field_gets_ordering():
+    cfg = build_query_config(User)
+    c = cfg.filterable["created_at"]
+    assert c.type == "datetime"
+    assert "$gte" in c.operators
+    assert "$contains" not in c.operators
+
+
+def test_string_field_and_relationship_path_resolve_to_leaf_type():
+    cfg = build_query_config(User)
+    assert cfg.filterable["username"].type == "string"
+    assert "$contains" in cfg.filterable["username"].operators
+    # A dotted relationship path resolves to its leaf column's type.
+    assert cfg.filterable["organization.name"].type == "string"
+
+
+def test_operators_follow_canonical_order_not_alphabetical():
+    cfg = build_query_config(User)
+    ops = cfg.filterable["username"].operators
+    assert ops.index("$eq") < ops.index("$ne") < ops.index("$contains")

fastapi_sqlalchemy_querykit-0.2.0/tests/test_pagination.py

@@ -0,0 +1,42 @@
+"""Pagination metadata math — ``build_page_meta`` (pure, no DB)."""
+
+from querybuilder import build_page_meta
+
+
+def test_first_page_has_next_not_prev():
+    m = build_page_meta(total=100, page=1, limit=25)
+    assert m.total == 100
+    assert m.total_pages == 4
+    assert m.has_next is True
+    assert m.has_prev is False
+
+
+def test_middle_page_has_both_neighbors():
+    m = build_page_meta(total=100, page=2, limit=25)
+    assert m.has_next is True
+    assert m.has_prev is True
+
+
+def test_last_page_has_prev_not_next():
+    m = build_page_meta(total=100, page=4, limit=25)
+    assert m.has_next is False
+    assert m.has_prev is True
+
+
+def test_partial_last_page_rounds_up():
+    m = build_page_meta(total=101, page=1, limit=25)
+    assert m.total_pages == 5
+
+
+def test_empty_result_has_zero_pages_and_no_neighbors():
+    m = build_page_meta(total=0, page=1, limit=25)
+    assert m.total_pages == 0
+    assert m.has_next is False
+    assert m.has_prev is False
+
+
+def test_limit_is_clamped_to_at_least_one():
+    # limit=0 would divide-by-zero without the max(1, limit) clamp.
+    m = build_page_meta(total=10, page=1, limit=0)
+    assert m.limit == 1
+    assert m.total_pages == 10

fastapi_sqlalchemy_querykit-0.2.0/tests/test_runner.py

@@ -0,0 +1,89 @@
+"""End-to-end pagination over async SQLite (``paginate`` + ``list_and_paginate``).
+
+Uses ``asyncio.run`` rather than pytest-asyncio; ``StaticPool`` keeps ``create_all``
+and the queries on a single in-memory connection (otherwise each checkout is a
+fresh, empty database).
+"""
+
+import asyncio
+
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.pool import StaticPool
+
+from querybuilder import build_query, list_and_paginate, paginate
+from querybuilder.pagination import PageParams
+
+from models import Address, Base, Organization, Region, Status, User, make_params
+
+
+def _run(coro):
+    return asyncio.run(coro)
+
+
+async def _fresh_session() -> AsyncSession:
+    engine = create_async_engine(
+        "sqlite+aiosqlite://",
+        poolclass=StaticPool,
+        connect_args={"check_same_thread": False},
+    )
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    return AsyncSession(engine)
+
+
+async def _seed(session: AsyncSession) -> None:
+    org = Organization(name="acme", region=Region(name="west"))
+    addr = Address(city="A")
+    session.add_all([org, addr])
+    await session.flush()
+    for i in range(5):
+        session.add(
+            User(
+                username=f"u{i}",
+                status=Status.ACTIVE if i % 2 == 0 else Status.INACTIVE,
+                home_address=addr,
+                work_address=addr,
+                organization=org,
+            )
+        )
+    await session.commit()
+
+
+async def _paginate_scenario():
+    session = await _fresh_session()
+    async with session:
+        await _seed(session)
+        stmt = build_query(User, make_params(sort="username:asc"))
+        rows, meta = await paginate(session, stmt, PageParams(page=1, limit=2))
+        return [r.username for r in rows], meta
+
+
+async def _scoped_scenario():
+    session = await _fresh_session()
+    async with session:
+        await _seed(session)
+
+        def scope(stmt):
+            return stmt.where(User.status == Status.ACTIVE)
+
+        rows, meta = await list_and_paginate(
+            session, User, make_params(), PageParams(page=1, limit=10), scope=scope
+        )
+        return meta.total, len(rows)
+
+
+def test_paginate_returns_first_page_and_full_total():
+    usernames, meta = _run(_paginate_scenario())
+    assert usernames == ["u0", "u1"]  # order_by stripped from count, kept on fetch
+    assert meta.total == 5
+    assert meta.total_pages == 3
+    assert meta.has_next is True
+    assert meta.has_prev is False
+
+
+def test_scope_constrains_the_pagination_count():
+    total, returned = _run(_scoped_scenario())
+    # 3 ACTIVE users (i = 0, 2, 4). A correct count means the scope landed inside
+    # stmt and reached the count subquery — not just the fetch.
+    assert total == 3
+    assert returned == 3