fastapi-sqlalchemy-querykit 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

{fastapi_sqlalchemy_querykit-0.1.0.dist-info → fastapi_sqlalchemy_querykit-0.2.0.dist-info}/METADATA

@@ -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.dist-info → fastapi_sqlalchemy_querykit-0.2.0.dist-info}/RECORD

@@ -1,17 +1,20 @@
-querybuilder/__init__.py,sha256=NIxtKiOIeas6dpnjurihR0lCL2n5xV0J7uLdVqzWq7w,825
+querybuilder/__init__.py,sha256=1kJ8B1g7GGOr3lb7xuFQYoPP_hP3l6LFZfam6RIP-Go,1336
 querybuilder/allowlist.py,sha256=OeJRFt2u8oJg6gUO0mz_4mFEVRNunyWlhZzyW1cl-rY,3514
 querybuilder/builder.py,sha256=BCSyRsiI-t44BD9sSx7Simp0qcvBleUjq1995rKF4Q4,11538
 querybuilder/columns.py,sha256=IybmfUho1d-a5CQ7A530a6WyDZ5sjeGwBih6W14tuAc,1986
+querybuilder/config.py,sha256=S7hfraek8D_xsPqOcSGMduc-ZzTroOZfl_Y5WO1w00s,4675
 querybuilder/dates.py,sha256=CtG1mxAC6NNofe2FVj40Fx3kB1IfbEXSE1BnsRymi08,1994
 querybuilder/errors.py,sha256=o7SfFhEZMZAktr1nSuHkhNajKBcHBjirHpV5y5Sd3pY,1504
 querybuilder/mixin.py,sha256=nvVkAVKubt8pDDbE5xcmIFm64FxL04A1y-IY0Ik4kCA,1185
 querybuilder/operators.py,sha256=0NN9oxZjUvJX02NasTKmSocFC8WoULNnXvmtxw5hwPA,9957
+querybuilder/pagination.py,sha256=pZf0_bgGYOw5ZT4jIc8LD8rwCPP7K-E2ogJp1ATTqIg,4757
 querybuilder/params.py,sha256=lyFvyFSEA0QU2R8w4mqVITN0Eeda6YYap1aDPm3f3aY,1362
 querybuilder/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 querybuilder/resolver.py,sha256=5RjArTbfrn5bheXmnfHX8GUUqRY08VVsb6-hQdhk_bQ,4009
+querybuilder/runner.py,sha256=4cMxQEmpWrsvgDYC0Ky71pl-hlU8CpAIATLX-00TScs,1893
 querybuilder/validation.py,sha256=kHudpTbCJvsBVHkQV3J2zJVM10_tubNUPgvVETpnXJU,2178
-fastapi_sqlalchemy_querykit-0.1.0.dist-info/METADATA,sha256=HKxZpLeeQXCZVzRkYLSZhhAK11Y_I4oc5_jnH0hDvYc,4870
-fastapi_sqlalchemy_querykit-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-fastapi_sqlalchemy_querykit-0.1.0.dist-info/licenses/LICENSE,sha256=cqZedEuNrvR7QYfocPvfNbKnnfYb14dvpFES61HGq7I,1166
-fastapi_sqlalchemy_querykit-0.1.0.dist-info/licenses/NOTICE,sha256=Wi8KVt1WphKO-KtYXuWEfxrsYRPAimbgAvI7_E9LP_E,394
-fastapi_sqlalchemy_querykit-0.1.0.dist-info/RECORD,,
+fastapi_sqlalchemy_querykit-0.2.0.dist-info/METADATA,sha256=MCg5r3PuYRaAaRuUAd04vUAfdXCi0wvaWY9cAsWihFg,5014
+fastapi_sqlalchemy_querykit-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+fastapi_sqlalchemy_querykit-0.2.0.dist-info/licenses/LICENSE,sha256=cqZedEuNrvR7QYfocPvfNbKnnfYb14dvpFES61HGq7I,1166
+fastapi_sqlalchemy_querykit-0.2.0.dist-info/licenses/NOTICE,sha256=Wi8KVt1WphKO-KtYXuWEfxrsYRPAimbgAvI7_E9LP_E,394
+fastapi_sqlalchemy_querykit-0.2.0.dist-info/RECORD,,

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"

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())),
+    )

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)

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)