Migración desde Flask-Admin

starlette-admin surgió como una adaptación de los conceptos de Flask-Admin al ecosistema ASGI, por lo que la migración es directa. Usted sigue heredando de ModelView, lo configura con atributos de clase y lo registra en una instancia de Admin. La mayor parte del trabajo consiste en renombrar atributos y pasar del contexto de petición implícito de Flask al objeto request explícito de Starlette.

Esta guía mapea la API de Flask-Admin, atributo por atributo, a su equivalente en starlette-admin.

Modelo mental

Configuración

from flask import Flask
from flask_admin import Admin
from flask_admin.contrib.sqla import ModelView

app = Flask(__name__)
admin = Admin(app, name="My Admin", template_mode="bootstrap4")
admin.add_view(ModelView(Post, db.session))

from starlette.applications import Starlette
from starlette_admin.contrib.sqla import Admin, ModelView

app = Starlette()  # or FastAPI()
admin = Admin(engine, title="My Admin", secret_key="change-me")
admin.add_view(ModelView(Post))
admin.mount_to(app)

No existe un interruptor template_mode. La interfaz utiliza Tabler (Bootstrap 5) e incluye modo oscuro. Para cambiar el aspecto, escriba un BaseTheme personalizado o sobrescriba las plantillas.

Atributos de la página de listado

Atributos del formulario

Exportación e importación

class PostView(ModelView):
    can_export = True
    export_types = ["csv", "xlsx"]
    export_max_rows = 10000

class PostView(ModelView):
    exporters = ["csv", "xlsx", "pdf"]
    importers = ["csv", "xlsx"]
    exclude_fields_from_export = ["internal_notes"]

La exportación en CSV y JSON está activada por defecto. Los límites de filas se aplican automáticamente, y el escape de fórmulas de hojas de cálculo es una opción configurable del exporter. La importación, que Flask-Admin no ofrece, incluye un paso de vista previa con validación por fila y actualizaciones opcionales de registros existentes mediante la clave primaria. Consulte Exportación e Importación.

Acciones

from flask_admin.actions import action


class PostView(ModelView):
    @action("publish", "Publish", "Publish selected posts?")
    def action_publish(self, ids):
        query = Post.query.filter(Post.id.in_(ids))
        for post in query.all():
            post.published = True

from starlette_admin import ActionSelection, action, flash


class PostView(ModelView):
    actions = ["publish", "delete"]

    @action(
        name="publish",
        text="Publish",
        confirmation="Publish selected posts?",
    )
    async def publish(self, request: Request, selection: ActionSelection) -> None:
        for post in await selection.rows():
            post.published = True
        flash(request, "Posts published")

El handler recibe un objeto ActionSelection en lugar de identificadores crudos. Resuelve las filas de forma diferida, expone los filtros activos y funciona igual cuando un usuario selecciona todos los registros coincidentes en varias páginas. Las acciones también pueden mostrar un formulario HTML personalizado dentro del diálogo de confirmación. Para operaciones por fila, @row_action y @link_row_action sustituyen a los formatters de columna personalizados.

Permisos y control de acceso

Los indicadores de clase can_* de Flask-Admin se convierten en métodos por petición en starlette-admin, de modo que las decisiones de autorización pueden depender del usuario autenticado.

Con Flask-Admin, usted integra Flask-Login por su cuenta. starlette-admin incluye un AuthProvider con una página de inicio de sesión lista para usar, y usted implementa los métodos login, logout y authenticate contra su almacén de usuarios. Un OAuthProvider cubre los flujos de redirección OIDC. El usuario autenticado está disponible en todas partes como request.state.admin_user.

Hooks del ciclo de vida del modelo

Más allá de los hooks por vista, el sistema de eventos permite que un único handler observe todas las vistas. Flask-Admin no tiene equivalente.

from starlette_admin.events import AdminEvent, AfterCreateContext


async def audit(ctx: AfterCreateContext) -> None: ...


admin.events.on(AdminEvent.AFTER_CREATE, audit)

Vistas personalizadas y página de índice

Modelos inline

class ArticleView(ModelView):
    inline_models = [Comment]

from starlette_admin.contrib.sqla import InlineModelView, ModelView


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


class ArticleView(ModelView):
    inlines = [CommentInline]

Una clase explícita otorga a cada modelo inline toda la superficie de configuración de ModelView: selección de campos, validación y soporte de claves foráneas compuestas. Consulte Formularios Inline.

Internacionalización

Flask-Admin depende de Flask-Babel y del entorno de Flask circundante. starlette-admin utiliza en su lugar un objeto de configuración:

from starlette_admin import I18nConfig

admin = Admin(engine, i18n_config=I18nConfig(default_locale="fr"))

El renderizado de fechas y horas con zona horaria funciona de la misma manera, mediante TimezoneConfig. Consulte Internacionalización y Zonas Horarias.

Lo que gana al migrar

• Un stack asíncrono. Se ejecuta de forma nativa sobre FastAPI y Starlette, con soporte para SQLAlchemy asíncrono, Beanie y Tortoise ORM. Flask-Admin es síncrono.
• Funciones de seguridad integradas. La protección CSRF, la sanitización de nombres de archivos subidos, la verificación del contenido de imágenes y los límites de filas de exportación están activos desde el momento en que instancia Admin, y puede habilitar el escape de fórmulas de hojas de cálculo en los exporters. Consulte Seguridad.
• Importación de datos. Un paso de vista previa valida cada fila antes de escribir nada. Flask-Admin no tiene función de importación.
• Un sistema de widgets para dashboards. Construya páginas de índice y vistas personalizadas en Python en lugar de escribir plantillas a mano.
• Diseño moderno. Una base de código mantenida activamente, con una interfaz pulida, modo oscuro incorporado y type hints de primera clase.

Lo que debe adaptar

• Objetos de petición explícitos. No existe un contexto de petición implícito. Cada hook y método de permisos recibe el request como parámetro.
• Handlers asíncronos. Los hooks y las acciones son corrutinas, así que mantenga fuera de ellos las llamadas bloqueantes o mueva ese trabajo a un hilo.
• No hay FileAdmin. Si su flujo de trabajo depende de explorar el sistema de archivos del servidor, starlette-admin no lo cubre.
• No hay modales de creación ni edición. Los formularios se muestran como páginas completas en lugar de modales emergentes.