Migración desde Django Admin

Si usted conoce Django Admin, starlette-admin le resultará familiar. Ambos generan una interfaz de administración a partir de una configuración declarativa por modelo, y ambos admiten edición en línea, acciones por lotes y permisos por petición.

Las diferencias son estructurales. starlette-admin se ejecuta sobre cualquier aplicación ASGI en lugar de requerir Django, funciona con varios ORM y le permite incorporar su propia autenticación en lugar de imponer un modelo de usuario integrado.

Esta guía mapea cada concepto principal de ModelAdmin a su equivalente en starlette-admin, con código lado a lado.

Modelo mental

Registro de un modelo

from django.contrib import admin
from .models import Post


@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ["title", "published", "created_at"]
    search_fields = ["title", "content"]

from starlette_admin.contrib.sqla import Admin, ModelView


class PostView(ModelView):
    fields = ["id", "title", "content", "published", "created_at"]
    exclude_fields_from_list = ["content"]
    searchable_fields = ["title", "content"]


admin = Admin(engine, title="Blog Admin", secret_key="change-me")
admin.add_view(PostView(Post, icon="fa fa-newspaper"))
admin.mount_to(app)  # app is your FastAPI or Starlette instance

Dos diferencias estructurales destacan:

1. Una sola lista de campos controla todas las páginas. fields es la única fuente de verdad. Después, usted utiliza exclude_fields_from_list, exclude_fields_from_detail, exclude_fields_from_create y exclude_fields_from_edit para las variaciones por página.
2. La instancia de Admin es propietaria del motor de base de datos. Usted no pasa una sesión a cada vista.

Opciones de la página de lista

Formularios

Ejemplo de fieldsets

class PostAdmin(admin.ModelAdmin):
    fieldsets = [
        ("Content", {"fields": ["title", "body"]}),
        ("Publication", {"fields": ["published", "created_at"]}),
    ]

from starlette_admin import FieldsetWidget


class PostView(ModelView):
    fields = ["id", "title", "body", "published", "created_at"]
    form_layout = [
        FieldsetWidget(legend="Content", children=["title", "body"]),
        FieldsetWidget(legend="Publication", children=["published", "created_at"]),
    ]

form_layout va más allá de los fieldsets: puede construir pestañas, cuadrículas responsivas y diseños anidados. Consulte Form Layout.

Inlines

class CommentInline(admin.TabularInline):
    model = Comment
    extra = 1


class ArticleAdmin(admin.ModelAdmin):
    inlines = [CommentInline]

from starlette_admin.contrib.sqla import InlineModelView, ModelView


class CommentInline(InlineModelView):
    model = Comment
    fields = ["author", "body"]


class ArticleView(ModelView):
    inlines = [CommentInline]

starlette-admin detecta la clave foránea cuando no es ambigua, y admite claves foráneas compuestas. Consulte Inline Forms para configuraciones avanzadas.

Acciones

@admin.action(description="Mark selected articles as published")
def make_published(modeladmin, request, queryset):
    queryset.update(published=True)


class ArticleAdmin(admin.ModelAdmin):
    actions = [make_published]

from starlette_admin import ActionSelection, action, flash


class ArticleView(ModelView):
    actions = ["make_published", "delete"]

    @action(
        name="make_published",
        text="Mark selected articles as published",
        confirmation="Publish the selected articles?",
    )
    async def make_published(
        self, request: Request, selection: ActionSelection
    ) -> None:
        for article in await selection.rows():
            article.published = True
        flash(request, "Articles published")

Donde Django Admin pasa un QuerySet, el handler de starlette-admin recibe un objeto ActionSelection. Este resuelve filas, claves primarias y filtros activos de forma perezosa, y se comporta de la misma manera cuando el usuario selecciona todos los registros coincidentes.

Las acciones también pueden renderizar un formulario HTML personalizado dentro del diálogo de confirmación, lo que en Django Admin implica construir una página intermedia. Para operaciones por fila, utilice @row_action y @link_row_action, que no tienen equivalente en Django Admin.

Permisos y autenticación

Django Admin delega en django.contrib.auth. starlette-admin divide el problema en dos: un AuthProvider responde "quién es este usuario", y los métodos por vista responden "qué puede hacer".

La siguiente vista restringe la eliminación a los usuarios con el rol admin:

class ArticleView(ModelView):
    def can_delete(self, request: Request) -> bool:
        return "admin" in request.state.admin_user.roles

Cada método can_* recibe la petición, de modo que sus decisiones de autorización pueden leer el usuario actual, las cabeceras HTTP o cualquier otro dato de la petición.

Hooks de guardado y señales

Configuración global del sitio

Lo que gana al migrar

• Asíncrono de extremo a extremo: Los handlers, los lifecycle hooks y los callbacks de widgets pueden ser todos coroutines que se ejecutan en su event loop existente, junto a sus endpoints de FastAPI.
• Flexibilidad de base de datos: La misma configuración de administración aplica tanto si utiliza SQLAlchemy, SQLModel, MongoDB mediante MongoEngine o Beanie, como Tortoise ORM.
• Exportación e importación integradas: CSV, JSON y PDF, además de Excel y otros formatos a través de tablib. Exporte registros directamente, o importe datos masivos mediante un asistente con vista previa que aplica validación a nivel de fila y admite upserts opcionales de clave primaria. Consulte Export and Import.
• Widgets de dashboard: Tarjetas de estadísticas, ApexCharts y cuadrículas de diseño se componen en páginas index y custom views, de modo que no necesita un paquete de temas externo para construir un dashboard. Consulte Custom Views and Widgets.
• Interfaz de usuario moderna: Tabler (Bootstrap 5) le ofrece modo oscuro, interruptores de visibilidad de columnas y resaltado de búsquedas por defecto.

Lo que debe aportar usted

• Autenticación: No hay ningún modelo de usuario ni base de datos de permisos incluidos. Implemente AuthProvider.authenticate() contra el almacén de datos que su aplicación ya utiliza.
• Registro de auditoría: starlette-admin no genera una tabla LogEntry. Conecte el sistema de eventos a su propia tabla de auditoría.
• Configuración de UI a nivel de modelo: Las comodidades de Django como choices, verbose_name y validators a nivel de modelo no se transfieren. Declárelos en el campo de starlette-admin en su lugar, con EnumField, label= y validators=.