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

fastapi_admin_kit/pagination/cursor.py

@@ -0,0 +1,97 @@
+"""Cursor-based (keyset) pagination using base64-encoded cursors."""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+
+from sqlalchemy import func, select
+
+from fastapi_admin_kit.pagination.base import BasePagination, PaginationResult
+
+
+class CursorPagination(BasePagination):
+    """Keyset pagination using opaque base64-encoded cursors.
+
+    Uses a configurable column (default: primary key) for cursor values.
+    Supports forward (after) and backward (before) navigation.
+    """
+
+    def __init__(self, cursor_column: str | None = None):
+        self.cursor_column = cursor_column
+
+    def _decode_cursor(self, cursor: str) -> Any:
+        """Decode base64 cursor to Python value."""
+        return json.loads(base64.b64decode(cursor))
+
+    def _encode_cursor(self, value: Any) -> str:
+        """Encode Python value to base64 cursor string."""
+        return base64.b64encode(json.dumps(value).encode()).decode()
+
+    async def paginate(
+        self,
+        stmt: Any,
+        session: Any,
+        per_page: int,
+        page: int = 1,
+        after: str | None = None,
+        before: str | None = None,
+        pk_col: Any = None,
+        model: Any = None,
+    ) -> PaginationResult:
+        # Determine cursor column
+        if self.cursor_column and model is not None:
+            col = getattr(model, self.cursor_column)
+        elif pk_col is not None:
+            col = pk_col
+        else:
+            raise ValueError(
+                "CursorPagination requires either cursor_column on a model "
+                "or pk_col to be provided."
+            )
+
+        # Apply cursor filter
+        if after:
+            cursor_val = self._decode_cursor(after)
+            stmt = stmt.where(col > cursor_val)
+        elif before:
+            cursor_val = self._decode_cursor(before)
+            stmt = stmt.where(col < cursor_val)
+            # For backward pagination, we need to reverse order then flip results
+            from sqlalchemy import desc as sa_desc
+
+            # Check current ordering and reverse it
+            stmt = stmt.order_by(sa_desc(col))
+
+        # Count filtered total
+        count_q = select(func.count()).select_from(stmt.subquery())
+        total = (await session.execute(count_q)).scalar() or 0
+
+        # Fetch per_page + 1 to detect has_next
+        stmt = stmt.limit(per_page + 1)
+        result = await session.execute(stmt)
+        items = list(result.unique().scalars().all())
+
+        # For backward pagination, reverse back to natural order
+        if before:
+            items = list(reversed(items))
+
+        has_next = len(items) > per_page
+        if has_next:
+            items = items[:per_page]
+
+        # Build next cursor from last item
+        next_cursor = None
+        if has_next and items:
+            last_val = getattr(items[-1], self.cursor_column or "id")
+            next_cursor = self._encode_cursor(last_val)
+
+        return PaginationResult(
+            items=items,
+            total=total,
+            per_page=per_page,
+            next_cursor=next_cursor,
+            has_next=has_next,
+            mode="cursor",
+        )

fastapi_admin_kit/pagination/dynamic.py

@@ -0,0 +1,48 @@
+"""Dynamic pagination — auto-selects offset vs cursor based on data volume."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import func, select
+
+from fastapi_admin_kit.pagination.base import BasePagination, PaginationResult
+from fastapi_admin_kit.pagination.cursor import CursorPagination
+from fastapi_admin_kit.pagination.offset import OffsetPagination
+
+
+class DynamicPagination(BasePagination):
+    """Automatically switches between offset and cursor pagination.
+
+    Uses offset for small datasets (fast page jumping),
+    cursor for large datasets (consistent performance at any depth).
+    """
+
+    def __init__(
+        self,
+        cursor_column: str | None = None,
+        threshold: int = 1000,
+    ):
+        self.cursor_column = cursor_column
+        self.threshold = threshold
+        self._offset = OffsetPagination()
+        self._cursor = CursorPagination(cursor_column=cursor_column)
+
+    async def paginate(
+        self,
+        stmt: Any,
+        session: Any,
+        per_page: int,
+        **kw: Any,
+    ) -> PaginationResult:
+        # Count total to decide strategy
+        count_q = select(func.count()).select_from(stmt.subquery())
+        total = (await session.execute(count_q)).scalar() or 0
+
+        if total <= self.threshold:
+            result = await self._offset.paginate(stmt, session, per_page, **kw)
+        else:
+            result = await self._cursor.paginate(stmt, session, per_page, **kw)
+
+        result.mode = "dynamic_offset" if total <= self.threshold else "dynamic_cursor"
+        return result

fastapi_admin_kit/pagination/offset.py

@@ -0,0 +1,42 @@
+"""Offset-based pagination (existing behavior)."""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+from sqlalchemy import func, select
+
+from fastapi_admin_kit.pagination.base import BasePagination, PaginationResult
+
+
+class OffsetPagination(BasePagination):
+    """Traditional page-number pagination using OFFSET/LIMIT."""
+
+    async def paginate(
+        self,
+        stmt: Any,
+        session: Any,
+        per_page: int,
+        page: int = 1,
+        **kw: Any,
+    ) -> PaginationResult:
+        count_q = select(func.count()).select_from(stmt.subquery())
+        total = (await session.execute(count_q)).scalar() or 0
+
+        total_pages = max(1, math.ceil(total / per_page))
+        page = max(1, min(page, total_pages))
+        offset = (page - 1) * per_page
+
+        stmt = stmt.offset(offset).limit(per_page)
+        result = await session.execute(stmt)
+        items = list(result.unique().scalars().all())
+
+        return PaginationResult(
+            items=items,
+            total=total,
+            per_page=per_page,
+            page=page,
+            total_pages=total_pages,
+            mode="offset",
+        )

fastapi_admin_kit/plugins/__init__.py

@@ -0,0 +1 @@
+"""Plugin system for extending admin functionality."""

fastapi_admin_kit/registry/__init__.py

@@ -0,0 +1,5 @@
+"""Registry package — AdminRegistry and related components."""
+
+from fastapi_admin_kit.registry.core import AdminRegistry, RegisteredModel
+
+__all__ = ["AdminRegistry", "RegisteredModel"]

fastapi_admin_kit/registry/core.py

@@ -0,0 +1,287 @@
+"""AdminRegistry — singleton holding all registered models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from fastapi_admin_kit.inspection.registry import ModelInspector
+from fastapi_admin_kit.registry.validation import ModelValidator
+
+if TYPE_CHECKING:
+    from fastapi_admin_kit.views import ModelAdmin
+    from fastapi_admin_kit.widgets.base import Widget
+    from fastapi_admin_kit.widgets.resolver import WidgetResolver
+
+
+@dataclass
+class RegisteredModel:
+    """Central dataclass holding a registered model and its admin config."""
+
+    model: type
+    admin: ModelAdmin
+    table_name: str
+    verbose_name: str
+    verbose_name_plural: str
+    columns: list = field(default_factory=list)
+    relationships: list = field(default_factory=list)
+    pk_field: str | tuple[str, ...] | None = "id"
+    _schemas: dict | None = field(default=None, repr=False)
+
+    def __post_init__(self) -> None:
+        # Find primary key
+        for col in self.columns:
+            if col.primary_key:
+                self.pk_field = col.name
+                break
+        # Ensure admin has reference to model for form field deduplication
+        if not hasattr(self.admin, "model") or self.admin.model is None:
+            self.admin.model = self.model
+
+    @property
+    def form_fields(self) -> list[Any]:
+        return self.admin.get_form_fields(
+            columns=self.columns,
+            relationships=self.relationships,
+        )
+
+    @property
+    def list_fields(self) -> list[str]:
+        if self.admin.list_display:
+            valid = {c.name for c in self.columns}
+            return [f for f in self.admin.list_display if f in valid]
+        return [c.name for c in self.columns if not c.primary_key]
+
+    def get_widget(
+        self, field_name: str, resolver: WidgetResolver | None = None
+    ) -> Widget:
+        from fastapi_admin_kit.inspection import auto_label
+        from fastapi_admin_kit.widgets.registry import widget_registry
+        from fastapi_admin_kit.widgets.relation import (
+            MultiRelationWidget,
+            RelationPickerWidget,
+        )
+        from fastapi_admin_kit.widgets.resolver import WidgetResolver
+
+        if resolver is None:
+            resolver = WidgetResolver(widget_registry)
+
+        overrides = getattr(self.admin, "formfield_overrides", {})
+        if field_name in overrides:
+            return overrides[field_name]
+
+        col = next((c for c in self.columns if c.name == field_name), None)
+        rel = next(
+            (r for r in self.relationships if r.name == field_name), None
+        )
+        if col is not None:
+            widget = resolver.resolve(col)
+            if (
+                isinstance(widget, RelationPickerWidget)
+                and not widget.related_table
+                and col.foreign_keys
+            ):
+                fk = col.foreign_keys[0]
+                widget.related_table = fk.column.table.name
+            return widget
+        if rel is not None:
+            related_verbose = auto_label(rel.target_model.__tablename__)
+            if rel.direction == "MANYTOONE" or not rel.uselist:
+                return RelationPickerWidget(
+                    related_table=rel.target_model.__tablename__,
+                    related_verbose=related_verbose,
+                )
+            return MultiRelationWidget(
+                related_table=rel.target_model.__tablename__,
+                related_verbose=related_verbose,
+            )
+        return resolver.resolve(  # type: ignore[arg-type]
+            type("_Col", (), {"type": type(None), "name": field_name})()
+        )
+
+
+class AdminRegistry:
+    """Singleton registry for admin models.
+
+    Uses dependency injection for ModelInspector and ModelValidator,
+    making the registry testable and separable from inspection/validation concerns.
+    """
+
+    _instance: AdminRegistry | None = None
+    _models: dict[str, RegisteredModel] = {}
+
+    def __new__(cls) -> AdminRegistry:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._models = {}
+        return cls._instance
+
+    def __init__(self) -> None:
+        """Initialize the registry with default inspector and validator."""
+        if not hasattr(self, "_inspector"):
+            self._inspector = ModelInspector()
+        if not hasattr(self, "_validator"):
+            self._validator = ModelValidator(self)
+
+    @property
+    def inspector(self) -> ModelInspector:
+        """Get the model inspector."""
+        return self._inspector
+
+    @inspector.setter
+    def inspector(self, value: ModelInspector) -> None:
+        """Set the model inspector."""
+        self._inspector = value
+
+    @property
+    def validator(self) -> ModelValidator:
+        """Get the model validator."""
+        return self._validator
+
+    @validator.setter
+    def validator(self, value: ModelValidator) -> None:
+        """Set the model validator."""
+        self._validator = value
+
+    def register(
+        self,
+        model: type,
+        admin_class: type[ModelAdmin] | None = None,
+    ) -> RegisteredModel:
+        """Register a model with the admin.
+
+        Args:
+            model: A SQLAlchemy declarative model class.
+            admin_class: Optional ModelAdmin subclass for the model.
+
+        Returns:
+            The registered model configuration.
+
+        Raises:
+            ValueError: If the model is not a valid SQLAlchemy model.
+        """
+        from fastapi_admin_kit.views import ModelAdmin
+
+        # Validate using the injected validator
+        self._validator.validate_model_registration(model, admin_class)
+
+        # Inspect using the injected inspector
+        columns, relationships = self._inspector.inspect_model(model)
+
+        admin = admin_class() if admin_class else ModelAdmin()
+        table_name = model.__tablename__
+        verbose_name = (
+            admin.verbose_name or table_name.replace("_", " ").title()
+        )
+        if admin.verbose_name_plural:
+            verbose_name_plural = admin.verbose_name_plural
+        elif (
+            verbose_name.endswith("y")
+            and len(verbose_name) > 1
+            and verbose_name[-2].lower() not in "aeiou"
+        ):
+            verbose_name_plural = f"{verbose_name[:-1]}ies"
+        else:
+            verbose_name_plural = f"{verbose_name}s"
+
+        registered = RegisteredModel(
+            model=model,
+            admin=admin,
+            table_name=table_name,
+            verbose_name=verbose_name,
+            verbose_name_plural=verbose_name_plural,
+            columns=columns,
+            relationships=relationships,
+        )
+
+        self._models[table_name] = registered
+        return registered
+
+    def get(self, table_name: str) -> RegisteredModel | None:
+        """Get a registered model by table name.
+
+        Args:
+            table_name: The table name to look up.
+
+        Returns:
+            The registered model, or None if not found.
+        """
+        return self._models.get(table_name)
+
+    def all(self) -> list[RegisteredModel]:
+        """Get all registered models.
+
+        Returns:
+            A list of all registered models.
+        """
+        return list(self._models.values())
+
+    def auto_discover(self) -> list[RegisteredModel]:
+        """Scan all subclasses of DeclarativeBase and register unregistered ones.
+
+        Also discovers SQLModel subclasses if SQLModel is installed.
+
+        Returns:
+            A list of newly registered models.
+        """
+        from sqlalchemy.orm import DeclarativeBase
+
+        discovered: list[RegisteredModel] = []
+        seen: set[type] = set()
+
+        # Discover SQLAlchemy DeclarativeBase subclasses
+        for subclass in _all_declarative_subclasses(DeclarativeBase):
+            if hasattr(subclass, "registry"):
+                for mapper in subclass.registry.mappers:
+                    cls = mapper.class_
+                    if cls not in seen:
+                        seen.add(cls)
+                        if (
+                            hasattr(cls, "__tablename__")
+                            and cls.__tablename__ not in self._models
+                        ):
+                            discovered.append(self.register(cls))
+
+        # Discover SQLModel subclasses (if installed)
+        try:
+            from sqlmodel import SQLModel
+
+            for subclass in _all_declarative_subclasses(SQLModel):
+                if hasattr(subclass, "registry"):
+                    for mapper in subclass.registry.mappers:
+                        cls = mapper.class_
+                        if cls not in seen:
+                            seen.add(cls)
+                            if (
+                                hasattr(cls, "__tablename__")
+                                and cls.__tablename__ not in self._models
+                            ):
+                                discovered.append(self.register(cls))
+        except ImportError:
+            pass
+
+        return discovered
+
+    def clear(self) -> None:
+        """Clear all registrations (useful for testing)."""
+        self._models.clear()
+
+
+def _all_declarative_subclasses(base: type) -> set[type]:
+    """Recursively collect all subclasses of *base*.
+
+    Args:
+        base: The base class to find subclasses of.
+
+    Returns:
+        A set of all subclasses.
+    """
+    result: set[type] = set()
+    work = [base]
+    while work:
+        cls = work.pop()
+        for sub in cls.__subclasses__():
+            if sub not in result:
+                result.add(sub)
+                work.append(sub)
+    return result

fastapi_admin_kit/registry/validation.py

@@ -0,0 +1,107 @@
+"""ModelValidator — validates model registration in AdminRegistry."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastapi_admin_kit.registry.core import AdminRegistry
+
+
+class ModelValidator:
+    """Validates model registration in AdminRegistry.
+
+    This class centralizes all validation logic, making it testable
+    and separable from the registry's storage and inspection concerns.
+    """
+
+    def __init__(self, registry: AdminRegistry) -> None:
+        """Initialize the validator with a reference to the registry.
+
+        Args:
+            registry: The AdminRegistry instance to validate against.
+        """
+        self._registry = registry
+
+    def validate_model_registration(
+        self,
+        model: type,
+        admin_class: type | None = None,
+    ) -> None:
+        """Validate that a model can be registered with the admin.
+
+        Args:
+            model: A SQLAlchemy declarative model class.
+            admin_class: Optional ModelAdmin subclass for the model.
+
+        Raises:
+            ValueError: If the model is not a valid SQLAlchemy model.
+            ValueError: If the model's table name conflicts with an existing registration.
+        """
+        self._validate_is_sqlalchemy_model(model)
+        self._check_table_name_conflicts(model)
+
+    def _validate_is_sqlalchemy_model(self, model: type) -> None:
+        """Validate that the model is a SQLAlchemy or SQLModel model.
+
+        Args:
+            model: A class to validate.
+
+        Raises:
+            ValueError: If the model is not a valid ORM model.
+        """
+        # SQLAlchemy models always have __tablename__
+        if hasattr(model, "__tablename__"):
+            return
+
+        # SQLModel with table=True always has __tablename__ via metaclass
+        # SQLModel without table=True won't have it
+        try:
+            from sqlmodel import SQLModel
+
+            if isinstance(model, type) and issubclass(model, SQLModel):
+                # Check if it's a table model (has registry = table is created)
+                has_table = getattr(model, "table", False) or hasattr(
+                    model, "metadata"
+                )
+                if not has_table:
+                    raise ValueError(
+                        f"{model.__name__} is a SQLModel but has no table. "
+                        f"Use SQLModel(table=True) to create a table model."
+                    )
+        except ImportError:
+            pass
+
+        if not hasattr(model, "__tablename__"):
+            raise ValueError(
+                f"{model.__name__} is not a SQLAlchemy model (no __tablename__)"
+            )
+
+    def _check_table_name_conflicts(self, model: type) -> None:
+        """Check for table name conflicts with existing registrations.
+
+        Args:
+            model: A SQLAlchemy declarative model class.
+
+        Raises:
+            ValueError: If the table name is already registered.
+        """
+        table_name = model.__tablename__
+        existing = self._registry.get(table_name)
+        if existing is not None and existing.model is not model:
+            raise ValueError(
+                f"Table name '{table_name}' is already registered for "
+                f"model {existing.model.__name__}. "
+                f"Cannot register {model.__name__} with the same table name."
+            )
+
+    def check_table_name_conflicts(self, table_name: str) -> bool:
+        """Check if a table name is already registered.
+
+        Args:
+            table_name: The table name to check.
+
+        Returns:
+            True if the table name is already registered, False otherwise.
+        """
+        return self._registry.get(table_name) is not None

fastapi_admin_kit/registry.py

@@ -0,0 +1,15 @@
+"""AdminRegistry — singleton holding all registered models.
+
+This module provides backward-compatible imports for the registry package.
+The actual implementation is in fastapi_admin_kit.registry.core.
+"""
+
+from __future__ import annotations
+
+from fastapi_admin_kit.registry.core import (
+    AdminRegistry,
+    RegisteredModel,
+    _all_declarative_subclasses,
+)
+
+__all__ = ["AdminRegistry", "RegisteredModel", "_all_declarative_subclasses"]