Traducción automática supervisada

Este contenido se traduce mediante generación automática guiada por glosarios y guías de estilo revisados por personas. Dado que el texto no se revisa manualmente línea por línea, pueden producirse errores ocasionales o expresiones poco naturales.

En caso de cualquier discrepancia, la versión en inglés constituye la autoridad y la fuente de referencia.

Inicio rápido

Cree una interfaz de administración CRUD completamente funcional para un blog en cuestión de minutos, con formularios, listas, búsqueda, importación y exportación generados automáticamente a partir de sus modelos de datos.

Instalación

Instale los paquetes necesarios utilizando su gestor de paquetes preferido:

pipuv

pip install starlette-admin sqlalchemy "fastapi[standard]"

uv add starlette-admin sqlalchemy "fastapi[standard]"

Note

El paquete fastapi[standard] incluye la CLI de FastAPI, que le permite iniciar el servidor de desarrollo ejecutando fastapi dev.

El ejemplo completo

Cree un archivo llamado main.py y añada el siguiente código:

from contextlib import asynccontextmanager
from datetime import datetime, timezone

from fastapi import FastAPI
from sqlalchemy import create_engine
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from starlette_admin.contrib.sqla import Admin, ModelView

engine = create_engine("sqlite:///blog.db", connect_args={"check_same_thread": False})


class Base(DeclarativeBase):
    pass


class Post(Base):
    __tablename__ = "posts"

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str]
    content: Mapped[str]
    published: Mapped[bool] = mapped_column(default=False)
    created_at: Mapped[datetime] = mapped_column(
        default=lambda: datetime.now(timezone.utc)
    )


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


@asynccontextmanager
async def lifespan(app: FastAPI):
    Base.metadata.create_all(engine)
    yield


# Note: This can also be replaced by Starlette(lifespan=lifespan)
app = FastAPI(lifespan=lifespan)

admin = Admin(engine, title="Blog Admin", secret_key="change-me")
admin.add_view(PostView(Post, icon="fa fa-newspaper"))
admin.mount_to(app)

Ejecute la aplicación

Inicie el servidor de desarrollo:

pipuv

fastapi dev

uv run -- fastapi dev

Abra un navegador y acceda a http://127.0.0.1:8000/admin.

En la barra lateral, seleccione Posts y, a continuación, Create. Ahora puede acceder a las páginas de lista paginada, detalle, creación, edición y eliminación. El sistema genera automáticamente todas estas interfaces a partir de la definición de su modelo.

Cómo funciona

Las siguientes secciones explican los componentes principales de la aplicación.

El modelo

class Post(Base):
    __tablename__ = "posts"

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str]
    content: Mapped[str]
    published: Mapped[bool] = mapped_column(default=False)
    created_at: Mapped[datetime] = mapped_column(
        default=lambda: datetime.now(timezone.utc)
    )

Este código utiliza SQLAlchemy 2.0 estándar. El paquete starlette-admin lee los metadatos de las columnas mapeadas a estos atributos para determinar el campo HTML exacto que debe generar. Por ejemplo, crea un campo de texto para str, una casilla de verificación para bool y un selector de fecha y hora para datetime.

La vista

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

PostView actúa como el objeto central de este recurso. El atributo fields controla qué columnas aparecen en la lista y en el formulario, mientras que searchable_fields habilita la barra de búsqueda. Toda la configuración relativa al aspecto y comportamiento de Post en el panel de administración reside en esta única clase.

Note

El ejemplo importa ModelView desde starlette_admin.contrib.sqla porque se basa en SQLAlchemy. Si utiliza otro backend, como Beanie, MongoEngine o Tortoise ORM, debe importar ModelView desde el paquete contrib correspondiente. La API de configuración se mantiene consistente en todos los backends compatibles.

El admin

admin = Admin(engine, title="Blog Admin", secret_key="change-me")
admin.add_view(PostView(Post, icon="fa fa-newspaper"))
admin.mount_to(app)

La clase Admin conecta el motor de base de datos con la interfaz de usuario.

add_view registra su vista en la barra lateral. El parámetro opcional icon acepta cualquier clase válida de Font Awesome.
mount_to adjunta la aplicación de administración a su aplicación de FastAPI o Starlette en la ruta /admin.

Warning

El parámetro secret_key firma las cookies de los datos de sesión, incluidos los mensajes flash y la protección CSRF. En entornos de producción, debe reemplazar el valor del ejemplo por una cadena larga, aleatoria y generada de forma segura. Nunca utilice un valor de marcador de posición en un despliegue real.

Añada un segundo modelo

Puede registrar un número ilimitado de modelos. Por ejemplo, para añadir un modelo Tag y su vista correspondiente, defina las clases y llame de nuevo a add_view:

class Tag(Base):
    __tablename__ = "tags"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]


class TagView(ModelView):
    fields = ["id", "name"]
    searchable_fields = ("name",)


admin.add_view(PostView(Post, icon="fa fa-newspaper"))
admin.add_view(TagView(Tag, icon="fa fa-tag"))

Actualice la ventana del navegador para ver tanto Posts como Tags en la barra lateral. Cada recurso cuenta ahora con sus propias páginas de lista, creación, edición y eliminación totalmente funcionales.

Próximos pasos

Concepts: Aprenda la terminología de los conceptos presentados aquí para navegar mejor por la Guía de usuario.
Admin: Descubra todas las opciones de Admin(...), incluyendo marca, temas, autenticación, seguridad e internacionalización.
Views: Explore todas las opciones de configuración de ModelView disponibles para personalizar la presentación de sus datos.