fastapi-basekit 0.4.1__tar.gz → 0.5.0__tar.gz

{fastapi_basekit-0.4.1 → fastapi_basekit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastapi-basekit
-Version: 0.4.1
+Version: 0.5.0
 Summary: Utilities and base classes for FastAPI async projects (Beanie, SQLAlchemy or SQLModel)
 Author-email: Jerson Moreno <jerson.ml820@hotmail.com>
 License: MIT
@@ -23,7 +23,7 @@ Provides-Extra: beanie
 Requires-Dist: beanie<3,>=2.0; extra == "beanie"
 Provides-Extra: sqlalchemy
 Requires-Dist: SQLAlchemy[asyncio]<3,>=2.0.30; extra == "sqlalchemy"
-Requires-Dist: psycopg2>=2.9.0; extra == "sqlalchemy"
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "sqlalchemy"
 Provides-Extra: sqlmodel
 Requires-Dist: sqlmodel>=0.0.37; extra == "sqlmodel"
 Provides-Extra: init
@@ -37,7 +37,7 @@ Requires-Dist: mike>=2.1.0; extra == "docs"
 Provides-Extra: all
 Requires-Dist: beanie<3,>=2.0; extra == "all"
 Requires-Dist: SQLAlchemy[asyncio]<3,>=2.0.30; extra == "all"
-Requires-Dist: psycopg2>=2.9.0; extra == "all"
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
 Requires-Dist: sqlmodel>=0.0.37; extra == "all"
 Requires-Dist: cookiecutter>=2.5.0; extra == "all"
 Requires-Dist: mkdocs>=1.6.0; extra == "all"

{fastapi_basekit-0.4.1 → fastapi_basekit-0.5.0}/fastapi_basekit/aio/beanie/controller/base.py

@@ -19,7 +19,7 @@ class BeanieBaseController(BaseController):
     async def list(self):
         """Lista documentos con paginación usando Beanie."""
         await self.prepare_action("list")
-        params = self._params(skip_frames=2)
+        params = self._params()
         items, total = await self.service.list(**params)
         count = params.get("count") or 0
         page = params.get("page") or 1

{fastapi_basekit-0.4.1 → fastapi_basekit-0.5.0}/fastapi_basekit/aio/beanie/repository/base.py

@@ -1,4 +1,5 @@
-from typing import Any, Dict, List, Optional, Type, Union
+import logging
+from typing import Any, Dict, Generic, List, Optional, Type, TypeVar, Union
 from typing import get_args, get_origin
 import re
 
@@ -8,10 +9,33 @@ from beanie import Document, Link
 from beanie.odm.queries.find import FindMany
 from beanie.operators import Or, RegEx
 
+logger = logging.getLogger(__name__)
+
+#: Tipo del Document Beanie que gestiona el repositorio. Parametrízalo al
+#: declarar la subclase — ``class UserRepository(BaseRepository[User])`` — para
+#: que ``get_by_id``/``create``/``update``/``list_all`` devuelvan el Document
+#: tipado (autocompletado + mypy para consumidores e IAs).
+ModelT = TypeVar("ModelT", bound=Document)
+
+
+class BaseRepository(Generic[ModelT]):
+    """Repositorio base para Beanie ODM (MongoDB), parametrizado por el modelo.
+
+    OJO — las firmas difieren del repo SQLAlchemy (misma clase, distinto ORM):
+      - get por id:  `get_by_id(id)`   (SQL usa `get(id)`)
+      - update:      `update(obj, data)` — el 1er arg es el **Document**, no el
+                     id (SQL usa `update(id, dict)`). Fetch primero con
+                     `get_by_id`, luego `update(obj, data)`.
+      - delete:      `delete(obj)` — recibe el Document (SQL usa `delete(id)`).
+      - create:      `create(obj | dict)`.
+    Listado: `build_list_queryset(...)`→FindMany + `paginate(...)`, o
+    `build_list_pipeline(...)` + `paginate_pipeline(...)` para joins (`$lookup`).
+    Preferí llamar el SERVICE (API unificada) en vez del repo directo; llamar
+    `get_by_id` directo bypassea el scoping de `get_filters()`.
+    """
+
+    model: Type[ModelT]
 
-class BaseRepository:
-    model: Type[Document]
-    
     def _parse_order_field(self, order_by: str) -> tuple[str, int, bool]:
         """Parse order_by string into components.
         
@@ -204,6 +228,17 @@ class BaseRepository:
     async def paginate(
         self, query: FindMany[Document], page: int, count: int, order_by: Optional[List[tuple]] = None
     ) -> tuple[List[Document], int]:
+        """MOTOR DE PAGINACIÓN (FindMany) — NO LO REIMPLEMENTES.
+
+        Único loop de paginación offset (count + skip/limit). Para personalizar
+        el listado, override el HOOK correcto, no copies skip/limit/count:
+        - query/filtros/scoping/orden → `build_list_queryset` (o `build_filter_query`)
+        - join `$lookup` / shape plano → `use_aggregation=True` + `build_list_pipeline`
+        - filtros por usuario/acción   → `Service.get_filters`
+        - orden por defecto            → `Service.get_order`
+        - enriquecer items de la página→ `Service.post_process_list`
+        - scroll infinito / cursor     → `paginate_keyset` (método+endpoint aparte)
+        """
         # Apply ordering if provided and not already applied
         if order_by:
             query = query.sort(order_by)
@@ -212,6 +247,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,
@@ -338,7 +411,13 @@ class BaseRepository:
         count: int,
         validate: bool = True,
     ) -> tuple[List[Any], int]:
-        """Run an aggregation pipeline with `$facet` pagination.
+        """MOTOR DE PAGINACIÓN (aggregation `$facet`) — NO LO REIMPLEMENTES.
+
+        Ejecuta el pipeline con paginación `$facet`. Para un listado agregado
+        NO copies este `$facet`/skip/limit: override `Service.build_list_pipeline`
+        (agrega `$lookup`/`$project`/`$group`) y activa `use_aggregation=True`;
+        este método le pone la paginación. Si la proyección no es el modelo,
+        `aggregation_validate=False`.
 
         Args:
             pipeline: Pipeline stages (without the final `$facet`).
@@ -371,11 +450,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(
@@ -410,7 +509,7 @@ class BaseRepository:
         self,
         obj_id: Union[str, ObjectId],
         **kwargs,
-    ) -> Optional[Document]:
+    ) -> Optional[ModelT]:
         if not isinstance(obj_id, ObjectId):
             obj_id = ObjectId(obj_id)
         return await self.model.find_one(
@@ -418,12 +517,19 @@ class BaseRepository:
             **self._get_query_kwargs(**kwargs),
         )
 
+    async def get(
+        self, obj_id: Union[str, ObjectId], **kwargs
+    ) -> Optional[ModelT]:
+        """Alias de `get_by_id(id)` — nombre unificado con los repos SQL
+        (`get`) para que las lecturas por id sean portables entre ORMs."""
+        return await self.get_by_id(obj_id, **kwargs)
+
     async def get_by_field(
         self,
         field_name: str,
         value: Any,
         **kwargs,
-    ) -> Optional[Document]:
+    ) -> Optional[ModelT]:
         if not hasattr(self.model, field_name):
             raise AttributeError(
                 f"{self.model.__name__} no tiene el campo '{field_name}'"
@@ -437,7 +543,7 @@ class BaseRepository:
         self,
         filters: Dict[str, Any],
         **kwargs,
-    ) -> Optional[Document]:
+    ) -> Optional[ModelT]:
         exprs = [
             getattr(self.model, f) == v
             for f, v in filters.items()
@@ -452,21 +558,27 @@ class BaseRepository:
     async def list_all(
         self,
         **kwargs,
-    ) -> List[Document]:
+    ) -> List[ModelT]:
         query = self.model.find_all(**self._get_query_kwargs(**kwargs))
         return await query.to_list()
 
-    async def create(self, obj: Union[Document, Dict[str, Any]]) -> Document:
+    async def create(self, obj: Union[ModelT, Dict[str, Any]]) -> ModelT:
         if isinstance(obj, dict):
             obj = self.model(**obj)
         await obj.insert()
         return obj
 
-    async def update(self, obj: Document, data: Dict[str, Any]) -> Document:
+    async def update(self, obj: ModelT, data: Dict[str, Any]) -> ModelT:
+        """Actualiza un Document Beanie ya cargado.
+
+        Divergencia con SQL: acá el 1er arg es el **Document** (no el id) y SÍ
+        setea ``None``. El repo SQLAlchemy usa ``update(id, dict)`` y omite
+        ``None``. Ver la tabla en el CLAUDE.md de la lib.
+        """
         for key, value in data.items():
             setattr(obj, key, value)
         await obj.save()
         return obj
 
-    async def delete(self, obj: Document) -> None:
+    async def delete(self, obj: ModelT) -> None:
         await obj.delete()

{fastapi_basekit-0.4.1 → fastapi_basekit-0.5.0}/fastapi_basekit/aio/beanie/service/base.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, Generic, List, Optional, Tuple, Union
 
 from beanie import Document
 from beanie.odm.queries.find import FindMany
@@ -6,17 +6,25 @@ from fastapi import Request
 from pydantic import BaseModel
 
 
-from ...beanie.repository.base import BaseRepository
+from ...beanie.repository.base import BaseRepository, ModelT
 from ....exceptions.api_exceptions import (
     NotFoundException,
     DatabaseIntegrityException,
 )
 
 
-class BaseService:
-    """Servicio base específico para Beanie ODM (async)."""
+class BaseService(Generic[ModelT]):
+    """Servicio base específico para Beanie ODM (async), parametrizado.
 
-    repository: BaseRepository
+    Declara el modelo vía el genérico para tipar el CRUD::
+
+        class UserService(BaseService[User]):
+            repository: UserRepository
+
+    Así ``retrieve``/``create``/``update`` devuelven ``User``.
+    """
+
+    repository: BaseRepository[ModelT]
     search_fields: List[str] = []
     duplicate_check_fields: List[str] = []
     kwargs_query: Dict[str, Union[str, int]] = {}
@@ -30,6 +38,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
         )
@@ -66,7 +82,7 @@ class BaseService:
         filters = filters or {}
         return filters
 
-    async def retrieve(self, id: str):
+    async def retrieve(self, id: str) -> ModelT:
         kwargs = self.get_kwargs_query()
         obj = await self.repository.get_by_id(id, **kwargs)
         if not obj:
@@ -125,7 +141,7 @@ class BaseService:
         count: int = 25,
         filters: Optional[Dict[str, Any]] = None,
         order_by: Optional[str] = None,  # Dynamic ordering (e.g., "-created_at" or "tool__name")
-    ):
+    ) -> Tuple[List[ModelT], int]:
         kwargs = self.get_kwargs_query()
         applied_filters = self.get_filters(filters)
 
@@ -151,34 +167,60 @@ class BaseService:
                 order_by=order_str,
                 **kwargs,
             )
-            return await self.repository.paginate_pipeline(
+            items, total = await self.repository.paginate_pipeline(
                 pipeline,
                 page=page,
                 count=count,
                 validate=self.aggregation_validate,
             )
+        else:
+            # FindMany path
+            order_list = None
+            if order_str:
+                direction = -1 if order_str.startswith("-") else 1
+                field = order_str.lstrip("-")
+                order_list = [(field, direction)]
 
-        # FindMany path
-        order_list = None
-        if order_str:
-            direction = -1 if order_str.startswith("-") else 1
-            field = order_str.lstrip("-")
-            order_list = [(field, direction)]
+            query = self.build_list_queryset(
+                search=search,
+                search_fields=self.search_fields,
+                filters=applied_filters,
+                order_by=order_list,
+                **kwargs,
+            )
+            items, total = await self.repository.paginate(
+                query, page, count, order_by=order_list
+            )
 
-        query = self.build_list_queryset(
-            search=search,
-            search_fields=self.search_fields,
-            filters=applied_filters,
-            order_by=order_list,
-            **kwargs,
-        )
-        return await self.repository.paginate(
-            query, page, count, order_by=order_list
-        )
+        items = await self.post_process_list(items)
+        return items, total
+
+    async def post_process_list(self, items: List[ModelT]) -> List[ModelT]:
+        """Hook: transforma/enriquece los items DE UNA PÁGINA ya paginada.
+
+        Este es el método para "hacer algo custom con los resultados" SIN
+        reescribir la paginación ni overridear `list()`. Corre después de
+        `paginate`/`paginate_pipeline`, sobre los items de la página actual
+        (no toda la colección), así que es seguro para un enrich con un `await`
+        extra por página (agrega un contador, resuelve un campo derivado, etc.).
+
+        Default: devuelve los items sin cambios. Ejemplo::
+
+            async def post_process_list(self, items):
+                ids = [c.id for c in items]
+                counts = await self.conv_repo.count_by_customer_ids(ids)
+                for c in items:
+                    c.conversation_count = counts.get(c.id, 0)
+                return items
+
+        NO cambies el `total` acá (es el de la query completa). NO filtres items
+        (eso va en `get_filters`/`build_list_*`, o el total quedaría mal).
+        """
+        return items
 
     async def create(
         self, payload: BaseModel, check_fields: Optional[List[str]] = None
-    ) -> Any:
+    ) -> ModelT:
         data = (
             payload.model_dump() if not isinstance(payload, dict) else payload
         )
@@ -197,7 +239,7 @@ class BaseService:
             else created
         )
 
-    async def update(self, id: str, data: BaseModel) -> Any:
+    async def update(self, id: str, data: BaseModel) -> ModelT:
         kwargs = self.get_kwargs_query()
         obj = await self.repository.get_by_id(id, **kwargs)
         if not obj: