fastapi-basekit 0.1.0__py3-none-any.whl

fastapi_basekit/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import version, PackageNotFoundError
+
+__all__ = ["aio", "exceptions", "schema", "servicios"]
+
+try:
+    __version__ = version("fastapi-basekit")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev0"

fastapi_basekit/aio/__init__.py

@@ -0,0 +1 @@
+__all__ = ["controller", "beanie", "sqlalchemy"]

fastapi_basekit/aio/beanie/__init__.py

@@ -0,0 +1,6 @@
+__all__ = ["repository", "service"]
+from .controller.base import BeanieBaseController
+
+__all__ = [
+    "BeanieBaseController",
+]

fastapi_basekit/aio/beanie/controller/base.py

@@ -0,0 +1,21 @@
+from typing import ClassVar, Type
+
+from fastapi import Depends
+from pydantic import BaseModel
+
+from ...controller.base import BaseController
+from ..service.base import BaseService
+
+
+class BeanieBaseController(BaseController):
+    """BaseController para Beanie ODM (async).
+
+    Hereda el comportamiento del controlador base y conecta con
+    `Beanie` a través de su `BaseService` sin requerir `db` explícito.
+    """
+
+    service: BaseService = Depends()
+    schema_class: ClassVar[Type[BaseModel]]
+
+    # No es necesario sobreescribir métodos CRUD; el base usa
+    # `self.service` con la firma de Beanie (sin `db`).

fastapi_basekit/aio/beanie/repository/__init__.py

@@ -0,0 +1 @@
+

fastapi_basekit/aio/beanie/repository/base.py

@@ -0,0 +1,129 @@
+from typing import Any, Dict, List, Optional, Type, Union
+
+from bson import ObjectId
+from pydantic import BaseModel
+from beanie import Document
+from beanie.odm.queries.find import FindMany
+from beanie.operators import Or, RegEx
+
+
+class BaseRepository:
+    model: Type[Document]
+
+    def _get_query_kwargs(
+        self,
+        fetch_links: bool = False,
+        nesting_depths_per_field: Optional[Dict[str, int]] = None,
+        projection: Optional[Union[List[str], Type[BaseModel]]] = None,
+    ):
+        kwargs = {
+            "fetch_links": fetch_links,
+            "nesting_depths_per_field": (
+                nesting_depths_per_field if fetch_links else None
+            ),
+        }
+        if projection is not None:
+            kwargs["projection"] = projection
+        return kwargs
+
+    def build_filter_query(
+        self,
+        search: Optional[str],
+        search_fields: List[str],
+        filters: dict = None,
+        **kwargs,
+    ) -> FindMany[Document]:
+        exprs = []
+
+        if search and search_fields:
+            exprs.append(
+                Or(
+                    *[
+                        RegEx(
+                            getattr(self.model, f),
+                            f".*{search}.*",
+                            options="i",
+                        )
+                        for f in search_fields
+                    ]
+                )
+            )
+
+        for k, v in (filters or {}).items():
+            if hasattr(self.model, k):
+                exprs.append(getattr(self.model, k) == v)
+
+        query = self.model.find(*exprs, **self._get_query_kwargs(**kwargs))
+        return query
+
+    async def paginate(
+        self, query: FindMany[Document], page: int, count: int
+    ) -> tuple[List[Document], int]:
+        total = await query.count()
+        items = await query.skip(count * (page - 1)).limit(count).to_list()
+        return items, total
+
+    async def get_by_id(
+        self,
+        obj_id: Union[str, ObjectId],
+        **kwargs,
+    ) -> Optional[Document]:
+        if not isinstance(obj_id, ObjectId):
+            obj_id = ObjectId(obj_id)
+        return await self.model.find_one(
+            self.model.id == obj_id,
+            **self._get_query_kwargs(**kwargs),
+        )
+
+    async def get_by_field(
+        self,
+        field_name: str,
+        value: Any,
+        **kwargs,
+    ) -> Optional[Document]:
+        if not hasattr(self.model, field_name):
+            raise AttributeError(
+                f"{self.model.__name__} no tiene el campo '{field_name}'"
+            )
+        return await self.model.find_one(
+            getattr(self.model, field_name) == value,
+            **self._get_query_kwargs(**kwargs),
+        )
+
+    async def get_by_fields(
+        self,
+        filters: Dict[str, Any],
+        **kwargs,
+    ) -> Optional[Document]:
+        exprs = [
+            getattr(self.model, f) == v
+            for f, v in filters.items()
+            if hasattr(self.model, f)
+        ]
+        if not exprs:
+            return None
+        return await self.model.find_one(
+            *exprs, **self._get_query_kwargs(**kwargs)
+        )
+
+    async def list_all(
+        self,
+        **kwargs,
+    ) -> List[Document]:
+        query = self.model.find_all(**self._get_query_kwargs(**kwargs))
+        return await query.to_list()
+
+    async def create(self, obj: Union[Document, Dict[str, Any]]) -> Document:
+        if isinstance(obj, dict):
+            obj = self.model(**obj)
+        await obj.insert()
+        return obj
+
+    async def update(self, obj: Document, data: Dict[str, Any]) -> Document:
+        for key, value in data.items():
+            setattr(obj, key, value)
+        await obj.save()
+        return obj
+
+    async def delete(self, obj: Document) -> None:
+        await obj.delete()

fastapi_basekit/aio/beanie/service/base.py

@@ -0,0 +1,115 @@
+from typing import Any, Dict, List, Optional, Union
+
+from fastapi import Request
+from pydantic import BaseModel
+
+
+from ...beanie.repository.base import BaseRepository
+from ....exceptions.api_exceptions import (
+    NotFoundException,
+    DatabaseIntegrityException,
+)
+
+
+class BaseService:
+    """Servicio base específico para Beanie ODM (async)."""
+
+    repository: BaseRepository
+    search_fields: List[str] = []
+    duplicate_check_fields: List[str] = []
+    kwargs_query: Dict[str, Union[str, int]] = {}
+    action: str = ""
+
+    def __init__(
+        self, repository: BaseRepository, request: Optional[Request] = None
+    ):
+        self.repository = repository
+        self.request = request
+        endpoint_func = (
+            self.request.scope.get("endpoint") if self.request else None
+        )
+        self.action = endpoint_func.__name__ if endpoint_func else None
+
+    async def _check_duplicate(self, data: Dict[str, Any], fields: List[str]):
+        filters = {f: data[f] for f in fields if f in data}
+        if not filters:
+            return
+
+        existing = await self.repository.get_by_fields(filters)
+        if existing:
+            raise DatabaseIntegrityException(
+                message="Registro ya existe",
+                data=filters,
+            )
+
+    def get_kwargs_query(self) -> Dict[str, Any]:
+        return self.kwargs_query
+
+    def get_filters(
+        self,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        filters = filters or {}
+        return filters
+
+    async def retrieve(self, id: str):
+        kwargs = self.get_kwargs_query()
+        obj = await self.repository.get_by_id(id, **kwargs)
+        if not obj:
+            raise NotFoundException(f"id={id} no encontrado")
+        return obj
+
+    async def list(
+        self,
+        search: Optional[str] = None,
+        page: int = 1,
+        count: int = 25,
+        filters: Optional[Dict[str, Any]] = None,
+    ):
+        kwargs = self.get_kwargs_query()
+        applied_filters = self.get_filters(filters)
+        query = self.repository.build_filter_query(
+            search=search,
+            search_fields=self.search_fields,
+            filters=applied_filters,
+            **kwargs,
+        )
+        return await self.repository.paginate(query, page, count)
+
+    async def create(
+        self, payload: BaseModel, check_fields: Optional[List[str]] = None
+    ) -> Any:
+        data = (
+            payload.model_dump() if not isinstance(payload, dict) else payload
+        )
+        fields = (
+            check_fields
+            if check_fields is not None
+            else self.duplicate_check_fields
+        )
+        if fields:
+            await self._check_duplicate(data, fields)
+        created = await self.repository.create(data)
+        kwargs = self.get_kwargs_query()
+        return (
+            await self.repository.get_by_id(created.id, **kwargs)
+            if kwargs
+            else created
+        )
+
+    async def update(self, id: str, data: BaseModel) -> Any:
+        kwargs = self.get_kwargs_query()
+        obj = await self.repository.get_by_id(id, **kwargs)
+        if not obj:
+            raise NotFoundException(f"id={id} no encontrado")
+        if isinstance(data, BaseModel):
+            data = data.model_dump(exclude_unset=True)
+        updated = await self.repository.update(obj, data)
+        return updated
+
+    async def delete(self, id: str) -> str:
+        obj = await self.repository.get_by_id(id)
+        if not obj:
+            raise NotFoundException(f"id={id} no encontrado")
+        await self.repository.delete(obj)
+        return "deleted"

fastapi_basekit/aio/controller/base.py

@@ -0,0 +1,131 @@
+from typing import Any, ClassVar, Dict, List, Optional, Type
+from fastapi import Depends, Request
+from pydantic import BaseModel, TypeAdapter
+
+from ..permissions.base import BasePermission
+
+from ...schema.base import BasePaginationResponse, BaseResponse
+from ...exceptions.api_exceptions import PermissionException
+
+
+class BaseController:
+    """Montar rutas CRUD genericas y captura errores de negocio."""
+
+    service = Depends()
+    schema_class: ClassVar[Type[BaseModel]]
+    action: ClassVar[Optional[str]] = None
+    request: Request
+
+    def __init__(self) -> None:
+        endpoint_func = (
+            self.request.scope.get("endpoint") if self.request else None
+        )
+        self.action = endpoint_func.__name__ if endpoint_func else None
+
+    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."
+            % 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):
+        params = self._params()
+        items, total = await self.service.list(**params)
+        pagination = {
+            "page": params.get("page"),
+            "count": params.get("count"),
+            "total": total,
+        }
+        return self.format_response(data=items, pagination=pagination)
+
+    async def retrieve(self, id: str):
+        item = await self.service.retrieve(id)
+        return self.format_response(data=item)
+
+    async def create(self, validated_data: Any):
+        result = await self.service.create(validated_data)
+        return self.format_response(result, message="Creado exitosamente")
+
+    async def update(self, id: str, validated_data: Any):
+        result = await self.service.update(id, validated_data)
+        return self.format_response(result, message="Actualizado exitosamente")
+
+    async def delete(self, id: str):
+        await self.service.delete(id)
+        return self.format_response(None, message="Eliminado exitosamente")
+
+    def format_response(
+        self,
+        data: Any,
+        pagination: Optional[Dict[str, Any]] = None,
+        message: Optional[str] = None,
+        status: str = "success",
+    ) -> BaseModel:
+        schema = self.get_schema_class()
+
+        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)
+        elif isinstance(data, dict):
+            data_parsed = schema.model_validate(data)
+        else:
+            data_parsed = data
+
+        if pagination:
+            return BasePaginationResponse(
+                data=data_parsed,
+                pagination=pagination,
+                message=message or "Operación exitosa",
+                status=status,
+            )
+        else:
+            return BaseResponse(
+                data=data_parsed,
+                message=message or "Operación exitosa",
+                status=status,
+            )
+
+    def _params(self) -> Dict[str, Any]:
+        query_params = self.request.query_params if self.request else {}
+
+        page = int(query_params.get("page", 1))
+        count = int(query_params.get("count", 10))
+        search = query_params.get("search")
+
+        filters = {
+            k: v
+            for k, v in query_params.items()
+            if k not in ["page", "count", "search"]
+        }
+
+        return {
+            "page": page,
+            "count": count,
+            "search": search,
+            "filters": filters,
+        }
+
+    def to_dict(self, obj: Any):
+        if hasattr(obj, "model_dump"):
+            return obj.model_dump()
+        return obj

fastapi_basekit/aio/permissions/base.py

@@ -0,0 +1,10 @@
+from fastapi import Request
+
+
+class BasePermission:
+    message_exception: str = "Permiso denegado"
+    """Clase base de permisos, para extender según lógica."""
+
+    async def has_permission(self, request: Request) -> bool:
+        """Sobreescribir con la lógica de permiso."""
+        return True

fastapi_basekit/aio/sqlalchemy/__init__.py

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

fastapi_basekit/aio/sqlalchemy/controller/base.py

@@ -0,0 +1,68 @@
+from typing import Any, ClassVar, List, Optional, Type
+
+from fastapi import Depends
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ...controller.base import BaseController
+from ..service.base import BaseService
+
+
+class SQLAlchemyBaseController(BaseController):
+    """BaseController para SQLAlchemy (AsyncSession).
+
+    - Acepta `db: AsyncSession` en operaciones CRUD.
+    - Construye y pasa parámetros específicos (joins, order_by, use_or).
+    """
+
+    service: BaseService = Depends()
+    schema_class: ClassVar[Type[BaseModel]]
+
+    async def list(
+        self,
+        db: AsyncSession,
+        *,
+        use_or: bool = False,
+        joins: Optional[List[str]] = None,
+        order_by: Optional[Any] = None,
+    ):
+        params = self._params()
+        service_params = {
+            "page": params.get("page"),
+            "count": params.get("count"),
+            "filters": params.get("filters"),
+            "use_or": use_or,
+            "joins": joins,
+            "order_by": order_by,
+        }
+        items, total = await self.service.list(db, **service_params)
+        pagination = {
+            "page": params.get("page"),
+            "count": params.get("count"),
+            "total": total,
+        }
+        return self.format_response(data=items, pagination=pagination)
+
+    async def retrieve(
+        self, db: AsyncSession, id: str, *, joins: Optional[List[str]] = None
+    ):
+        item = await self.service.retrieve(db, id, joins=joins)
+        return self.format_response(data=item)
+
+    async def create(
+        self,
+        db: AsyncSession,
+        validated_data: Any,
+        *,
+        check_fields: Optional[List[str]] = None,
+    ):
+        result = await self.service.create(db, validated_data, check_fields)
+        return self.format_response(result, message="Creado exitosamente")
+
+    async def update(self, db: AsyncSession, id: str, validated_data: Any):
+        result = await self.service.update(db, id, validated_data)
+        return self.format_response(result, message="Actualizado exitosamente")
+
+    async def delete(self, db: AsyncSession, id: str):
+        await self.service.delete(db, id)
+        return self.format_response(None, message="Eliminado exitosamente")

fastapi_basekit/aio/sqlalchemy/repository/__init__.py

@@ -0,0 +1 @@
+