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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastapi-basekit
-Version: 0.3.1
+Version: 0.3.2
 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.2}/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.2}/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.2/fastapi_basekit/exceptions/__init__.py

@@ -0,0 +1,3 @@
+from fastapi_basekit.exceptions.domain import DomainError
+
+__all__ = ["DomainError"]

fastapi_basekit-0.3.2/fastapi_basekit/exceptions/domain.py

@@ -0,0 +1,57 @@
+"""Generic domain-error base class with declarative HTTP mapping.
+
+Services raise `DomainError` (or a subclass) with a stable string `code` and
+a human `message`. Endpoints catch and re-raise as HTTPException via
+`exc.to_http()`. The status code per `code` is declared on the subclass via
+`STATUS_CODE_MAP`, so each domain owns its mapping in one place — no inline
+`if/elif` translator helpers in endpoint files.
+
+Pattern:
+
+    class MyDomainError(DomainError):
+        STATUS_CODE_MAP = {
+            "unauthorized": status.HTTP_401_UNAUTHORIZED,
+            "not_found": status.HTTP_404_NOT_FOUND,
+            "conflict": status.HTTP_409_CONFLICT,
+        }
+
+    # Service:
+    raise MyDomainError("not_found", "Recurso no encontrado")
+
+    # Endpoint:
+    try:
+        await service.do_thing()
+    except MyDomainError as exc:
+        raise exc.to_http()
+"""
+
+from typing import ClassVar
+
+from fastapi import HTTPException, status
+
+
+class DomainError(Exception):
+    """Base for service-layer domain errors with HTTP mapping baked in.
+
+    Subclasses override `STATUS_CODE_MAP` to map their codes to HTTP
+    statuses. Codes not present fall back to `DEFAULT_STATUS`.
+    """
+
+    DEFAULT_STATUS: ClassVar[int] = status.HTTP_400_BAD_REQUEST
+    STATUS_CODE_MAP: ClassVar[dict[str, int]] = {}
+
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+    def http_status(self) -> int:
+        return self.STATUS_CODE_MAP.get(self.code, self.DEFAULT_STATUS)
+
+    def to_http(self) -> HTTPException:
+        return HTTPException(
+            status_code=self.http_status(), detail=self.message
+        )
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__}[{self.code}]: {self.message}"

{fastapi_basekit-0.3.1 → fastapi_basekit-0.3.2}/fastapi_basekit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastapi-basekit
-Version: 0.3.1
+Version: 0.3.2
 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.2}/fastapi_basekit.egg-info/SOURCES.txt

@@ -39,6 +39,7 @@ fastapi_basekit/cli/__init__.py
 fastapi_basekit/cli/main.py
 fastapi_basekit/exceptions/__init__.py
 fastapi_basekit/exceptions/api_exceptions.py
+fastapi_basekit/exceptions/domain.py
 fastapi_basekit/exceptions/handler.py
 fastapi_basekit/schema/__init__.py
 fastapi_basekit/schema/base.py

{fastapi_basekit-0.3.1 → fastapi_basekit-0.3.2}/pyproject.toml

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