fastapi-toolsets 5.0.0b2__tar.gz → 5.1.0__tar.gz

{fastapi_toolsets-5.0.0b2 → fastapi_toolsets-5.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-toolsets
-Version: 5.0.0b2
+Version: 5.1.0
 Summary: Production-ready utilities for FastAPI applications
 Keywords: fastapi,sqlalchemy,postgresql
 Author: d3vyce
@@ -29,14 +29,12 @@ Requires-Dist: asyncpg>=0.29.0
 Requires-Dist: fastapi>=0.100.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: sqlalchemy[asyncio]>=2.0
-Requires-Dist: fastapi-toolsets[cli,metrics,pytest,security] ; extra == 'all'
+Requires-Dist: fastapi-toolsets[cli,metrics,pytest] ; extra == 'all'
 Requires-Dist: typer>=0.9.0 ; extra == 'cli'
 Requires-Dist: prometheus-client>=0.20.0 ; extra == 'metrics'
 Requires-Dist: httpx>=0.25.0 ; extra == 'pytest'
 Requires-Dist: pytest-xdist>=3.0.0 ; extra == 'pytest'
 Requires-Dist: pytest>=8.0.0 ; extra == 'pytest'
-Requires-Dist: async-lru>=1.0 ; extra == 'security'
-Requires-Dist: httpx>=0.25.0 ; extra == 'security'
 Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/d3vyce/fastapi-toolsets
 Project-URL: Documentation, https://fastapi-toolsets.d3vyce.fr/
@@ -46,7 +44,6 @@ Provides-Extra: all
 Provides-Extra: cli
 Provides-Extra: metrics
 Provides-Extra: pytest
-Provides-Extra: security
 Description-Content-Type: text/markdown
 
 # FastAPI Toolsets
@@ -82,7 +79,6 @@ Install only the extras you need:
 ```bash
 uv add "fastapi-toolsets[cli]"
 uv add "fastapi-toolsets[metrics]"
-uv add "fastapi-toolsets[security]"
 uv add "fastapi-toolsets[pytest]"
 ```
 
@@ -108,7 +104,6 @@ uv add "fastapi-toolsets[all]"
 
 ### Optional
 
-- **Security**: Composable authentication sources (`BearerTokenAuth`, `CookieAuth`, `APIKeyHeaderAuth`, `MultiAuth`) with HMAC-signed cookies and OAuth 2.0 / OIDC helpers
 - **CLI**: Django-like command-line interface with fixture management and custom commands support
 - **Metrics**: Prometheus metrics endpoint with provider/collector registry
 - **Pytest Helpers**: Async test client, database session management, `pytest-xdist` support, and table cleanup utilities

{fastapi_toolsets-5.0.0b2 → fastapi_toolsets-5.1.0}/README.md

@@ -31,7 +31,6 @@ Install only the extras you need:
 ```bash
 uv add "fastapi-toolsets[cli]"
 uv add "fastapi-toolsets[metrics]"
-uv add "fastapi-toolsets[security]"
 uv add "fastapi-toolsets[pytest]"
 ```
 
@@ -57,7 +56,6 @@ uv add "fastapi-toolsets[all]"
 
 ### Optional
 
-- **Security**: Composable authentication sources (`BearerTokenAuth`, `CookieAuth`, `APIKeyHeaderAuth`, `MultiAuth`) with HMAC-signed cookies and OAuth 2.0 / OIDC helpers
 - **CLI**: Django-like command-line interface with fixture management and custom commands support
 - **Metrics**: Prometheus metrics endpoint with provider/collector registry
 - **Pytest Helpers**: Async test client, database session management, `pytest-xdist` support, and table cleanup utilities

{fastapi_toolsets-5.0.0b2 → fastapi_toolsets-5.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "5.0.0b2"
+version = "5.1.0"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"
@@ -50,17 +50,13 @@ cli = [
 metrics = [
     "prometheus_client>=0.20.0",
 ]
-security = [
-    "async-lru>=1.0",
-    "httpx>=0.25.0",
-]
 pytest = [
     "httpx>=0.25.0",
     "pytest-xdist>=3.0.0",
     "pytest>=8.0.0",
 ]
 all = [
-    "fastapi-toolsets[cli,metrics,pytest,security]",
+    "fastapi-toolsets[cli,metrics,pytest]",
 ]
 
 [project.scripts]
@@ -98,6 +94,18 @@ docs-src = [
 requires = ["uv_build>=0.10,<0.12.0"]
 build-backend = "uv_build"
 
+[tool.ruff.format]
+exclude = ["*.md"]
+
+[tool.ruff.lint]
+extend-select = ["E712"]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["fastapi.Depends"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["RUF012", "RUF059", "SIM117", "DTZ001", "S110", "BLE001"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 filterwarnings = [

{fastapi_toolsets-5.0.0b2 → fastapi_toolsets-5.1.0}/src/fastapi_toolsets/__init__.py

@@ -24,4 +24,4 @@ Example usage:
         return Response(data={"user": user.username}, message="Success")
 """
 
-__version__ = "5.0.0b2"
+__version__ = "5.1.0"

{fastapi_toolsets-5.0.0b2 → fastapi_toolsets-5.1.0}/src/fastapi_toolsets/cli/commands/fixtures.py

@@ -57,7 +57,7 @@ async def load(
     ctx: typer.Context,
     contexts: Annotated[
         list[str] | None,
-        typer.Argument(help="Contexts to load."),
+        typer.Argument(help="Contexts to load.", envvar="FIXTURES_CONTEXT"),
     ] = None,
     strategy: Annotated[
         LoadStrategy,

{fastapi_toolsets-5.0.0b2 → fastapi_toolsets-5.1.0}/src/fastapi_toolsets/crud/factory.py

@@ -44,6 +44,7 @@ from ..types import (
 )
 from .search import (
     SearchConfig,
+    apply_search_joins,
     build_facets,
     build_filter_by,
     build_search_filters,
@@ -51,7 +52,6 @@ from .search import (
     search_field_keys,
 )
 
-
 _ForUpdateMode: TypeAlias = bool | Literal["nowait", "skip_locked"]
 
 
@@ -128,17 +128,6 @@ def _apply_joins(q: Any, joins: JoinType | None, outer_join: bool) -> Any:
     return q
 
 
-def _apply_search_joins(q: Any, search_joins: list[Any]) -> Any:
-    """Apply relationship-based outer joins (from search/filter_by) to a query."""
-    seen: set[str] = set()
-    for join_rel in search_joins:
-        key = str(join_rel)
-        if key not in seen:
-            seen.add(key)
-            q = q.outerjoin(join_rel)
-    return q
-
-
 class AsyncCrud(Generic[ModelType]):
     """Generic async CRUD operations for SQLAlchemy models.
 
@@ -184,16 +173,30 @@ class AsyncCrud(Generic[ModelType]):
         return cls.default_load_options
 
     @classmethod
-    async def _reload_with_options(
-        cls: type[Self], session: AsyncSession, instance: ModelType
+    def _capture_pk_values(cls: type[Self], instance: ModelType) -> dict[str, Any]:
+        """Capture PK values off instance — call before commit expires attributes."""
+        return {
+            cast(str, col.key): getattr(instance, cast(str, col.key))
+            for col in cls.model.__mapper__.primary_key
+        }
+
+    @classmethod
+    async def _reload_with_options_by_pk(
+        cls: type[Self], session: AsyncSession, pk_values: dict[str, Any]
     ) -> ModelType:
-        """Re-query instance by PK with default_load_options applied."""
-        mapper = cls.model.__mapper__
+        """Re-query by previously captured PK values, with default_load_options applied."""
+        # Only called when cls.default_load_options is set (see call sites).
         pk_filters = [
-            getattr(cls.model, col.key) == getattr(instance, col.key)
-            for col in mapper.primary_key
+            getattr(cls.model, key) == value for key, value in pk_values.items()
         ]
-        return await cls.get(session, filters=pk_filters)
+        q = select(cls.model).where(and_(*pk_filters))
+        q = q.execution_options(populate_existing=True)
+        q = q.options(*cast(Sequence[ExecutableOption], cls.default_load_options))
+        result = await session.execute(q)
+        item = result.unique().scalar_one_or_none()
+        if item is None:  # pragma: no cover — row was just flushed in this transaction
+            raise NotFoundError()
+        return cast(ModelType, item)
 
     @classmethod
     async def _resolve_m2m(
@@ -264,12 +267,12 @@ class AsyncCrud(Generic[ModelType]):
         cls: type[Self],
         filter_by: dict[str, Any] | BaseModel | None,
         facet_fields: Sequence[FacetFieldType] | None,
-    ) -> tuple[list[Any], list[Any]]:
-        """Normalize filter_by and return (filters, joins) to apply to the query."""
+    ) -> tuple[dict[str, Any], list[Any]]:
+        """Normalize filter_by and return ({facet_key: filter}, joins) to apply to the query."""
         if isinstance(filter_by, BaseModel):
             filter_by = filter_by.model_dump(exclude_none=True)
         if not filter_by:
-            return [], []
+            return {}, []
         resolved = cls._resolve_facet_fields(facet_fields)
         return build_filter_by(filter_by, resolved or [])
 
@@ -280,8 +283,13 @@ class AsyncCrud(Generic[ModelType]):
         facet_fields: Sequence[FacetFieldType] | None,
         filters: list[Any],
         search_joins: list[Any],
+        *,
+        include_facets: bool = True,
+        own_filters: dict[str, Any] | None = None,
     ) -> dict[str, list[Any]] | None:
-        """Build facet filter_attributes, or return None if no facet fields configured."""
+        """Build facet filter_attributes, or None if disabled/no facet fields configured."""
+        if not include_facets:
+            return None
         resolved = cls._resolve_facet_fields(facet_fields)
         if not resolved:
             return None
@@ -291,6 +299,7 @@ class AsyncCrud(Generic[ModelType]):
             resolved,
             base_filters=filters,
             base_joins=search_joins,
+            own_filters=own_filters,
         )
 
     @classmethod
@@ -474,6 +483,7 @@ class AsyncCrud(Generic[ModelType]):
         default_page_size: int = 20,
         max_page_size: int = 100,
         include_total: bool = True,
+        include_facets: bool = True,
         search: bool = True,
         filter: bool = True,
         order: bool = True,
@@ -489,6 +499,7 @@ class AsyncCrud(Generic[ModelType]):
             default_page_size: Default ``items_per_page`` value.
             max_page_size: Maximum ``items_per_page`` value.
             include_total: Whether to include total count (not a query param).
+            include_facets: Whether to run facet queries (not a query param).
             search: Enable search query parameters.
             filter: Enable facet filter query parameters.
             order: Enable order query parameters.
@@ -518,7 +529,10 @@ class AsyncCrud(Generic[ModelType]):
         ]
         return cls._build_paginate_params(
             pagination_params=pagination_params,
-            pagination_fixed={"include_total": include_total},
+            pagination_fixed={
+                "include_total": include_total,
+                "include_facets": include_facets,
+            },
             dep_name=f"{cls.model.__name__}OffsetPaginateParams",
             search=search,
             filter=filter,
@@ -536,6 +550,7 @@ class AsyncCrud(Generic[ModelType]):
         *,
         default_page_size: int = 20,
         max_page_size: int = 100,
+        include_facets: bool = True,
         search: bool = True,
         filter: bool = True,
         order: bool = True,
@@ -550,6 +565,7 @@ class AsyncCrud(Generic[ModelType]):
         Args:
             default_page_size: Default ``items_per_page`` value.
             max_page_size: Maximum ``items_per_page`` value.
+            include_facets: Whether to run facet queries (not a query param).
             search: Enable search query parameters.
             filter: Enable facet filter query parameters.
             order: Enable order query parameters.
@@ -581,7 +597,7 @@ class AsyncCrud(Generic[ModelType]):
         ]
         return cls._build_paginate_params(
             pagination_params=pagination_params,
-            pagination_fixed={},
+            pagination_fixed={"include_facets": include_facets},
             dep_name=f"{cls.model.__name__}CursorPaginateParams",
             search=search,
             filter=filter,
@@ -601,6 +617,7 @@ class AsyncCrud(Generic[ModelType]):
         max_page_size: int = 100,
         default_pagination_type: PaginationType = PaginationType.OFFSET,
         include_total: bool = True,
+        include_facets: bool = True,
         search: bool = True,
         filter: bool = True,
         order: bool = True,
@@ -617,6 +634,7 @@ class AsyncCrud(Generic[ModelType]):
             max_page_size: Maximum ``items_per_page`` value.
             default_pagination_type: Default pagination strategy.
             include_total: Whether to include total count (not a query param).
+            include_facets: Whether to run facet queries (not a query param).
             search: Enable search query parameters.
             filter: Enable facet filter query parameters.
             order: Enable order query parameters.
@@ -665,7 +683,10 @@ class AsyncCrud(Generic[ModelType]):
         ]
         return cls._build_paginate_params(
             pagination_params=pagination_params,
-            pagination_fixed={"include_total": include_total},
+            pagination_fixed={
+                "include_total": include_total,
+                "include_facets": include_facets,
+            },
             dep_name=f"{cls.model.__name__}PaginateParams",
             search=search,
             filter=filter,
@@ -729,9 +750,14 @@ class AsyncCrud(Generic[ModelType]):
                     setattr(db_model, rel_attr, related_instances)
 
             session.add(db_model)
-        await session.refresh(db_model)
-        if cls.default_load_options:
-            db_model = await cls._reload_with_options(session, db_model)
+            pk_values: dict[str, Any] | None = None
+            if cls.default_load_options:
+                await session.flush()
+                pk_values = cls._capture_pk_values(db_model)
+        if pk_values is not None:
+            db_model = await cls._reload_with_options_by_pk(session, pk_values)
+        else:
+            await session.refresh(db_model)
         result = cast(ModelType, db_model)
         if schema:
             return Response(data=schema.model_validate(result))
@@ -1096,9 +1122,15 @@ class AsyncCrud(Generic[ModelType]):
                 m2m_resolved = await cls._resolve_m2m(session, obj, only_set=True)
                 for rel_attr, related_instances in m2m_resolved.items():
                     setattr(db_model, rel_attr, related_instances)
-        await session.refresh(db_model)
-        if cls.default_load_options:
-            db_model = await cls._reload_with_options(session, db_model)
+
+            pk_values: dict[str, Any] | None = None
+            if cls.default_load_options:
+                await session.flush()
+                pk_values = cls._capture_pk_values(db_model)
+        if pk_values is not None:
+            db_model = await cls._reload_with_options_by_pk(session, pk_values)
+        else:
+            await session.refresh(db_model)
         if schema:
             return Response(data=schema.model_validate(db_model))
         return db_model
@@ -1270,6 +1302,7 @@ class AsyncCrud(Generic[ModelType]):
         search_column: str | None = None,
         order_fields: Sequence[OrderFieldType] | None = None,
         facet_fields: Sequence[FacetFieldType] | None = None,
+        include_facets: bool = True,
         filter_by: dict[str, Any] | BaseModel | None = None,
         schema: type[BaseModel],
     ) -> OffsetPaginatedResponse[Any]:
@@ -1291,6 +1324,9 @@ class AsyncCrud(Generic[ModelType]):
             search_column: Restrict search to a single column key.
             order_fields: Fields allowed for sorting (overrides class default).
             facet_fields: Columns to compute distinct values for (overrides class default)
+            include_facets: When ``False``, skip facet queries entirely;
+                ``filter_attributes`` will be ``None``. Useful on pages 2..N
+                where the facet counts were already fetched on page 1.
             filter_by: Dict of {column_key: value} to filter by declared facet fields.
                 Keys must match the column.key of a facet field. Scalar → equality,
                 list → IN clause. Raises InvalidFacetFilterError for unknown keys.
@@ -1303,7 +1339,6 @@ class AsyncCrud(Generic[ModelType]):
         offset = (page - 1) * items_per_page
 
         fb_filters, search_joins = cls._prepare_filter_by(filter_by, facet_fields)
-        filters.extend(fb_filters)
 
         # Build search filters
         if search:
@@ -1317,6 +1352,11 @@ class AsyncCrud(Generic[ModelType]):
             filters.extend(search_filters)
             search_joins.extend(new_search_joins)
 
+        # Facets combine these with each facet's own filter individually, so
+        # fb_filters is applied to the query below but excluded here.
+        facet_base_filters = list(filters)
+        filters.extend(fb_filters.values())
+
         # Build query with joins
         q = select(cls.model)
 
@@ -1324,11 +1364,11 @@ class AsyncCrud(Generic[ModelType]):
         q = _apply_joins(q, joins, outer_join)
 
         # Apply search joins (always outer joins for search)
-        q = _apply_search_joins(q, search_joins)
+        q = apply_search_joins(q, search_joins)
 
         # Apply order joins (relation joins required for order_by field)
         if order_joins:
-            q = _apply_search_joins(q, order_joins)
+            q = apply_search_joins(q, order_joins)
 
         if filters:
             q = q.where(and_(*filters))
@@ -1351,7 +1391,7 @@ class AsyncCrud(Generic[ModelType]):
             count_q = _apply_joins(count_q, joins, outer_join)
 
             # Apply search joins to count query
-            count_q = _apply_search_joins(count_q, search_joins)
+            count_q = apply_search_joins(count_q, search_joins)
 
             if filters:
                 count_q = count_q.where(and_(*filters))
@@ -1371,7 +1411,12 @@ class AsyncCrud(Generic[ModelType]):
         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
+            session,
+            facet_fields,
+            facet_base_filters,
+            search_joins,
+            include_facets=include_facets,
+            own_filters=fb_filters,
         )
         search_columns = cls._resolve_search_columns(search_fields)
         order_columns = cls._resolve_order_columns(order_fields)
@@ -1407,6 +1452,7 @@ class AsyncCrud(Generic[ModelType]):
         search_column: str | None = None,
         order_fields: Sequence[OrderFieldType] | None = None,
         facet_fields: Sequence[FacetFieldType] | None = None,
+        include_facets: bool = True,
         filter_by: dict[str, Any] | BaseModel | None = None,
         schema: type[BaseModel],
     ) -> CursorPaginatedResponse[Any]:
@@ -1429,6 +1475,8 @@ class AsyncCrud(Generic[ModelType]):
             search_column: Restrict search to a single column key.
             order_fields: Fields allowed for sorting (overrides class default).
             facet_fields: Columns to compute distinct values for (overrides class default).
+            include_facets: When ``False``, skip facet queries entirely;
+                ``filter_attributes`` will be ``None``.
             filter_by: Dict of {column_key: value} to filter by declared facet fields.
                 Keys must match the column.key of a facet field. Scalar → equality,
                 list → IN clause. Raises InvalidFacetFilterError for unknown keys.
@@ -1440,7 +1488,6 @@ class AsyncCrud(Generic[ModelType]):
         filters = list(filters) if filters else []
 
         fb_filters, search_joins = cls._prepare_filter_by(filter_by, facet_fields)
-        filters.extend(fb_filters)
 
         if cls.cursor_column is None:
             raise ValueError(
@@ -1472,6 +1519,11 @@ class AsyncCrud(Generic[ModelType]):
             filters.extend(search_filters)
             search_joins.extend(new_search_joins)
 
+        # Facets combine these with each facet's own filter individually, so
+        # fb_filters is applied to the query below but excluded here.
+        facet_base_filters = list(filters)
+        filters.extend(fb_filters.values())
+
         # Build query
         q = select(cls.model)
 
@@ -1479,11 +1531,11 @@ class AsyncCrud(Generic[ModelType]):
         q = _apply_joins(q, joins, outer_join)
 
         # Apply search joins (always outer joins)
-        q = _apply_search_joins(q, search_joins)
+        q = apply_search_joins(q, search_joins)
 
         # Apply order joins (relation joins required for order_by field)
         if order_joins:
-            q = _apply_search_joins(q, order_joins)
+            q = apply_search_joins(q, order_joins)
 
         if filters:
             q = q.where(and_(*filters))
@@ -1528,11 +1580,10 @@ class AsyncCrud(Generic[ModelType]):
 
         # prev_cursor: points before the first item in ascending order
         prev_cursor: str | None = None
-        if direction is _CursorDirection.NEXT and cursor is not None and items_page:
-            prev_cursor = _encode_cursor(
-                getattr(items_page[0], cursor_col_name), direction=_CursorDirection.PREV
-            )
-        elif direction is _CursorDirection.PREV and has_more and items_page:
+        if items_page and (
+            (direction is _CursorDirection.NEXT and cursor is not None)
+            or (direction is _CursorDirection.PREV and has_more)
+        ):
             prev_cursor = _encode_cursor(
                 getattr(items_page[0], cursor_col_name), direction=_CursorDirection.PREV
             )
@@ -1540,7 +1591,12 @@ class AsyncCrud(Generic[ModelType]):
         items: list[Any] = [schema.model_validate(item) for item in items_page]
 
         filter_attributes = await cls._build_filter_attributes(
-            session, facet_fields, filters, search_joins
+            session,
+            facet_fields,
+            facet_base_filters,
+            search_joins,
+            include_facets=include_facets,
+            own_filters=fb_filters,
         )
         search_columns = cls._resolve_search_columns(search_fields)
         order_columns = cls._resolve_order_columns(order_fields)
@@ -1580,6 +1636,7 @@ class AsyncCrud(Generic[ModelType]):
         search_column: str | None = ...,
         order_fields: Sequence[OrderFieldType] | None = ...,
         facet_fields: Sequence[FacetFieldType] | None = ...,
+        include_facets: bool = ...,
         filter_by: dict[str, Any] | BaseModel | None = ...,
         schema: type[BaseModel],
     ) -> OffsetPaginatedResponse[Any]: ...
@@ -1606,6 +1663,7 @@ class AsyncCrud(Generic[ModelType]):
         search_column: str | None = ...,
         order_fields: Sequence[OrderFieldType] | None = ...,
         facet_fields: Sequence[FacetFieldType] | None = ...,
+        include_facets: bool = ...,
         filter_by: dict[str, Any] | BaseModel | None = ...,
         schema: type[BaseModel],
     ) -> CursorPaginatedResponse[Any]: ...
@@ -1631,6 +1689,7 @@ class AsyncCrud(Generic[ModelType]):
         search_column: str | None = None,
         order_fields: Sequence[OrderFieldType] | None = None,
         facet_fields: Sequence[FacetFieldType] | None = None,
+        include_facets: bool = True,
         filter_by: dict[str, Any] | BaseModel | None = None,
         schema: type[BaseModel],
     ) -> OffsetPaginatedResponse[Any] | CursorPaginatedResponse[Any]:
@@ -1661,6 +1720,8 @@ class AsyncCrud(Generic[ModelType]):
             order_fields: Fields allowed for sorting (overrides class default).
             facet_fields: Columns to compute distinct values for (overrides
                 class default).
+            include_facets: When ``False``, skip facet queries entirely;
+                ``filter_attributes`` will be ``None``.
             filter_by: Dict of ``{column_key: value}`` to filter by declared
                 facet fields.  Keys must match the ``column.key`` of a facet
                 field.  Scalar → equality, list → IN clause.  Raises
@@ -1691,6 +1752,7 @@ class AsyncCrud(Generic[ModelType]):
                     search_column=search_column,
                     order_fields=order_fields,
                     facet_fields=facet_fields,
+                    include_facets=include_facets,
                     filter_by=filter_by,
                     schema=schema,
                 )
@@ -1713,6 +1775,7 @@ class AsyncCrud(Generic[ModelType]):
                     search_column=search_column,
                     order_fields=order_fields,
                     facet_fields=facet_fields,
+                    include_facets=include_facets,
                     filter_by=filter_by,
                     schema=schema,
                 )