fastapi-basekit 0.3.1__tar.gz → 0.3.3__tar.gz

{fastapi_basekit-0.3.1 → fastapi_basekit-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastapi-basekit
-Version: 0.3.1
+Version: 0.3.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.3.1 → fastapi_basekit-0.3.3}/fastapi_basekit/aio/beanie/controller/base.py

@@ -18,6 +18,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)
         items, total = await self.service.list(**params)
         count = params.get("count") or 0
@@ -39,6 +40,7 @@ class BeanieBaseController(BaseController):
         check_fields: Optional[List[str]] = None,
     ):
         """Crea un nuevo documento con validación de campos únicos."""
+        await self.prepare_action("create")
         result = await self.service.create(validated_data, check_fields)
         return self.format_response(result, message="Creado exitosamente")
 

{fastapi_basekit-0.3.1 → fastapi_basekit-0.3.3}/fastapi_basekit/aio/beanie/repository/base.py

@@ -207,27 +207,42 @@ class BaseRepository:
         # Apply ordering if provided and not already applied
         if order_by:
             query = query.sort(order_by)
-        
+
         total = await query.count()
         items = await query.skip(count * (page - 1)).limit(count).to_list()
         return items, total
-    
-    async def list_with_aggregation(
+
+    def build_list_queryset(
+        self,
+        search: Optional[str] = None,
+        search_fields: Optional[List[str]] = None,
+        filters: Optional[dict] = None,
+        order_by: Optional[List[tuple]] = None,
+        **kwargs,
+    ) -> FindMany[Document]:
+        """Hook: returns the FindMany query used by `list` endpoints.
+
+        Beanie equivalent of SQLAlchemy `build_list_queryset`. Override at
+        repository OR service level (`BaseService.build_list_queryset`) to
+        customize filters, projections, or query options before pagination.
+        Default implementation delegates to `build_filter_query`.
+        """
+        return self.build_filter_query(
+            search=search,
+            search_fields=search_fields or [],
+            filters=filters or {},
+            order_by=order_by,
+            **kwargs,
+        )
+
+    def _build_match_stage(
         self,
         search: Optional[str],
-        search_fields: List[str],
-        filters: dict,
-        order_by: str,
-        page: int,
-        count: int,
-        **kwargs
-    ) -> tuple[List[Document], int]:
-        """List with support for nested ordering using aggregation ($facet optimized)."""
-        field_path, direction, is_nested = self._parse_order_field(order_by)
-        pipeline = []
-        
-        # 1. Match stage (same as before)
-        match_conditions = {}
+        search_fields: Optional[List[str]],
+        filters: Optional[dict],
+    ) -> Dict[str, Any]:
+        """Build a `$match` stage dict (without the `$match` wrapper)."""
+        match_conditions: Dict[str, Any] = {}
         if filters:
             for key, value in filters.items():
                 if isinstance(value, ObjectId):
@@ -236,7 +251,7 @@ class BaseRepository:
                     match_conditions[f"{key}.$id"] = value.id
                 else:
                     match_conditions[key] = value
-        
+
         if search and search_fields:
             search_conditions = [
                 {field: {"$regex": f".*{search}.*", "$options": "i"}}
@@ -244,22 +259,47 @@ class BaseRepository:
             ]
             if search_conditions:
                 if match_conditions:
-                    match_conditions = {"$and": [match_conditions, {"$or": search_conditions}]}
+                    match_conditions = {
+                        "$and": [
+                            match_conditions,
+                            {"$or": search_conditions},
+                        ]
+                    }
                 else:
                     match_conditions = {"$or": search_conditions}
-        
+        return match_conditions
+
+    def build_list_pipeline(
+        self,
+        search: Optional[str] = None,
+        search_fields: Optional[List[str]] = None,
+        filters: Optional[dict] = None,
+        order_by: Optional[str] = None,
+        **kwargs,
+    ) -> List[Dict[str, Any]]:
+        """Hook: returns the aggregation pipeline used by `list` endpoints.
+
+        Beanie equivalent of SQL subqueries / JOINs. Override at repository
+        OR service level (`BaseService.build_list_pipeline`) to add `$lookup`,
+        `$project`, `$group`, etc. Default builds `$match` + optional `$sort`
+        (with auto `$lookup` for nested-link ordering). The `$facet` pagination
+        stage is appended later by `paginate_pipeline`.
+        """
+        pipeline: List[Dict[str, Any]] = []
+
+        match_conditions = self._build_match_stage(search, search_fields, filters)
         if match_conditions:
             pipeline.append({"$match": match_conditions})
-        
-        # 2. Lookup & Sort (same as before)
-        collection_name = None
-        first_field = None
-        
+
+        if not order_by:
+            return pipeline
+
+        field_path, direction, is_nested = self._parse_order_field(order_by)
+
         if is_nested:
             parts = field_path.split(".")
             first_field = parts[0]
             collection_name = self._get_collection_name_from_field(first_field)
-            
             if collection_name:
                 pipeline.extend([
                     {
@@ -267,65 +307,105 @@ class BaseRepository:
                             "from": collection_name,
                             "localField": f"{first_field}.$id",
                             "foreignField": "_id",
-                            "as": f"{first_field}_data"
+                            "as": f"{first_field}_data",
                         }
                     },
                     {
                         "$unwind": {
                             "path": f"${first_field}_data",
-                            "preserveNullAndEmptyArrays": True
+                            "preserveNullAndEmptyArrays": True,
                         }
-                    }
+                    },
                 ])
                 remaining_path = ".".join(parts[1:]) if len(parts) > 1 else ""
-                sort_field = f"{first_field}_data.{remaining_path}" if remaining_path else f"{first_field}_data"
+                sort_field = (
+                    f"{first_field}_data.{remaining_path}"
+                    if remaining_path
+                    else f"{first_field}_data"
+                )
             else:
                 sort_field = field_path
         else:
             sort_field = field_path
-            
+
         pipeline.append({"$sort": {sort_field: direction}})
-        
-        # 3. Facet for Single Query Pagination
-        project_exclusion = {f"{first_field}_data": 0} if (is_nested and collection_name) else None
-        
-        facet_stage = {
-            "$facet": {
-                "metadata": [{"$count": "total"}],
-                "data": [
-                    {"$skip": count * (page - 1)},
-                    {"$limit": count}
-                ]
+        return pipeline
+
+    async def paginate_pipeline(
+        self,
+        pipeline: List[Dict[str, Any]],
+        page: int,
+        count: int,
+        validate: bool = True,
+    ) -> tuple[List[Any], int]:
+        """Run an aggregation pipeline with `$facet` pagination.
+
+        Args:
+            pipeline: Pipeline stages (without the final `$facet`).
+            page, count: Pagination params.
+            validate: If True, validates each row against `self.model`.
+                Set False when the pipeline projects a non-model shape (e.g.
+                joined columns) — the raw dicts are returned untouched.
+        """
+        full_pipeline = list(pipeline) + [
+            {
+                "$facet": {
+                    "metadata": [{"$count": "total"}],
+                    "data": [
+                        {"$skip": count * (page - 1)},
+                        {"$limit": count},
+                    ],
+                }
             }
-        }
-        
-        # Add projection to remove join artifacts if needed
-        if project_exclusion:
-             facet_stage["$facet"]["data"].append({"$project": project_exclusion})
-             
-        pipeline.append(facet_stage)
-        
-        # Execute Pipeline
-        results = await self.model.aggregate(pipeline).to_list()
-        
-        # Process Results
+        ]
+
+        results = await self.model.aggregate(full_pipeline).to_list()
         if not results or not results[0].get("metadata"):
             return [], 0
-            
+
         data = results[0]
         total = data["metadata"][0]["total"] if data["metadata"] else 0
         items_raw = data["data"]
-        
-        # Efficient Validation
-        items = []
+
+        if not validate:
+            return items_raw, total
+
+        items: List[Any] = []
         for raw_item in items_raw:
             try:
                 items.append(self.model.model_validate(raw_item))
             except Exception:
                 continue
-                
         return items, total
 
+    async def list_with_aggregation(
+        self,
+        search: Optional[str],
+        search_fields: List[str],
+        filters: dict,
+        order_by: str,
+        page: int,
+        count: int,
+        **kwargs,
+    ) -> tuple[List[Document], int]:
+        """Backward-compat wrapper: delegates to `build_list_pipeline` +
+        `paginate_pipeline`. Kept for callers that hit it directly.
+        """
+        pipeline = self.build_list_pipeline(
+            search=search,
+            search_fields=search_fields,
+            filters=filters,
+            order_by=order_by,
+            **kwargs,
+        )
+        # Strip join artifacts when default sort-lookup added them
+        field_path, _, is_nested = self._parse_order_field(order_by) if order_by else ("", 0, False)
+        if is_nested:
+            first_field = field_path.split(".")[0]
+            if self._get_collection_name_from_field(first_field):
+                pipeline.append({"$project": {f"{first_field}_data": 0}})
+        return await self.paginate_pipeline(pipeline, page, count, validate=True)
+
     async def get_by_id(
         self,
         obj_id: Union[str, ObjectId],

{fastapi_basekit-0.3.1 → fastapi_basekit-0.3.3}/fastapi_basekit/aio/beanie/service/base.py

@@ -1,5 +1,7 @@
 from typing import Any, Dict, List, Optional, Union
 
+from beanie import Document
+from beanie.odm.queries.find import FindMany
 from fastapi import Request
 from pydantic import BaseModel
 
@@ -20,6 +22,8 @@ class BaseService:
     kwargs_query: Dict[str, Union[str, int]] = {}
     action: str = ""
     order_by: Optional[List[tuple]] = None
+    use_aggregation: bool = False
+    aggregation_validate: bool = True
 
     def __init__(
         self, repository: BaseRepository, request: Optional[Request] = None
@@ -69,61 +73,108 @@ class BaseService:
             raise NotFoundException(f"id={id} no encontrado")
         return obj
 
+    def build_list_queryset(
+        self,
+        search: Optional[str] = None,
+        search_fields: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        order_by: Optional[List[tuple]] = None,
+        **kwargs,
+    ) -> FindMany[Document]:
+        """Service-level hook over `repository.build_list_queryset`.
+
+        Override here to compose query options across repositories or to
+        decorate the FindMany before pagination.
+        """
+        return self.repository.build_list_queryset(
+            search=search,
+            search_fields=search_fields or self.search_fields,
+            filters=filters,
+            order_by=order_by,
+            **kwargs,
+        )
+
+    def build_list_pipeline(
+        self,
+        search: Optional[str] = None,
+        search_fields: Optional[List[str]] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        order_by: Optional[str] = None,
+        **kwargs,
+    ) -> List[Dict[str, Any]]:
+        """Service-level hook over `repository.build_list_pipeline`.
+
+        Override here to add `$lookup`, `$project`, `$group`, etc. for
+        cross-collection joins (subquery-like). Set `use_aggregation = True`
+        on the service to force the pipeline path even without nested order.
+        Set `aggregation_validate = False` if the projection produces a
+        non-model shape (joined columns / flattened rows).
+        """
+        return self.repository.build_list_pipeline(
+            search=search,
+            search_fields=search_fields or self.search_fields,
+            filters=filters,
+            order_by=order_by,
+            **kwargs,
+        )
+
     async def list(
         self,
         search: Optional[str] = None,
         page: int = 1,
         count: int = 25,
         filters: Optional[Dict[str, Any]] = None,
-        order_by: Optional[str] = None,  # NEW: Dynamic ordering (e.g., "-created_at" or "tool__name")
+        order_by: Optional[str] = None,  # Dynamic ordering (e.g., "-created_at" or "tool__name")
     ):
         kwargs = self.get_kwargs_query()
         applied_filters = self.get_filters(filters)
-        
-        # Determine which ordering to use
+
+        # Resolve ordering
         if order_by:
-            # Dynamic ordering from parameter (takes precedence)
             order_str = order_by
         else:
-            # Fall back to service-level ordering
             default_order = self.get_order()
             if default_order:
-                # Convert list of tuples to string format
-                # e.g., [("created_at", -1)] -> "-created_at"
                 field, direction = default_order[0]
                 order_str = f"{'-' if direction == -1 else ''}{field}"
             else:
                 order_str = None
-        
-        # Check if we need aggregation (nested field with __ or .)
-        if order_str and ("__" in order_str or "." in order_str):
-            # Use aggregation pipeline for nested ordering
-            return await self.repository.list_with_aggregation(
+
+        nested_order = bool(order_str and ("__" in order_str or "." in order_str))
+        use_pipeline = self.use_aggregation or nested_order
+
+        if use_pipeline:
+            pipeline = self.build_list_pipeline(
                 search=search,
                 search_fields=self.search_fields,
                 filters=applied_filters,
                 order_by=order_str,
-                page=page,
-                count=count,
                 **kwargs,
             )
-        else:
-            # Use standard query for simple ordering
-            order_list = None
-            if order_str:
-                # Parse the order string
-                direction = -1 if order_str.startswith("-") else 1
-                field = order_str.lstrip("-")
-                order_list = [(field, direction)]
-            
-            query = self.repository.build_filter_query(
-                search=search,
-                search_fields=self.search_fields,
-                filters=applied_filters,
-                order_by=order_list,
-                **kwargs,
+            return await self.repository.paginate_pipeline(
+                pipeline,
+                page=page,
+                count=count,
+                validate=self.aggregation_validate,
             )
-            return await self.repository.paginate(query, page, count, order_by=order_list)
+
+        # 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,
+        )
+        return await self.repository.paginate(
+            query, page, count, order_by=order_list
+        )
 
     async def create(
         self, payload: BaseModel, check_fields: Optional[List[str]] = None

{fastapi_basekit-0.3.1 → fastapi_basekit-0.3.3}/fastapi_basekit/aio/controller/base.py

@@ -14,7 +14,11 @@ class BaseController:
 
     service = Depends()
     schema_class: ClassVar[Type[BaseModel]]
-    action: ClassVar[Optional[str]] = None
+
+    # DRF Style: Permisos globales por defecto
+    permission_classes: ClassVar[List[Type[BasePermission]]] = []
+
+    action: Optional[str] = None
     request: Request
     _params_excluded_fields: ClassVar[Set[str]] = {
         "self",
@@ -32,34 +36,73 @@ class BaseController:
     }
 
     def __init__(self) -> None:
-        endpoint_func = (
-            self.request.scope.get("endpoint")
-            if hasattr(self, "request") and self.request
-            else None
-        )
-        self.action = endpoint_func.__name__ if endpoint_func else None
+        """Inicializa el controller."""
+        pass
+
+    def get_permissions(self) -> List[Type[BasePermission]]:
+        """
+        Instancia y retorna la lista de permisos que esta vista requiere.
+
+        Sobrescribir esto permite lógica tipo DRF:
+
+        if self.action == 'list':
+            return [AllowAny]
+        return [IsAuthenticated]
+        """
+        return self.permission_classes
+
+    async def prepare_action(self, action_name: str) -> None:
+        """Set the current action and run permission checks.
+
+        Auto-called by ``ControllerMeta`` for every public async method on
+        the controller. Idempotent within one invocation: if the same
+        ``action_name`` has already been prepared on this instance,
+        subsequent calls are no-ops. This lets custom methods opt into
+        calling ``await self.prepare_action(...)`` explicitly without
+        double-firing permission checks (when the metaclass already ran
+        before entering the method body).
+        """
+        if getattr(self, "_basekit_prepared_action", None) == action_name:
+            return
+        self.action = action_name
+        self._basekit_prepared_action = action_name
+        await self.check_permissions()
+
+    async def check_permissions(self):
+        """Run each declared permission. Raises ``PermissionException``
+        on the first denial.
+        """
+        for permission_class in self.get_permissions():
+            permission = permission_class()
+            has_perm = await permission.has_permission(self.request)
+            if not has_perm:
+                message = getattr(
+                    permission,
+                    "message_exception",
+                    "No tienes permiso para realizar esta acción.",
+                )
+                raise PermissionException(message)
+
+    async def check_permissions_class(self):
+        """Backward-compat alias for ``check_permissions``.
+
+        Pre-0.3.2 controllers called this manually inside endpoint methods.
+        Keep working for users who haven't migrated to ``permission_classes``
+        + auto-wrapping yet. New code should declare ``permission_classes``
+        on the controller and let the metaclass run permissions.
+        """
+        await self.check_permissions()
 
     def get_schema_class(self) -> Type[BaseModel]:
         assert self.schema_class is not None, (
             "'%s' should either include a `schema_class` attribute, "
-            "or override the `get_serializer_class()` method."
+            "or override the `get_schema_class()` method."
             % self.__class__.__name__
         )
         return self.schema_class
 
-    async def check_permissions_class(self):
-        permissions = self.check_permissions()
-        if permissions:
-            for permission in permissions:
-                obj = permission()
-                check = await obj.has_permission(self.request)
-                if not check:
-                    raise PermissionException(obj.message_exception)
-
-    def check_permissions(self) -> List[Type[BasePermission]]:
-        pass
-
     async def list(self):
+        await self.prepare_action("list")
         params = self._params()
         items, total = await self.service.list(**params)
         count = params.get("count") or 0
@@ -75,18 +118,22 @@ class BaseController:
         return self.format_response(data=items, pagination=pagination)
 
     async def retrieve(self, id: str):
+        await self.prepare_action("retrieve")
         item = await self.service.retrieve(id)
         return self.format_response(data=item)
 
     async def create(self, validated_data: Any):
+        await self.prepare_action("create")
         result = await self.service.create(validated_data)
         return self.format_response(result, message="Creado exitosamente")
 
     async def update(self, id: str, validated_data: Any):
+        await self.prepare_action("update")
         result = await self.service.update(id, validated_data)
         return self.format_response(result, message="Actualizado exitosamente")
 
     async def delete(self, id: str):
+        await self.prepare_action("delete")
         await self.service.delete(id)
         return self.format_response(None, message="Eliminado exitosamente")
 
@@ -99,33 +146,48 @@ class BaseController:
     ) -> BaseModel:
         schema = self.get_schema_class()
 
+        # Robust Pydantic v2 validation. Each branch falls back to the
+        # raw value when the schema doesn't fit (custom-action endpoints
+        # often return ad-hoc dicts that don't match the controller's
+        # default schema_class — those should pass through untouched).
         if isinstance(data, list):
             data_dicts = [self.to_dict(item) for item in data]
-            adapter = TypeAdapter(List[schema])
-            data_parsed = adapter.validate_python(data_dicts)
-        elif self.service.repository and isinstance(
-            data, self.service.repository.model
-        ):
-            data_parsed = self.to_dict(data)
-            data_parsed = schema.model_validate(data_parsed)
+            try:
+                adapter = TypeAdapter(List[schema])
+                data_parsed = adapter.validate_python(data_dicts)
+            except Exception:
+                data_parsed = data_dicts
+
         elif isinstance(data, dict):
-            data_parsed = schema.model_validate(data)
+            try:
+                data_parsed = schema.model_validate(data)
+            except Exception:
+                data_parsed = data
+
+        elif hasattr(data, "__dict__"):
+            data_dict = self.to_dict(data)
+            try:
+                data_parsed = schema.model_validate(data_dict)
+            except Exception:
+                data_parsed = data_dict
+
+        elif data is None:
+            data_parsed = None
         else:
             data_parsed = data
 
+        response_cls = BasePaginationResponse if pagination else BaseResponse
+
+        # Construcción dinámica de argumentos
+        kwargs = {
+            "data": data_parsed,
+            "message": message or "Operación exitosa",
+            "status": response_status,
+        }
         if pagination:
-            return BasePaginationResponse(
-                data=data_parsed,
-                pagination=pagination,
-                message=message or "Operación exitosa",
-                status=response_status,
-            )
-        else:
-            return BaseResponse(
-                data=data_parsed,
-                message=message or "Operación exitosa",
-                status=response_status,
-            )
+            kwargs["pagination"] = pagination
+
+        return response_cls(**kwargs)
 
     def _params(self, skip_frames: int = 1) -> Dict[str, Any]:
         """
@@ -208,6 +270,14 @@ class BaseController:
         }
 
     def to_dict(self, obj: Any):
-        if hasattr(obj, "model_dump"):
+        """Helper para convertir modelos ORM/Pydantic a dict."""
+        if hasattr(obj, "model_dump"):  # Pydantic v2
             return obj.model_dump()
+        if hasattr(obj, "dict"):  # Pydantic v1
+            return obj.dict()
+        if hasattr(obj, "__dict__"):  # SQLAlchemy models (basic)
+            # Filtramos atributos privados de SQLAlchemy
+            return {
+                k: v for k, v in obj.__dict__.items() if not k.startswith("_")
+            }
         return obj

{fastapi_basekit-0.3.1 → fastapi_basekit-0.3.3}/fastapi_basekit/aio/sqlalchemy/controller/base.py

@@ -48,6 +48,7 @@ class SQLAlchemyBaseController(BaseController):
             joins: Lista de relaciones a hacer JOIN eager loading
             order_by: Expresión de ordenamiento (ej: User.created_at.desc())
         """
+        await self.prepare_action("list")
         params = self._params(skip_frames=2)
         service_params = {
             **params,
@@ -73,6 +74,7 @@ class SQLAlchemyBaseController(BaseController):
             id: ID del registro
             joins: Lista de relaciones a hacer JOIN eager loading
         """
+        await self.prepare_action("retrieve")
         item = await self.service.retrieve(id, joins=joins)
         return self.format_response(data=item)
 
@@ -89,6 +91,7 @@ class SQLAlchemyBaseController(BaseController):
             validated_data: Datos validados para crear
             check_fields: Campos a verificar por duplicados antes de crear
         """
+        await self.prepare_action("create")
         result = await self.service.create(validated_data, check_fields)
         return self.format_response(result, message="Creado exitosamente")