fastapi-toolsets 2.4.0__tar.gz → 2.4.1__tar.gz

{fastapi_toolsets-2.4.0 → fastapi_toolsets-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-toolsets
-Version: 2.4.0
+Version: 2.4.1
 Summary: Production-ready utilities for FastAPI applications
 Keywords: fastapi,sqlalchemy,postgresql
 Author: d3vyce

{fastapi_toolsets-2.4.0 → fastapi_toolsets-2.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "2.4.0"
+version = "2.4.1"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"

{fastapi_toolsets-2.4.0 → fastapi_toolsets-2.4.1}/src/fastapi_toolsets/__init__.py

@@ -21,4 +21,4 @@ Example usage:
         return Response(data={"user": user.username}, message="Success")
 """
 
-__version__ = "2.4.0"
+__version__ = "2.4.1"

{fastapi_toolsets-2.4.0 → fastapi_toolsets-2.4.1}/src/fastapi_toolsets/crud/factory.py

@@ -58,18 +58,33 @@ class _CursorDirection(str, Enum):
 def _encode_cursor(
     value: Any, *, direction: _CursorDirection = _CursorDirection.NEXT
 ) -> str:
-    """Encode a cursor column value and navigation direction as a base64 string."""
-    return base64.b64encode(
-        json.dumps({"val": str(value), "dir": direction}).encode()
-    ).decode()
+    """Encode a cursor column value and navigation direction as a URL-safe base64 string."""
+    return (
+        base64.urlsafe_b64encode(
+            json.dumps({"val": str(value), "dir": direction}).encode()
+        )
+        .decode()
+        .rstrip("=")
+    )
 
 
 def _decode_cursor(cursor: str) -> tuple[str, _CursorDirection]:
-    """Decode a cursor base64 string into ``(raw_value, direction)``."""
-    payload = json.loads(base64.b64decode(cursor.encode()).decode())
+    """Decode a URL-safe base64 cursor string into ``(raw_value, direction)``."""
+    padded = cursor + "=" * (-len(cursor) % 4)
+    payload = json.loads(base64.urlsafe_b64decode(padded).decode())
     return payload["val"], _CursorDirection(payload["dir"])
 
 
+def _page_size_query(default: int, max_size: int) -> int:
+    """Return a FastAPI ``Query`` for the ``items_per_page`` parameter."""
+    return Query(
+        default,
+        ge=1,
+        le=max_size,
+        description=f"Number of items per page (max {max_size})",
+    )
+
+
 def _parse_cursor_value(raw_val: str, col_type: Any) -> Any:
     """Parse a raw cursor string value back into the appropriate Python type."""
     if isinstance(col_type, Integer):
@@ -254,6 +269,7 @@ class AsyncCrud(Generic[ModelType]):
         facet_fields: Sequence[FacetFieldType] | None = None,
     ) -> Callable[..., Awaitable[dict[str, list[str]]]]:
         """Return a FastAPI dependency that collects facet filter values from query parameters.
+
         Args:
             facet_fields: Override the facet fields for this dependency. Falls back to the
                 class-level ``facet_fields`` if not provided.
@@ -293,6 +309,121 @@ class AsyncCrud(Generic[ModelType]):
 
         return dependency
 
+    @classmethod
+    def offset_params(
+        cls: type[Self],
+        *,
+        default_page_size: int = 20,
+        max_page_size: int = 100,
+        include_total: bool = True,
+    ) -> Callable[..., Awaitable[dict[str, Any]]]:
+        """Return a FastAPI dependency that collects offset pagination params from query params.
+
+        Args:
+            default_page_size: Default value for the ``items_per_page`` query parameter.
+            max_page_size: Maximum allowed value for ``items_per_page`` (enforced via
+                ``le`` on the ``Query``).
+            include_total: Server-side flag forwarded as-is to ``include_total`` in
+                :meth:`offset_paginate`. Not exposed as a query parameter.
+
+        Returns:
+            An async dependency that resolves to a dict with ``page``,
+            ``items_per_page``, and ``include_total`` keys, ready to be
+            unpacked into :meth:`offset_paginate`.
+        """
+
+        async def dependency(
+            page: int = Query(1, ge=1, description="Page number (1-indexed)"),
+            items_per_page: int = _page_size_query(default_page_size, max_page_size),
+        ) -> dict[str, Any]:
+            return {
+                "page": page,
+                "items_per_page": items_per_page,
+                "include_total": include_total,
+            }
+
+        dependency.__name__ = f"{cls.model.__name__}OffsetParams"
+        return dependency
+
+    @classmethod
+    def cursor_params(
+        cls: type[Self],
+        *,
+        default_page_size: int = 20,
+        max_page_size: int = 100,
+    ) -> Callable[..., Awaitable[dict[str, Any]]]:
+        """Return a FastAPI dependency that collects cursor pagination params from query params.
+
+        Args:
+            default_page_size: Default value for the ``items_per_page`` query parameter.
+            max_page_size: Maximum allowed value for ``items_per_page`` (enforced via
+                ``le`` on the ``Query``).
+
+        Returns:
+            An async dependency that resolves to a dict with ``cursor`` and
+            ``items_per_page`` keys, ready to be unpacked into
+            :meth:`cursor_paginate`.
+        """
+
+        async def dependency(
+            cursor: str | None = Query(
+                None, description="Cursor token from a previous response"
+            ),
+            items_per_page: int = _page_size_query(default_page_size, max_page_size),
+        ) -> dict[str, Any]:
+            return {"cursor": cursor, "items_per_page": items_per_page}
+
+        dependency.__name__ = f"{cls.model.__name__}CursorParams"
+        return dependency
+
+    @classmethod
+    def paginate_params(
+        cls: type[Self],
+        *,
+        default_page_size: int = 20,
+        max_page_size: int = 100,
+        default_pagination_type: PaginationType = PaginationType.OFFSET,
+        include_total: bool = True,
+    ) -> Callable[..., Awaitable[dict[str, Any]]]:
+        """Return a FastAPI dependency that collects all pagination params from query params.
+
+        Args:
+            default_page_size: Default value for the ``items_per_page`` query parameter.
+            max_page_size: Maximum allowed value for ``items_per_page`` (enforced via
+                ``le`` on the ``Query``).
+            default_pagination_type: Default pagination strategy.
+            include_total: Server-side flag forwarded as-is to ``include_total`` in
+                :meth:`paginate`. Not exposed as a query parameter.
+
+        Returns:
+            An async dependency that resolves to a dict with ``pagination_type``,
+            ``page``, ``cursor``, ``items_per_page``, and ``include_total`` keys,
+            ready to be unpacked into :meth:`paginate`.
+        """
+
+        async def dependency(
+            pagination_type: PaginationType = Query(
+                default_pagination_type, description="Pagination strategy"
+            ),
+            page: int = Query(
+                1, ge=1, description="Page number (1-indexed, offset only)"
+            ),
+            cursor: str | None = Query(
+                None, description="Cursor token from a previous response (cursor only)"
+            ),
+            items_per_page: int = _page_size_query(default_page_size, max_page_size),
+        ) -> dict[str, Any]:
+            return {
+                "pagination_type": pagination_type,
+                "page": page,
+                "cursor": cursor,
+                "items_per_page": items_per_page,
+                "include_total": include_total,
+            }
+
+        dependency.__name__ = f"{cls.model.__name__}PaginateParams"
+        return dependency
+
     @classmethod
     def order_params(
         cls: type[Self],
@@ -922,6 +1053,7 @@ class AsyncCrud(Generic[ModelType]):
         order_by: OrderByClause | None = None,
         page: int = 1,
         items_per_page: int = 20,
+        include_total: bool = True,
         search: str | SearchConfig | None = None,
         search_fields: Sequence[SearchFieldType] | None = None,
         facet_fields: Sequence[FacetFieldType] | None = None,
@@ -939,6 +1071,8 @@ class AsyncCrud(Generic[ModelType]):
             order_by: Column or list of columns to order by
             page: Page number (1-indexed)
             items_per_page: Number of items per page
+            include_total: When ``False``, skip the ``COUNT`` query;
+                ``pagination.total_count`` will be ``None``.
             search: Search query string or SearchConfig object
             search_fields: Fields to search in (overrides class default)
             facet_fields: Columns to compute distinct values for (overrides class default)
@@ -983,27 +1117,38 @@ class AsyncCrud(Generic[ModelType]):
         if order_by is not None:
             q = q.order_by(order_by)
 
-        q = q.offset(offset).limit(items_per_page)
-        result = await session.execute(q)
-        raw_items = cast(list[ModelType], result.unique().scalars().all())
-        items: list[Any] = [schema.model_validate(item) for item in raw_items]
+        if include_total:
+            q = q.offset(offset).limit(items_per_page)
+            result = await session.execute(q)
+            raw_items = cast(list[ModelType], result.unique().scalars().all())
 
-        # Count query (with same joins and filters)
-        pk_col = cls.model.__mapper__.primary_key[0]
-        count_q = select(func.count(func.distinct(getattr(cls.model, pk_col.name))))
-        count_q = count_q.select_from(cls.model)
+            # Count query (with same joins and filters)
+            pk_col = cls.model.__mapper__.primary_key[0]
+            count_q = select(func.count(func.distinct(getattr(cls.model, pk_col.name))))
+            count_q = count_q.select_from(cls.model)
 
-        # Apply explicit joins to count query
-        count_q = _apply_joins(count_q, joins, outer_join)
+            # Apply explicit joins to count query
+            count_q = _apply_joins(count_q, joins, outer_join)
 
-        # Apply search joins to count query
-        count_q = _apply_search_joins(count_q, search_joins)
+            # Apply search joins to count query
+            count_q = _apply_search_joins(count_q, search_joins)
 
-        if filters:
-            count_q = count_q.where(and_(*filters))
+            if filters:
+                count_q = count_q.where(and_(*filters))
 
-        count_result = await session.execute(count_q)
-        total_count = count_result.scalar_one()
+            count_result = await session.execute(count_q)
+            total_count: int | None = count_result.scalar_one()
+            has_more = page * items_per_page < total_count
+        else:
+            # Fetch one extra row to detect if a next page exists without COUNT
+            q = q.offset(offset).limit(items_per_page + 1)
+            result = await session.execute(q)
+            raw_items = cast(list[ModelType], result.unique().scalars().all())
+            has_more = len(raw_items) > items_per_page
+            raw_items = raw_items[:items_per_page]
+            total_count = None
+
+        items: list[Any] = [schema.model_validate(item) for item in raw_items]
 
         filter_attributes = await cls._build_filter_attributes(
             session, facet_fields, filters, search_joins
@@ -1015,7 +1160,7 @@ class AsyncCrud(Generic[ModelType]):
                 total_count=total_count,
                 items_per_page=items_per_page,
                 page=page,
-                has_more=page * items_per_page < total_count,
+                has_more=has_more,
             ),
             filter_attributes=filter_attributes,
         )
@@ -1190,6 +1335,7 @@ class AsyncCrud(Generic[ModelType]):
         page: int = ...,
         cursor: str | None = ...,
         items_per_page: int = ...,
+        include_total: bool = ...,
         search: str | SearchConfig | None = ...,
         search_fields: Sequence[SearchFieldType] | None = ...,
         facet_fields: Sequence[FacetFieldType] | None = ...,
@@ -1212,6 +1358,7 @@ class AsyncCrud(Generic[ModelType]):
         page: int = ...,
         cursor: str | None = ...,
         items_per_page: int = ...,
+        include_total: bool = ...,
         search: str | SearchConfig | None = ...,
         search_fields: Sequence[SearchFieldType] | None = ...,
         facet_fields: Sequence[FacetFieldType] | None = ...,
@@ -1233,6 +1380,7 @@ class AsyncCrud(Generic[ModelType]):
         page: int = 1,
         cursor: str | None = None,
         items_per_page: int = 20,
+        include_total: bool = True,
         search: str | SearchConfig | None = None,
         search_fields: Sequence[SearchFieldType] | None = None,
         facet_fields: Sequence[FacetFieldType] | None = None,
@@ -1258,6 +1406,8 @@ class AsyncCrud(Generic[ModelType]):
                 :class:`.CursorPaginatedResponse`.  Only used when
                 ``pagination_type`` is ``CURSOR``.
             items_per_page: Number of items per page (default 20).
+            include_total: When ``False``, skip the ``COUNT`` query;
+                only applies when ``pagination_type`` is ``OFFSET``.
             search: Search query string or :class:`.SearchConfig` object.
             search_fields: Fields to search in (overrides class default).
             facet_fields: Columns to compute distinct values for (overrides
@@ -1304,6 +1454,7 @@ class AsyncCrud(Generic[ModelType]):
                     order_by=order_by,
                     page=page,
                     items_per_page=items_per_page,
+                    include_total=include_total,
                     search=search,
                     search_fields=search_fields,
                     facet_fields=facet_fields,

{fastapi_toolsets-2.4.0 → fastapi_toolsets-2.4.1}/src/fastapi_toolsets/schemas.py

@@ -1,9 +1,10 @@
 """Base Pydantic schemas for API responses."""
 
+import math
 from enum import Enum
 from typing import Annotated, Any, ClassVar, Generic, Literal, TypeVar, Union
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, computed_field
 
 from .types import DataT
 
@@ -98,17 +99,29 @@ class OffsetPagination(PydanticBase):
     """Pagination metadata for offset-based list responses.
 
     Attributes:
-        total_count: Total number of items across all pages
+        total_count: Total number of items across all pages.
+            ``None`` when ``include_total=False``.
         items_per_page: Number of items per page
         page: Current page number (1-indexed)
         has_more: Whether there are more pages
+        pages: Total number of pages
     """
 
-    total_count: int
+    total_count: int | None
     items_per_page: int
     page: int
     has_more: bool
 
+    @computed_field
+    @property
+    def pages(self) -> int | None:
+        """Total number of pages, or ``None`` when ``total_count`` is unknown."""
+        if self.total_count is None:
+            return None
+        if self.items_per_page == 0:
+            return 0
+        return math.ceil(self.total_count / self.items_per_page)
+
 
 class CursorPagination(PydanticBase):
     """Pagination metadata for cursor-based list responses.