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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastapi-basekit
-Version: 0.4.3
+Version: 0.5.2
 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.3 → fastapi_basekit-0.5.2}/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.3 → fastapi_basekit-0.5.2}/fastapi_basekit/aio/beanie/repository/base.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Any, Dict, List, Optional, Type, Union
+from typing import Any, Dict, Generic, List, Optional, Type, TypeVar, Union
 from typing import get_args, get_origin
 import re
 
@@ -11,10 +11,31 @@ 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.
         
@@ -194,6 +215,19 @@ class BaseRepository:
                     exprs.append(field_attr.id == _coerce_objectid(v))
                     continue
 
+            # Clave no resoluble (typo, campo inexistente, nesting mal escrito).
+            # Se descarta — pero se AVISA: si la clave venía de `get_filters`
+            # (scoping por tenant/owner), su desaparición silenciosa deja el
+            # listado sin filtrar → fuga cross-tenant (IDOR). El warning hace
+            # visible la pérdida en logs/Sentry en vez de fallar en silencio.
+            logger.warning(
+                "build_filter_query: filtro '%s' descartado (no resuelve a "
+                "ningún campo de %s). Si era un filtro de scoping, el listado "
+                "queda SIN ese filtro.",
+                k,
+                getattr(self.model, "__name__", self.model),
+            )
+
         # Raw MongoDB filters go first so Beanie processes them as a dict condition
         query_args: list = ([raw_filters] if raw_filters else []) + exprs
         query = self.model.find(*query_args, **self._get_query_kwargs(**kwargs))
@@ -207,6 +241,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)
@@ -379,7 +424,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`).
@@ -471,7 +522,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(
@@ -479,12 +530,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}'"
@@ -498,7 +556,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()
@@ -513,21 +571,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.3 → fastapi_basekit-0.5.2}/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]] = {}
@@ -74,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:
@@ -133,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)
 
@@ -159,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
         )
@@ -205,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: