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

fastapi_admin_kit/widgets/inputs.py

@@ -0,0 +1,363 @@
+"""Built-in widget classes — all standard form widgets per spec."""
+
+from __future__ import annotations
+
+import json
+from datetime import date, datetime
+from typing import Any
+
+from fastapi_admin_kit.types import FieldMeta
+from fastapi_admin_kit.widgets.base import Widget
+
+
+class TextInputWidget(Widget):
+    macro_name = "text_input"
+
+    def __init__(self, maxlength: int | None = None):
+        self.maxlength = maxlength
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        ctx["maxlength"] = self.maxlength
+        return ctx
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        errors = super().validate(value, field)
+        if value and self.maxlength and len(value) > self.maxlength:
+            errors.append(f"{field.label} must be {self.maxlength} characters or fewer.")
+        return errors
+
+
+class TextareaWidget(Widget):
+    macro_name = "textarea"
+
+    def __init__(self, rows: int = 5):
+        self.rows = rows
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        ctx["rows"] = self.rows
+        return ctx
+
+
+class NumberInputWidget(Widget):
+    macro_name = "number_input"
+
+    def __init__(self, step: str = "1", min: str | None = None, max: str | None = None):
+        self.step = step
+        self.min = min
+        self.max = max
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        ctx.update({"step": self.step, "min": self.min, "max": self.max})
+        return ctx
+
+    def parse(self, raw: str | None) -> int | float | None:
+        if raw is None or raw == "":
+            return None
+        try:
+            return int(raw) if "." not in str(raw) else float(raw)
+        except ValueError:
+            return raw
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        errors = super().validate(value, field)
+        if value is not None:
+            try:
+                float(value)
+            except (TypeError, ValueError):
+                errors.append(f"{field.label} must be a number.")
+        return errors
+
+
+class ToggleWidget(Widget):
+    macro_name = "toggle"
+
+    def parse(self, raw: str | None) -> bool:
+        if raw is None:
+            return False
+        if isinstance(raw, bool):
+            return raw
+        return str(raw).lower() in ("on", "true", "1", "yes")
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        return []
+
+
+class SelectWidget(Widget):
+    macro_name = "select"
+
+    def __init__(self, choices: list[tuple[str, str]] | None = None):
+        self.choices = choices or []
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        ctx["choices"] = self.choices
+        return ctx
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        errors = super().validate(value, field)
+        if value and self.choices:
+            valid = {c[0] for c in self.choices}
+            if value not in valid:
+                errors.append(f"'{value}' is not a valid choice for {field.label}.")
+        return errors
+
+
+class DatePickerWidget(Widget):
+    macro_name = "date_picker"
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        if isinstance(value, date) and not isinstance(value, datetime):
+            ctx["value"] = value.isoformat()
+        elif isinstance(value, datetime):
+            ctx["value"] = value.date().isoformat()
+        return ctx
+
+    def parse(self, raw: str | None) -> date | str | None:
+        if not raw:
+            return None
+        try:
+            return date.fromisoformat(raw)
+        except ValueError:
+            return raw
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        errors = super().validate(value, field)
+        if value is not None and not isinstance(value, date):
+            errors.append(f"{field.label} must be a valid date.")
+        return errors
+
+
+class DateTimePickerWidget(Widget):
+    macro_name = "datetime_picker"
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        if isinstance(value, datetime):
+            ctx["value"] = value.replace(tzinfo=None).isoformat(timespec="minutes")
+        elif isinstance(value, date):
+            combined = datetime.combine(value, datetime.min.time())
+            ctx["value"] = combined.isoformat(timespec="minutes")
+        return ctx
+
+    def parse(self, raw: str | None) -> datetime | str | None:
+        if not raw:
+            return None
+        try:
+            return datetime.fromisoformat(raw)
+        except ValueError:
+            return raw
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        errors = super().validate(value, field)
+        if value is not None and not isinstance(value, datetime):
+            errors.append(f"{field.label} must be a valid date and time.")
+        return errors
+
+
+class JsonEditorWidget(Widget):
+    macro_name = "json_editor"
+
+    def parse(self, raw: str | None) -> Any:
+        if not raw:
+            return None
+        if isinstance(raw, str):
+            try:
+                return json.loads(raw)
+            except (json.JSONDecodeError, TypeError):
+                return None
+        return raw
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        errors = super().validate(value, field)
+        if isinstance(value, str):
+            try:
+                json.loads(value)
+            except json.JSONDecodeError as e:
+                errors.append(f"{field.label} contains invalid JSON: {e}")
+        return errors
+
+
+class AutocompleteWidget(Widget):
+    """Text input with datalist autocomplete suggestions."""
+
+    macro_name = "autocomplete"
+
+    def __init__(
+        self,
+        suggestions: list[str] | None = None,
+        suggestions_fn: Any = None,
+    ):
+        self.suggestions = suggestions
+        self.suggestions_fn = suggestions_fn
+
+    def _get_suggestions(self) -> list[str]:
+        if self.suggestions_fn is not None:
+            return self.suggestions_fn()
+        return self.suggestions or []
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        ctx["suggestions"] = self._get_suggestions()
+        return ctx
+
+
+class PasswordWidget(Widget):
+    macro_name = "password_input"
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        ctx["value"] = ""  # NEVER pre-fill passwords
+        return ctx
+
+    def parse(self, raw: str | None) -> str | None:
+        if not raw:
+            return None
+        return raw
+
+
+class ReadOnlyWidget(Widget):
+    macro_name = "readonly"
+
+    def parse(self, raw: str | None) -> None:
+        return None
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        return []
+
+
+class HiddenWidget(Widget):
+    macro_name = "hidden"
+
+
+class FileUploadWidget(Widget):
+    """File upload widget — stores file via StorageBackend, saves path string."""
+
+    macro_name = "file_upload"
+
+    def __init__(
+        self,
+        max_size_mb: float | None = None,
+        accept: str | None = None,
+    ) -> None:
+        self.max_size_mb = max_size_mb
+        self.accept = accept  # e.g. ".pdf,.docx" or "application/pdf"
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        ctx["max_size_mb"] = self.max_size_mb
+        ctx["accept"] = self.accept
+        ctx["current_file"] = value if value else ""
+        return ctx
+
+    def parse(self, raw: Any) -> Any:
+        """Raw form data — the actual UploadFile handling happens in the
+        form submit factory because ``UploadFile`` objects need async read."""
+        if raw is None or raw == "":
+            return None
+        return raw
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        errors = super().validate(value, field)
+        # Size validation happens at save time in the form submit factory
+        # because reading the file requires async I/O.
+        return errors
+
+
+class ImageUploadWidget(Widget):
+    """Image upload widget — like FileUploadWidget but restricted to images."""
+
+    macro_name = "image_upload"
+
+    def __init__(
+        self,
+        max_size_mb: float | None = None,
+        accept: str = "image/*",
+    ) -> None:
+        self.max_size_mb = max_size_mb
+        self.accept = accept
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        ctx["max_size_mb"] = self.max_size_mb
+        ctx["accept"] = self.accept
+        ctx["current_file"] = value if value else ""
+        return ctx
+
+    def parse(self, raw: Any) -> Any:
+        if raw is None or raw == "":
+            return None
+        return raw
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        errors = super().validate(value, field)
+        return errors
+
+
+class WysiwygWidget(Widget):
+    """Wysiwyg rich text editor widget (contenteditable-based)."""
+
+    macro_name = "wysiwyg"
+
+    def __init__(self, height: int = 200):
+        self.height = height
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        ctx["height"] = self.height
+        return ctx
+
+    def parse(self, raw: str | None) -> str | None:
+        if not raw:
+            return None
+        return raw
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        return []
+
+
+class ArrayWidget(Widget):
+    """Array/list input widget — dynamic add/remove items."""
+
+    macro_name = "array_input"
+
+    def __init__(self, min_items: int = 0, max_items: int | None = None):
+        self.min_items = min_items
+        self.max_items = max_items
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        if isinstance(value, str):
+            try:
+                import json
+                ctx["value"] = json.loads(value)
+            except (json.JSONDecodeError, TypeError):
+                ctx["value"] = []
+        ctx["min_items"] = self.min_items
+        ctx["max_items"] = self.max_items
+        return ctx
+
+    def parse(self, raw: str | list | None) -> list:
+        if raw is None:
+            return []
+        if isinstance(raw, list):
+            return raw
+        if isinstance(raw, str):
+            try:
+                import json
+                return json.loads(raw)
+            except (json.JSONDecodeError, TypeError):
+                return [raw] if raw else []
+        return []
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        errors = super().validate(value, field)
+        if isinstance(value, list):
+            if self.min_items and len(value) < self.min_items:
+                errors.append(f"{field.label} requires at least {self.min_items} items.")
+            if self.max_items and len(value) > self.max_items:
+                errors.append(f"{field.label} allows at most {self.max_items} items.")
+        return errors

fastapi_admin_kit/widgets/registry.py

@@ -0,0 +1,110 @@
+"""WidgetRegistry — stores type-to-widget and name-to-widget mappings.
+
+This class handles ONLY registration/storage of widget mappings.
+Resolution logic lives in WidgetResolver (fastapi_admin_kit/widgets/resolver.py).
+
+Resolution order (documented here for reference, implemented in WidgetResolver):
+  1. Exact field name pattern  ->  e.g. "password" -> PasswordWidget
+  2. FK column present         ->  RelationPickerWidget
+  3. Enum type                 ->  SelectWidget
+  4. SQLAlchemy type match     ->  via type_map dict
+  5. Fallback                  ->  TextInputWidget
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import (
+    Boolean,
+    Date,
+    DateTime,
+    Float,
+    Integer,
+    LargeBinary,
+    Numeric,
+    String,
+    Text,
+    Uuid,
+)
+
+from fastapi_admin_kit.widgets.base import Widget
+from fastapi_admin_kit.widgets.inputs import (
+    DatePickerWidget,
+    DateTimePickerWidget,
+    FileUploadWidget,
+    NumberInputWidget,
+    PasswordWidget,
+    TextareaWidget,
+    TextInputWidget,
+    ToggleWidget,
+)
+
+
+class WidgetRegistry:
+    """Stores SQLAlchemy column type and name pattern mappings to widget classes.
+
+    This class is responsible ONLY for registration and storage.
+    Use WidgetResolver to determine which widget to use for a column.
+    """
+
+    def __init__(self) -> None:
+        self._type_map: dict[type, type[Widget]] = {}
+        self._name_patterns: list[tuple[str, type[Widget]]] = []
+
+    @property
+    def type_map(self) -> dict[type, type[Widget]]:
+        """Read-only access to the type-to-widget mapping."""
+        return dict(self._type_map)
+
+    @property
+    def name_patterns(self) -> list[tuple[str, type[Widget]]]:
+        """Read-only access to the name pattern list."""
+        return list(self._name_patterns)
+
+    def register_type(self, sa_type: type, widget_cls: type[Widget]) -> None:
+        """Register a widget class for a SQLAlchemy column type."""
+        self._type_map[sa_type] = widget_cls
+
+    def unregister_type(self, sa_type: type) -> None:
+        """Remove a registered type mapping."""
+        self._type_map.pop(sa_type, None)
+
+    def register_name(self, pattern: str, widget_cls: type[Widget]) -> None:
+        """Register a widget class for a name pattern (case-insensitive substring)."""
+        self._name_patterns.append((pattern.lower(), widget_cls))
+
+    def unregister_name(self, pattern: str) -> None:
+        """Remove all registrations for a name pattern."""
+        self._name_patterns = [
+            (p, w) for p, w in self._name_patterns if p != pattern.lower()
+        ]
+
+    def clear(self) -> None:
+        """Remove all registered mappings."""
+        self._type_map.clear()
+        self._name_patterns.clear()
+
+    def has_type(self, sa_type: type) -> bool:
+        """Check if a type is registered."""
+        return sa_type in self._type_map
+
+    def has_name(self, pattern: str) -> bool:
+        """Check if a name pattern is registered."""
+        return any(p == pattern.lower() for p, _ in self._name_patterns)
+
+
+widget_registry = WidgetRegistry()
+
+widget_registry.register_type(String, TextInputWidget)
+widget_registry.register_type(Text, TextareaWidget)
+widget_registry.register_type(Integer, NumberInputWidget)
+widget_registry.register_type(Float, NumberInputWidget)
+widget_registry.register_type(Numeric, NumberInputWidget)
+widget_registry.register_type(Boolean, ToggleWidget)
+widget_registry.register_type(Date, DatePickerWidget)
+widget_registry.register_type(DateTime, DateTimePickerWidget)
+widget_registry.register_type(LargeBinary, FileUploadWidget)
+widget_registry.register_type(Uuid, TextInputWidget)
+
+widget_registry.register_name("password", PasswordWidget)
+widget_registry.register_name("secret", PasswordWidget)
+widget_registry.register_name("token", PasswordWidget)

fastapi_admin_kit/widgets/relation.py

@@ -0,0 +1,70 @@
+"""Relation widgets — ForeignKey and many-to-many pickers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi_admin_kit.types import FieldMeta
+from fastapi_admin_kit.widgets.base import Widget
+
+
+class RelationPickerWidget(Widget):
+    """ForeignKey (many-to-one) picker — HTMX async searchable select with autocomplete."""
+
+    macro_name = "relation_picker"
+
+    def __init__(
+        self,
+        related_table: str = "",
+        related_verbose: str = "",
+        autocomplete: bool = True,
+        search_url: str | None = None,
+    ):
+        self.related_table = related_table
+        self.related_verbose = related_verbose
+        self.autocomplete = autocomplete
+        self.search_url = search_url
+
+    def parse(self, raw: str | None) -> int | str | None:
+        if not raw:
+            return None
+        try:
+            return int(raw)
+        except ValueError:
+            return raw
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        ctx["related_table"] = self.related_table
+        ctx["related_verbose"] = self.related_verbose
+        ctx["autocomplete"] = self.autocomplete
+        ctx["search_url"] = self.search_url or f"/admin/{self.related_table}/autocomplete/"
+        return ctx
+
+
+class MultiRelationWidget(Widget):
+    """Many-to-many tag-style multi-select."""
+
+    macro_name = "multi_relation"
+
+    def __init__(self, related_table: str = "", related_verbose: str = "", search_url: str = ""):
+        self.related_table = related_table
+        self.related_verbose = related_verbose
+        self.search_url = search_url
+
+    def render_context(self, field: FieldMeta, value: Any) -> dict:
+        ctx = super().render_context(field, value)
+        ctx["related_table"] = self.related_table
+        ctx["related_verbose"] = self.related_verbose
+        ctx["search_url"] = self.search_url
+        return ctx
+
+    def parse(self, raw: str | list | None) -> list[str]:
+        if raw is None:
+            return []
+        if isinstance(raw, list):
+            return [str(v) for v in raw if v]
+        return [str(raw)]
+
+    def validate(self, value: Any, field: FieldMeta) -> list[str]:
+        return []

fastapi_admin_kit/widgets/resolver.py

@@ -0,0 +1,102 @@
+"""WidgetResolver — dedicated class for resolving which widget to use for a column.
+
+Resolution order (fixed, cannot be short-circuited):
+  1. Exact field name pattern  ->  e.g. "password" -> PasswordWidget
+  2. FK column present         ->  RelationPickerWidget
+  3. Enum type                 ->  SelectWidget
+  4. SQLAlchemy type match     ->  via type_registry
+  5. Fallback                  ->  TextInputWidget
+
+This class separates resolution logic from registration (WidgetRegistry),
+creating a clear seam between "what widgets exist" and "which widget to use."
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi_admin_kit.types import ColumnMeta
+
+if TYPE_CHECKING:
+    from fastapi_admin_kit.widgets.base import Widget
+    from fastapi_admin_kit.widgets.registry import WidgetRegistry
+
+
+class WidgetResolver:
+    """Resolves which widget instance to use for a given ColumnMeta.
+
+    Uses dependency injection for the WidgetRegistry, making resolution
+    testable and separable from registration concerns.
+
+    Supports both SQLAlchemy types and Python built-in types (used by SQLModel).
+    """
+
+    # Python type to SQLAlchemy type name mapping for SQLModel support
+    PYTHON_TYPE_MAP: dict[type, str] = {
+        int: "Integer",
+        str: "String",
+        float: "Float",
+        bool: "Boolean",
+    }
+
+    def __init__(self, registry: WidgetRegistry) -> None:
+        self._registry = registry
+
+    @property
+    def registry(self) -> WidgetRegistry:
+        """Get the underlying widget registry."""
+        return self._registry
+
+    def resolve(self, col: ColumnMeta) -> Widget:
+        """Resolve which widget instance to use for a given column.
+
+        Resolution priority:
+          1. Name pattern match (case-insensitive substring)
+          2. Foreign key column -> RelationPickerWidget
+          3. Enum type -> SelectWidget with choices
+          4. SQLAlchemy type match via registry
+          5. Python type match (for SQLModel)
+          6. Fallback -> TextInputWidget
+        """
+        for pattern, widget_cls in self._registry.name_patterns:
+            if pattern in col.name.lower():
+                return widget_cls()
+
+        if col.foreign_keys:
+            from fastapi_admin_kit.widgets.relation import RelationPickerWidget
+
+            return RelationPickerWidget()
+
+        col_type = col.type
+        if hasattr(col_type, "enums") and col_type.enums:
+            choices = [(v, v.replace("_", " ").title()) for v in col_type.enums]
+            from fastapi_admin_kit.widgets.inputs import SelectWidget
+
+            return SelectWidget(choices=choices)
+
+        # Try SQLAlchemy type match via registry
+        for sa_type, widget_cls in self._registry.type_map.items():
+            if isinstance(col_type, sa_type):
+                from fastapi_admin_kit.widgets.inputs import TextInputWidget
+
+                has_length = hasattr(col_type, "length") and col_type.length
+                if widget_cls == TextInputWidget and has_length:
+                    return TextInputWidget(maxlength=col_type.length)
+                return widget_cls()
+
+        # Handle Python built-in types (used by SQLModel)
+        if col_type in self.PYTHON_TYPE_MAP:
+            import sqlalchemy as sa
+
+            sa_type_name = self.PYTHON_TYPE_MAP[col_type]
+            sa_type = getattr(sa, sa_type_name, None)
+            if sa_type is not None:
+                for sa_registered_type, widget_cls in self._registry.type_map.items():
+                    if sa_type is sa_registered_type or (
+                        isinstance(sa_type, type) and isinstance(sa_type(), sa_registered_type)
+                    ):
+                        return widget_cls()
+
+        from fastapi_admin_kit.widgets.inputs import TextInputWidget
+
+        return TextInputWidget()