FastAdmin | Documentation
- Version: 0.4.7
- Author: Seva D.
- Created: 7 March 2023
- Updated: 11 March 2026
Introduction
FastAdmin is an easy-to-use admin dashboard for FastAPI, Django, and Flask, inspired by Django Admin.
FastAdmin is built with relationships in mind and admiration for Django Admin. Its design focuses on making it as easy as possible to configure your admin dashboard for FastAPI, Django, or Flask.
FastAdmin aims to be minimal, functional, and familiar.
Getting Started
If you have questions beyond this documentation, feel free to email us.
Installation
Follow the steps below to set up FastAdmin:
Install the package with pip:
On zsh and macOS, use quotes: pip install 'fastadmin[fastapi,django]'
pip install fastadmin[fastapi,django] # FastAPI with Django ORM
pip install fastadmin[fastapi,tortoise-orm] # FastAPI with Tortoise ORM
pip install fastadmin[fastapi,pony] # FastAPI with Pony ORM
pip install fastadmin[fastapi,sqlalchemy] # FastAPI with SQLAlchemy (includes greenlet)
pip install fastadmin[django] # Django with Django ORM
pip install fastadmin[django,pony] # Django with Pony ORM
pip install fastadmin[flask,sqlalchemy] # Flask with SQLAlchemy (includes greenlet)
Or install with Poetry:
poetry add 'fastadmin[fastapi,django]'
poetry add 'fastadmin[fastapi,tortoise-orm]'
poetry add 'fastadmin[fastapi,pony]'
poetry add 'fastadmin[fastapi,sqlalchemy]'
poetry add 'fastadmin[django]'
poetry add 'fastadmin[django,pony]'
poetry add 'fastadmin[flask,sqlalchemy]'
When using SQLAlchemy, the greenlet package is required (included in the fastadmin[sqlalchemy] extra).
Configure the required settings with environment variables:
You can add these variables to a .env file and load them with python-dotenv. See all settings in the full documentation.
export ADMIN_USER_MODEL=User
export ADMIN_USER_MODEL_USERNAME_FIELD=username
export ADMIN_SECRET_KEY=secret_key
Settings
The following settings have default values:
Set environment variables or create a .env file and load it with the python-dotenv package.
class Settings:
"""Settings"""
# This value is the prefix you used for mounting FastAdmin app for FastAPI.
ADMIN_PREFIX: str = os.getenv("ADMIN_PREFIX", "admin")
# This value is the site name on sign-in page and on header.
ADMIN_SITE_NAME: str = os.getenv("ADMIN_SITE_NAME", "FastAdmin")
# This value is the logo path on sign-in page.
ADMIN_SITE_SIGN_IN_LOGO: str = os.getenv("ADMIN_SITE_SIGN_IN_LOGO", "/admin/static/images/sign-in-logo.svg")
# This value is the logo path on header.
ADMIN_SITE_HEADER_LOGO: str = os.getenv("ADMIN_SITE_HEADER_LOGO", "/admin/static/images/header-logo.svg")
# This value is the favicon path.
ADMIN_SITE_FAVICON: str = os.getenv("ADMIN_SITE_FAVICON", "/admin/static/images/favicon.png")
# This value is the primary color for FastAdmin.
ADMIN_PRIMARY_COLOR: str = os.getenv("ADMIN_PRIMARY_COLOR", "#009485")
# This value is the session id key to store session id in http only cookies.
ADMIN_SESSION_ID_KEY: str = os.getenv("ADMIN_SESSION_ID_KEY", "admin_session_id")
# This value is the expired_at period (in sec) for session id.
ADMIN_SESSION_EXPIRED_AT: int = os.getenv("ADMIN_SESSION_EXPIRED_AT", 144000) # in sec
# This value is the date format for JS widgets.
ADMIN_DATE_FORMAT: str = os.getenv("ADMIN_DATE_FORMAT", "YYYY-MM-DD")
# This value is the datetime format for JS widgets.
ADMIN_DATETIME_FORMAT: str = os.getenv("ADMIN_DATETIME_FORMAT", "YYYY-MM-DD HH:mm")
# This value is the time format for JS widgets.
ADMIN_TIME_FORMAT: str = os.getenv("ADMIN_TIME_FORMAT", "HH:mm:ss")
# This value is the name for User db/orm model class for authentication.
ADMIN_USER_MODEL: str = os.getenv("ADMIN_USER_MODEL")
# This value is the username field for User db/orm model for for authentication.
ADMIN_USER_MODEL_USERNAME_FIELD: str = os.getenv("ADMIN_USER_MODEL_USERNAME_FIELD")
# This value is the key to securing signed data - it is vital you keep this secure,
# or attackers could use it to generate their own signed values.
ADMIN_SECRET_KEY: str = os.getenv("ADMIN_SECRET_KEY")
Settings without default values are required.
Model Admins
Registering Models
import os
import uuid
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager
os.environ["ADMIN_USER_MODEL"] = "User"
os.environ["ADMIN_USER_MODEL_USERNAME_FIELD"] = "username"
os.environ["ADMIN_SECRET_KEY"] = "secret"
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from models import BaseEvent, Event, Tournament, User, UserAttachment
from tortoise.contrib.fastapi import RegisterTortoise
from fastadmin import (
TortoiseInlineModelAdmin,
TortoiseModelAdmin,
WidgetActionArgumentProps,
WidgetActionChartProps,
WidgetActionFilter,
WidgetActionInputSchema,
WidgetActionParentArgumentProps,
WidgetActionProps,
WidgetActionResponseSchema,
WidgetActionType,
WidgetType,
action,
display,
)
from fastadmin import fastapi_app as admin_app
from fastadmin import (
register,
widget_action,
)
class UserAttachmentModelInline(TortoiseInlineModelAdmin):
model = UserAttachment
formfield_overrides = { # noqa: RUF012
"attachment_url": (
WidgetType.UploadFile,
{
"required": True,
},
),
}
async def upload_file(
self,
field_name: str,
file_name: str,
file_content: bytes,
) -> None:
# save file to media directory or to s3/filestorage here
return f"/media/{file_name}"
@register(User)
class UserModelAdmin(TortoiseModelAdmin):
menu_section = "Users"
list_display = ("id", "username", "is_superuser")
list_display_links = ("id", "username")
list_filter = ("id", "username", "is_superuser")
search_fields = ("username",)
formfield_overrides = { # noqa: RUF012
"username": (WidgetType.SlugInput, {"required": True}),
"password": (WidgetType.PasswordInput, {"passwordModalForm": True}),
"avatar_url": (
WidgetType.UploadImage,
{
"required": False,
# Disable crop image for upload field
# "disableCropImage": True,
},
),
}
inlines = (UserAttachmentModelInline,)
widget_actions = (
"sales_chart",
"sales_area_chart",
"sales_column_chart",
"sales_bar_chart",
"sales_pie_chart",
"sales_action",
)
async def authenticate(self, username: str, password: str) -> uuid.UUID | int | None:
obj = await self.model_cls.filter(username=username, password=password, is_superuser=True).first()
if not obj:
return None
return obj.id
async def change_password(self, id: uuid.UUID | int, password: str) -> None:
user = await self.model_cls.filter(id=id).first()
if not user:
return
# direct saving password is only for tests - use hash
user.password = password
await user.save()
async def upload_file(
self,
field_name: str,
file_name: str,
file_content: bytes,
) -> None:
# save file to media directory or to s3/filestorage here
return f"/media/{file_name}"
async def pre_generate_models_schema(self) -> None:
model_cls: User = self.model_cls
options = await model_cls.all().values_list("username", flat=True)
# inject options to the class
widget_action_props: WidgetActionProps = self.__class__.sales_action.widget_action_props
for argument in widget_action_props.arguments:
if argument.name == "username":
argument.widget_props["options"] = [{"label": option, "value": option} for option in options]
break
@widget_action(
widget_action_type=WidgetActionType.ChartLine,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Sales": "#1677ff",
"Sales 2": "#52c41a",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="x",
widget_type=WidgetType.DatePicker,
),
WidgetActionFilter(
field_name="y",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
],
tab="Analytics",
sub_tab="Sales",
title="Sales over time",
description="Line chart of sales",
width=24,
)
async def sales_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{
"x": "2026-01-01",
"y": 100,
"series": "Sales",
},
{
"x": "2026-01-02",
"y": 200,
"series": "Sales",
},
{
"x": "2026-01-01",
"y": 300,
"series": "Sales 2",
},
{
"x": "2026-01-04",
"y": 400,
"series": "Sales 2",
},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartArea,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Online": "#722ed1",
"Retail": "#13c2c2",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="period",
widget_type=WidgetType.RangePicker,
),
WidgetActionFilter(
field_name="channel",
widget_type=WidgetType.Select,
widget_props={
"mode": "multiple",
"options": [
{"label": "Online", "value": "Online"},
{"label": "Retail", "value": "Retail"},
],
},
),
],
tab="Analytics",
title="Sales trend area",
description="Area chart of sales",
width=12,
)
async def sales_area_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 80, "series": "Online"},
{"x": "2026-01-02", "y": 120, "series": "Online"},
{"x": "2026-01-01", "y": 60, "series": "Retail"},
{"x": "2026-01-02", "y": 90, "series": "Retail"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartColumn,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"2025": "#fa8c16",
"2026": "#f5222d",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="year",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "2025", "value": "2025"},
{"label": "2026", "value": "2026"},
],
},
),
],
tab="Analytics",
title="Sales by month",
description="Column chart of sales",
width=12,
)
async def sales_column_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Jan", "y": 320, "series": "2025"},
{"x": "Feb", "y": 410, "series": "2025"},
{"x": "Jan", "y": 380, "series": "2026"},
{"x": "Feb", "y": 460, "series": "2026"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartBar,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Q1": "#2f54eb",
"Q2": "#eb2f96",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="quarter",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Q1", "value": "Q1"},
{"label": "Q2", "value": "Q2"},
],
},
),
],
tab="Analytics",
title="Sales by region",
description="Bar chart of sales",
width=12,
)
async def sales_bar_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "North", "y": 540, "series": "Q1"},
{"x": "South", "y": 420, "series": "Q1"},
{"x": "North", "y": 610, "series": "Q2"},
{"x": "South", "y": 480, "series": "Q2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartPie,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_color=[
"#1677ff",
"#52c41a",
"#faad14",
],
),
widget_action_filters=[
WidgetActionFilter(
field_name="month",
widget_type=WidgetType.DatePicker,
),
],
tab="Analytics",
title="Sales share",
description="Pie chart of sales share",
width=12,
)
async def sales_pie_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Online", "y": 45},
{"x": "Retail", "y": 30},
{"x": "Partners", "y": 25},
],
)
@widget_action(
widget_action_type=WidgetActionType.Action,
widget_action_props=WidgetActionProps(
arguments=[
# Example of using AsyncSelect widget with parentModel
WidgetActionArgumentProps(
name="user_id",
widget_type=WidgetType.AsyncSelect,
widget_props={
"required": True,
"parentModel": "User",
"idField": "id",
"labelFields": ["__str__", "id"],
},
),
# Example of using Select widget with dynamically loaded options
WidgetActionArgumentProps(
name="username",
widget_type=WidgetType.Select,
widget_props={
"required": True,
# dynamically load options from the database in pre_generate_models_schema method
"options": [],
},
),
# Example of using parent argument with filtered children arguments
WidgetActionArgumentProps(
name="type",
widget_type=WidgetType.Select,
widget_props={
"required": True,
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
WidgetActionArgumentProps(
name="sales_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="sales",
),
),
WidgetActionArgumentProps(
name="revenue_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="revenue",
),
),
],
),
tab="Data",
title="Get sales data",
description="Get sales data",
width=12,
)
async def sales_action(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{
"id": 1,
"name": "Sales",
},
{
"id": 2,
"name": "Sales",
},
{
"id": 3,
"name": "Sales",
},
],
)
class EventInlineModelAdmin(TortoiseInlineModelAdmin):
model = Event
@register(Tournament)
class TournamentModelAdmin(TortoiseModelAdmin):
list_display = ("id", "name")
inlines = (EventInlineModelAdmin,)
widget_actions = ("tournament_action",)
@widget_action(
widget_action_type=WidgetActionType.Action,
tab="Data",
title="Get tournament data",
description="Get tournament data",
width=12,
)
async def tournament_action(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{
"id": 1,
"name": "Tournament 1",
},
{
"id": 2,
"name": "Tournament 2",
},
{
"id": 3,
"name": "Tournament 3",
},
],
)
@register(BaseEvent)
class BaseEventModelAdmin(TortoiseModelAdmin):
pass
@register(Event)
class EventModelAdmin(TortoiseModelAdmin):
actions = ("make_is_active", "make_is_not_active")
list_display = (
"id",
"tournament_name",
"name_with_price",
"rating",
"event_type",
"is_active",
"started",
"start_time",
"date",
)
list_filter = ("event_type", "is_active", "start_time", "date", "event_type")
search_fields = ("name", "tournament__name")
list_select_related = ("tournament",)
@action(description="Make event active")
async def make_is_active(self, ids):
await self.model_cls.filter(id__in=ids).update(is_active=True)
@action
async def make_is_not_active(self, ids):
await self.model_cls.filter(id__in=ids).update(is_active=False)
@display
async def started(self, obj):
return bool(obj.start_time)
@display
async def tournament_name(self, obj):
tournament = await obj.tournament
return tournament.name
@display()
async def name_with_price(self, obj):
return f"{obj.name} - {obj.price}"
async def create_superuser():
await User.create(
username="admin",
password="admin",
is_superuser=True,
)
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
# RegisterTortoise sets up TortoiseContext so request handlers can use the DB
# (_enable_global_fallback=True by default for ASGI lifespan in a background task)
async with RegisterTortoise(
app=app,
db_url="sqlite://:memory:",
modules={"models": ["models"]},
generate_schemas=True,
use_tz=False,
timezone="UTC",
):
await create_superuser()
yield
app = FastAPI(lifespan=lifespan)
app.mount("/admin", admin_app)
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3030", "http://localhost:8090"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
import asyncio
import uuid
from django.db import models
from fastadmin import (
DjangoInlineModelAdmin,
DjangoModelAdmin,
WidgetActionArgumentProps,
WidgetActionChartProps,
WidgetActionFilter,
WidgetActionInputSchema,
WidgetActionParentArgumentProps,
WidgetActionProps,
WidgetActionResponseSchema,
WidgetActionType,
WidgetType,
action,
display,
register,
widget_action,
)
EventTypeEnum = (
("PRIVATE", "PRIVATE"),
("PUBLIC", "PUBLIC"),
)
class BaseModel(models.Model):
id = models.AutoField(primary_key=True)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
class Meta:
abstract = True
class User(BaseModel):
username = models.CharField(max_length=255)
password = models.CharField(max_length=255)
is_superuser = models.BooleanField(default=False)
avatar_url = models.ImageField(null=True)
attachment_url = models.FileField()
def __str__(self):
return self.username
class Meta:
db_table = "user"
class Tournament(BaseModel):
name = models.CharField(max_length=255)
def __str__(self):
return self.name
class Meta:
db_table = "tournament"
class BaseEvent(BaseModel):
name = models.CharField(max_length=255)
def __str__(self):
return self.name
class Meta:
db_table = "base_event"
class Event(BaseModel):
base = models.OneToOneField(BaseEvent, related_name="event", null=True, on_delete=models.SET_NULL)
name = models.CharField(max_length=255)
tournament = models.ForeignKey(Tournament, related_name="events", on_delete=models.CASCADE)
participants = models.ManyToManyField(User, related_name="events")
rating = models.IntegerField(default=0)
description = models.TextField(null=True)
event_type = models.CharField(max_length=255, default="PUBLIC", choices=EventTypeEnum)
is_active = models.BooleanField(default=True)
start_time = models.TimeField(null=True)
date = models.DateField(null=True)
latitude = models.FloatField(null=True)
longitude = models.FloatField(null=True)
price = models.DecimalField(max_digits=10, decimal_places=2, null=True)
json = models.JSONField(null=True)
def __str__(self):
return self.name
class Meta:
db_table = "event"
@register(User)
class UserModelAdmin(DjangoModelAdmin):
menu_section = "Users"
list_display = ("id", "username", "is_superuser")
list_display_links = ("id", "username")
list_filter = ("id", "username", "is_superuser")
search_fields = ("username",)
formfield_overrides = { # noqa: RUF012
"username": (WidgetType.SlugInput, {"required": True}),
"password": (WidgetType.PasswordInput, {"passwordModalForm": True}),
}
widget_actions = (
"sales_chart",
"sales_area_chart",
"sales_column_chart",
"sales_bar_chart",
"sales_pie_chart",
"sales_action",
)
def authenticate(self, username: str, password: str) -> uuid.UUID | int | None:
obj = self.model_cls.objects.filter(username=username, is_superuser=True).first()
if not obj:
return None
# if not obj.check_password(password):
# return None
return obj.id
def change_password(self, id: uuid.UUID | int, password: str) -> None:
user = self.model_cls.objects.filter(id=id).first()
if not user:
return
# direct saving password is only for tests - use hash
user.password = password
user.save()
def upload_file(
self,
field_name: str,
file_name: str,
file_content: bytes,
) -> str:
# save file to media directory or to s3/filestorage here
return f"/media/{file_name}"
async def pre_generate_models_schema(self) -> None:
def get_options() -> list:
return list(self.model_cls.objects.values_list("username", flat=True))
options = await asyncio.to_thread(get_options)
widget_action_props: WidgetActionProps = self.__class__.sales_action.widget_action_props
for argument in widget_action_props.arguments:
if argument.name == "username":
argument.widget_props["options"] = [{"label": option, "value": option} for option in options]
break
@widget_action(
widget_action_type=WidgetActionType.ChartLine,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Sales": "#1677ff",
"Sales 2": "#52c41a",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="x",
widget_type=WidgetType.DatePicker,
),
WidgetActionFilter(
field_name="y",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
],
tab="Analytics",
sub_tab="Sales",
title="Sales over time",
description="Line chart of sales",
width=24,
)
def sales_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 100, "series": "Sales"},
{"x": "2026-01-02", "y": 200, "series": "Sales"},
{"x": "2026-01-01", "y": 300, "series": "Sales 2"},
{"x": "2026-01-04", "y": 400, "series": "Sales 2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartArea,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Online": "#722ed1",
"Retail": "#13c2c2",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="period",
widget_type=WidgetType.RangePicker,
),
WidgetActionFilter(
field_name="channel",
widget_type=WidgetType.Select,
widget_props={
"mode": "multiple",
"options": [
{"label": "Online", "value": "Online"},
{"label": "Retail", "value": "Retail"},
],
},
),
],
tab="Analytics",
title="Sales trend area",
description="Area chart of sales",
width=12,
)
def sales_area_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 80, "series": "Online"},
{"x": "2026-01-02", "y": 120, "series": "Online"},
{"x": "2026-01-01", "y": 60, "series": "Retail"},
{"x": "2026-01-02", "y": 90, "series": "Retail"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartColumn,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"2025": "#fa8c16",
"2026": "#f5222d",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="year",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "2025", "value": "2025"},
{"label": "2026", "value": "2026"},
],
},
),
],
tab="Analytics",
title="Sales by month",
description="Column chart of sales",
width=12,
)
def sales_column_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Jan", "y": 320, "series": "2025"},
{"x": "Feb", "y": 410, "series": "2025"},
{"x": "Jan", "y": 380, "series": "2026"},
{"x": "Feb", "y": 460, "series": "2026"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartBar,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Q1": "#2f54eb",
"Q2": "#eb2f96",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="quarter",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Q1", "value": "Q1"},
{"label": "Q2", "value": "Q2"},
],
},
),
],
tab="Analytics",
title="Sales by region",
description="Bar chart of sales",
width=12,
)
def sales_bar_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "North", "y": 540, "series": "Q1"},
{"x": "South", "y": 420, "series": "Q1"},
{"x": "North", "y": 610, "series": "Q2"},
{"x": "South", "y": 480, "series": "Q2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartPie,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_color=[
"#1677ff",
"#52c41a",
"#faad14",
],
),
widget_action_filters=[
WidgetActionFilter(
field_name="month",
widget_type=WidgetType.DatePicker,
),
],
tab="Analytics",
title="Sales share",
description="Pie chart of sales share",
width=12,
)
def sales_pie_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Online", "y": 45},
{"x": "Retail", "y": 30},
{"x": "Partners", "y": 25},
],
)
@widget_action(
widget_action_type=WidgetActionType.Action,
widget_action_props=WidgetActionProps(
arguments=[
# Example of using AsyncSelect widget with parentModel
WidgetActionArgumentProps(
name="user_id",
widget_type=WidgetType.AsyncSelect,
widget_props={
"required": True,
"parentModel": "User",
"idField": "id",
"labelFields": ["__str__", "id"],
},
),
# Example of using Select widget with dynamically loaded options
WidgetActionArgumentProps(
name="username",
widget_type=WidgetType.Select,
widget_props={
"required": True,
# dynamically load options from the database in pre_generate_models_schema method
"options": [],
},
),
# Example of using parent argument with filtered children arguments
WidgetActionArgumentProps(
name="type",
widget_type=WidgetType.Select,
widget_props={
"required": True,
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
WidgetActionArgumentProps(
name="sales_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="sales",
),
),
WidgetActionArgumentProps(
name="revenue_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="revenue",
),
),
],
),
tab="Data",
title="Get sales data",
description="Get sales data",
width=12,
)
def sales_action(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"id": 1, "name": "Sales"},
{"id": 2, "name": "Sales"},
{"id": 3, "name": "Sales"},
],
)
class EventInlineModelAdmin(DjangoInlineModelAdmin):
model = Event
@register(Tournament)
class TournamentModelAdmin(DjangoModelAdmin):
list_display = ("id", "name")
inlines = (EventInlineModelAdmin,)
@register(BaseEvent)
class BaseEventModelAdmin(DjangoModelAdmin):
pass
@register(Event)
class EventModelAdmin(DjangoModelAdmin):
actions = ("make_is_active", "make_is_not_active")
list_display = ("id", "tournament", "name_with_price", "rating", "event_type", "is_active", "started")
list_filter = ("tournament", "event_type", "is_active")
search_fields = ("name", "tournament__name")
@action(description="Make event active")
def make_is_active(self, ids):
self.model_cls.objects.filter(id__in=ids).update(is_active=True)
@action
def make_is_not_active(self, ids):
self.model_cls.objects.filter(id__in=ids).update(is_active=False)
@display
def started(self, obj):
return bool(obj.start_time)
@display()
def name_with_price(self, obj):
return f"{obj.name} - {obj.price}"
import os
import uuid
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager
os.environ["ADMIN_USER_MODEL"] = "User"
os.environ["ADMIN_USER_MODEL_USERNAME_FIELD"] = "username"
os.environ["ADMIN_SECRET_KEY"] = "secret"
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from models import Base, BaseEvent, Event, Tournament, User, sqlalchemy_engine, sqlalchemy_sessionmaker
from sqlalchemy import select, update
from fastadmin import (
SqlAlchemyInlineModelAdmin,
SqlAlchemyModelAdmin,
WidgetActionArgumentProps,
WidgetActionChartProps,
WidgetActionFilter,
WidgetActionInputSchema,
WidgetActionParentArgumentProps,
WidgetActionProps,
WidgetActionResponseSchema,
WidgetActionType,
WidgetType,
action,
display,
)
from fastadmin import fastapi_app as admin_app
from fastadmin import (
register,
widget_action,
)
@register(User, sqlalchemy_sessionmaker=sqlalchemy_sessionmaker)
class UserModelAdmin(SqlAlchemyModelAdmin):
menu_section = "Users"
list_display = ("id", "username", "is_superuser")
list_display_links = ("id", "username")
list_filter = ("id", "username", "is_superuser")
search_fields = ("username",)
formfield_overrides = { # noqa: RUF012
"username": (WidgetType.SlugInput, {"required": True}),
"password": (WidgetType.PasswordInput, {"passwordModalForm": True}),
"avatar_url": (
WidgetType.UploadImage,
{
"required": False,
# Disable crop image for upload field
# "disableCropImage": True,
},
),
"attachment_url": (
WidgetType.UploadFile,
{
"required": True,
},
),
}
widget_actions = (
"sales_chart",
"sales_area_chart",
"sales_column_chart",
"sales_bar_chart",
"sales_pie_chart",
"sales_action",
)
async def authenticate(self, username: str, password: str) -> uuid.UUID | int | None:
sessionmaker = self.get_sessionmaker()
async with sessionmaker() as session:
query = select(self.model_cls).filter_by(username=username, password=password, is_superuser=True)
result = await session.scalars(query)
obj = result.first()
if not obj:
return None
return obj.id
async def change_password(self, id: uuid.UUID | int, password: str) -> None:
sessionmaker = self.get_sessionmaker()
async with sessionmaker() as session:
# use hash password for real usage
query = update(self.model_cls).where(User.id.in_([id])).values(password=password)
await session.execute(query)
await session.commit()
async def upload_file(
self,
field_name: str,
file_name: str,
file_content: bytes,
) -> None:
# save file to media directory or to s3/filestorage here
return f"/media/{file_name}"
async def pre_generate_models_schema(self) -> None:
sessionmaker = self.get_sessionmaker()
async with sessionmaker() as session:
result = await session.execute(select(self.model_cls.username))
options = list(result.scalars().all())
widget_action_props: WidgetActionProps = self.__class__.sales_action.widget_action_props
for argument in widget_action_props.arguments:
if argument.name == "username":
argument.widget_props["options"] = [{"label": option, "value": option} for option in options]
break
@widget_action(
widget_action_type=WidgetActionType.ChartLine,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Sales": "#1677ff",
"Sales 2": "#52c41a",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="x",
widget_type=WidgetType.DatePicker,
),
WidgetActionFilter(
field_name="y",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
],
tab="Analytics",
sub_tab="Sales",
title="Sales over time",
description="Line chart of sales",
width=24,
)
async def sales_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 100, "series": "Sales"},
{"x": "2026-01-02", "y": 200, "series": "Sales"},
{"x": "2026-01-01", "y": 300, "series": "Sales 2"},
{"x": "2026-01-04", "y": 400, "series": "Sales 2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartArea,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Online": "#722ed1",
"Retail": "#13c2c2",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="period",
widget_type=WidgetType.RangePicker,
),
WidgetActionFilter(
field_name="channel",
widget_type=WidgetType.Select,
widget_props={
"mode": "multiple",
"options": [
{"label": "Online", "value": "Online"},
{"label": "Retail", "value": "Retail"},
],
},
),
],
tab="Analytics",
title="Sales trend area",
description="Area chart of sales",
width=12,
)
async def sales_area_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 80, "series": "Online"},
{"x": "2026-01-02", "y": 120, "series": "Online"},
{"x": "2026-01-01", "y": 60, "series": "Retail"},
{"x": "2026-01-02", "y": 90, "series": "Retail"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartColumn,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"2025": "#fa8c16",
"2026": "#f5222d",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="year",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "2025", "value": "2025"},
{"label": "2026", "value": "2026"},
],
},
),
],
tab="Analytics",
title="Sales by month",
description="Column chart of sales",
width=12,
)
async def sales_column_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Jan", "y": 320, "series": "2025"},
{"x": "Feb", "y": 410, "series": "2025"},
{"x": "Jan", "y": 380, "series": "2026"},
{"x": "Feb", "y": 460, "series": "2026"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartBar,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Q1": "#2f54eb",
"Q2": "#eb2f96",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="quarter",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Q1", "value": "Q1"},
{"label": "Q2", "value": "Q2"},
],
},
),
],
tab="Analytics",
title="Sales by region",
description="Bar chart of sales",
width=12,
)
async def sales_bar_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "North", "y": 540, "series": "Q1"},
{"x": "South", "y": 420, "series": "Q1"},
{"x": "North", "y": 610, "series": "Q2"},
{"x": "South", "y": 480, "series": "Q2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartPie,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_color=[
"#1677ff",
"#52c41a",
"#faad14",
],
),
widget_action_filters=[
WidgetActionFilter(
field_name="month",
widget_type=WidgetType.DatePicker,
),
],
tab="Analytics",
title="Sales share",
description="Pie chart of sales share",
width=12,
)
async def sales_pie_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Online", "y": 45},
{"x": "Retail", "y": 30},
{"x": "Partners", "y": 25},
],
)
@widget_action(
widget_action_type=WidgetActionType.Action,
widget_action_props=WidgetActionProps(
arguments=[
# Example of using AsyncSelect widget with parentModel
WidgetActionArgumentProps(
name="user_id",
widget_type=WidgetType.AsyncSelect,
widget_props={
"required": True,
"parentModel": "User",
"idField": "id",
"labelFields": ["__str__", "id"],
},
),
# Example of using Select widget with dynamically loaded options
WidgetActionArgumentProps(
name="username",
widget_type=WidgetType.Select,
widget_props={
"required": True,
# dynamically load options from the database in pre_generate_models_schema method
"options": [],
},
),
# Example of using parent argument with filtered children arguments
WidgetActionArgumentProps(
name="type",
widget_type=WidgetType.Select,
widget_props={
"required": True,
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
WidgetActionArgumentProps(
name="sales_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="sales",
),
),
WidgetActionArgumentProps(
name="revenue_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="revenue",
),
),
],
),
tab="Data",
title="Get sales data",
description="Get sales data",
width=12,
)
async def sales_action(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"id": 1, "name": "Sales"},
{"id": 2, "name": "Sales"},
{"id": 3, "name": "Sales"},
],
)
class EventInlineModelAdmin(SqlAlchemyInlineModelAdmin):
model = Event
@register(Tournament, sqlalchemy_sessionmaker=sqlalchemy_sessionmaker)
class TournamentModelAdmin(SqlAlchemyModelAdmin):
list_display = ("id", "name")
inlines = (EventInlineModelAdmin,)
@register(BaseEvent, sqlalchemy_sessionmaker=sqlalchemy_sessionmaker)
class BaseEventModelAdmin(SqlAlchemyModelAdmin):
pass
@register(Event, sqlalchemy_sessionmaker=sqlalchemy_sessionmaker)
class EventModelAdmin(SqlAlchemyModelAdmin):
actions = ("make_is_active", "make_is_not_active")
list_display = ("id", "tournament", "name_with_price", "rating", "event_type", "is_active", "started")
list_filter = ("tournament", "event_type", "is_active")
search_fields = ("name", "tournament__name")
@action(description="Make event active")
async def make_is_active(self, ids):
sessionmaker = self.get_sessionmaker()
async with sessionmaker() as session:
query = update(Event).where(Event.id.in_(ids)).values(is_active=True)
await session.execute(query)
await session.commit()
@action
async def make_is_not_active(self, ids):
sessionmaker = self.get_sessionmaker()
async with sessionmaker() as session:
query = update(Event).where(Event.id.in_(ids)).values(is_active=False)
await session.execute(query)
await session.commit()
@display
async def started(self, obj):
return bool(obj.start_time)
@display()
async def name_with_price(self, obj):
return f"{obj.name} - {obj.price}"
async def init_db():
async with sqlalchemy_engine.begin() as c:
await c.run_sync(Base.metadata.drop_all)
await c.run_sync(Base.metadata.create_all)
async def create_superuser():
async with sqlalchemy_sessionmaker() as s:
user = User(
username="admin",
password="admin",
is_superuser=True,
attachment_url="/media/attachment.txt",
)
s.add(user)
await s.commit()
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
await init_db()
await create_superuser()
yield
app = FastAPI(lifespan=lifespan)
app.mount("/admin", admin_app)
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3030", "http://localhost:8090"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
import asyncio
import os
import uuid
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager
os.environ["ADMIN_USER_MODEL"] = "User"
os.environ["ADMIN_USER_MODEL_USERNAME_FIELD"] = "username"
os.environ["ADMIN_SECRET_KEY"] = "secret"
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from models import BaseEvent, Event, Tournament, User, db
from pony.orm import commit, db_session
from pony.orm import select as pony_select
from fastadmin import (
PonyORMInlineModelAdmin,
PonyORMModelAdmin,
WidgetActionArgumentProps,
WidgetActionChartProps,
WidgetActionFilter,
WidgetActionInputSchema,
WidgetActionParentArgumentProps,
WidgetActionProps,
WidgetActionResponseSchema,
WidgetActionType,
WidgetType,
action,
display,
)
from fastadmin import fastapi_app as admin_app
from fastadmin import (
register,
widget_action,
)
@register(User)
class UserModelAdmin(PonyORMModelAdmin):
menu_section = "Users"
list_display = ("id", "username", "is_superuser")
list_display_links = ("id", "username")
list_filter = ("id", "username", "is_superuser")
search_fields = ("username",)
formfield_overrides = { # noqa: RUF012
"username": (WidgetType.SlugInput, {"required": True}),
"password": (WidgetType.PasswordInput, {"passwordModalForm": True}),
"avatar_url": (
WidgetType.UploadImage,
{
"required": False,
# Disable crop image for upload field
# "disableCropImage": True,
},
),
"attachment_url": (
WidgetType.UploadFile,
{
"required": True,
},
),
}
widget_actions = (
"sales_chart",
"sales_area_chart",
"sales_column_chart",
"sales_bar_chart",
"sales_pie_chart",
"sales_action",
)
@db_session
def authenticate(self, username: str, password: str) -> uuid.UUID | int | None:
obj = next((f for f in User.select(username=username, password=password, is_superuser=True)), None) # fmt: skip
if not obj:
return None
return obj.id
@db_session
def change_password(self, id: uuid.UUID | int, password: str) -> None:
obj = next((f for f in self.model_cls.select(id=id)), None)
if not obj:
return
# direct saving password is only for tests - use hash
obj.password = password
commit()
def upload_file(
self,
field_name: str,
file_name: str,
file_content: bytes,
) -> str:
# save file to media directory or to s3/filestorage here
return f"/media/{file_name}"
async def pre_generate_models_schema(self) -> None:
def get_options() -> list:
with db_session:
return [u.username for u in pony_select(u for u in User)]
options = await asyncio.to_thread(get_options)
widget_action_props: WidgetActionProps = self.__class__.sales_action.widget_action_props
for argument in widget_action_props.arguments:
if argument.name == "username":
argument.widget_props["options"] = [{"label": option, "value": option} for option in options]
break
@widget_action(
widget_action_type=WidgetActionType.ChartLine,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Sales": "#1677ff",
"Sales 2": "#52c41a",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="x",
widget_type=WidgetType.DatePicker,
),
WidgetActionFilter(
field_name="y",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
],
tab="Analytics",
sub_tab="Sales",
title="Sales over time",
description="Line chart of sales",
width=24,
)
def sales_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 100, "series": "Sales"},
{"x": "2026-01-02", "y": 200, "series": "Sales"},
{"x": "2026-01-01", "y": 300, "series": "Sales 2"},
{"x": "2026-01-04", "y": 400, "series": "Sales 2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartArea,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Online": "#722ed1",
"Retail": "#13c2c2",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="period",
widget_type=WidgetType.RangePicker,
),
WidgetActionFilter(
field_name="channel",
widget_type=WidgetType.Select,
widget_props={
"mode": "multiple",
"options": [
{"label": "Online", "value": "Online"},
{"label": "Retail", "value": "Retail"},
],
},
),
],
tab="Analytics",
title="Sales trend area",
description="Area chart of sales",
width=12,
)
def sales_area_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 80, "series": "Online"},
{"x": "2026-01-02", "y": 120, "series": "Online"},
{"x": "2026-01-01", "y": 60, "series": "Retail"},
{"x": "2026-01-02", "y": 90, "series": "Retail"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartColumn,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"2025": "#fa8c16",
"2026": "#f5222d",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="year",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "2025", "value": "2025"},
{"label": "2026", "value": "2026"},
],
},
),
],
tab="Analytics",
title="Sales by month",
description="Column chart of sales",
width=12,
)
def sales_column_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Jan", "y": 320, "series": "2025"},
{"x": "Feb", "y": 410, "series": "2025"},
{"x": "Jan", "y": 380, "series": "2026"},
{"x": "Feb", "y": 460, "series": "2026"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartBar,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Q1": "#2f54eb",
"Q2": "#eb2f96",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="quarter",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Q1", "value": "Q1"},
{"label": "Q2", "value": "Q2"},
],
},
),
],
tab="Analytics",
title="Sales by region",
description="Bar chart of sales",
width=12,
)
def sales_bar_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "North", "y": 540, "series": "Q1"},
{"x": "South", "y": 420, "series": "Q1"},
{"x": "North", "y": 610, "series": "Q2"},
{"x": "South", "y": 480, "series": "Q2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartPie,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_color=[
"#1677ff",
"#52c41a",
"#faad14",
],
),
widget_action_filters=[
WidgetActionFilter(
field_name="month",
widget_type=WidgetType.DatePicker,
),
],
tab="Analytics",
title="Sales share",
description="Pie chart of sales share",
width=12,
)
def sales_pie_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Online", "y": 45},
{"x": "Retail", "y": 30},
{"x": "Partners", "y": 25},
],
)
@widget_action(
widget_action_type=WidgetActionType.Action,
widget_action_props=WidgetActionProps(
arguments=[
# Example of using AsyncSelect widget with parentModel
WidgetActionArgumentProps(
name="user_id",
widget_type=WidgetType.AsyncSelect,
widget_props={
"required": True,
"parentModel": "User",
"idField": "id",
"labelFields": ["__str__", "id"],
},
),
# Example of using Select widget with dynamically loaded options
WidgetActionArgumentProps(
name="username",
widget_type=WidgetType.Select,
widget_props={
"required": True,
# dynamically load options from the database in pre_generate_models_schema method
"options": [],
},
),
# Example of using parent argument with filtered children arguments
WidgetActionArgumentProps(
name="type",
widget_type=WidgetType.Select,
widget_props={
"required": True,
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
WidgetActionArgumentProps(
name="sales_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="sales",
),
),
WidgetActionArgumentProps(
name="revenue_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="revenue",
),
),
],
),
tab="Data",
title="Get sales data",
description="Get sales data",
width=12,
)
def sales_action(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"id": 1, "name": "Sales"},
{"id": 2, "name": "Sales"},
{"id": 3, "name": "Sales"},
],
)
class EventInlineModelAdmin(PonyORMInlineModelAdmin):
model = Event
@register(Tournament)
class TournamentModelAdmin(PonyORMModelAdmin):
list_display = ("id", "name")
inlines = (EventInlineModelAdmin,)
@register(BaseEvent)
class BaseEventModelAdmin(PonyORMModelAdmin):
pass
@register(Event)
class EventModelAdmin(PonyORMModelAdmin):
actions = ("make_is_active", "make_is_not_active")
list_display = ("id", "tournament", "name_with_price", "rating", "event_type", "is_active", "started")
list_filter = ("tournament", "event_type", "is_active")
search_fields = ("name", "tournament__name")
@action(description="Make event active")
@db_session
def make_is_active(self, ids):
# update(o.set(is_active=True) for o in self.model_cls if o.id in ids)
objs = self.model_cls.select(lambda o: o.id in ids)
for obj in objs:
obj.is_active = True
commit()
@action
@db_session
def make_is_not_active(self, ids):
# update(o.set(is_active=False) for o in self.model_cls if o.id in ids)
objs = self.model_cls.select(lambda o: o.id in ids)
for obj in objs:
obj.is_active = False
commit()
@display
@db_session
def started(self, obj):
return bool(obj.start_time)
@display()
@db_session
def name_with_price(self, obj):
return f"{obj.name} - {obj.price}"
def init_db():
# Use shared in-memory sqlite DB so tables are visible across connections/threads.
db.bind(provider="sqlite", filename=":sharedmemory:", create_db=True)
db.generate_mapping(create_tables=True)
@db_session
def create_superuser():
User(
username="admin",
password="admin",
is_superuser=True,
attachment_url="/media/attachment.txt",
)
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
init_db()
create_superuser()
yield
app = FastAPI(lifespan=lifespan)
app.mount("/admin", admin_app)
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3030", "http://localhost:8090"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
Authentication
You must implement authenticate and change_password in the model admin for the User model. See the example above.
Methods and Attributes
The following methods and attributes are available for model admins:
class BaseModelAdmin:
"""Base class for model admin"""
_request_context: ContextVar[Any | None]
_user_context: ContextVar[Any | None]
# Use it only if you use several orms in your project.
model_name_prefix: str | None = None
# A list of actions to make available on the change list page.
# You have to implement methods with names like action_name in your ModelAdmin class and decorate them with @action decorator.
# Example of usage:
#
# actions = ("make_published",)
# @action(
# description="Mark selected stories as published",
# )
# async def make_published(self, objs: list[Any]) -> ActionResponseSchema | None:
# ...
actions: Sequence[str] = ()
# Controls where on the page the actions bar appears.
# By default, the admin changelist displays actions at the top of the page (actions_on_top = False; actions_on_bottom = True).
# Example of usage: actions_on_top = True
actions_on_top: bool = False
# Controls where on the page the actions bar appears.
# By default, the admin changelist displays actions at the top of the page (actions_on_top = False; actions_on_bottom = True).
# Example of usage: actions_on_bottom = False
actions_on_bottom: bool = True
# Controls whether a selection counter is displayed next to the action dropdown. By default, the admin changelist will display it
# Example of usage: actions_selection_counter = False
actions_selection_counter: bool = True
# Not supported setting
# date_hierarchy
# This attribute overrides the default display value for record's fields that are empty (None, empty string, etc.). The default value is - (a dash).
# Example of usage: empty_value_display = "N/A"
empty_value_display: str = "-"
# This attribute, if given, should be a list of field names to exclude from the form.
# Example of usage: exclude = ("password", "otp")
exclude: Sequence[str] = ()
# Use the fields option to make simple layout changes in the forms on the “add” and “change” pages
# such as showing only a subset of available fields, modifying their order, or grouping them into rows.
# For more complex layout needs, see the fieldsets option.
# Example of usage: fields = ("id", "mobile_number", "email", "is_superuser", "is_active", "created_at")
fields: Sequence[str] = ()
# Set fieldsets to control the layout of admin “add” and “change” pages.
# fieldsets is a list of two-tuples, in which each two-tuple represents a fieldset on the admin form page. (A fieldset is a “section” of the form.)
fieldsets: Sequence[tuple[str | None, dict[str, Sequence[str]]]] = ()
# By default, a ManyToManyField is displayed in the admin dashboard with a select multiple.
# However, multiple-select boxes can be difficult to use when selecting many items.
# Adding a ManyToManyField to this list will instead use a nifty unobtrusive JavaScript “filter” interface that allows searching within the options.
# The unselected and selected options appear in two boxes side by side. See filter_vertical to use a vertical interface.
# Example of usage: filter_horizontal = ("groups", "user_permissions")
filter_horizontal: Sequence[str] = ()
# Same as filter_horizontal, but uses a vertical display of the filter interface with the box of unselected options appearing above the box of selected options.
# Example of usage: filter_vertical = ("groups", "user_permissions")
filter_vertical: Sequence[str] = ()
# Not supported setting
# form
# This provides a quick-and-dirty way to override some of the Field options for use in the admin.
# formfield_overrides is a dictionary mapping a field class to a dict
# of arguments to pass to the field at construction time.
# Example of usage:
# formfield_overrides = {
# "description": (WidgetType.RichTextArea, {})
# }
formfield_overrides: dict[str, tuple[WidgetType, dict]] = {} # noqa: RUF012
# Set list_display to control which fields are displayed on the list page of the admin.
# If you don't set list_display, the admin site will display a single column that displays the __str__() representation of each object
# Example of usage: list_display = ("id", "mobile_number", "email", "is_superuser", "is_active", "created_at")
list_display: Sequence[str] = ()
# Use list_display_links to control if and which fields in list_display should be linked to the “change” page for an object.
# Example of usage: list_display_links = ("id", "mobile_number", "email")
list_display_links: Sequence[str] = ()
# A dictionary containing the field names and the corresponding widget type and
# column widths (px, %) for the list view.
# Example of usage:
# list_display_widths = {
# "id": "100px",
# }
list_display_widths: dict[str, str] = {} # noqa: RUF012
# Set list_filter to activate filters in the tabel columns of the list page of the admin.
# Example of usage: list_filter = ("is_superuser", "is_active", "created_at")
list_filter: Sequence[str] = ()
# By default, applied filters are preserved on the list view after creating, editing, or deleting an object.
# You can have filters cleared by setting this attribute to False.
# Example of usage: preserve_filters = False
preserve_filters: bool = True
# Set list_max_show_all to control how many items can appear on a “Show all” admin change list page.
# The admin will display a “Show all” link on the change list only if the total result count is less than or equal to this setting. By default, this is set to 200.
# Example of usage: list_max_show_all = 100
list_max_show_all: int = 200
# Set list_per_page to control how many items appear on each paginated admin list page. By default, this is set to 10.
# Example of usage: list_per_page = 50
list_per_page = 10
# Set list_select_related to tell ORM to use select_related() in retrieving the list of objects on the admin list page.
# This can save you a bunch of database queries.
# Example of usage: list_select_related = ("user",)
list_select_related: Sequence[str] = ()
# Set ordering to specify how lists of objects should be ordered in the admin views.
# This should be a list or tuple in the same format as a model's ordering parameter.
# Example of usage: ordering = ("-created_at",)
ordering: Sequence[str] = ()
# Not supported setting
# paginator
# When set, the given fields will use a bit of JavaScript to populate from the fields assigned.
# The main use for this functionality is
# to automatically generate the value for SlugField fields from one or more other fields.
# The generated value is produced by concatenating the values of the source fields,
# and then by transforming that result into a valid slug
# (e.g. substituting dashes for spaces and lowercasing ASCII letters).
# prepopulated_fields: dict[str, Sequence[str]] = {}
# By default, FastAPI admin uses a select-box interface (select) for fields that are ForeignKey or have choices set.
# If a field is present in radio_fields, FastAPI admin will use a radio-button interface instead.
# Example of usage: radio_fields = ("user",)
radio_fields: Sequence[str] = ()
# Not supported setting (all fk, m2m uses select js widget as default)
# autocomplete_fields
# By default, FastAPI admin uses a select-box interface (select) for fields that are ForeignKey.
# Sometimes you don't want to incur the overhead of having to select all the related instances to display in the drop-down.
# raw_id_fields is a list of fields you would like to change into an Input widget for either a ForeignKey or ManyToManyField.
# Example of usage: raw_id_fields = ("user",)
raw_id_fields: Sequence[str] = ()
# By default the admin shows all fields as editable.
# Any fields in this option (which should be a list or tuple) will display its data as-is and non-editable.
# Example of usage: readonly_fields = ("created_at",)
readonly_fields: Sequence[str] = ()
# Set search_fields to enable a search box on the admin list page.
# This should be set to a list of field names that will be searched whenever somebody submits a search query in that text box.
# Example of usage: search_fields = ("mobile_number", "email")
search_fields: Sequence[str] = ()
# Set search_help_text to specify a descriptive text for the search box which will be displayed below it.
# Example of usage: search_help_text = "Search by mobile number or email"
search_help_text: str = ""
# Set show_full_result_count to control whether the full count of objects should be displayed
# on a filtered admin page (e.g. 99 results (103 total)).
# If this option is set to False, a text like 99 results (Show all) is displayed instead.
# Example of usage: show_full_result_count = True
show_full_result_count: bool = False
# By default, the list page allows sorting by all model fields
# If you want to disable sorting for some columns, set sortable_by to a collection (e.g. list, tuple, or set)
# of the subset of list_display that you want to be sortable.
# An empty collection disables sorting for all columns.
# Example of usage: sortable_by = ("mobile_number", "email")
sortable_by: Sequence[str] = ()
# An override to the verbose_name from the model's inner Meta class.
verbose_name: str | None = None
# An override to the verbose_name_plural from the model's inner Meta class.
verbose_name_plural: str | None = None
# Widgets actions
widget_actions: Sequence[str] = ()
def __init__(self, model_cls: Any):
"""This method is used to initialize admin class.
:params model_cls: an orm/db model class.
"""
self.model_cls = model_cls
self._request_context = ContextVar(f"fastadmin_admin_request_context_{id(self)}", default=None)
self._user_context = ContextVar(f"fastadmin_admin_user_context_{id(self)}", default=None)
@property
def request(self) -> Any | None:
"""Current request object for this async context."""
return self._request_context.get()
@property
def user(self) -> Any | None:
"""Current authenticated user object for this async context."""
return self._user_context.get()
def set_context(self, request: Any | None = None, user: Any | None = None) -> None:
"""Set request/user context for the current async task."""
self._request_context.set(request)
self._user_context.set(user)
@staticmethod
def get_model_pk_name(orm_model_cls: Any) -> str:
"""This method is used to get model pk name.
:return: A str.
"""
raise NotImplementedError
def get_model_fields_with_widget_types(
self,
with_m2m: bool | None = None,
) -> list[ModelFieldWidgetSchema]:
"""This method is used to get model fields with widget types.
:params with_m2m: a flag to include m2m fields.
:return: A list of ModelFieldWidgetSchema.
"""
raise NotImplementedError
async def pre_generate_models_schema(self) -> None:
"""This method is used to pre-generate models schema.
:return: None.
"""
async def orm_get_list(
self,
offset: int | None = None,
limit: int | None = None,
search: str | None = None,
sort_by: str | None = None,
filters: dict | None = None,
) -> tuple[list[Any], int]:
"""This method is used to get list of orm/db model objects.
:params offset: an offset for pagination.
:params limit: a limit for pagination.
:params search: a search query.
:params sort_by: a sort by field name.
:params filters: a dict of filters.
:return: A tuple of list of objects and total count.
"""
raise NotImplementedError
async def orm_get_obj(self, id: UUID | int | str) -> Any | None:
"""This method is used to get orm/db model object.
:params id: an id of object.
:return: An object or None.
"""
raise NotImplementedError
async def orm_serialize_obj_by_id(self, id: UUID | int | str) -> dict | None:
"""Serialize object by id (e.g. in a single session to avoid DetachedInstanceError).
Override in ORM layer to run get+serialize inside one session when needed.
"""
obj = await self.orm_get_obj(id)
if obj is None:
return None
return await self.serialize_obj(obj)
async def orm_save_obj(self, id: UUID | Any | None, payload: dict) -> Any:
"""This method is used to save orm/db model object.
:params id: an id of object.
:params payload: a dict of payload.
:return: An object.
"""
raise NotImplementedError
async def orm_delete_obj(self, id: UUID | int | str) -> None:
"""This method is used to delete orm/db model object.
:params id: an id of object.
:return: None.
"""
raise NotImplementedError
async def orm_get_m2m_ids(self, obj: Any, field: str) -> list[int | UUID]:
"""This method is used to get m2m ids.
:params obj: an object.
:params field: a m2m field name.
:return: A list of ids.
"""
raise NotImplementedError
async def orm_save_m2m_ids(self, obj: Any, field: str, ids: list[int | UUID]) -> None:
"""This method is used to get m2m ids.
:params obj: an object.
:params field: a m2m field name.
:params ids: a list of ids.
:return: A list of ids.
"""
raise NotImplementedError
@classmethod
def get_sessionmaker(cls) -> Any:
"""This method is used to get db session maker for sqlalchemy.
:return: A db session maker.
"""
return cls.db_session_maker
@classmethod
def set_sessionmaker(cls, db_session_maker: Any) -> None:
"""This method is used to set db session maker for sqlalchemy.
:params db_session: a db session maker.
:return: None.
"""
cls.db_session_maker = db_session_maker
def get_fields_for_serialize(self) -> set[str]:
"""This method is used to get fields for serialize.
:return: A set of fields.
"""
fields = self.get_model_fields_with_widget_types()
fields_for_serialize = {field.name for field in fields}
if self.fields:
fields_for_serialize &= set(self.fields)
if self.exclude:
fields_for_serialize -= set(self.exclude)
if self.list_display:
fields_for_serialize |= set(self.list_display)
return fields_for_serialize
def resolve_sort_by(self, sort_by: str) -> str:
"""Resolve sort_by to the actual ORM ordering expression.
For display columns with sorter=str, returns that string; otherwise returns sort_by.
"""
if not sort_by:
return sort_by
field_name = sort_by.lstrip("-")
display_fn = getattr(self, field_name, None)
if display_fn and getattr(display_fn, "is_display", False):
sorter = getattr(display_fn, "sorter", False)
if isinstance(sorter, str):
prefix = "-" if sort_by.startswith("-") else ""
return f"{prefix}{sorter}"
return sort_by
async def serialize_obj_attributes(
self, obj: Any, attributes_to_serizalize: list[ModelFieldWidgetSchema]
) -> dict[str, Any]:
"""Serialize orm model obj attribute to dict.
:params obj: an object.
:params attributes_to_serizalize: a list of attributes to serialize.
:return: A dict of serialized attributes.
"""
serialized_dict: dict[str, Any] = {}
for field in attributes_to_serizalize:
value = getattr(obj, field.column_name)
if isinstance(value, Decimal):
# Avoid scientific notation for Decimal values in API responses,
# e.g. 3.75E+3 -> "3750"
value = format(value, "f")
serialized_dict[field.name] = value
if inspect.iscoroutinefunction(obj.__str__):
str_fn = obj.__str__
else:
str_fn = sync_to_async(obj.__str__)
serialized_dict["__str__"] = await str_fn()
return serialized_dict
async def _serialize_obj_after_save(self, obj: Any) -> dict:
"""Serialize object after save; re-fetch if detached/session is over."""
try:
return await self.serialize_obj(obj)
except Exception as exc:
# ORM-specific detached/session-over cases after commit.
if exc.__class__.__name__ not in {"DetachedInstanceError", "DatabaseSessionIsOver"}:
raise
pk_name = self.get_model_pk_name(self.model_cls)
pk = getattr(obj, pk_name, None)
if pk is None:
raise
result = await self.orm_serialize_obj_by_id(pk)
if result is None:
raise
return result
async def serialize_obj(self, obj: Any, list_view: bool = False) -> dict:
"""Serialize orm model obj to dict.
:params obj: an object.
:params exclude_fields: a list of fields to exclude.
:return: A dict.
"""
fields = self.get_model_fields_with_widget_types()
fields_for_serialize = self.get_fields_for_serialize()
obj_dict = {}
attributes_to_serizalize = []
for field in fields:
if field.name not in fields_for_serialize:
continue
if field.is_m2m and list_view:
continue
if field.is_m2m:
obj_dict[field.name] = await self.orm_get_m2m_ids(obj, field.column_name)
else:
attributes_to_serizalize.append(field)
obj_dict.update(await self.serialize_obj_attributes(obj, attributes_to_serizalize))
for field_name in fields_for_serialize:
display_field_function = getattr(self, field_name, None)
if not display_field_function or not hasattr(display_field_function, "is_display"):
continue
if inspect.iscoroutinefunction(display_field_function):
display_field_function_fn = display_field_function
else:
display_field_function_fn = sync_to_async(display_field_function)
obj_dict[field_name] = await display_field_function_fn(obj)
return obj_dict
def deserialize_value(self, field: ModelFieldWidgetSchema, value: Any) -> Any:
if not value:
return value
match field.form_widget_type:
case WidgetType.TimePicker:
try:
return datetime.datetime.fromisoformat(value).time()
except ValueError:
return datetime.time.fromisoformat(value)
case WidgetType.DatePicker:
return datetime.datetime.fromisoformat(value).date()
case WidgetType.DateTimePicker:
return datetime.datetime.fromisoformat(value)
case _:
return value
async def get_list(
self,
offset: int | None = None,
limit: int | None = None,
search: str | None = None,
sort_by: str | None = None,
filters: dict | None = None,
) -> tuple[list[dict], int]:
"""This method is used to get list of seriaized objects.
:params offset: an offset for pagination.
:params limit: a limit for pagination.
:params search: a search query.
:params sort_by: a sort by field name.
:params filters: a dict of filters.
:return: A tuple of list of dict and total count.
"""
resolved_sort_by = self.resolve_sort_by(sort_by) if sort_by else None
objs, total = await self.orm_get_list(
offset=offset,
limit=limit,
search=search,
sort_by=resolved_sort_by,
filters=filters,
)
serialized_objs = []
for obj in objs:
serialized_objs.append(await self.serialize_obj(obj, list_view=True))
return serialized_objs, total
async def get_obj(self, id: UUID | int | str) -> dict | None:
"""This method is used to get serialized object by id.
:params id: an id of object.
:return: A dict or None.
"""
obj = await self.orm_get_obj(id)
if not obj:
return None
return await self.serialize_obj(obj)
async def save_model(self, id: UUID | int | str | None, payload: dict) -> dict | None:
"""This method is used to save orm/db model object.
:params id: an id of object.
:params payload: a payload from request.
:return: A saved object or None.
"""
fields = self.get_model_fields_with_widget_types(with_m2m=False)
m2m_fields = self.get_model_fields_with_widget_types(with_m2m=True)
fields_payload = {
field.column_name: self.deserialize_value(field, payload[field.name])
for field in fields
if field.name in payload
}
obj = await self.orm_save_obj(id, fields_payload)
if not obj:
return None
for m2m_field in m2m_fields:
if m2m_field.name in payload:
await self.orm_save_m2m_ids(obj, m2m_field.column_name, payload[m2m_field.name])
return await self._serialize_obj_after_save(obj)
async def delete_model(self, id: UUID | int | str) -> None:
"""This method is used to delete orm/db model object.
:params id: an id of object.
:return: None.
"""
await self.orm_delete_obj(id)
async def upload_file(
self,
field_name: str,
file_name: str,
file_content: bytes,
) -> str:
"""This method is used to upload files.
:params field_name: a name of field.
:params file_name: a name of file.
:params file_content: a content of file.
:return: A file url.
"""
raise NotImplementedError
async def get_export(
self,
export_format: ExportFormat | None,
offset: int | None = None,
limit: int | None = None,
search: str | None = None,
sort_by: str | None = None,
filters: dict | None = None,
) -> StringIO | BytesIO | None:
"""This method is used to get export data (str or bytes stream).
:params export_format: a n export format (CSV at default).
:params offset: an offset for pagination.
:params limit: a limit for pagination.
:params search: a search query.
:params sort_by: a sort by field name.
:params filters: a dict of filters.
:return: A StringIO or BytesIO object.
"""
resolved_sort_by = self.resolve_sort_by(sort_by) if sort_by else None
objs, _ = await self.orm_get_list(
offset=offset, limit=limit, search=search, sort_by=resolved_sort_by, filters=filters
)
fields = self.get_model_fields_with_widget_types(with_m2m=False)
export_fields = [f.name for f in fields]
match export_format:
case ExportFormat.CSV:
output = StringIO()
writer = csv.DictWriter(output, fieldnames=export_fields)
writer.writeheader()
for obj in objs:
obj_dict = await self.serialize_obj(obj, list_view=True)
obj_dict = {k: v for k, v in obj_dict.items() if k in export_fields}
writer.writerow(obj_dict)
output.seek(0)
return output
case ExportFormat.JSON:
class JSONEncoder(json.JSONEncoder):
def default(self, obj):
try:
return super().default(obj)
except TypeError:
return str(obj)
output = StringIO()
json.dump([await self.serialize_obj(obj, list_view=True) for obj in objs], output, cls=JSONEncoder)
output.seek(0)
return output
case _:
return None
async def has_add_permission(self, user_id: UUID | int | None = None) -> bool:
"""This method is used to check if user has permission to add new model instance.
:param user_id: The user id.
:return: A boolean value.
"""
return True
async def has_change_permission(self, user_id: UUID | int | None = None) -> bool:
"""This method is used to check if user has permission to change model instance.
:param user_id: The user id.
:return: A boolean value.
"""
return True
async def has_delete_permission(self, user_id: UUID | int | None = None) -> bool:
"""This method is used to check if user has permission to delete model instance.
:param user_id: The user id.
:return: A boolean value.
"""
return True
async def has_export_permission(self, user_id: UUID | int | None = None) -> bool:
"""This method is used to check if user has permission to export model instance.
:param user_id: The user id.
:return: A boolean value.
"""
return True
Use self.request and self.user in your admin methods (permissions, save hooks, actions) to access request-scoped context.
class EventAdmin(TortoiseModelAdmin):
async def has_change_permission(self, user_id=None):
# request/user are available for current request context
if self.user and self.user.get("is_superuser"):
return True
return False
async def save_model(self, id, payload):
if self.request:
payload["changed_from_ip"] = getattr(self.request, "client", None)
return await super().save_model(id, payload)
Model-admin-specific methods and attributes:
class ModelAdmin(BaseModelAdmin):
"""This class is used to create admin model class."""
# Optional section name for grouping models in the left menu.
# Example of usage: menu_section = "Users"
menu_section: str | None = None
# Normally, objects have three save options: “Save”, “Save and continue editing”, and “Save and add another”.
# If save_as is True, “Save and add another” will be replaced
# by a “Save as new” button that creates a new object (with a new ID) rather than updating the existing object.
# Example of usage: save_as = True
save_as: bool = False
# When save_as_continue=True, the default redirect after saving the new object is to the change view for that object.
# If you set save_as_continue=False, the redirect will be to the changelist view.
# Example of usage: save_as_continue = False
save_as_continue: bool = False
# Normally, the save buttons appear only at the bottom of the forms.
# If you set save_on_top, the buttons will appear both on the top and the bottom.
# Example of usage: save_on_top = True
save_on_top: bool = False
# Set view_on_site to control whether or not to display the “View on site” link.
# This link should bring you to a URL where you can display the saved object.
# Example of usage: view_on_site = "http://example.com"
view_on_site: str | None = None
# Inlines
inlines: Sequence[type[InlineModelAdmin]] = ()
async def authenticate(self, username: str, password: str) -> UUID | int | None:
"""This method is used to implement authentication for settings.ADMIN_USER_MODEL orm/db model.
:params username: a value for user model settings.ADMIN_USER_MODEL_USERNAME_FIELD field.
:params password: a password.
:return: An user id or None.
"""
raise NotImplementedError
async def change_password(self, id: UUID | int | str, password: str) -> None:
"""This method is used to change user password.
:params id: An user id.
:params password: A new password.
"""
raise NotImplementedError
async def save_model(self, id: UUID | int | str | None, payload: dict) -> dict | None:
"""This method is used to save orm/db model object.
:params id: an id of object.
:params payload: a payload from request.
:return: A saved object or None.
"""
obj = await super().save_model(id, payload)
fields = self.get_model_fields_with_widget_types(with_m2m=False)
password_fields = [field.name for field in fields if field.form_widget_type == WidgetType.PasswordInput]
if obj and id is None and password_fields:
# save hashed password for create
pk_name = self.get_model_pk_name(self.model_cls)
pk = obj[pk_name]
password_values = [payload[field] for field in password_fields if field in payload]
if password_values:
await self.change_password(pk, password_values[0])
return obj
Form Field Types
The following form field types are available for model admins:
class WidgetType(str, Enum):
"""Widget type"""
Input = "Input"
InputNumber = "InputNumber"
SlugInput = "SlugInput"
EmailInput = "EmailInput"
PhoneInput = "PhoneInput"
UrlInput = "UrlInput"
PasswordInput = "PasswordInput"
TextArea = "TextArea"
RichTextArea = "RichTextArea"
JsonTextArea = "JsonTextArea"
Select = "Select"
AsyncSelect = "AsyncSelect"
AsyncTransfer = "AsyncTransfer"
Switch = "Switch"
Checkbox = "Checkbox"
TimePicker = "TimePicker"
DatePicker = "DatePicker"
DateTimePicker = "DateTimePicker"
RangePicker = "RangePicker"
RadioGroup = "RadioGroup"
CheckboxGroup = "CheckboxGroup"
UploadFile = "UploadFile"
UploadImage = "UploadImage"
See antd components for more details (e.g. how they look).
For file and image fields use UploadFile and UploadImage widgets in formfield_overrides. Implement upload_file(obj, field_name, file_name, file_content) on the model admin to handle uploads; it must return the file URL (e.g. after saving to disk or S3).
Use formfield_overrides to customize widget props per field. You can set label for a custom field label and help for description text below the field:
formfield_overrides = {
"username": (
WidgetType.SlugInput,
{
"required": True,
"label": "Custom label",
"help": "Detailed description of the field",
},
),
}
Inline Model Admins
Registering Inlines
import os
import uuid
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager
os.environ["ADMIN_USER_MODEL"] = "User"
os.environ["ADMIN_USER_MODEL_USERNAME_FIELD"] = "username"
os.environ["ADMIN_SECRET_KEY"] = "secret"
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from models import BaseEvent, Event, Tournament, User, UserAttachment
from tortoise.contrib.fastapi import RegisterTortoise
from fastadmin import (
TortoiseInlineModelAdmin,
TortoiseModelAdmin,
WidgetActionArgumentProps,
WidgetActionChartProps,
WidgetActionFilter,
WidgetActionInputSchema,
WidgetActionParentArgumentProps,
WidgetActionProps,
WidgetActionResponseSchema,
WidgetActionType,
WidgetType,
action,
display,
)
from fastadmin import fastapi_app as admin_app
from fastadmin import (
register,
widget_action,
)
class UserAttachmentModelInline(TortoiseInlineModelAdmin):
model = UserAttachment
formfield_overrides = { # noqa: RUF012
"attachment_url": (
WidgetType.UploadFile,
{
"required": True,
},
),
}
async def upload_file(
self,
field_name: str,
file_name: str,
file_content: bytes,
) -> None:
# save file to media directory or to s3/filestorage here
return f"/media/{file_name}"
@register(User)
class UserModelAdmin(TortoiseModelAdmin):
menu_section = "Users"
list_display = ("id", "username", "is_superuser")
list_display_links = ("id", "username")
list_filter = ("id", "username", "is_superuser")
search_fields = ("username",)
formfield_overrides = { # noqa: RUF012
"username": (WidgetType.SlugInput, {"required": True}),
"password": (WidgetType.PasswordInput, {"passwordModalForm": True}),
"avatar_url": (
WidgetType.UploadImage,
{
"required": False,
# Disable crop image for upload field
# "disableCropImage": True,
},
),
}
inlines = (UserAttachmentModelInline,)
widget_actions = (
"sales_chart",
"sales_area_chart",
"sales_column_chart",
"sales_bar_chart",
"sales_pie_chart",
"sales_action",
)
async def authenticate(self, username: str, password: str) -> uuid.UUID | int | None:
obj = await self.model_cls.filter(username=username, password=password, is_superuser=True).first()
if not obj:
return None
return obj.id
async def change_password(self, id: uuid.UUID | int, password: str) -> None:
user = await self.model_cls.filter(id=id).first()
if not user:
return
# direct saving password is only for tests - use hash
user.password = password
await user.save()
async def upload_file(
self,
field_name: str,
file_name: str,
file_content: bytes,
) -> None:
# save file to media directory or to s3/filestorage here
return f"/media/{file_name}"
async def pre_generate_models_schema(self) -> None:
model_cls: User = self.model_cls
options = await model_cls.all().values_list("username", flat=True)
# inject options to the class
widget_action_props: WidgetActionProps = self.__class__.sales_action.widget_action_props
for argument in widget_action_props.arguments:
if argument.name == "username":
argument.widget_props["options"] = [{"label": option, "value": option} for option in options]
break
@widget_action(
widget_action_type=WidgetActionType.ChartLine,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Sales": "#1677ff",
"Sales 2": "#52c41a",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="x",
widget_type=WidgetType.DatePicker,
),
WidgetActionFilter(
field_name="y",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
],
tab="Analytics",
sub_tab="Sales",
title="Sales over time",
description="Line chart of sales",
width=24,
)
async def sales_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{
"x": "2026-01-01",
"y": 100,
"series": "Sales",
},
{
"x": "2026-01-02",
"y": 200,
"series": "Sales",
},
{
"x": "2026-01-01",
"y": 300,
"series": "Sales 2",
},
{
"x": "2026-01-04",
"y": 400,
"series": "Sales 2",
},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartArea,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Online": "#722ed1",
"Retail": "#13c2c2",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="period",
widget_type=WidgetType.RangePicker,
),
WidgetActionFilter(
field_name="channel",
widget_type=WidgetType.Select,
widget_props={
"mode": "multiple",
"options": [
{"label": "Online", "value": "Online"},
{"label": "Retail", "value": "Retail"},
],
},
),
],
tab="Analytics",
title="Sales trend area",
description="Area chart of sales",
width=12,
)
async def sales_area_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 80, "series": "Online"},
{"x": "2026-01-02", "y": 120, "series": "Online"},
{"x": "2026-01-01", "y": 60, "series": "Retail"},
{"x": "2026-01-02", "y": 90, "series": "Retail"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartColumn,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"2025": "#fa8c16",
"2026": "#f5222d",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="year",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "2025", "value": "2025"},
{"label": "2026", "value": "2026"},
],
},
),
],
tab="Analytics",
title="Sales by month",
description="Column chart of sales",
width=12,
)
async def sales_column_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Jan", "y": 320, "series": "2025"},
{"x": "Feb", "y": 410, "series": "2025"},
{"x": "Jan", "y": 380, "series": "2026"},
{"x": "Feb", "y": 460, "series": "2026"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartBar,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Q1": "#2f54eb",
"Q2": "#eb2f96",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="quarter",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Q1", "value": "Q1"},
{"label": "Q2", "value": "Q2"},
],
},
),
],
tab="Analytics",
title="Sales by region",
description="Bar chart of sales",
width=12,
)
async def sales_bar_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "North", "y": 540, "series": "Q1"},
{"x": "South", "y": 420, "series": "Q1"},
{"x": "North", "y": 610, "series": "Q2"},
{"x": "South", "y": 480, "series": "Q2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartPie,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_color=[
"#1677ff",
"#52c41a",
"#faad14",
],
),
widget_action_filters=[
WidgetActionFilter(
field_name="month",
widget_type=WidgetType.DatePicker,
),
],
tab="Analytics",
title="Sales share",
description="Pie chart of sales share",
width=12,
)
async def sales_pie_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Online", "y": 45},
{"x": "Retail", "y": 30},
{"x": "Partners", "y": 25},
],
)
@widget_action(
widget_action_type=WidgetActionType.Action,
widget_action_props=WidgetActionProps(
arguments=[
# Example of using AsyncSelect widget with parentModel
WidgetActionArgumentProps(
name="user_id",
widget_type=WidgetType.AsyncSelect,
widget_props={
"required": True,
"parentModel": "User",
"idField": "id",
"labelFields": ["__str__", "id"],
},
),
# Example of using Select widget with dynamically loaded options
WidgetActionArgumentProps(
name="username",
widget_type=WidgetType.Select,
widget_props={
"required": True,
# dynamically load options from the database in pre_generate_models_schema method
"options": [],
},
),
# Example of using parent argument with filtered children arguments
WidgetActionArgumentProps(
name="type",
widget_type=WidgetType.Select,
widget_props={
"required": True,
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
WidgetActionArgumentProps(
name="sales_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="sales",
),
),
WidgetActionArgumentProps(
name="revenue_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="revenue",
),
),
],
),
tab="Data",
title="Get sales data",
description="Get sales data",
width=12,
)
async def sales_action(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{
"id": 1,
"name": "Sales",
},
{
"id": 2,
"name": "Sales",
},
{
"id": 3,
"name": "Sales",
},
],
)
class EventInlineModelAdmin(TortoiseInlineModelAdmin):
model = Event
@register(Tournament)
class TournamentModelAdmin(TortoiseModelAdmin):
list_display = ("id", "name")
inlines = (EventInlineModelAdmin,)
widget_actions = ("tournament_action",)
@widget_action(
widget_action_type=WidgetActionType.Action,
tab="Data",
title="Get tournament data",
description="Get tournament data",
width=12,
)
async def tournament_action(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{
"id": 1,
"name": "Tournament 1",
},
{
"id": 2,
"name": "Tournament 2",
},
{
"id": 3,
"name": "Tournament 3",
},
],
)
@register(BaseEvent)
class BaseEventModelAdmin(TortoiseModelAdmin):
pass
@register(Event)
class EventModelAdmin(TortoiseModelAdmin):
actions = ("make_is_active", "make_is_not_active")
list_display = (
"id",
"tournament_name",
"name_with_price",
"rating",
"event_type",
"is_active",
"started",
"start_time",
"date",
)
list_filter = ("event_type", "is_active", "start_time", "date", "event_type")
search_fields = ("name", "tournament__name")
list_select_related = ("tournament",)
@action(description="Make event active")
async def make_is_active(self, ids):
await self.model_cls.filter(id__in=ids).update(is_active=True)
@action
async def make_is_not_active(self, ids):
await self.model_cls.filter(id__in=ids).update(is_active=False)
@display
async def started(self, obj):
return bool(obj.start_time)
@display
async def tournament_name(self, obj):
tournament = await obj.tournament
return tournament.name
@display()
async def name_with_price(self, obj):
return f"{obj.name} - {obj.price}"
async def create_superuser():
await User.create(
username="admin",
password="admin",
is_superuser=True,
)
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
# RegisterTortoise sets up TortoiseContext so request handlers can use the DB
# (_enable_global_fallback=True by default for ASGI lifespan in a background task)
async with RegisterTortoise(
app=app,
db_url="sqlite://:memory:",
modules={"models": ["models"]},
generate_schemas=True,
use_tz=False,
timezone="UTC",
):
await create_superuser()
yield
app = FastAPI(lifespan=lifespan)
app.mount("/admin", admin_app)
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3030", "http://localhost:8090"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
import asyncio
import uuid
from django.db import models
from fastadmin import (
DjangoInlineModelAdmin,
DjangoModelAdmin,
WidgetActionArgumentProps,
WidgetActionChartProps,
WidgetActionFilter,
WidgetActionInputSchema,
WidgetActionParentArgumentProps,
WidgetActionProps,
WidgetActionResponseSchema,
WidgetActionType,
WidgetType,
action,
display,
register,
widget_action,
)
EventTypeEnum = (
("PRIVATE", "PRIVATE"),
("PUBLIC", "PUBLIC"),
)
class BaseModel(models.Model):
id = models.AutoField(primary_key=True)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
class Meta:
abstract = True
class User(BaseModel):
username = models.CharField(max_length=255)
password = models.CharField(max_length=255)
is_superuser = models.BooleanField(default=False)
avatar_url = models.ImageField(null=True)
attachment_url = models.FileField()
def __str__(self):
return self.username
class Meta:
db_table = "user"
class Tournament(BaseModel):
name = models.CharField(max_length=255)
def __str__(self):
return self.name
class Meta:
db_table = "tournament"
class BaseEvent(BaseModel):
name = models.CharField(max_length=255)
def __str__(self):
return self.name
class Meta:
db_table = "base_event"
class Event(BaseModel):
base = models.OneToOneField(BaseEvent, related_name="event", null=True, on_delete=models.SET_NULL)
name = models.CharField(max_length=255)
tournament = models.ForeignKey(Tournament, related_name="events", on_delete=models.CASCADE)
participants = models.ManyToManyField(User, related_name="events")
rating = models.IntegerField(default=0)
description = models.TextField(null=True)
event_type = models.CharField(max_length=255, default="PUBLIC", choices=EventTypeEnum)
is_active = models.BooleanField(default=True)
start_time = models.TimeField(null=True)
date = models.DateField(null=True)
latitude = models.FloatField(null=True)
longitude = models.FloatField(null=True)
price = models.DecimalField(max_digits=10, decimal_places=2, null=True)
json = models.JSONField(null=True)
def __str__(self):
return self.name
class Meta:
db_table = "event"
@register(User)
class UserModelAdmin(DjangoModelAdmin):
menu_section = "Users"
list_display = ("id", "username", "is_superuser")
list_display_links = ("id", "username")
list_filter = ("id", "username", "is_superuser")
search_fields = ("username",)
formfield_overrides = { # noqa: RUF012
"username": (WidgetType.SlugInput, {"required": True}),
"password": (WidgetType.PasswordInput, {"passwordModalForm": True}),
}
widget_actions = (
"sales_chart",
"sales_area_chart",
"sales_column_chart",
"sales_bar_chart",
"sales_pie_chart",
"sales_action",
)
def authenticate(self, username: str, password: str) -> uuid.UUID | int | None:
obj = self.model_cls.objects.filter(username=username, is_superuser=True).first()
if not obj:
return None
# if not obj.check_password(password):
# return None
return obj.id
def change_password(self, id: uuid.UUID | int, password: str) -> None:
user = self.model_cls.objects.filter(id=id).first()
if not user:
return
# direct saving password is only for tests - use hash
user.password = password
user.save()
def upload_file(
self,
field_name: str,
file_name: str,
file_content: bytes,
) -> str:
# save file to media directory or to s3/filestorage here
return f"/media/{file_name}"
async def pre_generate_models_schema(self) -> None:
def get_options() -> list:
return list(self.model_cls.objects.values_list("username", flat=True))
options = await asyncio.to_thread(get_options)
widget_action_props: WidgetActionProps = self.__class__.sales_action.widget_action_props
for argument in widget_action_props.arguments:
if argument.name == "username":
argument.widget_props["options"] = [{"label": option, "value": option} for option in options]
break
@widget_action(
widget_action_type=WidgetActionType.ChartLine,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Sales": "#1677ff",
"Sales 2": "#52c41a",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="x",
widget_type=WidgetType.DatePicker,
),
WidgetActionFilter(
field_name="y",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
],
tab="Analytics",
sub_tab="Sales",
title="Sales over time",
description="Line chart of sales",
width=24,
)
def sales_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 100, "series": "Sales"},
{"x": "2026-01-02", "y": 200, "series": "Sales"},
{"x": "2026-01-01", "y": 300, "series": "Sales 2"},
{"x": "2026-01-04", "y": 400, "series": "Sales 2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartArea,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Online": "#722ed1",
"Retail": "#13c2c2",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="period",
widget_type=WidgetType.RangePicker,
),
WidgetActionFilter(
field_name="channel",
widget_type=WidgetType.Select,
widget_props={
"mode": "multiple",
"options": [
{"label": "Online", "value": "Online"},
{"label": "Retail", "value": "Retail"},
],
},
),
],
tab="Analytics",
title="Sales trend area",
description="Area chart of sales",
width=12,
)
def sales_area_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 80, "series": "Online"},
{"x": "2026-01-02", "y": 120, "series": "Online"},
{"x": "2026-01-01", "y": 60, "series": "Retail"},
{"x": "2026-01-02", "y": 90, "series": "Retail"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartColumn,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"2025": "#fa8c16",
"2026": "#f5222d",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="year",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "2025", "value": "2025"},
{"label": "2026", "value": "2026"},
],
},
),
],
tab="Analytics",
title="Sales by month",
description="Column chart of sales",
width=12,
)
def sales_column_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Jan", "y": 320, "series": "2025"},
{"x": "Feb", "y": 410, "series": "2025"},
{"x": "Jan", "y": 380, "series": "2026"},
{"x": "Feb", "y": 460, "series": "2026"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartBar,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Q1": "#2f54eb",
"Q2": "#eb2f96",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="quarter",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Q1", "value": "Q1"},
{"label": "Q2", "value": "Q2"},
],
},
),
],
tab="Analytics",
title="Sales by region",
description="Bar chart of sales",
width=12,
)
def sales_bar_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "North", "y": 540, "series": "Q1"},
{"x": "South", "y": 420, "series": "Q1"},
{"x": "North", "y": 610, "series": "Q2"},
{"x": "South", "y": 480, "series": "Q2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartPie,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_color=[
"#1677ff",
"#52c41a",
"#faad14",
],
),
widget_action_filters=[
WidgetActionFilter(
field_name="month",
widget_type=WidgetType.DatePicker,
),
],
tab="Analytics",
title="Sales share",
description="Pie chart of sales share",
width=12,
)
def sales_pie_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Online", "y": 45},
{"x": "Retail", "y": 30},
{"x": "Partners", "y": 25},
],
)
@widget_action(
widget_action_type=WidgetActionType.Action,
widget_action_props=WidgetActionProps(
arguments=[
# Example of using AsyncSelect widget with parentModel
WidgetActionArgumentProps(
name="user_id",
widget_type=WidgetType.AsyncSelect,
widget_props={
"required": True,
"parentModel": "User",
"idField": "id",
"labelFields": ["__str__", "id"],
},
),
# Example of using Select widget with dynamically loaded options
WidgetActionArgumentProps(
name="username",
widget_type=WidgetType.Select,
widget_props={
"required": True,
# dynamically load options from the database in pre_generate_models_schema method
"options": [],
},
),
# Example of using parent argument with filtered children arguments
WidgetActionArgumentProps(
name="type",
widget_type=WidgetType.Select,
widget_props={
"required": True,
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
WidgetActionArgumentProps(
name="sales_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="sales",
),
),
WidgetActionArgumentProps(
name="revenue_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="revenue",
),
),
],
),
tab="Data",
title="Get sales data",
description="Get sales data",
width=12,
)
def sales_action(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"id": 1, "name": "Sales"},
{"id": 2, "name": "Sales"},
{"id": 3, "name": "Sales"},
],
)
class EventInlineModelAdmin(DjangoInlineModelAdmin):
model = Event
@register(Tournament)
class TournamentModelAdmin(DjangoModelAdmin):
list_display = ("id", "name")
inlines = (EventInlineModelAdmin,)
@register(BaseEvent)
class BaseEventModelAdmin(DjangoModelAdmin):
pass
@register(Event)
class EventModelAdmin(DjangoModelAdmin):
actions = ("make_is_active", "make_is_not_active")
list_display = ("id", "tournament", "name_with_price", "rating", "event_type", "is_active", "started")
list_filter = ("tournament", "event_type", "is_active")
search_fields = ("name", "tournament__name")
@action(description="Make event active")
def make_is_active(self, ids):
self.model_cls.objects.filter(id__in=ids).update(is_active=True)
@action
def make_is_not_active(self, ids):
self.model_cls.objects.filter(id__in=ids).update(is_active=False)
@display
def started(self, obj):
return bool(obj.start_time)
@display()
def name_with_price(self, obj):
return f"{obj.name} - {obj.price}"
import os
import uuid
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager
os.environ["ADMIN_USER_MODEL"] = "User"
os.environ["ADMIN_USER_MODEL_USERNAME_FIELD"] = "username"
os.environ["ADMIN_SECRET_KEY"] = "secret"
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from models import Base, BaseEvent, Event, Tournament, User, sqlalchemy_engine, sqlalchemy_sessionmaker
from sqlalchemy import select, update
from fastadmin import (
SqlAlchemyInlineModelAdmin,
SqlAlchemyModelAdmin,
WidgetActionArgumentProps,
WidgetActionChartProps,
WidgetActionFilter,
WidgetActionInputSchema,
WidgetActionParentArgumentProps,
WidgetActionProps,
WidgetActionResponseSchema,
WidgetActionType,
WidgetType,
action,
display,
)
from fastadmin import fastapi_app as admin_app
from fastadmin import (
register,
widget_action,
)
@register(User, sqlalchemy_sessionmaker=sqlalchemy_sessionmaker)
class UserModelAdmin(SqlAlchemyModelAdmin):
menu_section = "Users"
list_display = ("id", "username", "is_superuser")
list_display_links = ("id", "username")
list_filter = ("id", "username", "is_superuser")
search_fields = ("username",)
formfield_overrides = { # noqa: RUF012
"username": (WidgetType.SlugInput, {"required": True}),
"password": (WidgetType.PasswordInput, {"passwordModalForm": True}),
"avatar_url": (
WidgetType.UploadImage,
{
"required": False,
# Disable crop image for upload field
# "disableCropImage": True,
},
),
"attachment_url": (
WidgetType.UploadFile,
{
"required": True,
},
),
}
widget_actions = (
"sales_chart",
"sales_area_chart",
"sales_column_chart",
"sales_bar_chart",
"sales_pie_chart",
"sales_action",
)
async def authenticate(self, username: str, password: str) -> uuid.UUID | int | None:
sessionmaker = self.get_sessionmaker()
async with sessionmaker() as session:
query = select(self.model_cls).filter_by(username=username, password=password, is_superuser=True)
result = await session.scalars(query)
obj = result.first()
if not obj:
return None
return obj.id
async def change_password(self, id: uuid.UUID | int, password: str) -> None:
sessionmaker = self.get_sessionmaker()
async with sessionmaker() as session:
# use hash password for real usage
query = update(self.model_cls).where(User.id.in_([id])).values(password=password)
await session.execute(query)
await session.commit()
async def upload_file(
self,
field_name: str,
file_name: str,
file_content: bytes,
) -> None:
# save file to media directory or to s3/filestorage here
return f"/media/{file_name}"
async def pre_generate_models_schema(self) -> None:
sessionmaker = self.get_sessionmaker()
async with sessionmaker() as session:
result = await session.execute(select(self.model_cls.username))
options = list(result.scalars().all())
widget_action_props: WidgetActionProps = self.__class__.sales_action.widget_action_props
for argument in widget_action_props.arguments:
if argument.name == "username":
argument.widget_props["options"] = [{"label": option, "value": option} for option in options]
break
@widget_action(
widget_action_type=WidgetActionType.ChartLine,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Sales": "#1677ff",
"Sales 2": "#52c41a",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="x",
widget_type=WidgetType.DatePicker,
),
WidgetActionFilter(
field_name="y",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
],
tab="Analytics",
sub_tab="Sales",
title="Sales over time",
description="Line chart of sales",
width=24,
)
async def sales_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 100, "series": "Sales"},
{"x": "2026-01-02", "y": 200, "series": "Sales"},
{"x": "2026-01-01", "y": 300, "series": "Sales 2"},
{"x": "2026-01-04", "y": 400, "series": "Sales 2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartArea,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Online": "#722ed1",
"Retail": "#13c2c2",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="period",
widget_type=WidgetType.RangePicker,
),
WidgetActionFilter(
field_name="channel",
widget_type=WidgetType.Select,
widget_props={
"mode": "multiple",
"options": [
{"label": "Online", "value": "Online"},
{"label": "Retail", "value": "Retail"},
],
},
),
],
tab="Analytics",
title="Sales trend area",
description="Area chart of sales",
width=12,
)
async def sales_area_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 80, "series": "Online"},
{"x": "2026-01-02", "y": 120, "series": "Online"},
{"x": "2026-01-01", "y": 60, "series": "Retail"},
{"x": "2026-01-02", "y": 90, "series": "Retail"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartColumn,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"2025": "#fa8c16",
"2026": "#f5222d",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="year",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "2025", "value": "2025"},
{"label": "2026", "value": "2026"},
],
},
),
],
tab="Analytics",
title="Sales by month",
description="Column chart of sales",
width=12,
)
async def sales_column_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Jan", "y": 320, "series": "2025"},
{"x": "Feb", "y": 410, "series": "2025"},
{"x": "Jan", "y": 380, "series": "2026"},
{"x": "Feb", "y": 460, "series": "2026"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartBar,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Q1": "#2f54eb",
"Q2": "#eb2f96",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="quarter",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Q1", "value": "Q1"},
{"label": "Q2", "value": "Q2"},
],
},
),
],
tab="Analytics",
title="Sales by region",
description="Bar chart of sales",
width=12,
)
async def sales_bar_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "North", "y": 540, "series": "Q1"},
{"x": "South", "y": 420, "series": "Q1"},
{"x": "North", "y": 610, "series": "Q2"},
{"x": "South", "y": 480, "series": "Q2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartPie,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_color=[
"#1677ff",
"#52c41a",
"#faad14",
],
),
widget_action_filters=[
WidgetActionFilter(
field_name="month",
widget_type=WidgetType.DatePicker,
),
],
tab="Analytics",
title="Sales share",
description="Pie chart of sales share",
width=12,
)
async def sales_pie_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Online", "y": 45},
{"x": "Retail", "y": 30},
{"x": "Partners", "y": 25},
],
)
@widget_action(
widget_action_type=WidgetActionType.Action,
widget_action_props=WidgetActionProps(
arguments=[
# Example of using AsyncSelect widget with parentModel
WidgetActionArgumentProps(
name="user_id",
widget_type=WidgetType.AsyncSelect,
widget_props={
"required": True,
"parentModel": "User",
"idField": "id",
"labelFields": ["__str__", "id"],
},
),
# Example of using Select widget with dynamically loaded options
WidgetActionArgumentProps(
name="username",
widget_type=WidgetType.Select,
widget_props={
"required": True,
# dynamically load options from the database in pre_generate_models_schema method
"options": [],
},
),
# Example of using parent argument with filtered children arguments
WidgetActionArgumentProps(
name="type",
widget_type=WidgetType.Select,
widget_props={
"required": True,
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
WidgetActionArgumentProps(
name="sales_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="sales",
),
),
WidgetActionArgumentProps(
name="revenue_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="revenue",
),
),
],
),
tab="Data",
title="Get sales data",
description="Get sales data",
width=12,
)
async def sales_action(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"id": 1, "name": "Sales"},
{"id": 2, "name": "Sales"},
{"id": 3, "name": "Sales"},
],
)
class EventInlineModelAdmin(SqlAlchemyInlineModelAdmin):
model = Event
@register(Tournament, sqlalchemy_sessionmaker=sqlalchemy_sessionmaker)
class TournamentModelAdmin(SqlAlchemyModelAdmin):
list_display = ("id", "name")
inlines = (EventInlineModelAdmin,)
@register(BaseEvent, sqlalchemy_sessionmaker=sqlalchemy_sessionmaker)
class BaseEventModelAdmin(SqlAlchemyModelAdmin):
pass
@register(Event, sqlalchemy_sessionmaker=sqlalchemy_sessionmaker)
class EventModelAdmin(SqlAlchemyModelAdmin):
actions = ("make_is_active", "make_is_not_active")
list_display = ("id", "tournament", "name_with_price", "rating", "event_type", "is_active", "started")
list_filter = ("tournament", "event_type", "is_active")
search_fields = ("name", "tournament__name")
@action(description="Make event active")
async def make_is_active(self, ids):
sessionmaker = self.get_sessionmaker()
async with sessionmaker() as session:
query = update(Event).where(Event.id.in_(ids)).values(is_active=True)
await session.execute(query)
await session.commit()
@action
async def make_is_not_active(self, ids):
sessionmaker = self.get_sessionmaker()
async with sessionmaker() as session:
query = update(Event).where(Event.id.in_(ids)).values(is_active=False)
await session.execute(query)
await session.commit()
@display
async def started(self, obj):
return bool(obj.start_time)
@display()
async def name_with_price(self, obj):
return f"{obj.name} - {obj.price}"
async def init_db():
async with sqlalchemy_engine.begin() as c:
await c.run_sync(Base.metadata.drop_all)
await c.run_sync(Base.metadata.create_all)
async def create_superuser():
async with sqlalchemy_sessionmaker() as s:
user = User(
username="admin",
password="admin",
is_superuser=True,
attachment_url="/media/attachment.txt",
)
s.add(user)
await s.commit()
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
await init_db()
await create_superuser()
yield
app = FastAPI(lifespan=lifespan)
app.mount("/admin", admin_app)
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3030", "http://localhost:8090"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
import asyncio
import os
import uuid
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager
os.environ["ADMIN_USER_MODEL"] = "User"
os.environ["ADMIN_USER_MODEL_USERNAME_FIELD"] = "username"
os.environ["ADMIN_SECRET_KEY"] = "secret"
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from models import BaseEvent, Event, Tournament, User, db
from pony.orm import commit, db_session
from pony.orm import select as pony_select
from fastadmin import (
PonyORMInlineModelAdmin,
PonyORMModelAdmin,
WidgetActionArgumentProps,
WidgetActionChartProps,
WidgetActionFilter,
WidgetActionInputSchema,
WidgetActionParentArgumentProps,
WidgetActionProps,
WidgetActionResponseSchema,
WidgetActionType,
WidgetType,
action,
display,
)
from fastadmin import fastapi_app as admin_app
from fastadmin import (
register,
widget_action,
)
@register(User)
class UserModelAdmin(PonyORMModelAdmin):
menu_section = "Users"
list_display = ("id", "username", "is_superuser")
list_display_links = ("id", "username")
list_filter = ("id", "username", "is_superuser")
search_fields = ("username",)
formfield_overrides = { # noqa: RUF012
"username": (WidgetType.SlugInput, {"required": True}),
"password": (WidgetType.PasswordInput, {"passwordModalForm": True}),
"avatar_url": (
WidgetType.UploadImage,
{
"required": False,
# Disable crop image for upload field
# "disableCropImage": True,
},
),
"attachment_url": (
WidgetType.UploadFile,
{
"required": True,
},
),
}
widget_actions = (
"sales_chart",
"sales_area_chart",
"sales_column_chart",
"sales_bar_chart",
"sales_pie_chart",
"sales_action",
)
@db_session
def authenticate(self, username: str, password: str) -> uuid.UUID | int | None:
obj = next((f for f in User.select(username=username, password=password, is_superuser=True)), None) # fmt: skip
if not obj:
return None
return obj.id
@db_session
def change_password(self, id: uuid.UUID | int, password: str) -> None:
obj = next((f for f in self.model_cls.select(id=id)), None)
if not obj:
return
# direct saving password is only for tests - use hash
obj.password = password
commit()
def upload_file(
self,
field_name: str,
file_name: str,
file_content: bytes,
) -> str:
# save file to media directory or to s3/filestorage here
return f"/media/{file_name}"
async def pre_generate_models_schema(self) -> None:
def get_options() -> list:
with db_session:
return [u.username for u in pony_select(u for u in User)]
options = await asyncio.to_thread(get_options)
widget_action_props: WidgetActionProps = self.__class__.sales_action.widget_action_props
for argument in widget_action_props.arguments:
if argument.name == "username":
argument.widget_props["options"] = [{"label": option, "value": option} for option in options]
break
@widget_action(
widget_action_type=WidgetActionType.ChartLine,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Sales": "#1677ff",
"Sales 2": "#52c41a",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="x",
widget_type=WidgetType.DatePicker,
),
WidgetActionFilter(
field_name="y",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
],
tab="Analytics",
sub_tab="Sales",
title="Sales over time",
description="Line chart of sales",
width=24,
)
def sales_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 100, "series": "Sales"},
{"x": "2026-01-02", "y": 200, "series": "Sales"},
{"x": "2026-01-01", "y": 300, "series": "Sales 2"},
{"x": "2026-01-04", "y": 400, "series": "Sales 2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartArea,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Online": "#722ed1",
"Retail": "#13c2c2",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="period",
widget_type=WidgetType.RangePicker,
),
WidgetActionFilter(
field_name="channel",
widget_type=WidgetType.Select,
widget_props={
"mode": "multiple",
"options": [
{"label": "Online", "value": "Online"},
{"label": "Retail", "value": "Retail"},
],
},
),
],
tab="Analytics",
title="Sales trend area",
description="Area chart of sales",
width=12,
)
def sales_area_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 80, "series": "Online"},
{"x": "2026-01-02", "y": 120, "series": "Online"},
{"x": "2026-01-01", "y": 60, "series": "Retail"},
{"x": "2026-01-02", "y": 90, "series": "Retail"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartColumn,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"2025": "#fa8c16",
"2026": "#f5222d",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="year",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "2025", "value": "2025"},
{"label": "2026", "value": "2026"},
],
},
),
],
tab="Analytics",
title="Sales by month",
description="Column chart of sales",
width=12,
)
def sales_column_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Jan", "y": 320, "series": "2025"},
{"x": "Feb", "y": 410, "series": "2025"},
{"x": "Jan", "y": 380, "series": "2026"},
{"x": "Feb", "y": 460, "series": "2026"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartBar,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_field="series",
series_color={
"Q1": "#2f54eb",
"Q2": "#eb2f96",
},
),
widget_action_filters=[
WidgetActionFilter(
field_name="quarter",
widget_type=WidgetType.Select,
widget_props={
"options": [
{"label": "Q1", "value": "Q1"},
{"label": "Q2", "value": "Q2"},
],
},
),
],
tab="Analytics",
title="Sales by region",
description="Bar chart of sales",
width=12,
)
def sales_bar_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "North", "y": 540, "series": "Q1"},
{"x": "South", "y": 420, "series": "Q1"},
{"x": "North", "y": 610, "series": "Q2"},
{"x": "South", "y": 480, "series": "Q2"},
],
)
@widget_action(
widget_action_type=WidgetActionType.ChartPie,
widget_action_props=WidgetActionChartProps(
x_field="x",
y_field="y",
series_color=[
"#1677ff",
"#52c41a",
"#faad14",
],
),
widget_action_filters=[
WidgetActionFilter(
field_name="month",
widget_type=WidgetType.DatePicker,
),
],
tab="Analytics",
title="Sales share",
description="Pie chart of sales share",
width=12,
)
def sales_pie_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"x": "Online", "y": 45},
{"x": "Retail", "y": 30},
{"x": "Partners", "y": 25},
],
)
@widget_action(
widget_action_type=WidgetActionType.Action,
widget_action_props=WidgetActionProps(
arguments=[
# Example of using AsyncSelect widget with parentModel
WidgetActionArgumentProps(
name="user_id",
widget_type=WidgetType.AsyncSelect,
widget_props={
"required": True,
"parentModel": "User",
"idField": "id",
"labelFields": ["__str__", "id"],
},
),
# Example of using Select widget with dynamically loaded options
WidgetActionArgumentProps(
name="username",
widget_type=WidgetType.Select,
widget_props={
"required": True,
# dynamically load options from the database in pre_generate_models_schema method
"options": [],
},
),
# Example of using parent argument with filtered children arguments
WidgetActionArgumentProps(
name="type",
widget_type=WidgetType.Select,
widget_props={
"required": True,
"options": [
{"label": "Sales", "value": "sales"},
{"label": "Revenue", "value": "revenue"},
],
},
),
WidgetActionArgumentProps(
name="sales_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="sales",
),
),
WidgetActionArgumentProps(
name="revenue_date",
widget_type=WidgetType.DatePicker,
widget_props={
"required": True,
},
parent_argument=WidgetActionParentArgumentProps(
name="type",
value="revenue",
),
),
],
),
tab="Data",
title="Get sales data",
description="Get sales data",
width=12,
)
def sales_action(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
return WidgetActionResponseSchema(
data=[
{"id": 1, "name": "Sales"},
{"id": 2, "name": "Sales"},
{"id": 3, "name": "Sales"},
],
)
class EventInlineModelAdmin(PonyORMInlineModelAdmin):
model = Event
@register(Tournament)
class TournamentModelAdmin(PonyORMModelAdmin):
list_display = ("id", "name")
inlines = (EventInlineModelAdmin,)
@register(BaseEvent)
class BaseEventModelAdmin(PonyORMModelAdmin):
pass
@register(Event)
class EventModelAdmin(PonyORMModelAdmin):
actions = ("make_is_active", "make_is_not_active")
list_display = ("id", "tournament", "name_with_price", "rating", "event_type", "is_active", "started")
list_filter = ("tournament", "event_type", "is_active")
search_fields = ("name", "tournament__name")
@action(description="Make event active")
@db_session
def make_is_active(self, ids):
# update(o.set(is_active=True) for o in self.model_cls if o.id in ids)
objs = self.model_cls.select(lambda o: o.id in ids)
for obj in objs:
obj.is_active = True
commit()
@action
@db_session
def make_is_not_active(self, ids):
# update(o.set(is_active=False) for o in self.model_cls if o.id in ids)
objs = self.model_cls.select(lambda o: o.id in ids)
for obj in objs:
obj.is_active = False
commit()
@display
@db_session
def started(self, obj):
return bool(obj.start_time)
@display()
@db_session
def name_with_price(self, obj):
return f"{obj.name} - {obj.price}"
def init_db():
# Use shared in-memory sqlite DB so tables are visible across connections/threads.
db.bind(provider="sqlite", filename=":sharedmemory:", create_db=True)
db.generate_mapping(create_tables=True)
@db_session
def create_superuser():
User(
username="admin",
password="admin",
is_superuser=True,
attachment_url="/media/attachment.txt",
)
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
init_db()
create_superuser()
yield
app = FastAPI(lifespan=lifespan)
app.mount("/admin", admin_app)
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3030", "http://localhost:8090"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
Methods and Attributes
The following methods and attributes are available for inline model admins:
See the BaseModelAdmin methods and attributes in the model admin section.
Inline-model-specific methods and attributes:
class InlineModelAdmin(BaseModelAdmin):
"""This class is used to create admin inline model class."""
# The model class which the inline is using. This is required.
model: Any
# The name of the foreign key on the model.
# In most cases this will be dealt with automatically, but fk_name must be specified explicitly
# if there are more than one foreign key to the same parent model.
fk_name: str | None = None
# This controls the maximum number of forms to show in the inline.
# This doesn't directly correlate to the number of objects, but can if the value is small enough.
# See Limiting the number of editable objects for more information.
max_num: int = 10
# This controls the minimum number of forms to show in the inline.
min_num: int = 1
Dashboard Widget Admins
Registering Widgets
To show dashboard widgets, define @widget_action methods on your model admin and list their method names in the model admin's widget_actions attribute.
If you forget to add the method name to widget_actions, the widget will not appear on the dashboard.
from fastadmin import TortoiseModelAdmin, widget_action
from fastadmin.models.schemas import (
WidgetActionChartProps,
WidgetActionInputSchema,
WidgetActionResponseSchema,
WidgetActionType,
)
class UserAdmin(TortoiseModelAdmin):
# Register widgets by method name
widget_actions = ("users_chart",)
@widget_action(
widget_action_type=WidgetActionType.ChartLine,
widget_action_props=WidgetActionChartProps(x_field="x", y_field="y"),
tab="Analytics",
title="Users over time",
)
async def users_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
# Build and return data for the chart
return WidgetActionResponseSchema(
data=[
{"x": "2026-01-01", "y": 10},
{"x": "2026-01-02", "y": 15},
],
)
Methods and Attributes
Use the @widget_action decorator on ModelAdmin methods to declare dashboard widgets and actions. The decorator attaches metadata used to render chart widgets and action forms on the dashboard.
def widget_action(
function=None,
*,
tab: str = "Default",
sub_tab: str | None = None,
title: str = "Action",
description: str | None = None,
widget_action_type: WidgetActionType = WidgetActionType.Action,
widget_action_props: WidgetActionChartProps | WidgetActionProps | None = None,
widget_action_filters: list[WidgetActionFilter] | None = None,
width: (
tp.Literal[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24] | None
) = None, # width in 1-24 grid system
max_height: int | None = None,
):
"""Conveniently add attributes to a widget action function:
Example of usage:
@widget_action(
tab="Default",
title="Action",
description="Chart of total sales by status",
widget_action_type=WidgetActionType.Action,
widget_action_props=WidgetActionChartProps(
x_field="date",
y_field="total_sales",
series_field="status",
),
widget_action_filters=[WidgetActionFilter(
field_name="status",
widget_type=WidgetType.Select,
widget_props={
"mode": "multiple",
"options": [
{
"label": "Pending",
"value": "Pending",
},
{
"label": "Completed",
"value": "Completed",
},
],
},
)],
)
async def sales_chart(self, payload: WidgetActionInputSchema) -> WidgetActionResponseSchema:
# filter by payload.query
return WidgetActionResponseSchema(
data=[
{
"date": "2026-01-01",
"total_sales": 100,
"status": "Pending",
},
{
"date": "2026-01-02",
"total_sales": 200,
"status": "Completed",
},
],
)
:param function: A function to decorate.
:param description: A string value to set the function's short_description
"""
def decorator(func):
wrapped = _wrap_callable(func)
wrapped.is_widget_action = True
wrapped.widget_action_type = widget_action_type
wrapped.widget_action_props = widget_action_props
wrapped.widget_action_filters = widget_action_filters
wrapped.tab = tab
wrapped.sub_tab = sub_tab
wrapped.title = title
wrapped.width = width
wrapped.max_height = max_height
if description is not None:
wrapped.short_description = description
return wrapped
if function is None:
return decorator
return decorator(function)
Widget actions use the following types for configuration (chart props, arguments, filters and payload schema):
@dataclass
class WidgetActionChartProps:
"""Widget action chart props"""
x_field: str
y_field: str
series_field: str | None = None
series_color: list[str] | dict[str, str] | None = None
@dataclass
class WidgetActionArgumentProps:
"""Widget action chart props"""
name: str
widget_type: WidgetType
widget_props: dict | None = None
# if None, show always
# if not None, show only if parent selected/input value is equal to the parent_argument.value
parent_argument: WidgetActionParentArgumentProps | None = None
@dataclass
class WidgetActionProps:
"""Widget action props"""
arguments: list[WidgetActionArgumentProps]
@dataclass
class WidgetActionFilter:
"""Model widget filter action"""
field_name: str
widget_type: WidgetType
widget_props: dict | None = None
@dataclass
class WidgetActionInputSchema:
"""Widget action input schema"""
query: list[WidgetActionQuerySchema]
@dataclass
class WidgetActionResponseSchema:
"""Widget action response schema"""
data: list[dict[str, tp.Any]]
If you call @widget_action() without arguments, FastAdmin uses the documented defaults: tab='Default', title='Action', widget_action_type=WidgetActionType.Action and no props or filters.
After defining a @widget_action method, add its name to the model admin's widget_actions attribute so that it is rendered on the dashboard.
Chart Types
The FastAdmin dashboard supports the following widget action types for charts and actions:
class WidgetActionType(str, Enum):
"""Widget action type"""
ChartLine = "ChartLine"
ChartArea = "ChartArea"
ChartColumn = "ChartColumn"
ChartBar = "ChartBar"
ChartPie = "ChartPie"
Action = "Action"
Chart-* widget actions render charts on the dashboard; the Action type renders a simple action widget. See antd charts for more details (e.g. how they look).
Changelog
See what was added, changed, fixed, or improved in the latest versions.
v0.4.7
Add sub_tab to widget action props.
Dark mode support.
v0.4.6
Add max_height to widget action props.
Add highlight search results to widget action results.
Add copy to clipboard to widget action results.
Add expand results modal to widget action results.
Add menu_section to model admins.
v0.4.5
Add parent argument to widget action props.
Add wraps to decorator to keep the original function name and docstring.
Add pre_generate_models_schema method to ModelAdmin to pre-generate models schema.
Fix examples.
v0.4.4
Replace helmet to update title and description.
Improve frontend coverage.
v0.4.3
Add series field to widget action props. Fix examples.
Add search by actions.
v0.4.2
Replace DashboardWidgetAdmin with widget_action decorator. (no backward compatibility)
Fix mobile view.
v0.4.1
Fix upload file functionality. Fix examples.
v0.4.0
Add new upload file functionality (without backward compatibility). See documentation for details.
Add example for flask with sqlalchemy
Removed ADMIN_DISABLE_CROP_IMAGE setting. Use disableCropImage prop in UploadImage widget instead.
v0.3.11
Fix API service errors.
v0.3.10
Fix file download issue for actions.
v0.3.9
Add response types for actions.
Fix Decimal fields handling.
v0.3.8
Fix inline add/change issue.
Fix inline filter reset issue.
v0.3.7
Fix filter reset issue.
Fix date/time handling in transform helpers.
Fix examples.
Fix JSON textarea handling.
v0.3.6
Fix datetime/time handling in transform helpers.
Revert get_orm_list method to original implementation. We can use list_select_related and search_fields for prefetch_related_fields and additional_search_fields.
v0.3.5
Enhance get_orm_list method to support prefetch_related_fields and additional_search_fields.
Add request/user context on BaseModelAdmin for per-request custom logic.
v0.3.4
Fix sort by and search by relations. Fix examples.
v0.3.3
Fix DetachedInstanceError when session is closed after commit.
Fix list display widths.
Fix flask issues.
v0.3.2
Add formfield_overrides example. Add label and help props.
v0.3.1
Fix sqlalchemy required fields. Fix CI.
v0.3.0
Clean up documentation. Update dependencies. Fix linters and tests. Frontend refactoring.
v0.2.22
Fix upload base64 widget; add disableCropImage prop. Fix examples.
v0.2.21
Fix cleaning of async select fields on forms.
v0.2.20
Fix _id fields handling. Bump backend and frontend packages.
v0.2.19
Fix is_pk for Tortoise ORM.
v0.2.18
Fix M2M/FK handling for SQLAlchemy with PostgreSQL (convert str to int).
v0.2.17
Fix FK handling for SQLAlchemy with PostgreSQL (convert str to int).
v0.2.16
Add ADMIN_DISABLE_CROP_IMAGE setting to configure image cropping on upload.
v0.2.15
Fix password logic for user model.
v0.2.14
Make permission functions awaitable. Bump frontend and backend packages.
v0.2.13
Fix edit page frontend issue for Date field.
v0.2.12
Remove python-dotenv dependency. Bump Django. Add Django example.
v0.2.11
Fix examples. Fix Pony ORM (delete, update M2M). Allow sorting by custom columns. Fix list_display ordering.
v0.2.10
Fix empty M2M issue. Optimize unit tests. Fix Pony ORM. Optimize Tortoise ORM search.
v0.2.9
Fix modal inline dialogs. Fix M2M multiple select.
v0.2.8
Fix SQLAlchemy delete functionality. Add more examples.
v0.2.7
Fix helper functions. Add regex support.
v0.2.6
Add edit button for async select.
v0.2.5
Fix async select in inlines.
v0.2.4
Fix dashboard widgets and auto-register inlines.
v0.2.3
Fix filter issue on list views. Remove Jinja from dependencies.
v0.2.2
Fix datetime-related bugs.
v0.2.1
Update packages. Fix linters and tests in Vite frontend. Remove Pydantic from dependencies.
v0.2.0
Update packages. Use Vite instead of deprecated react-scripts.