fast-platform 0.12.2__py3-none-any.whl

admin/__init__.py

@@ -0,0 +1,31 @@
+"""
+fast_admin – CRUD API for admin resources (users, roles, audit log) for FastMVC.
+"""
+
+from .audit_hooks import (
+    AuditLogHook,
+    AuditTarget,
+    as_audit_hook,
+    audit_repository_hook,
+)
+from .crud import crud_router_from_model
+from .repositories import IAdminRoleRepository, IAdminUserRepository, IAuditLogRepository
+from .router import get_admin_router
+from .schemas import AdminRoleSummary, AdminUserSummary, AuditLogEntry
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "AdminUserSummary",
+    "AdminRoleSummary",
+    "AuditLogEntry",
+    "IAdminUserRepository",
+    "IAdminRoleRepository",
+    "IAuditLogRepository",
+    "get_admin_router",
+    "crud_router_from_model",
+    "AuditLogHook",
+    "AuditTarget",
+    "audit_repository_hook",
+    "as_audit_hook",
+]

admin/abstraction.py

@@ -0,0 +1,14 @@
+"""admin package abstractions."""
+
+from __future__ import annotations
+
+from abc import ABC
+
+
+class IAdmin(ABC):
+    """Marker base for concrete types in the ``admin`` package."""
+
+    __slots__ = ()
+
+
+__all__ = ["IAdmin"]

admin/abstractions.py

@@ -0,0 +1,24 @@
+"""
+Admin resource abstractions: users, roles, audit log.
+
+Prefer importing from :mod:`admin.schemas` and :mod:`admin.repositories`;
+this module re-exports the same names for backward compatibility.
+"""
+
+from __future__ import annotations
+
+from .repositories import (
+    IAdminRoleRepository,
+    IAdminUserRepository,
+    IAuditLogRepository,
+)
+from .schemas import AdminRoleSummary, AdminUserSummary, AuditLogEntry
+
+__all__ = [
+    "AdminRoleSummary",
+    "AdminUserSummary",
+    "AuditLogEntry",
+    "IAdminUserRepository",
+    "IAdminRoleRepository",
+    "IAuditLogRepository",
+]

admin/audit_hooks.py

@@ -0,0 +1,98 @@
+"""
+Optional audit hooks for CRUD and admin flows.
+
+Use :class:`AuditLogHook` with :func:`crud_router_from_model`, or wrap
+:class:`~fast_admin.repositories.IAuditLogRepository` with
+:func:`audit_repository_hook`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional, Protocol, Union, cast
+
+from .abstractions import IAuditLogRepository
+
+
+class AuditLogHook(Protocol):
+    """Async callback invoked after a successful create, update, or delete."""
+
+    async def __call__(
+        self,
+        *,
+        action: str,
+        resource_type: str,
+        resource_id: Optional[str],
+        details: Optional[dict[str, Any]],
+        request: Optional[Any] = None,
+    ) -> None: ...
+
+
+AuditTarget = Union[AuditLogHook, IAuditLogRepository, None]
+
+
+def audit_repository_hook(
+    repo: IAuditLogRepository,
+    *,
+    get_actor_id: Optional[Callable[[Any], Optional[str]]] = None,
+    get_ip_address: Optional[Callable[[Any], Optional[str]]] = None,
+    get_user_agent: Optional[Callable[[Any], Optional[str]]] = None,
+) -> AuditLogHook:
+    """
+    Wrap an :class:`~fast_admin.repositories.IAuditLogRepository` as an
+    :class:`AuditLogHook`, mapping ``request`` through optional extractors.
+    """
+
+    async def hook(
+        *,
+        action: str,
+        resource_type: str,
+        resource_id: Optional[str],
+        details: Optional[dict[str, Any]],
+        request: Optional[Any] = None,
+    ) -> None:
+        actor_id = get_actor_id(request) if get_actor_id and request else None
+        ip = get_ip_address(request) if get_ip_address and request else None
+        ua = get_user_agent(request) if get_user_agent and request else None
+        await repo.append(
+            action,
+            resource_type,
+            actor_id=actor_id,
+            resource_id=resource_id,
+            details=details,
+            ip_address=ip,
+            user_agent=ua,
+        )
+
+    return hook
+
+
+def as_audit_hook(
+    target: AuditTarget,
+    *,
+    get_actor_id: Optional[Callable[[Any], Optional[str]]] = None,
+    get_ip_address: Optional[Callable[[Any], Optional[str]]] = None,
+    get_user_agent: Optional[Callable[[Any], Optional[str]]] = None,
+) -> Optional[AuditLogHook]:
+    """
+    Normalize ``None``, a plain :class:`AuditLogHook`, or an
+    :class:`~fast_admin.repositories.IAuditLogRepository` into a single hook
+    (or ``None``).
+    """
+    if target is None:
+        return None
+    if isinstance(target, IAuditLogRepository):
+        return audit_repository_hook(
+            cast("IAuditLogRepository", target),
+            get_actor_id=get_actor_id,
+            get_ip_address=get_ip_address,
+            get_user_agent=get_user_agent,
+        )
+    return cast("AuditLogHook", target)
+
+
+__all__ = [
+    "AuditLogHook",
+    "AuditTarget",
+    "audit_repository_hook",
+    "as_audit_hook",
+]

admin/crud.py

@@ -0,0 +1,203 @@
+"""
+Generic FastAPI CRUD router from a SQLAlchemy 2.0 model and Pydantic v2 schemas.
+
+Requires SQLAlchemy (included with ``fast-platform``; install ``sqlalchemy`` if using a minimal env).
+
+Note: ``from __future__ import annotations`` is omitted so FastAPI can resolve
+dynamic ``create_schema`` / ``update_schema`` / ``read_schema`` types on routes.
+"""
+
+from typing import Any, Callable, Optional, Type
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
+from pydantic import BaseModel
+
+from .audit_hooks import AuditLogHook, AuditTarget, as_audit_hook
+
+
+def crud_router_from_model(
+    model: Any,
+    *,
+    create_schema: Type[BaseModel],
+    update_schema: Type[BaseModel],
+    read_schema: Type[BaseModel],
+    session_dep: Callable[..., Any],
+    resource_type: Optional[str] = None,
+    prefix: str = "",
+    tags: Optional[list[str]] = None,
+    audit: AuditTarget = None,
+    get_actor_id_from_request: Optional[Callable[[Request], Optional[str]]] = None,
+    get_ip_from_request: Optional[Callable[[Request], Optional[str]]] = None,
+    get_user_agent_from_request: Optional[Callable[[Request], Optional[str]]] = None,
+) -> APIRouter:
+    """
+    Build an ``APIRouter`` with list/create/read/update/delete for a single table.
+
+    **Requirements**
+
+    - Model must use a **single-column** primary key.
+    - ``read_schema`` should use ``model_config = ConfigDict(from_attributes=True)``
+      so ORM instances serialize correctly.
+    - ``create_schema`` / ``update_schema`` field names should match mapped
+      attribute names on the model (excluding the primary key on create if
+      auto-generated).
+
+    **Audit**
+
+    Pass ``audit`` as an :class:`~fast_admin.audit_hooks.AuditLogHook` or
+    :class:`~fast_admin.repositories.IAuditLogRepository`. Hooks run **after**
+    a successful create, update, or delete. Use ``get_*_from_request`` when
+    ``audit`` is a repository to populate actor / IP / user-agent.
+
+    **Session**
+
+    ``session_dep`` is used as ``Depends(session_dep)`` and must yield or return
+    a SQLAlchemy :class:`~sqlalchemy.orm.Session`.
+    """
+    try:
+        from sqlalchemy import inspect as sa_inspect
+        from sqlalchemy import select
+    except ImportError as e:  # pragma: no cover - exercised when sqlalchemy missing
+        raise RuntimeError(
+            "crud_router_from_model requires SQLAlchemy. Install: pip install sqlalchemy"
+        ) from e
+
+    mapper = sa_inspect(model).mapper
+    if len(mapper.primary_key) != 1:
+        raise ValueError("crud_router_from_model requires exactly one primary key column")
+
+    pk_col = mapper.primary_key[0]
+    pk_name = pk_col.key
+    pk_python = getattr(pk_col.type, "python_type", None)
+
+    rtype = resource_type or getattr(model, "__tablename__", model.__name__).lower()
+
+    def _parse_id(raw: str) -> Any:
+        if pk_python is int:
+            try:
+                return int(raw)
+            except ValueError as err:
+                raise HTTPException(
+                    status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="Invalid id"
+                ) from err
+        return raw
+
+    hook: Optional[AuditLogHook] = as_audit_hook(
+        audit,
+        get_actor_id=get_actor_id_from_request,
+        get_ip_address=get_ip_from_request,
+        get_user_agent=get_user_agent_from_request,
+    )
+
+    async def _audit(
+        *,
+        action: str,
+        resource_id: Optional[str],
+        details: Optional[dict[str, Any]],
+        request: Optional[Request],
+    ) -> None:
+        if hook is None:
+            return
+        await hook(
+            action=action,
+            resource_type=rtype,
+            resource_id=resource_id,
+            details=details,
+            request=request,
+        )
+
+    tag_list = tags if tags is not None else [rtype]
+    router = APIRouter(prefix=prefix, tags=tag_list)
+
+    @router.get("", response_model=list[read_schema])
+    async def list_items(
+        skip: int = Query(0, ge=0),
+        limit: int = Query(50, ge=1, le=500),
+        db: Any = Depends(session_dep),
+    ) -> list[BaseModel]:
+        rows = db.scalars(select(model).offset(skip).limit(limit)).all()
+        return [read_schema.model_validate(r) for r in rows]
+
+    @router.post("", response_model=read_schema, status_code=status.HTTP_201_CREATED)
+    async def create_item(
+        body: create_schema,
+        request: Request,
+        db: Any = Depends(session_dep),
+    ) -> BaseModel:
+        data = body.model_dump(exclude_unset=True)
+        if pk_name in data:
+            del data[pk_name]
+        obj = model(**data)
+        db.add(obj)
+        db.commit()
+        db.refresh(obj)
+        pk_val = getattr(obj, pk_name)
+        await _audit(
+            action="create",
+            resource_id=str(pk_val),
+            details={"payload": body.model_dump()},
+            request=request,
+        )
+        return read_schema.model_validate(obj)
+
+    @router.get("/{item_id}", response_model=read_schema)
+    async def get_item(
+        item_id: str,
+        db: Any = Depends(session_dep),
+    ) -> BaseModel:
+        pk = _parse_id(item_id)
+        obj = db.get(model, pk)
+        if obj is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not found")
+        return read_schema.model_validate(obj)
+
+    @router.patch("/{item_id}", response_model=read_schema)
+    async def update_item(
+        item_id: str,
+        body: update_schema,
+        request: Request,
+        db: Any = Depends(session_dep),
+    ) -> BaseModel:
+        pk = _parse_id(item_id)
+        obj = db.get(model, pk)
+        if obj is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not found")
+        patch = body.model_dump(exclude_unset=True)
+        before = {k: getattr(obj, k, None) for k in patch}
+        for k, v in patch.items():
+            setattr(obj, k, v)
+        db.commit()
+        db.refresh(obj)
+        await _audit(
+            action="update",
+            resource_id=str(pk),
+            details={"before": before, "after": patch},
+            request=request,
+        )
+        return read_schema.model_validate(obj)
+
+    @router.delete("/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
+    async def delete_item(
+        item_id: str,
+        request: Request,
+        db: Any = Depends(session_dep),
+    ) -> None:
+        pk = _parse_id(item_id)
+        obj = db.get(model, pk)
+        if obj is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not found")
+        snapshot = read_schema.model_validate(obj).model_dump()
+        db.delete(obj)
+        db.commit()
+        await _audit(
+            action="delete",
+            resource_id=str(pk),
+            details={"snapshot": snapshot},
+            request=request,
+        )
+        return None
+
+    return router
+
+
+__all__ = ["crud_router_from_model"]

admin/repositories.py

@@ -0,0 +1,105 @@
+"""
+Repository interfaces for admin users, roles, and audit log.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Optional
+
+from .abstraction import IAdmin
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+    from .schemas import AdminRoleSummary, AdminUserSummary, AuditLogEntry
+
+__all__ = [
+    "IAdminRoleRepository",
+    "IAdminUserRepository",
+    "IAuditLogRepository",
+]
+
+
+class IAdminUserRepository(IAdmin, ABC):
+    """Admin view over users (list, toggle active, assign roles)."""
+
+    @abstractmethod
+    async def list_users(
+        self,
+        *,
+        skip: int = 0,
+        limit: int = 50,
+        search: Optional[str] = None,
+        active_only: Optional[bool] = None,
+    ) -> list[AdminUserSummary]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_user(self, user_id: str) -> Optional[AdminUserSummary]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def set_user_active(self, user_id: str, is_active: bool) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def set_user_roles(self, user_id: str, role_ids: list[str]) -> None:
+        raise NotImplementedError
+
+
+class IAdminRoleRepository(IAdmin, ABC):
+    """Admin CRUD for roles."""
+
+    @abstractmethod
+    async def list_roles(self) -> list[AdminRoleSummary]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def get_role(self, role_id: str) -> Optional[AdminRoleSummary]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def create_role(self, name: str, permissions: list[str]) -> AdminRoleSummary:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def update_role(
+        self, role_id: str, name: Optional[str] = None, permissions: Optional[list[str]] = None
+    ) -> Optional[AdminRoleSummary]:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_role(self, role_id: str) -> None:
+        raise NotImplementedError
+
+
+class IAuditLogRepository(IAdmin, ABC):
+    """Append-only audit log for admin review."""
+
+    @abstractmethod
+    async def append(
+        self,
+        action: str,
+        resource_type: str,
+        *,
+        actor_id: Optional[str] = None,
+        resource_id: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+        ip_address: Optional[str] = None,
+        user_agent: Optional[str] = None,
+    ) -> AuditLogEntry:
+        raise NotImplementedError
+
+    @abstractmethod
+    async def list_entries(
+        self,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        actor_id: Optional[str] = None,
+        resource_type: Optional[str] = None,
+        resource_id: Optional[str] = None,
+        since: Optional[datetime] = None,
+    ) -> list[AuditLogEntry]:
+        raise NotImplementedError

admin/router.py

@@ -0,0 +1,98 @@
+"""
+Optional FastAPI router for admin API.
+
+Mount under /admin and protect with your auth (e.g. require admin role).
+"""
+
+from typing import Optional
+
+from fastapi import APIRouter, Query
+from pydantic import BaseModel
+
+from .repositories import IAdminRoleRepository, IAdminUserRepository, IAuditLogRepository
+from .schemas import AdminRoleSummary, AdminUserSummary, AuditLogEntry
+
+
+def get_admin_router(
+    user_repo: Optional[IAdminUserRepository] = None,
+    role_repo: Optional[IAdminRoleRepository] = None,
+    audit_repo: Optional[IAuditLogRepository] = None,
+    prefix: str = "/admin",
+) -> APIRouter:
+    """
+    Build an admin API router. Pass repos for the sections you want to expose.
+    """
+    router = APIRouter(prefix=prefix, tags=["admin"])
+
+    if user_repo is not None:
+
+        @router.get("/users", response_model=list[AdminUserSummary])
+        async def list_users(
+            skip: int = Query(0, ge=0),
+            limit: int = Query(50, ge=1, le=100),
+            search: Optional[str] = None,
+            active_only: Optional[bool] = None,
+        ) -> list[AdminUserSummary]:
+            return await user_repo.list_users(
+                skip=skip, limit=limit, search=search, active_only=active_only
+            )
+
+        @router.get("/users/{user_id}", response_model=AdminUserSummary)
+        async def get_user(user_id: str) -> AdminUserSummary:
+            u = await user_repo.get_user(user_id)
+            if u is None:
+                from fastapi import HTTPException
+
+                raise HTTPException(404, "User not found")
+            return u
+
+        class ActiveBody(BaseModel):
+            is_active: bool
+
+        @router.patch("/users/{user_id}/active")
+        async def set_user_active(user_id: str, body: ActiveBody) -> dict[str, bool]:
+            await user_repo.set_user_active(user_id, body.is_active)
+            return {"ok": True}
+
+        class RolesBody(BaseModel):
+            role_ids: list[str] = []
+
+        @router.put("/users/{user_id}/roles")
+        async def set_user_roles(user_id: str, body: RolesBody) -> dict[str, bool]:
+            await user_repo.set_user_roles(user_id, body.role_ids)
+            return {"ok": True}
+
+    if role_repo is not None:
+
+        @router.get("/roles", response_model=list[AdminRoleSummary])
+        async def list_roles() -> list[AdminRoleSummary]:
+            return await role_repo.list_roles()
+
+        @router.get("/roles/{role_id}", response_model=AdminRoleSummary)
+        async def get_role(role_id: str) -> AdminRoleSummary:
+            r = await role_repo.get_role(role_id)
+            if r is None:
+                from fastapi import HTTPException
+
+                raise HTTPException(404, "Role not found")
+            return r
+
+    if audit_repo is not None:
+
+        @router.get("/audit", response_model=list[AuditLogEntry])
+        async def list_audit(
+            skip: int = Query(0, ge=0),
+            limit: int = Query(100, ge=1, le=500),
+            actor_id: Optional[str] = None,
+            resource_type: Optional[str] = None,
+            resource_id: Optional[str] = None,
+        ) -> list[AuditLogEntry]:
+            return await audit_repo.list_entries(
+                skip=skip,
+                limit=limit,
+                actor_id=actor_id,
+                resource_type=resource_type,
+                resource_id=resource_id,
+            )
+
+    return router

admin/schemas.py

@@ -0,0 +1,49 @@
+"""
+Pydantic DTOs for the admin API (users, roles, audit log).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime  # noqa: TC003
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+__all__ = [
+    "AdminRoleSummary",
+    "AdminUserSummary",
+    "AuditLogEntry",
+]
+
+
+class AdminUserSummary(BaseModel):
+    """Summary of a user for admin listing."""
+
+    id: str
+    email: str
+    is_active: bool
+    created_at: datetime
+    roles: list[str] = []
+
+
+class AdminRoleSummary(BaseModel):
+    """Summary of a role for admin listing."""
+
+    id: str
+    name: str
+    permissions: list[str] = []
+
+
+class AuditLogEntry(BaseModel):
+    """Single audit log entry."""
+
+    id: str
+    actor_id: Optional[str] = None
+    actor_type: str = "user"
+    action: str
+    resource_type: str
+    resource_id: Optional[str] = None
+    details: dict[str, Any] = {}
+    ip_address: Optional[str] = None
+    user_agent: Optional[str] = None
+    created_at: datetime

analytics/__init__.py

@@ -0,0 +1,31 @@
+"""
+fast_analytics – Analytics and event tracking for FastMVC.
+"""
+
+from fast_platform import AnalyticsConfiguration, AnalyticsConfigurationDTO
+
+from .base import IAnalyticsBackend, build_analytics_client
+from .buffer import BufferedAnalyticsBackend
+from .middleware import AnalyticsSamplingMiddleware, default_analytics_user_key
+from .pii import ScrubbingAnalyticsBackend, scrub_pii_properties
+from .rate_limit import RateLimitedAnalyticsBackend
+from .schema_registry import EventSchemaRegistry, parse_versioned_event_name
+from .validating_backend import ValidatingAnalyticsBackend
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "AnalyticsSamplingMiddleware",
+    "BufferedAnalyticsBackend",
+    "EventSchemaRegistry",
+    "IAnalyticsBackend",
+    "RateLimitedAnalyticsBackend",
+    "ScrubbingAnalyticsBackend",
+    "ValidatingAnalyticsBackend",
+    "AnalyticsConfiguration",
+    "AnalyticsConfigurationDTO",
+    "build_analytics_client",
+    "default_analytics_user_key",
+    "parse_versioned_event_name",
+    "scrub_pii_properties",
+]

analytics/abstraction.py

@@ -0,0 +1,14 @@
+"""analytics package abstractions."""
+
+from __future__ import annotations
+
+from abc import ABC
+
+
+class IAnalytics(ABC):
+    """Marker base for concrete types in the ``analytics`` package."""
+
+    __slots__ = ()
+
+
+__all__ = ["IAnalytics"]