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

fastapi_admin_kit/filters/base.py

@@ -0,0 +1,170 @@
+"""Filter ABCs."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Filter(ABC):
+    """Abstract base class for list view filters."""
+
+    def __init__(self, field_name: str, label: str = "") -> None:
+        self.field_name = field_name
+        self.label = label or field_name.replace("_", " ").title()
+
+    @abstractmethod
+    def apply(self, query: Any, value: str) -> Any:
+        """Apply the filter to a SQLAlchemy select query."""
+        ...
+
+    def get_choices(self, session: Any) -> list[tuple[str, str]]:
+        """Return available filter choices as (value, label) pairs."""
+        return []
+
+
+class TextFilter(Filter):
+    """Simple text equality filter."""
+
+    def apply(self, query: Any, value: str) -> Any:
+        model = query.column_descriptions[0]["entity"]
+        if hasattr(model, self.field_name):
+            col = getattr(model, self.field_name)
+            return query.where(col == value)
+        return query
+
+
+class BooleanFilter(Filter):
+    """Boolean filter — maps '1' to True, '0' to False."""
+
+    def apply(self, query: Any, value: str) -> Any:
+        model = query.column_descriptions[0]["entity"]
+        if hasattr(model, self.field_name):
+            col = getattr(model, self.field_name)
+            return query.where(col == (value == "1"))
+        return query
+
+
+class RelationFilter(Filter):
+    """Filter by foreign key relationship."""
+
+    def apply(self, query: Any, value: str) -> Any:
+        model = query.column_descriptions[0]["entity"]
+        if hasattr(model, self.field_name):
+            col = getattr(model, self.field_name)
+            return query.where(col == value)
+        return query
+
+
+class EnumFilter(Filter):
+    """Filter for enum columns."""
+
+    def __init__(
+        self,
+        field_name: str,
+        label: str = "",
+        choices: list[str] | None = None,
+    ) -> None:
+        super().__init__(field_name, label)
+        self._enum_choices = choices or []
+
+    def apply(self, query: Any, value: str) -> Any:
+        model = query.column_descriptions[0]["entity"]
+        if hasattr(model, self.field_name):
+            col = getattr(model, self.field_name)
+            return query.where(col == value)
+        return query
+
+    def get_choices(self, session: Any) -> list[tuple[str, str]]:
+        choices = [("", "All")]
+        for val in self._enum_choices:
+            choices.append((val, val.replace("_", " ").title()))
+        return choices
+
+
+class NumericFilter(Filter):
+    """Numeric range filter (gte/lte)."""
+
+    def apply(self, query: Any, value: str) -> Any:
+        model = query.column_descriptions[0]["entity"]
+        if not hasattr(model, self.field_name):
+            return query
+        col = getattr(model, self.field_name)
+        if isinstance(value, dict):
+            if value.get("gte"):
+                query = query.where(col >= value["gte"])
+            if value.get("lte"):
+                query = query.where(col <= value["lte"])
+        return query
+
+
+class DateRangeFilter(Filter):
+    """Date range filter (from/to)."""
+
+    def apply(self, query: Any, value: str) -> Any:
+        from datetime import date
+
+        model = query.column_descriptions[0]["entity"]
+        if not hasattr(model, self.field_name):
+            return query
+        col = getattr(model, self.field_name)
+        if isinstance(value, dict):
+            if value.get("from"):
+                try:
+                    d = date.fromisoformat(value["from"])
+                    query = query.where(col >= d)
+                except (ValueError, TypeError):
+                    pass
+            if value.get("to"):
+                try:
+                    d = date.fromisoformat(value["to"])
+                    query = query.where(col <= d)
+                except (ValueError, TypeError):
+                    pass
+        return query
+
+
+class DatetimeRangeFilter(Filter):
+    """Datetime range filter (from/to)."""
+
+    def apply(self, query: Any, value: str) -> Any:
+        from datetime import datetime
+
+        model = query.column_descriptions[0]["entity"]
+        if not hasattr(model, self.field_name):
+            return query
+        col = getattr(model, self.field_name)
+        if isinstance(value, dict):
+            if value.get("from"):
+                try:
+                    dt = datetime.fromisoformat(value["from"])
+                    query = query.where(col >= dt)
+                except (ValueError, TypeError):
+                    pass
+            if value.get("to"):
+                try:
+                    dt = datetime.fromisoformat(value["to"])
+                    query = query.where(col <= dt)
+                except (ValueError, TypeError):
+                    pass
+        return query
+
+
+class AutocompleteFilter(Filter):
+    """Autocomplete search filter for related fields."""
+
+    def __init__(
+        self,
+        field_name: str,
+        label: str = "",
+        search_fields: list[str] | None = None,
+    ) -> None:
+        super().__init__(field_name, label)
+        self.search_fields = search_fields or ["name"]
+
+    def apply(self, query: Any, value: str) -> Any:
+        model = query.column_descriptions[0]["entity"]
+        if not hasattr(model, self.field_name):
+            return query
+        col = getattr(model, self.field_name)
+        return query.where(col == value)

fastapi_admin_kit/filters/registry.py

@@ -0,0 +1,68 @@
+"""Filter registry."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi_admin_kit.filters.base import (
+    BooleanFilter,
+    EnumFilter,
+    Filter,
+    RelationFilter,
+    TextFilter,
+)
+
+
+class FilterRegistry:
+    """Registry for custom filters per model."""
+
+    def __init__(self) -> None:
+        self._filters: dict[str, dict[str, Filter]] = {}
+
+    def register(self, model_name: str, filter_obj: Filter) -> None:
+        self._filters.setdefault(model_name, {})[filter_obj.field_name] = (
+            filter_obj
+        )
+
+    def get_filters(self, model_name: str) -> dict[str, Filter]:
+        return self._filters.get(model_name, {}).copy()
+
+    def auto_generate(
+        self, model: Any, columns: list[Any]
+    ) -> dict[str, Filter]:
+        from sqlalchemy import inspect as sa_inspect
+
+        mapper = sa_inspect(model)
+        filters: dict[str, Filter] = {}
+
+        for col_meta in columns:
+            field_name = col_meta.name
+            if field_name == "id":
+                continue
+
+            rel_names = {r.key for r in mapper.relationships}
+            if field_name in rel_names:
+                filters[field_name] = RelationFilter(field_name)
+                continue
+
+            for prop in mapper.column_attrs:
+                if prop.key != field_name:
+                    continue
+                col = prop.columns[0] if prop.columns else None
+                if col is None:
+                    break
+
+                type_name = col.type.__class__.__name__
+                if type_name == "Boolean":
+                    filters[field_name] = BooleanFilter(field_name)
+                elif hasattr(col.type, "enums") and col.type.enums:
+                    filters[field_name] = EnumFilter(
+                        field_name, choices=list(col.type.enums)
+                    )
+                elif col.foreign_keys:
+                    filters[field_name] = RelationFilter(field_name)
+                else:
+                    filters[field_name] = TextFilter(field_name)
+                break
+
+        return filters

fastapi_admin_kit/flash.py

@@ -0,0 +1,45 @@
+"""Flash message helpers for the admin UI.
+
+Stored in a signed session cookie so they survive exactly one redirect-safe read.
+"""
+
+from __future__ import annotations
+
+from fastapi import Request
+
+SESSION_KEY = "admin_flash"
+
+
+async def add_flash(request: Request, level: str, message: str) -> None:
+    session_backend = request.app.state.admin_session_backend
+    cookie_name = getattr(session_backend, "cookie_name", "admin_session")
+    data: dict[str, list[dict[str, str]]] | None = None
+    raw = request.cookies.get(cookie_name)
+    if raw and hasattr(session_backend, "load"):
+        loaded = session_backend.load(raw)
+        if isinstance(loaded, dict):
+            data = loaded
+    if data is None:
+        data = {}
+    data.setdefault(SESSION_KEY, []).append({"level": level, "text": message})
+    if hasattr(session_backend, "save"):
+        from starlette.responses import Response
+        response = Response()
+        session_backend.save(response, data)
+
+
+async def get_flash_messages(request: Request) -> list[dict[str, str]]:
+    session_backend = request.app.state.admin_session_backend
+    cookie_name = getattr(session_backend, "cookie_name", "admin_session")
+    raw = request.cookies.get(cookie_name)
+    if not raw or not hasattr(session_backend, "load"):
+        return []
+    data = session_backend.load(raw)
+    if not isinstance(data, dict):
+        return []
+    messages = data.pop(SESSION_KEY, []) if SESSION_KEY in data else []
+    if hasattr(session_backend, "save"):
+        from starlette.responses import Response
+        response = Response()
+        session_backend.save(response, data)
+    return messages

fastapi_admin_kit/form/__init__.py

@@ -0,0 +1 @@
+"""Form generation and handling."""

fastapi_admin_kit/form/pipeline.py

@@ -0,0 +1,106 @@
+"""Build FormContext from a RegisteredModel + DB object + values + errors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi_admin_kit.types import (
+    FieldRenderContext,
+    FieldsetContext,
+    FormContext,
+    PermissionSet,
+)
+
+
+def build_form_context(
+    registered: Any,
+    obj: Any | None = None,
+    values: dict[str, Any] | None = None,
+    errors: dict[str, list[str]] | None = None,
+    request: Any = None,
+    is_create: bool = False,
+    rel_labels: dict[str, str] | None = None,
+) -> FormContext:
+    values = values or {}
+    errors = errors or {}
+    rendered: list[FieldRenderContext] = []
+    fieldsets: list[FieldsetContext] = [FieldsetContext(fields=[])]
+
+    for field_meta in registered.form_fields:
+        col = next((c for c in registered.columns if c.name == field_meta.name), None)
+        rel = next((r for r in registered.relationships if r.name == field_meta.name), None)
+        widget = registered.get_widget(field_meta.name)
+
+        value = values.get(field_meta.name)
+        if value is None and obj is not None:
+            if hasattr(obj, "__dict__"):
+                value = obj.__dict__.get(field_meta.name)
+            # For M2M relationships, extract IDs from loaded collection
+            if value is None and rel is not None:
+                try:
+                    from sqlalchemy import inspect as sa_inspect
+                    mapper = sa_inspect(type(obj))
+                    rel_prop = mapper.relationships.get(rel.name)
+                    if rel_prop is not None:
+                        if rel_prop.direction.name == "MANYTOMANY":
+                            collection = getattr(obj, rel_prop.key, None)
+                            if collection is not None:
+                                value = [str(item.id) for item in collection]
+                        else:
+                            local_cols = [c.key for c in rel_prop.local_columns]
+                            if local_cols:
+                                value = getattr(obj, local_cols[0], None)
+                except Exception:
+                    pass
+            # Handle case where __dict__ returned loaded M2M collection objects
+            if (
+                value is not None
+                and rel is not None
+                and isinstance(value, list)
+                and value
+                and hasattr(value[0], "id")
+            ):
+                try:
+                    from sqlalchemy import inspect as sa_inspect
+                    mapper = sa_inspect(type(obj))
+                    rel_prop = mapper.relationships.get(rel.name)
+                    if rel_prop is not None and rel_prop.direction.name == "MANYTOMANY":
+                        value = [str(item.id) for item in value]
+                except Exception:
+                    pass
+            elif value is None and col is not None:
+                value = getattr(obj, field_meta.name, None)
+
+        widget_macro = widget.macro_name
+        widget_ctx = widget.render_context(field_meta, value)
+        widget_ctx["is_create"] = is_create
+        if obj is not None:
+            widget_ctx["obj_id"] = getattr(obj, "id", "")
+        if rel is not None and rel_labels:
+            widget_ctx["label_text"] = rel_labels.get(rel.name, "")
+        field_errors = errors.get(field_meta.name, [])
+        rendered.append(
+            FieldRenderContext(
+                meta=field_meta,
+                widget_macro=widget_macro,
+                widget_context=widget_ctx,
+                errors=field_errors,
+            )
+        )
+
+    fieldsets[0].fields = rendered
+
+    return FormContext(
+        model_name=registered.table_name,
+        verbose_name=registered.verbose_name,
+        is_create=is_create,
+        obj=obj,
+        fieldsets=fieldsets,
+        errors=errors,
+        values=values,
+        action_url="",
+        list_url="",
+        can_delete=not is_create,
+        permissions=PermissionSet(),
+        readonly=False,
+    )

fastapi_admin_kit/inspection/__init__.py

@@ -0,0 +1,117 @@
+"""Model inspection — SQLAlchemy model → ColumnMeta / RelationMeta."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from sqlalchemy import inspect
+
+from fastapi_admin_kit.types import ColumnMeta, RelationMeta
+
+
+def inspect_model(model: type) -> tuple[list[ColumnMeta], list[RelationMeta]]:
+    """Inspect a SQLAlchemy model and return column + relationship metadata."""
+    mapper = inspect(model)
+    columns: list[ColumnMeta] = []
+    relationships: list[RelationMeta] = []
+
+    for col in mapper.columns:
+        columns.append(
+            ColumnMeta(
+                name=col.key,
+                type=col.type,
+                nullable=col.nullable,
+                primary_key=col.primary_key,
+                foreign_keys=list(col.foreign_keys),
+                default=col.default,
+                server_default=col.server_default,
+                index=col.index,
+                unique=col.unique,
+            )
+        )
+
+    for rel in mapper.relationships:
+        relationships.append(
+            RelationMeta(
+                name=rel.key,
+                direction=rel.direction.name,
+                target_model=rel.mapper.class_,
+                uselist=rel.uselist,
+                back_populates=rel.back_populates,
+                secondary=rel.secondary,
+            )
+        )
+
+    return columns, relationships
+
+
+def is_abstract(model: type) -> bool:
+    """Check if a model is abstract and should be skipped during auto-discovery."""
+    return getattr(model, "__abstract__", False)
+
+
+def get_pk_field(model: type) -> str | None:
+    """Get the primary key field name for a model.
+
+    Returns the single PK field name for simple PKs,
+    or a tuple of names for composite PKs.
+    Returns None if no primary key is found.
+    """
+    mapper = inspect(model)
+    pk_cols = mapper.primary_key
+    if not pk_cols:
+        return None
+    if len(pk_cols) == 1:
+        return pk_cols[0].key
+    return tuple(col.key for col in pk_cols)
+
+
+def auto_label(name: str) -> str:
+    """Auto-generate a human-readable label from a field name.
+
+    Examples:
+        "category_id"  → "Category"
+        "is_active"    → "Is Active"
+        "created_at"   → "Created At"
+        "skuCode"      → "Sku Code"
+    """
+    label = name
+    if label.endswith("_id"):
+        label = label[:-3]
+    label = re.sub(r"([A-Z])", r" \1", label)
+    return label.replace("_", " ").strip().title()
+
+
+def is_required(col: ColumnMeta) -> bool:
+    """Determine if a column is required (NOT NULL with no default).
+
+    A column is required if:
+    - It is NOT NULL
+    - It has no Python default
+    - It has no server_default (DB-side default)
+    - It is NOT a primary key (PKs are handled separately)
+    """
+    return (
+        not col.nullable
+        and col.default is None
+        and col.server_default is None
+        and not col.primary_key
+    )
+
+
+def model_display_name(obj: Any) -> str:
+    """Return a human-readable label for an ORM object.
+
+    Uses the model's ``__str__`` if it has a custom implementation.
+    Falls back to ``name``, ``title``, or ``ClassName:pk``.
+    """
+    if type(obj).__str__ is not object.__str__:
+        return str(obj)
+    label = getattr(obj, "name", None) or getattr(obj, "title", None)
+    if label is not None:
+        return str(label)
+    pk = getattr(obj, "id", None)
+    return (
+        f"{type(obj).__name__}:{pk}" if pk is not None else type(obj).__name__
+    )