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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastapi-basekit
-Version: 0.3.2
+Version: 0.4.0
 Summary: Utilities and base classes for FastAPI async projects (Beanie, SQLAlchemy or SQLModel)
 Author-email: Jerson Moreno <jerson.ml820@hotmail.com>
 License: MIT
@@ -105,13 +105,25 @@ Abre http://localhost:8000/docs. Login con `admin@example.com` / `ChangeMe2026!`
 
 ## Como plugin de Claude Code
 
+Dentro de Claude Code (terminal) corre:
+
 ```bash
-/plugin marketplace add https://github.com/mundobien2025/fastapi-basekit
-/plugin install fastapi-basekit
-/plugin list
+/plugin marketplace add mundobien2025/fastapi-basekit
+/plugin install fastapi-basekit@fastapi-basekit
+/plugin list                                       # verifica instalación
 ```
 
-Luego pide: *"Crea el recurso `Invoice` con CRUD completo"* — Claude usa la skill automáticamente.
+Eso registra el marketplace `fastapi-basekit` desde el repo de GitHub e
+instala el plugin (que incluye la skill `fastapi-basekit-crud`). Luego
+pide: *"Crea el recurso `Invoice` con CRUD completo siguiendo
+fastapi-basekit"* — Claude detecta la skill y aplica el patrón canónico
+(model → repo → service → schema → controller con `@cbv`).
+
+Para actualizar a una versión nueva:
+
+```bash
+/plugin update fastapi-basekit@fastapi-basekit
+```
 
 ## Instalación por ORM
 
@@ -127,8 +139,6 @@ pip install fastapi-basekit[all]          # todo
 
 PRs bienvenidos. Setup local en [docs/contributing](https://mundobien2025.github.io/fastapi-basekit/contributing).
 
-Mantenedores: [`RELEASING.md`](./RELEASING.md) tiene release flow, CI/CD, mike y troubleshooting.
-
 ## Licencia
 
 [MIT](./LICENSE) — © Jerson Moreno

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

@@ -59,13 +59,25 @@ Abre http://localhost:8000/docs. Login con `admin@example.com` / `ChangeMe2026!`
 
 ## Como plugin de Claude Code
 
+Dentro de Claude Code (terminal) corre:
+
 ```bash
-/plugin marketplace add https://github.com/mundobien2025/fastapi-basekit
-/plugin install fastapi-basekit
-/plugin list
+/plugin marketplace add mundobien2025/fastapi-basekit
+/plugin install fastapi-basekit@fastapi-basekit
+/plugin list                                       # verifica instalación
 ```
 
-Luego pide: *"Crea el recurso `Invoice` con CRUD completo"* — Claude usa la skill automáticamente.
+Eso registra el marketplace `fastapi-basekit` desde el repo de GitHub e
+instala el plugin (que incluye la skill `fastapi-basekit-crud`). Luego
+pide: *"Crea el recurso `Invoice` con CRUD completo siguiendo
+fastapi-basekit"* — Claude detecta la skill y aplica el patrón canónico
+(model → repo → service → schema → controller con `@cbv`).
+
+Para actualizar a una versión nueva:
+
+```bash
+/plugin update fastapi-basekit@fastapi-basekit
+```
 
 ## Instalación por ORM
 
@@ -81,8 +93,6 @@ pip install fastapi-basekit[all]          # todo
 
 PRs bienvenidos. Setup local en [docs/contributing](https://mundobien2025.github.io/fastapi-basekit/contributing).
 
-Mantenedores: [`RELEASING.md`](./RELEASING.md) tiene release flow, CI/CD, mike y troubleshooting.
-
 ## Licencia
 
 [MIT](./LICENSE) — © Jerson Moreno

{fastapi_basekit-0.3.2 → fastapi_basekit-0.4.0}/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.2 → fastapi_basekit-0.4.0}/fastapi_basekit/aio/controller/base.py

@@ -14,6 +14,14 @@ class BaseController:
 
     service = Depends()
     schema_class: ClassVar[Type[BaseModel]]
+
+    # DRF Style: Permisos globales por defecto
+    permission_classes: ClassVar[List[Type[BasePermission]]] = []
+
+    # ClassVar so cbv (fastapi-restful) does NOT promote it to a query param.
+    # A plain `Optional[str]` annotation here leaks a spurious `action` query
+    # parameter onto every mounted endpoint. `prepare_action` still assigns
+    # `self.action` (instance attr) at runtime, which works fine.
     action: ClassVar[Optional[str]] = None
     request: Request
     _params_excluded_fields: ClassVar[Set[str]] = {
@@ -22,6 +30,7 @@ class BaseController:
         "count",
         "search",
         "order_by",
+        "action",
         "__class__",
         "args",
         "kwargs",
@@ -32,34 +41,84 @@ 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
+        # Propagate the canonical CRUD action ("list"/"retrieve"/...) to the
+        # service so `get_kwargs_query` / `get_filters` can branch on it. The
+        # service's own constructor derives `action` from the endpoint
+        # function name (e.g. "list_users"), which is unreliable for that
+        # purpose; the controller knows the canonical action.
+        service = getattr(self, "service", None)
+        if service is not None:
+            try:
+                service.action = action_name
+            except Exception:
+                pass
+        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 +134,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 +162,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]:
         """
@@ -195,7 +273,10 @@ class BaseController:
                 search = final_value
             elif param_name == "order_by":
                 order_by = final_value
-            elif param_name not in standard_params:
+            elif (
+                param_name not in standard_params
+                and param_name not in self._params_excluded_fields
+            ):
                 # Es un filtro
                 filters[param_name] = final_value
 
@@ -208,6 +289,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.2 → fastapi_basekit-0.4.0}/fastapi_basekit/aio/sqlalchemy/controller/base.py

@@ -24,6 +24,7 @@ class SQLAlchemyBaseController(BaseController):
         "use_or",
         "joins",
         "order_by",
+        "action",
         "__class__",
         "args",
         "kwargs",
@@ -48,6 +49,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 +75,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 +92,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")
 

{fastapi_basekit-0.3.2 → fastapi_basekit-0.4.0}/fastapi_basekit/aio/sqlalchemy/repository/base.py

@@ -131,7 +131,13 @@ class BaseRepository:
         joins_to_apply = {}
 
         for filter_path, value in filters.items():
-            attr, field_joins = self._resolve_field_path(filter_path)
+            # Detect an optional trailing operator suffix (e.g.
+            # "age__gte", "created_at__lte", "name__ilike", "id__in").
+            # The remaining path is resolved normally, so relationship
+            # traversal ("user__role__code") keeps working — only a final
+            # token that matches a known operator is treated as one.
+            resolve_path, op = self._split_operator(filter_path)
+            attr, field_joins = self._resolve_field_path(resolve_path)
 
             if attr is None:
                 continue
@@ -156,10 +162,53 @@ class BaseRepository:
             )
 
             if not is_relationship and is_column:
-                resolved_filters[filter_path] = (attr, processed_value)
+                resolved_filters[filter_path] = (attr, processed_value, op)
 
         return resolved_filters, joins_to_apply
 
+    # Operadores de filtro soportados como sufijo "campo__op".
+    FILTER_OPERATORS = frozenset(
+        {"eq", "ne", "gt", "gte", "lt", "lte", "in", "like", "ilike"}
+    )
+
+    def _split_operator(self, filter_path: str) -> Tuple[str, str]:
+        """Separa un sufijo de operador del path de filtro.
+
+        "age__gte" → ("age", "gte"); "user__role__code" → (..., "eq").
+        Solo se interpreta como operador si el último token coincide con
+        ``FILTER_OPERATORS`` y queda al menos un token de campo delante.
+        """
+        if "__" in filter_path:
+            head, _, last = filter_path.rpartition("__")
+            if head and last in self.FILTER_OPERATORS:
+                return head, last
+        return filter_path, "eq"
+
+    @staticmethod
+    def _condition_for(field: Any, value: Any, op: str) -> Any:
+        """Construye la condición SQLAlchemy para un operador dado."""
+        if op == "ne":
+            return field != value
+        if op == "gt":
+            return field > value
+        if op == "gte":
+            return field >= value
+        if op == "lt":
+            return field < value
+        if op == "lte":
+            return field <= value
+        if op == "in":
+            seq = value if isinstance(value, (list, tuple, set)) else [value]
+            return field.in_(list(seq))
+        if op == "like":
+            return field.like(f"%{value}%")
+        if op == "ilike":
+            return field.ilike(f"%{value}%")
+        # op == "eq" (default): conserva la semántica IN para listas.
+        if isinstance(value, (list, tuple)) and not isinstance(value, str):
+            return field.in_(value)
+        return field == value
+
     def _resolve_order_by(
         self,
         order_by: Optional[Any] = None,
@@ -292,14 +341,13 @@ class BaseRepository:
 
         # Modo avanzado: usar resolved_filters si está disponible
         if resolved_filters is not None:
-            for _, (field, processed_value) in resolved_filters.items():
-                # Aplicar la lógica de IN o ==
-                if isinstance(
-                    processed_value, (list, tuple)
-                ) and not isinstance(processed_value, str):
-                    conditions.append(field.in_(processed_value))
-                else:
-                    conditions.append(field == processed_value)
+            for _, resolved in resolved_filters.items():
+                # Tupla (field, value) legacy o (field, value, op) con operador.
+                field, processed_value = resolved[0], resolved[1]
+                op = resolved[2] if len(resolved) > 2 else "eq"
+                conditions.append(
+                    self._condition_for(field, processed_value, op)
+                )
         # Modo legacy: compatibilidad con código existente
         elif filters is not None:
             for fn, value in filters.items():
@@ -442,8 +490,10 @@ class BaseRepository:
             if not resolved_filters:
                 return None
 
-            # Obtener el atributo resuelto
-            _, (field, processed_value) = next(iter(resolved_filters.items()))
+            # Obtener el atributo resuelto (puede traer operador como 3er elem)
+            _, resolved = next(iter(resolved_filters.items()))
+            field, processed_value = resolved[0], resolved[1]
+            op = resolved[2] if len(resolved) > 2 else "eq"
 
             # Construir query con JOINs de filtrado
             query = select(self.model)
@@ -453,7 +503,7 @@ class BaseRepository:
                 query = query.join(relation_attr)
 
             # Aplicar condición
-            query = query.where(field == processed_value)
+            query = query.where(self._condition_for(field, processed_value, op))
 
             # Aplicar joins de carga
             query = self._apply_joins(query, joins)

{fastapi_basekit-0.3.2 → fastapi_basekit-0.4.0}/fastapi_basekit/aio/sqlmodel/controller/base.py

@@ -49,6 +49,7 @@ class SQLModelBaseController(BaseController):
             joins: Lista de relaciones para eager loading.
             order_by: Expresión de ordenamiento (ej: ``"-created_at"``).
         """
+        await self.prepare_action("list")
         params = self._params(skip_frames=2)
         service_params = {
             **params,
@@ -73,6 +74,7 @@ class SQLModelBaseController(BaseController):
             id: ID del registro.
             joins: Lista de relaciones para eager loading.
         """
+        await self.prepare_action("retrieve")
         item = await self.service.retrieve(id, joins=joins)
         return self.format_response(data=item)
 
@@ -88,6 +90,7 @@ class SQLModelBaseController(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")
 

fastapi_basekit-0.4.0/fastapi_basekit/exceptions/__init__.py

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

{fastapi_basekit-0.3.2 → fastapi_basekit-0.4.0}/fastapi_basekit/exceptions/handler.py

@@ -109,3 +109,89 @@ async def value_exception_handler(
         status_code=status.HTTP_400_BAD_REQUEST,
         content=response.model_dump(mode="json"),
     )
+
+
+async def request_validation_handler(
+    request: Request, exc: RequestValidationError
+):
+    """FastAPI request validation → envelope unificado (no relanza).
+
+    Equivalente a `validation_exception_handler` pero devuelve la respuesta
+    directamente, sin depender de que otro handler capture la excepción
+    relanzada. Cuerpo idéntico al que produciría `ValidationException`.
+    """
+    response = BaseResponse(
+        status="VALIDATION_ERROR",
+        message="Error de validación",
+        data=exc.errors(),
+    )
+    return JSONResponse(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        content=response.model_dump(mode="json"),
+    )
+
+
+async def integrity_error_handler(request: Request, exc: Exception):
+    """SQLAlchemy IntegrityError → envelope de integridad (HTTP 400)."""
+    detail = getattr(exc, "orig", None)
+    response = BaseResponse(
+        status="DATABASE_INTEGRITY_ERROR",
+        message="Registro ya existe o viola una restricción de integridad",
+        data={"detail": str(detail) if detail is not None else str(exc)},
+    )
+    return JSONResponse(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        content=response.model_dump(mode="json"),
+    )
+
+
+def register_exception_handlers(
+    app,
+    *,
+    sqlalchemy: bool = True,
+    mongo: bool = True,
+) -> None:
+    """Registra el conjunto completo de handlers sobre una app FastAPI.
+
+    Un solo punto de cableado para que cada proyecto NO copie-pegue el
+    mapeo de excepciones → ``BaseResponse``. Todas las subclases de
+    ``APIException`` (NotFound, Permission, JWT, Validation, Integrity,
+    Global...) las atiende ``api_exception_handler`` vía resolución por MRO.
+
+    Args:
+        app: instancia FastAPI.
+        sqlalchemy: registra el handler de ``IntegrityError`` (requiere
+            SQLAlchemy instalado).
+        mongo: registra handlers de Mongo/Beanie si están disponibles.
+    """
+    app.add_exception_handler(APIException, api_exception_handler)
+    app.add_exception_handler(
+        RequestValidationError, request_validation_handler
+    )
+    app.add_exception_handler(ValidationError, value_exception_handler)
+    app.add_exception_handler(ValueError, value_exception_handler)
+
+    if sqlalchemy:
+        try:  # pragma: no cover - dependencia opcional
+            from sqlalchemy.exc import IntegrityError
+
+            app.add_exception_handler(
+                IntegrityError, integrity_error_handler
+            )
+        except ImportError:
+            pass
+
+    if mongo:
+        # Solo registra si las clases reales (no los fallbacks) existen.
+        if DuplicateKeyError.__module__ != __name__:
+            app.add_exception_handler(
+                DuplicateKeyError, duplicate_key_exception_handler
+            )
+        if DocumentNotFound.__module__ != __name__:
+            app.add_exception_handler(
+                DocumentNotFound, document_not_found_handler
+            )
+
+    # Catch-all al final; las subclases de APIException ya tienen prioridad
+    # por especificidad de tipo.
+    app.add_exception_handler(Exception, global_exception_handler)