fastapi-admin-kit 0.1.0__py3-none-any.whl

fastapi_admin_kit/api/roles.py

@@ -0,0 +1,128 @@
+"""API endpoints for role management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel
+from sqlalchemy import select
+
+from fastapi_admin_kit.api.deps import require_api_superuser
+from fastapi_admin_kit.auth.models import AdminRole
+from fastapi_admin_kit.db import get_db_session
+
+router = APIRouter(prefix="/roles", tags=["api-roles"])
+
+
+class RoleCreate(BaseModel):
+    name: str
+    description: str = ""
+
+
+class RoleUpdate(BaseModel):
+    name: str | None = None
+    description: str | None = None
+
+
+class RoleResponse(BaseModel):
+    id: int
+    name: str
+    description: str | None = None
+    user_count: int = 0
+
+
+@router.get("/", response_model=list[RoleResponse])
+async def list_roles(
+    request: Request,
+    user: dict[str, Any] = Depends(require_api_superuser()),
+) -> list[RoleResponse]:
+    """GET /api/roles/ — list all roles (superuser only)."""
+    db_session = get_db_session(request)
+    result = await db_session.execute(select(AdminRole))
+    roles = result.scalars().all()
+    return [
+        RoleResponse(
+            id=r.id,
+            name=r.name,
+            description=r.description,
+            user_count=len(r.users),
+        )
+        for r in roles
+    ]
+
+
+@router.post("/", response_model=RoleResponse, status_code=201)
+async def create_role(
+    request: Request,
+    body: RoleCreate,
+    user: dict[str, Any] = Depends(require_api_superuser()),
+) -> RoleResponse:
+    """POST /api/roles/ — create a role (superuser only)."""
+    db_session = get_db_session(request)
+
+    existing = await db_session.execute(
+        select(AdminRole).where(AdminRole.name == body.name)
+    )
+    if existing.scalar_one_or_none():
+        raise HTTPException(status_code=400, detail="Role name already exists.")
+
+    role = AdminRole(name=body.name, description=body.description)
+    db_session.add(role)
+    await db_session.flush()
+    await db_session.refresh(role)
+
+    return RoleResponse(
+        id=role.id, name=role.name, description=role.description
+    )
+
+
+@router.put("/{role_id}", response_model=RoleResponse)
+async def update_role(
+    request: Request,
+    role_id: int,
+    body: RoleUpdate,
+    user: dict[str, Any] = Depends(require_api_superuser()),
+) -> RoleResponse:
+    """PUT /api/roles/{id} — update a role (superuser only)."""
+    db_session = get_db_session(request)
+    role = await db_session.get(AdminRole, role_id)
+    if role is None:
+        raise HTTPException(status_code=404, detail="Role not found.")
+
+    if body.name is not None:
+        role.name = body.name
+    if body.description is not None:
+        role.description = body.description
+
+    await db_session.flush()
+    await db_session.refresh(role)
+
+    return RoleResponse(
+        id=role.id,
+        name=role.name,
+        description=role.description,
+        user_count=len(role.users),
+    )
+
+
+@router.delete("/{role_id}", status_code=204)
+async def delete_role(
+    request: Request,
+    role_id: int,
+    user: dict[str, Any] = Depends(require_api_superuser()),
+) -> None:
+    """DELETE /api/roles/{id} — delete a role (superuser only)."""
+    db_session = get_db_session(request)
+    role = await db_session.get(AdminRole, role_id)
+    if role is None:
+        raise HTTPException(status_code=404, detail="Role not found.")
+
+    if len(role.users) > 0:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Cannot delete role. {len(role.users)} user(s) are still assigned.",
+        )
+
+    await db_session.delete(role)
+    await db_session.flush()

fastapi_admin_kit/api/schema_generator.py

@@ -0,0 +1,171 @@
+"""Dynamic Pydantic schema generation from SQLAlchemy models."""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field, create_model
+
+
+def _sa_type_to_python(sa_type: Any) -> type:
+    """Map a SQLAlchemy column type to a Python type for Pydantic."""
+    from sqlalchemy import (
+        Boolean,
+        Date,
+        DateTime,
+        Enum,
+        Float,
+        Integer,
+        LargeBinary,
+        Numeric,
+        String,
+        Text,
+        Time,
+    )
+
+    type_cls = type(sa_type)
+
+    if type_cls in (Integer,):
+        return int
+    if type_cls in (Float, Numeric):
+        return float
+    if type_cls in (Boolean,):
+        return bool
+    if type_cls in (String, Text):
+        return str
+    if type_cls in (DateTime,):
+        return datetime.datetime
+    if type_cls in (Date,):
+        return datetime.date
+    if type_cls in (Time,):
+        return datetime.time
+    if type_cls in (LargeBinary,):
+        return bytes
+    if type_cls is Enum:
+        return str
+    return Any
+
+
+def _get_column_python_type(col: Any) -> type:
+    """Get the Python type for a column, handling ForeignKey."""
+    if col.foreign_keys:
+        return int
+    return _sa_type_to_python(col.type)
+
+
+def _collect_fields(registered: Any, *, exclude_pk: bool = False) -> list[Any]:
+    """Collect columns to include in a schema, respecting ModelAdmin config."""
+    admin = registered.admin
+    columns = list(registered.columns)
+
+    if exclude_pk:
+        columns = [c for c in columns if not c.primary_key]
+
+    if admin.fields is not None:
+        field_names = set(admin.fields)
+        columns = [c for c in columns if c.name in field_names]
+
+    if admin.exclude:
+        columns = [c for c in columns if c.name not in admin.exclude]
+
+    return columns
+
+
+def build_create_schema(registered: Any) -> type[BaseModel]:
+    """Build a Pydantic model for create requests.
+
+    Excludes PK, readonly fields, and server-default-only fields.
+    """
+    admin = registered.admin
+    readonly = set(admin.readonly_fields or [])
+    columns = _collect_fields(registered, exclude_pk=True)
+
+    fields: dict[str, Any] = {}
+    for col in columns:
+        if col.name in readonly:
+            continue
+        if col.server_default is not None and col.default is None:
+            continue
+
+        python_type = _get_column_python_type(col)
+        if col.nullable:
+            field_info = (python_type | None, Field(default=None))
+        else:
+            field_info = (python_type, Field(...))
+
+        fields[col.name] = field_info
+
+    model_name = f"{registered.verbose_name.replace(' ', '')}Create"
+    return create_model(model_name, __config__=None, **fields)
+
+
+def build_update_schema(registered: Any) -> type[BaseModel]:
+    """Build a Pydantic model for update requests.
+
+    All fields optional. Excludes PK and readonly fields.
+    """
+    admin = registered.admin
+    readonly = set(admin.readonly_fields or [])
+    columns = _collect_fields(registered, exclude_pk=True)
+
+    fields: dict[str, Any] = {}
+    for col in columns:
+        if col.name in readonly:
+            continue
+
+        python_type = _get_column_python_type(col)
+        field_info = (python_type | None, Field(default=None))
+        fields[col.name] = field_info
+
+    model_name = f"{registered.verbose_name.replace(' ', '')}Update"
+    return create_model(model_name, __config__=None, **fields)
+
+
+def build_response_schema(registered: Any) -> type[BaseModel]:
+    """Build a Pydantic model for response output."""
+    columns = list(registered.columns)
+
+    fields: dict[str, Any] = {}
+    for col in columns:
+        python_type = _get_column_python_type(col)
+        if col.nullable:
+            field_info = (python_type | None, Field(default=None))
+        else:
+            field_info = (python_type, Field(...))
+        fields[col.name] = field_info
+
+    model_name = f"{registered.verbose_name.replace(' ', '')}Response"
+    return create_model(model_name, __config__=None, **fields)
+
+
+def build_list_response_schema(registered: Any) -> type[BaseModel]:
+    """Build a paginated list response schema wrapping the response schema."""
+    item_schema = build_response_schema(registered)
+
+    model_name = f"{registered.verbose_name.replace(' ', '')}ListResponse"
+    return create_model(
+        model_name,
+        items=(list[item_schema], Field(...)),
+        total=(int, Field(...)),
+        page=(int | None, Field(default=None)),
+        per_page=(int, Field(...)),
+        total_pages=(int | None, Field(default=None)),
+        next_cursor=(str | None, Field(default=None)),
+        has_next=(bool, Field(default=False)),
+    )
+
+
+def get_or_build_schemas(registered: Any) -> dict[str, type[BaseModel]]:
+    """Get or generate and cache schemas for a registered model."""
+    if hasattr(registered, "_schemas") and registered._schemas is not None:
+        return registered._schemas
+
+    schemas = {
+        "create": build_create_schema(registered),
+        "update": build_update_schema(registered),
+        "response": build_response_schema(registered),
+        "list_response": build_list_response_schema(registered),
+    }
+    registered._schemas = schemas
+    return schemas

fastapi_admin_kit/api/schemas.py

@@ -0,0 +1,81 @@
+"""Pydantic schemas for the Admin JSON API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class TokenRequest(BaseModel):
+    """Request body for token authentication."""
+
+    email: str
+    password: str
+
+
+class TokenResponse(BaseModel):
+    """Response containing access and refresh tokens."""
+
+    access_token: str
+    refresh_token: str = ""
+    token_type: str = "bearer"
+    expires_in: int = 0
+
+
+class RefreshRequest(BaseModel):
+    """Request body for token refresh."""
+
+    refresh_token: str
+
+
+class RefreshResponse(BaseModel):
+    """Response containing refreshed access and refresh tokens."""
+
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+    expires_in: int = 0
+
+
+class PaginationParams(BaseModel):
+    """Pagination query parameters."""
+
+    page: int = 1
+    per_page: int = 25
+    q: str = ""
+    order: str = ""
+    after: str | None = None
+    before: str | None = None
+
+
+class PaginatedResponse(BaseModel):
+    """Paginated list response."""
+
+    items: list[Any]
+    total: int
+    page: int | None = None
+    per_page: int
+    total_pages: int | None = None
+    next_cursor: str | None = None
+    has_next: bool = False
+
+
+class ErrorResponse(BaseModel):
+    """Error response."""
+
+    detail: str
+
+
+class TwoFARequiredResponse(BaseModel):
+    """Response when 2FA is required."""
+
+    requires_2fa: bool = True
+    temp_token: str
+
+
+class TwoFAVerifyRequest(BaseModel):
+    """Request body for 2FA verification."""
+
+    temp_token: str
+    code: str

fastapi_admin_kit/api/search.py

@@ -0,0 +1,132 @@
+"""Global search API — returns model and field suggestions for the topbar search bar."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+
+router = APIRouter(tags=["api-search"])
+
+
+async def require_any_auth(request: Request) -> Any:
+    """Accept either JWT Bearer token or session cookie.
+
+    Only validates the credential — no DB lookup (pure metadata search needs
+    no user object, just proof of authentication).
+    """
+    # Try JWT first (Authorization: Bearer <token>)
+    auth_header = request.headers.get("Authorization", "")
+    if auth_header.startswith("Bearer "):
+        from fastapi_admin_kit.api.auth import _get_secret_key, decode_access_token
+
+        token = auth_header[7:]
+        secret_key = _get_secret_key(request)
+        payload = decode_access_token(token, secret_key)
+        if payload is not None:
+            return payload
+
+    # Fall back to session cookie — just verify it decodes, no DB hit
+    session_backend = getattr(request.app.state, "admin_session_backend", None)
+    if session_backend is not None:
+        token = request.cookies.get(session_backend.cookie_name)
+        if token:
+            session = session_backend.decode(token)
+            if session and session.get("user_id") is not None:
+                return session
+
+    raise HTTPException(status_code=401, detail="Not authenticated.")
+
+
+@router.get("/search/suggestions")
+async def get_search_suggestions(
+    request: Request,
+    q: str = Query("", min_length=0),
+    _user: Any = Depends(require_any_auth),
+) -> dict[str, Any]:
+    """GET /admin/search/suggestions?q=... — return model and field suggestions.
+
+    Pure metadata scan — no DB queries, extremely fast.
+    Results are categorised into:
+      - ``model`` suggestions  (verbose model name matches the query)
+      - ``field``  suggestions (field label / name matches the query)
+    """
+
+    registry = getattr(request.app.state, "admin_registry", None)
+    if registry is None or not q.strip():
+        return {"suggestions": [], "query": q}
+
+    query_lower = q.strip().lower()
+    suggestions: list[dict[str, Any]] = []
+
+    for registered in registry.all():
+        if getattr(registered.admin, "skip_auto_routes", False):
+            continue
+        table_name: str = registered.table_name
+        verbose_name: str = registered.verbose_name
+        verbose_name_plural: str = registered.verbose_name_plural
+        admin = registered.admin
+
+        # ── Model-level match ─────────────────────────────────────────────
+        if (
+            query_lower in verbose_name.lower()
+            or query_lower in verbose_name_plural.lower()
+            or query_lower in table_name.lower()
+        ):
+            suggestions.append(
+                {
+                    "type": "model",
+                    "model": table_name,
+                    "label": verbose_name_plural,
+                    "sublabel": table_name,
+                    "url": f"/admin/{table_name}",
+                }
+            )
+
+        # ── Field-level matches ───────────────────────────────────────────
+        field_entries: list[tuple[str, str]] = []  # (field_name, human_label)
+
+        for col in registered.columns:
+            if col.primary_key:
+                continue
+            name = col.name
+            if name.endswith("_id"):
+                label = name[:-3].replace("_", " ").title()
+            else:
+                label = name.replace("_", " ").title()
+            field_entries.append((name, label))
+
+        for rel in getattr(registered, "relationships", []):
+            label = rel.name.replace("_", " ").title()
+            field_entries.append((rel.name, label))
+
+        extra_fields: list[str] = list(
+            set(
+                (getattr(admin, "search_fields", None) or [])
+                + (getattr(admin, "list_display", None) or [])
+            )
+        )
+        existing_names = {fe[0] for fe in field_entries}
+        for fname in extra_fields:
+            if fname not in existing_names:
+                field_entries.append((fname, fname.replace("_", " ").title()))
+
+        for field_name, field_label in field_entries:
+            if query_lower in field_label.lower() or query_lower in field_name.lower():
+                suggestions.append(
+                    {
+                        "type": "field",
+                        "model": table_name,
+                        "field": field_name,
+                        "label": f"{verbose_name_plural} → {field_label}",
+                        "sublabel": f"{table_name}.{field_name}",
+                        "url": f"/admin/{table_name}?q={q}",
+                    }
+                )
+
+    # ── Rank: model matches first, then field matches; cap at 15 ──────────
+    model_hits = [s for s in suggestions if s["type"] == "model"]
+    field_hits = [s for s in suggestions if s["type"] == "field"]
+    ranked = (model_hits + field_hits)[:15]
+
+    return {"suggestions": ranked, "query": q}

fastapi_admin_kit/audit/__init__.py

@@ -0,0 +1,36 @@
+"""Audit module — AuditLog model, SQLAlchemy event listener, diff, context, middleware."""
+
+from __future__ import annotations
+
+from fastapi_admin_kit.audit.context import (
+    AuditContext,
+    clear_audit_context,
+    get_audit_context,
+    set_audit_context,
+)
+from fastapi_admin_kit.audit.diff import compute_diff, snapshot
+from fastapi_admin_kit.audit.event_bus import AuditEventBus
+from fastapi_admin_kit.audit.events import AuditEvent
+from fastapi_admin_kit.audit.listener import (
+    attach_audit_listener,
+    is_registered_model,
+)
+from fastapi_admin_kit.audit.logger import AuditLogger
+from fastapi_admin_kit.audit.middleware import AuditContextMiddleware
+from fastapi_admin_kit.audit.models import AuditLog
+
+__all__ = [
+    "AuditContext",
+    "AuditContextMiddleware",
+    "AuditEvent",
+    "AuditEventBus",
+    "AuditLog",
+    "AuditLogger",
+    "attach_audit_listener",
+    "clear_audit_context",
+    "compute_diff",
+    "get_audit_context",
+    "is_registered_model",
+    "set_audit_context",
+    "snapshot",
+]

fastapi_admin_kit/audit/context.py

@@ -0,0 +1,62 @@
+"""Audit context — thread-local storage for audit information."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Any
+
+# Context variable to store audit context (user, IP, user_agent, etc.)
+_current_audit_context: ContextVar[dict] = ContextVar("_current_audit_context", default={})
+
+
+def get_audit_context() -> dict:
+    """Get the current audit context."""
+    return _current_audit_context.get()
+
+
+def set_audit_context(data: dict) -> None:
+    """Set the audit context (merges with existing)."""
+    current = get_audit_context()
+    current.update(data)
+    _current_audit_context.set(current)
+
+
+def clear_audit_context() -> None:
+    """Clear the audit context."""
+    _current_audit_context.set({})
+
+
+class AuditContext:
+    """Manages the current audit context for a request lifecycle.
+
+    Wraps the ContextVar-based functions in a class interface that
+    can be injected into the event bus and listener.
+    """
+
+    def set_context(self, user: Any = None, request: Any = None) -> None:
+        """Set audit context from a user object and/or request.
+
+        Args:
+            user: An object with 'id' and 'email' attributes (e.g. AdminUser)
+            request: A Starlette/FastAPI Request with client and headers
+        """
+        data: dict[str, Any] = {}
+        if user is not None:
+            data["user_id"] = getattr(user, "id", None)
+            data["user_email"] = getattr(user, "email", None)
+        if request is not None:
+            if request.client is not None:
+                data["ip_address"] = request.client.host
+            user_agent = request.headers.get("user-agent")
+            if user_agent:
+                data["user_agent"] = user_agent
+        if data:
+            set_audit_context(data)
+
+    def get_context(self) -> dict:
+        """Get the current audit context."""
+        return get_audit_context()
+
+    def clear_context(self) -> None:
+        """Clear the audit context."""
+        clear_audit_context()

fastapi_admin_kit/audit/diff.py

@@ -0,0 +1,77 @@
+"""Audit diff utilities — snapshot and diff computation for SQLAlchemy models."""
+
+from __future__ import annotations
+
+import datetime
+import decimal
+import enum
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy.inspection import inspect as sqlalchemy_inspect
+
+
+def serialize_value(val: Any) -> Any:
+    """Convert a value to a JSON-serializable form.
+    
+    Handles:
+        - datetime.datetime -> ISO string
+        - datetime.date -> ISO string
+        - datetime.time -> ISO string
+        - decimal.Decimal -> string
+        - UUID -> string
+        - bytes -> base64 string? (but we'll keep as is for now, or maybe hex?)
+        - Enum -> value or name? We'll use value.
+        - Other types returned as-is if they are JSON serializable (int, float, str, bool, None)
+    """
+    if val is None:
+        return None
+    if isinstance(val, (datetime.datetime, datetime.date, datetime.time)):
+        return val.isoformat()
+    if isinstance(val, decimal.Decimal):
+        return str(val)
+    if isinstance(val, UUID):
+        return str(val)
+    if isinstance(val, bytes):
+        # For simplicity, we'll return the hex representation.
+        # Alternatively, we could use base64, but hex is simpler.
+        return val.hex()
+    if isinstance(val, enum.Enum):
+        return val.value
+    # For other types, we assume they are JSON serializable (or let JSON encoder handle it)
+    return val
+
+
+def snapshot(obj: Any) -> dict[str, Any]:
+    """Snapshot all mapped columns of a SQLAlchemy model instance.
+    
+    Returns a dict mapping column name to serialized value.
+    """
+    if not hasattr(obj, "__table__"):
+        raise ValueError("Object is not a SQLAlchemy model instance")
+    
+    mapper = sqlalchemy_inspect(obj.__class__)
+    data = {}
+    for column in mapper.columns:
+        # Skip foreign key columns that are represented by relationships?
+        # We'll include all columns for simplicity.
+        value = getattr(obj, column.key)
+        data[column.key] = serialize_value(value)
+    return data
+
+
+def compute_diff(before: dict[str, Any], after: dict[str, Any]) -> dict[str, Any]:
+    """Compute the difference between two snapshots.
+    
+    Returns a dict of changed fields, each containing:
+        {"old": <value>, "new": <value>}
+    Only fields that have changed are included.
+    """
+    diff = {}
+    all_keys = set(before.keys()) | set(after.keys())
+    for key in all_keys:
+        old_val = before.get(key)
+        new_val = after.get(key)
+        if old_val != new_val:
+            diff[key] = {"old": old_val, "new": new_val}
+    return diff