Migration von Django Admin

Wenn Sie Django Admin kennen, wird Ihnen starlette-admin vertraut vorkommen. Beide erzeugen eine Admin-Oberfläche aus deklarativer Konfiguration pro Modell, und beide unterstützen Inline-Bearbeitung, Batch-Aktionen und Berechtigungen pro Anfrage.

Die Unterschiede sind struktureller Natur. starlette-admin läuft auf jeder ASGI-Anwendung, statt Django vorauszusetzen, arbeitet mit mehreren ORMs und erlaubt es Ihnen, Ihre eigene Authentifizierung anzubinden, statt ein eingebautes Benutzermodell vorzugeben.

Dieser Leitfaden ordnet jedes zentrale ModelAdmin-Konzept seiner starlette-admin-Entsprechung zu – mit Code im direkten Vergleich.

Mentales Modell

Registrieren eines Modells

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

Zwei strukturelle Unterschiede fallen besonders auf:

1. Eine Feldliste steuert jede Seite. fields ist die alleinige Quelle der Wahrheit. Für Abweichungen pro Seite verwenden Sie anschließend exclude_fields_from_list, exclude_fields_from_detail, exclude_fields_from_create und exclude_fields_from_edit.
2. Die Admin-Instanz besitzt die Datenbank-Engine. Sie übergeben keine Session an die einzelnen Views.

Optionen der Listenseite

Formulare

Fieldsets-Beispiel

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 geht über Fieldsets hinaus: Sie können damit Tabs, responsive Grids und verschachtelte Layouts erstellen. Siehe Formularlayout.

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 erkennt den Fremdschlüssel, wenn dieser eindeutig ist, und unterstützt zusammengesetzte Fremdschlüssel. Fortgeschrittene Konfigurationen finden Sie unter Inline-Formulare.

Aktionen

@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")

Wo Django Admin ein QuerySet übergibt, erhält der Handler in starlette-admin ein ActionSelection-Objekt. Es löst Zeilen, Primärschlüssel und aktive Filter verzögert (lazy) auf und verhält sich genauso, wenn ein Benutzer alle übereinstimmenden Datensätze auswählt.

Aktionen können außerdem ein eigenes HTML-Formular innerhalb des Bestätigungsdialogs rendern – in Django Admin entspräche das dem Bau einer separaten Zwischenseite. Für Operationen auf Zeilenebene verwenden Sie @row_action und @link_row_action; dafür existiert kein Pendant in Django Admin.

Berechtigungen und Authentifizierung

Django Admin delegiert an django.contrib.auth. starlette-admin zerlegt das Problem in zwei Teile: Ein AuthProvider beantwortet die Frage „Wer ist dieser Benutzer?“, und die Methoden pro View beantworten die Frage „Was darf dieser Benutzer tun?“.

Die folgende View beschränkt das Löschen auf Benutzer mit der Rolle admin:

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

Jede can_*-Methode erhält die Anfrage, sodass Ihre Autorisierungsentscheidungen auf den aktuellen Benutzer, HTTP-Header oder beliebige andere Angaben der Anfrage zugreifen können.

Save-Hooks und Signale

Globale Konfiguration

Was Sie durch den Wechsel gewinnen

• Durchgängig asynchron: Handler, Lifecycle-Hooks und Widget-Callbacks können alle Coroutines sein, die auf Ihrer bestehenden Event-Loop laufen – neben Ihren FastAPI-Endpoints.
• Datenbankflexibilität: Dieselbe Admin-Konfiguration gilt unabhängig davon, ob Sie SQLAlchemy, SQLModel, MongoDB über MongoEngine oder Beanie oder Tortoise ORM verwenden.
• Export und Import eingebaut: CSV, JSON und PDF, dazu Excel und weitere Formate über tablib. Exportieren Sie Datensätze direkt oder importieren Sie Massendaten über einen Wizard mit vorangestellter Vorschau, der Validierung auf Zeilenebene erzwingt und optionale Upserts per Primärschlüssel unterstützt. Siehe Export und Import.
• Dashboard-Widgets: Stat-Karten, ApexCharts und Layout-Grids lassen sich zu Indexseiten und Custom Views kombinieren, sodass Sie kein externes Theme-Paket benötigen, um ein Dashboard zu bauen. Siehe Custom Views und Widgets.
• Moderne Benutzeroberfläche: Tabler (Bootstrap 5) bietet Dark Mode, Umschalter für die Spaltensichtbarkeit und Suchhervorhebung ab Werk.

Was Sie selbst bereitstellen müssen

• Authentifizierung: Es gibt kein gebündeltes Benutzermodell und keine Berechtigungsdatenbank. Implementieren Sie AuthProvider.authenticate() gegen den Datenspeicher, den Ihre Anwendung bereits verwendet.
• Audit-Logging: starlette-admin erzeugt keine LogEntry-Tabelle. Verbinden Sie das Event-System mit Ihrer eigenen Audit-Tabelle.
• UI-Konfiguration auf Modellebene: Django-Komfortfunktionen wie choices, verbose_name und Validatoren auf Modellebene werden nicht übernommen. Deklarieren Sie sie stattdessen am starlette-admin-Feld, mit EnumField, label= und validators=.