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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastapi-basekit
-Version: 0.3.0
+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
@@ -16,14 +16,13 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastapi>=0.116.1
-Requires-Dist: pydantic<3,>=2.11.7
+Requires-Dist: pydantic<3,>=2.13.0
 Requires-Dist: fastapi-restful[all]>=0.6.0
-Requires-Dist: pyjwt>=2.10.1
+Requires-Dist: pyjwt>=2.12.1
 Provides-Extra: beanie
-Requires-Dist: beanie>=1.24.0; extra == "beanie"
-Requires-Dist: motor>=3.3.0; extra == "beanie"
+Requires-Dist: beanie<3,>=2.0; extra == "beanie"
 Provides-Extra: sqlalchemy
-Requires-Dist: SQLAlchemy[asyncio]>=2.0.0; extra == "sqlalchemy"
+Requires-Dist: SQLAlchemy[asyncio]<3,>=2.0.30; extra == "sqlalchemy"
 Requires-Dist: psycopg2>=2.9.0; extra == "sqlalchemy"
 Provides-Extra: sqlmodel
 Requires-Dist: sqlmodel>=0.0.37; extra == "sqlmodel"
@@ -36,9 +35,8 @@ Requires-Dist: mkdocstrings[python]>=0.27.0; extra == "docs"
 Requires-Dist: pymdown-extensions>=10.10; extra == "docs"
 Requires-Dist: mike>=2.1.0; extra == "docs"
 Provides-Extra: all
-Requires-Dist: beanie>=1.24.0; extra == "all"
-Requires-Dist: motor>=3.3.0; extra == "all"
-Requires-Dist: SQLAlchemy[asyncio]>=2.0.0; 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: sqlmodel>=0.0.37; extra == "all"
 Requires-Dist: cookiecutter>=2.5.0; extra == "all"
@@ -48,18 +46,24 @@ Requires-Dist: mkdocstrings[python]>=0.27.0; extra == "all"
 
 <div align="center">
 
-# FastAPI BaseKit
+<img src="docs/assets/logo-mark.svg" width="120" alt="fastapi-basekit">
 
-**Toolkit base para construir APIs FastAPI rápido — sin reinventar repos, services y controllers.**
+# fastapi-basekit
 
-[![PyPI](https://img.shields.io/pypi/v/fastapi-basekit?style=flat-square&color=teal)](https://pypi.org/project/fastapi-basekit/)
-![Python](https://img.shields.io/badge/python-3.11+-blue?style=flat-square&logo=python)
-![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat-square&logo=fastapi)
-![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-2.0-red?style=flat-square)
-![Beanie](https://img.shields.io/badge/MongoDB-Beanie-47A248?style=flat-square&logo=mongodb)
-![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)
+**FastAPI toolkit con repos, services y controllers listos para producción.**
+**Multi-ORM · CLI scaffolder · plugin Claude Code.**
 
-[**Docs**](https://mundobien2025.github.io/fastapi-basekit) · [**PyPI**](https://pypi.org/project/fastapi-basekit/) · [**Issues**](https://github.com/mundobien2025/fastapi-basekit/issues) · [**Changelog**](./CHANGELOG.md)
+[![PyPI](https://img.shields.io/pypi/v/fastapi-basekit?style=flat-square&color=009485&logo=pypi&logoColor=white)](https://pypi.org/project/fastapi-basekit/)
+[![Python](https://img.shields.io/badge/python-3.11+-2c5282?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/fastapi-basekit/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
+[![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-2.0-c41616?style=flat-square)](https://www.sqlalchemy.org/)
+[![Beanie](https://img.shields.io/badge/MongoDB-Beanie-47A248?style=flat-square&logo=mongodb&logoColor=white)](https://beanie-odm.dev/)
+[![License](https://img.shields.io/badge/license-MIT-009485?style=flat-square)](./LICENSE)
+
+[**Docs**](https://mundobien2025.github.io/fastapi-basekit) ·
+[**PyPI**](https://pypi.org/project/fastapi-basekit/) ·
+[**Issues**](https://github.com/mundobien2025/fastapi-basekit/issues) ·
+[**Changelog**](./CHANGELOG.md)
 
 </div>
 
@@ -89,7 +93,7 @@ Abre http://localhost:8000/docs. Login con `admin@example.com` / `ChangeMe2026!`
 
 ## Documentación
 
-📚 **[mundobien2025.github.io/fastapi-basekit](https://mundobien2025.github.io/fastapi-basekit)**
+**[mundobien2025.github.io/fastapi-basekit](https://mundobien2025.github.io/fastapi-basekit)**
 
 | Sección | Contenido |
 |---|---|

{fastapi_basekit-0.3.0 → fastapi_basekit-0.3.2}/README.md

@@ -1,17 +1,23 @@
 <div align="center">
 
-# FastAPI BaseKit
+<img src="docs/assets/logo-mark.svg" width="120" alt="fastapi-basekit">
 
-**Toolkit base para construir APIs FastAPI rápido — sin reinventar repos, services y controllers.**
+# fastapi-basekit
 
-[![PyPI](https://img.shields.io/pypi/v/fastapi-basekit?style=flat-square&color=teal)](https://pypi.org/project/fastapi-basekit/)
-![Python](https://img.shields.io/badge/python-3.11+-blue?style=flat-square&logo=python)
-![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat-square&logo=fastapi)
-![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-2.0-red?style=flat-square)
-![Beanie](https://img.shields.io/badge/MongoDB-Beanie-47A248?style=flat-square&logo=mongodb)
-![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)
+**FastAPI toolkit con repos, services y controllers listos para producción.**
+**Multi-ORM · CLI scaffolder · plugin Claude Code.**
 
-[**Docs**](https://mundobien2025.github.io/fastapi-basekit) · [**PyPI**](https://pypi.org/project/fastapi-basekit/) · [**Issues**](https://github.com/mundobien2025/fastapi-basekit/issues) · [**Changelog**](./CHANGELOG.md)
+[![PyPI](https://img.shields.io/pypi/v/fastapi-basekit?style=flat-square&color=009485&logo=pypi&logoColor=white)](https://pypi.org/project/fastapi-basekit/)
+[![Python](https://img.shields.io/badge/python-3.11+-2c5282?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/fastapi-basekit/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
+[![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-2.0-c41616?style=flat-square)](https://www.sqlalchemy.org/)
+[![Beanie](https://img.shields.io/badge/MongoDB-Beanie-47A248?style=flat-square&logo=mongodb&logoColor=white)](https://beanie-odm.dev/)
+[![License](https://img.shields.io/badge/license-MIT-009485?style=flat-square)](./LICENSE)
+
+[**Docs**](https://mundobien2025.github.io/fastapi-basekit) ·
+[**PyPI**](https://pypi.org/project/fastapi-basekit/) ·
+[**Issues**](https://github.com/mundobien2025/fastapi-basekit/issues) ·
+[**Changelog**](./CHANGELOG.md)
 
 </div>
 
@@ -41,7 +47,7 @@ Abre http://localhost:8000/docs. Login con `admin@example.com` / `ChangeMe2026!`
 
 ## Documentación
 
-📚 **[mundobien2025.github.io/fastapi-basekit](https://mundobien2025.github.io/fastapi-basekit)**
+**[mundobien2025.github.io/fastapi-basekit](https://mundobien2025.github.io/fastapi-basekit)**
 
 | Sección | Contenido |
 |---|---|

{fastapi_basekit-0.3.0 → fastapi_basekit-0.3.2}/fastapi_basekit/aio/beanie/repository/base.py

@@ -2,9 +2,9 @@ from typing import Any, Dict, List, Optional, Type, Union
 from typing import get_args, get_origin
 import re
 
-from bson import ObjectId, Link
+from bson import ObjectId
 from pydantic import BaseModel
-from beanie import Document
+from beanie import Document, Link
 from beanie.odm.queries.find import FindMany
 from beanie.operators import Or, RegEx
 
@@ -154,18 +154,42 @@ class BaseRepository:
 
         raw_filters: Dict[str, Any] = {}
 
+        def _coerce_objectid(value: Any) -> Any:
+            """str/UUID → ObjectId para queries Mongo sobre Link.id."""
+            if isinstance(value, ObjectId):
+                return value
+            if isinstance(value, str):
+                try:
+                    return ObjectId(value)
+                except Exception:
+                    return value
+            return value
+
         for k, v in (filters or {}).items():
             # MongoDB-style keys (dot-notation like "user.$id" or operators like "$or")
             # cannot be resolved via hasattr — pass them as a raw dict to find()
             if "." in k or k.startswith("$"):
                 raw_filters[k] = v
-            elif hasattr(self.model, k):
-                field_attr = getattr(self.model, k)
+                continue
 
+            if hasattr(self.model, k):
+                field_attr = getattr(self.model, k)
                 if _is_link_field(k):
-                    exprs.append(field_attr.id == v)
+                    exprs.append(field_attr.id == _coerce_objectid(v))
                 else:
                     exprs.append(field_attr == v)
+                continue
+
+            # `<field>_id` alias para Link fields. Permite filtros con
+            # `customer_id`, `user_id`, etc. sin que el caller deba conocer
+            # la sintaxis Mongo nested. Sólo se activa si <field> existe en
+            # el modelo y es un Link[X].
+            if k.endswith("_id"):
+                base = k[:-3]
+                if hasattr(self.model, base) and _is_link_field(base):
+                    field_attr = getattr(self.model, base)
+                    exprs.append(field_attr.id == _coerce_objectid(v))
+                    continue
 
         # Raw MongoDB filters go first so Beanie processes them as a dict condition
         query_args: list = ([raw_filters] if raw_filters else []) + exprs
@@ -183,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):
@@ -212,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"}}
@@ -220,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([
                     {
@@ -243,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.0 → 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.0 → fastapi_basekit-0.3.2}/fastapi_basekit/aio/sqlalchemy/__init__.py

@@ -1,6 +1,7 @@
-__all__ = ["repository", "service", "controller"]
 from .controller.base import SQLAlchemyBaseController
+from .session import make_session_lifecycle
 
 __all__ = [
     "SQLAlchemyBaseController",
+    "make_session_lifecycle",
 ]

{fastapi_basekit-0.3.0 → fastapi_basekit-0.3.2}/fastapi_basekit/aio/sqlalchemy/service/base.py

@@ -10,7 +10,14 @@ from ....exceptions.api_exceptions import (
 
 
 class BaseService:
-    """Servicio base para SQLAlchemy AsyncSession."""
+    """Servicio base para SQLAlchemy AsyncSession.
+
+    Regla del proyecto: los servicios NO deben llamar `session.flush()`,
+    `session.commit()` ni `session.refresh()`. El flush vive en
+    `BaseRepository.create / update`; el commit/rollback único por
+    request lo gestiona el lifecycle creado con
+    `fastapi_basekit.aio.sqlalchemy.make_session_lifecycle`.
+    """
 
     repository: BaseRepository
     search_fields: List[str] = []