fastapi-basekit 0.4.0__tar.gz → 0.4.3__tar.gz

{fastapi_basekit-0.4.0 → fastapi_basekit-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastapi-basekit
-Version: 0.4.0
+Version: 0.4.3
 Summary: Utilities and base classes for FastAPI async projects (Beanie, SQLAlchemy or SQLModel)
 Author-email: Jerson Moreno <jerson.ml820@hotmail.com>
 License: MIT

{fastapi_basekit-0.4.0 → fastapi_basekit-0.4.3}/fastapi_basekit/aio/beanie/repository/base.py

@@ -1,3 +1,4 @@
+import logging
 from typing import Any, Dict, List, Optional, Type, Union
 from typing import get_args, get_origin
 import re
@@ -8,6 +9,8 @@ from beanie import Document, Link
 from beanie.odm.queries.find import FindMany
 from beanie.operators import Or, RegEx
 
+logger = logging.getLogger(__name__)
+
 
 class BaseRepository:
     model: Type[Document]
@@ -212,6 +215,44 @@ class BaseRepository:
         items = await query.skip(count * (page - 1)).limit(count).to_list()
         return items, total
 
+    async def paginate_keyset(
+        self,
+        query: FindMany[Document],
+        limit: int,
+        cursor_field: str,
+        cursor_value: Optional[Any] = None,
+        ascending: bool = False,
+    ) -> tuple[List[Document], bool]:
+        """Keyset (cursor) pagination — O(1) por página, sin `skip` ni `count`.
+
+        Alternativa a `paginate` para listados que escalan: en vez de contar
+        toda la colección y saltar `count*(page-1)` documentos (coste que crece
+        con la profundidad), filtra por un cursor sobre `cursor_field` y trae
+        `limit + 1` para saber si quedan más — sin un `count()`.
+
+        Args:
+            query: FindMany ya filtrado (los filtros base del listado).
+            limit: tamaño de página.
+            cursor_field: campo Mongo indexado del cursor (ej. "_id",
+                "created_at", "timestamp"). Debe existir un índice que lo cubra.
+            cursor_value: valor del último item de la página previa. None =
+                primera página.
+            ascending: True = orden ascendente (`> cursor`); False = descendente
+                (`< cursor`), útil para "más recientes primero".
+
+        Returns:
+            (items, has_more). El caller deriva el próximo cursor del último
+            item devuelto (`getattr(items[-1], cursor_field)`).
+        """
+        limit = max(1, int(limit))
+        op = "$gt" if ascending else "$lt"
+        if cursor_value is not None:
+            query = query.find({cursor_field: {op: cursor_value}})
+        query = query.sort((cursor_field, 1 if ascending else -1))
+        docs = await query.limit(limit + 1).to_list()
+        has_more = len(docs) > limit
+        return docs[:limit], has_more
+
     def build_list_queryset(
         self,
         search: Optional[str] = None,
@@ -371,11 +412,31 @@ class BaseRepository:
             return items_raw, total
 
         items: List[Any] = []
+        dropped = 0
         for raw_item in items_raw:
             try:
                 items.append(self.model.model_validate(raw_item))
-            except Exception:
-                continue
+            except Exception as exc:
+                # No tragar en silencio: una fila que no valida se pierde de la
+                # respuesta sin aviso (menos items que el limit, total inflado).
+                # Se loguea para que sea diagnosticable; la fila igual se omite
+                # para no romper el listado completo por un doc corrupto.
+                dropped += 1
+                logger.warning(
+                    "paginate_pipeline: fila descartada por fallo de "
+                    "validación contra %s: %s",
+                    getattr(self.model, "__name__", self.model),
+                    exc,
+                )
+        if dropped:
+            logger.warning(
+                "paginate_pipeline: %d/%d filas descartadas en %s "
+                "(total reportado=%d)",
+                dropped,
+                len(items_raw),
+                getattr(self.model, "__name__", self.model),
+                total,
+            )
         return items, total
 
     async def list_with_aggregation(

{fastapi_basekit-0.4.0 → fastapi_basekit-0.4.3}/fastapi_basekit/aio/beanie/service/base.py

@@ -30,6 +30,14 @@ class BaseService:
     ):
         self.repository = repository
         self.request = request
+        # Copia por instancia de los defaults mutables (heredados como
+        # atributos de CLASE, compartidos por todo el proceso). Sin esto, una
+        # mutación en runtime (`self.search_fields.append(...)`) se filtraría a
+        # la clase y contaminaría otras requests. Respeta el override del
+        # subclass: `list(self.search_fields)` lee su atributo de clase.
+        self.search_fields = list(self.search_fields)
+        self.duplicate_check_fields = list(self.duplicate_check_fields)
+        self.kwargs_query = dict(self.kwargs_query)
         endpoint_func = (
             self.request.scope.get("endpoint") if self.request else None
         )

{fastapi_basekit-0.4.0 → fastapi_basekit-0.4.3}/fastapi_basekit/aio/controller/base.py

@@ -30,7 +30,6 @@ class BaseController:
         "count",
         "search",
         "order_by",
-        "action",
         "__class__",
         "args",
         "kwargs",

{fastapi_basekit-0.4.0 → fastapi_basekit-0.4.3}/fastapi_basekit/aio/sqlalchemy/controller/base.py

@@ -24,7 +24,6 @@ class SQLAlchemyBaseController(BaseController):
         "use_or",
         "joins",
         "order_by",
-        "action",
         "__class__",
         "args",
         "kwargs",

{fastapi_basekit-0.4.0 → fastapi_basekit-0.4.3}/fastapi_basekit/aio/sqlalchemy/repository/base.py

@@ -783,4 +783,15 @@ class BaseRepository:
             raise NotFoundException(message=f"{model.__name__} no encontrado")
         await db.delete(record)
         await db.flush()
-        return True
+        return True
+
+    async def save(self, obj: Any) -> Any:
+        """Persiste una entidad nueva o mutada (add + flush)."""
+        self.session.add(obj)
+        await self.session.flush()
+        return obj
+
+    async def hard_delete(self, obj: Any) -> None:
+        """Elimina físicamente la fila (sin soft delete)."""
+        await self.session.delete(obj)
+        await self.session.flush()

{fastapi_basekit-0.4.0 → fastapi_basekit-0.4.3}/fastapi_basekit/aio/sqlalchemy/service/base.py

@@ -2,8 +2,10 @@ from typing import Any, Dict, List, Optional
 
 from fastapi import Request
 from pydantic import BaseModel
+from sqlalchemy import select
 from ..repository.base import BaseRepository
 from ....exceptions.api_exceptions import (
+    APIException,
     NotFoundException,
     DatabaseIntegrityException,
 )
@@ -26,6 +28,17 @@ class BaseService:
     action: str | None = None
     kwargs_query: Dict[str, Any] = {}
 
+    # --- Política de borrado (ver `delete`) ---
+    #   "hard"           -> elimina físicamente (default, comportamiento histórico)
+    #   "soft"           -> marca deleted_at (requiere model con soft_delete())
+    #   "soft_mangle"    -> soft + renombra `mangle_fields` (`<valor>__del_<id>`)
+    #                       para liberar un valor único y poder recrear el registro
+    #   "hard_if_unused" -> elimina físicamente si no está referenciado, si no -> 409
+    delete_mode: str = "hard"
+    mangle_fields: List[str] = []
+    # [(Model, "fk_attr"), ...] revisados en "hard_if_unused".
+    delete_references: List[Any] = []
+
     def __init__(
         self,
         repository: BaseRepository,
@@ -184,5 +197,49 @@ class BaseService:
         updated = await self.repository.update(id, update_data)
         return updated
 
+    async def _referenced_label(self, obj: Any) -> Optional[str]:
+        """Nombre de un modelo que aún referencia a `obj` (bloquea hard delete), o None."""
+        session = self.repository.session
+        for model, fk in self.delete_references:
+            query = select(model.id).where(getattr(model, fk) == obj.id)
+            if hasattr(model, "deleted_at"):
+                query = query.where(model.deleted_at.is_(None))
+            if (await session.execute(query.limit(1))).first():
+                return model.__name__
+        return None
+
+    async def apply_delete(self, obj: Any) -> bool:
+        """Aplica la política de borrado (`delete_mode`) sobre una entidad ya cargada.
+
+        Útil cuando una subclase necesita resolver/scopear el objeto antes de borrar
+        (p. ej. tenant + region scope): hace `obj = self._get_scoped(id)` y luego
+        `await self.apply_delete(obj)`.
+        """
+        mode = self.delete_mode
+        if mode in ("soft", "soft_mangle"):
+            if not hasattr(obj, "soft_delete"):  # modelo sin soft delete -> físico
+                await self.repository.hard_delete(obj)
+                return True
+            obj.soft_delete()
+            if mode == "soft_mangle":
+                for field in self.mangle_fields:
+                    current = getattr(obj, field, None)
+                    if current is not None:
+                        setattr(obj, field, f"{current}__del_{obj.id}")
+            await self.repository.save(obj)
+        elif mode == "hard_if_unused":
+            if await self._referenced_label(obj) is not None:
+                raise APIException(
+                    message="No se puede eliminar: el registro está en uso.",
+                    status_code="IN_USE", status=409,
+                )
+            await self.repository.hard_delete(obj)
+        else:  # "hard"
+            await self.repository.hard_delete(obj)
+        return True
+
     async def delete(self, id: str) -> bool:
-        return await self.repository.delete(id)
+        obj = await self.repository.get(id)
+        if not obj:
+            raise NotFoundException(message=f"id={id} no encontrado")
+        return await self.apply_delete(obj)

{fastapi_basekit-0.4.0 → fastapi_basekit-0.4.3}/fastapi_basekit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastapi-basekit
-Version: 0.4.0
+Version: 0.4.3
 Summary: Utilities and base classes for FastAPI async projects (Beanie, SQLAlchemy or SQLModel)
 Author-email: Jerson Moreno <jerson.ml820@hotmail.com>
 License: MIT

{fastapi_basekit-0.4.0 → fastapi_basekit-0.4.3}/fastapi_basekit.egg-info/SOURCES.txt

@@ -110,6 +110,8 @@ tests/test_base_response.py
 tests/test_base_service.py
 tests/test_beanie_aggregation_hooks.py
 tests/test_beanie_aggregation_integration.py
+tests/test_beanie_keyset_pagination.py
+tests/test_beanie_service_mutable_defaults.py
 tests/test_controller_auto_permissions.py
 tests/test_crud_beanie_controller.py
 tests/test_crud_controller.py

{fastapi_basekit-0.4.0 → fastapi_basekit-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fastapi-basekit"
-version = "0.4.0"
+version = "0.4.3"
 description = "Utilities and base classes for FastAPI async projects (Beanie, SQLAlchemy or SQLModel)"
 readme = "README.md"
 requires-python = ">=3.11"

{fastapi_basekit-0.4.0 → fastapi_basekit-0.4.3}/tests/test_action_param_leak.py

@@ -33,3 +33,19 @@ def test_declared_query_filters_still_present():
     get_list = spec["paths"]["/users/"]["get"]
     names = {p["name"] for p in get_list.get("parameters", [])}
     assert {"page", "count", "search", "is_active", "age_min"} <= names
+
+
+def test_action_is_filterable_not_excluded():
+    """Regresión inversa: `action` NO debe estar en `_params_excluded_fields`.
+
+    El ClassVar ya evita el `?action=` espurio (test de arriba); excluir
+    `action` del set de filtros rompía filtrar por una columna `action`
+    declarada como query param (ej. audit-logs `?action=...`). v0.4.1.
+    """
+    from fastapi_basekit.aio.sqlalchemy.controller.base import (
+        SQLAlchemyBaseController,
+    )
+    from fastapi_basekit.aio.controller.base import BaseController
+
+    assert "action" not in SQLAlchemyBaseController._params_excluded_fields
+    assert "action" not in BaseController._params_excluded_fields

fastapi_basekit-0.4.3/tests/test_beanie_keyset_pagination.py

@@ -0,0 +1,75 @@
+"""Tests de `BaseRepository.paginate_keyset` (paginación por cursor, sin skip/count)."""
+
+import pytest
+import mongomock_motor
+from beanie import init_beanie
+
+from example_crud_beanie.models import UserDocument
+from example_crud_beanie.repository import UserBeanieRepository
+
+
+@pytest.fixture
+async def init_db():
+    client = mongomock_motor.AsyncMongoMockClient()
+    await init_beanie(database=client.test_db, document_models=[UserDocument])
+    yield
+    client.close()
+
+
+async def _seed(n: int):
+    for i in range(n):
+        await UserDocument(
+            name=f"u{i:02d}", email=f"u{i}@x.com", age=i
+        ).insert()
+
+
+class TestKeysetPagination:
+    async def test_desc_latest_first_and_cursor_walk(self, init_db):
+        repo = UserBeanieRepository()
+        await _seed(25)
+
+        # Página 1: los más "nuevos" por age desc.
+        items, has_more = await repo.paginate_keyset(
+            repo.model.find(), limit=10, cursor_field="age", ascending=False
+        )
+        assert [d.age for d in items] == list(range(24, 14, -1))
+        assert has_more is True
+
+        # Página 2 vía cursor (age del último item).
+        items2, has_more2 = await repo.paginate_keyset(
+            repo.model.find(),
+            limit=10,
+            cursor_field="age",
+            cursor_value=items[-1].age,
+            ascending=False,
+        )
+        assert [d.age for d in items2] == list(range(14, 4, -1))
+        assert has_more2 is True
+
+        # Página 3 (final): quedan 5, sin has_more.
+        items3, has_more3 = await repo.paginate_keyset(
+            repo.model.find(),
+            limit=10,
+            cursor_field="age",
+            cursor_value=items2[-1].age,
+            ascending=False,
+        )
+        assert [d.age for d in items3] == list(range(4, -1, -1))
+        assert has_more3 is False
+
+    async def test_ascending_order(self, init_db):
+        repo = UserBeanieRepository()
+        await _seed(5)
+        items, has_more = await repo.paginate_keyset(
+            repo.model.find(), limit=3, cursor_field="age", ascending=True
+        )
+        assert [d.age for d in items] == [0, 1, 2]
+        assert has_more is True
+
+    async def test_no_skip_or_count_on_empty(self, init_db):
+        repo = UserBeanieRepository()
+        items, has_more = await repo.paginate_keyset(
+            repo.model.find(), limit=10, cursor_field="age", ascending=False
+        )
+        assert items == []
+        assert has_more is False

fastapi_basekit-0.4.3/tests/test_beanie_service_mutable_defaults.py

@@ -0,0 +1,29 @@
+"""Los defaults mutables del BaseService (search_fields, kwargs_query,
+duplicate_check_fields) deben ser por instancia — mutar uno no puede filtrarse
+a otra instancia ni al atributo de clase (contaminación cross-request)."""
+
+from example_crud_beanie.repository import UserBeanieRepository
+from example_crud_beanie.service import UserBeanieService
+
+
+class TestMutableDefaultsIsolation:
+    def test_subclass_override_preserved(self):
+        s = UserBeanieService(repository=UserBeanieRepository())
+        # El override del subclass sigue vigente (copiado, no perdido).
+        assert s.search_fields == ["name", "email"]
+        assert s.duplicate_check_fields == ["email"]
+
+    def test_mutation_does_not_leak_across_instances(self):
+        s1 = UserBeanieService(repository=UserBeanieRepository())
+        s2 = UserBeanieService(repository=UserBeanieRepository())
+        s1.search_fields.append("phone")
+        assert "phone" not in s2.search_fields
+        # El atributo de CLASE queda intacto.
+        assert "phone" not in UserBeanieService.search_fields
+
+    def test_kwargs_query_dict_isolated(self):
+        s1 = UserBeanieService(repository=UserBeanieRepository())
+        s2 = UserBeanieService(repository=UserBeanieRepository())
+        s1.kwargs_query["fetch_links"] = True
+        assert s2.kwargs_query == {}
+        assert UserBeanieService.kwargs_query == {}