Formularmodelle¶

uvx library-skills

Sie können Pydantic-Modelle verwenden, um Formularfelder in FastAPI zu deklarieren.

$ uv add python-multipart

Pydantic-Modelle für Formulare¶

Sie müssen nur ein Pydantic-Modell mit den Feldern deklarieren, die Sie als Formularfelder erhalten möchten, und dann den Parameter als Form deklarieren:

from typing import Annotated

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str


@app.post("/login/")
async def login(data: Annotated[FormData, Form()]):
    return data

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str


@app.post("/login/")
async def login(data: FormData = Form()):
    return data

FastAPI wird die Daten für jedes Feld aus den Formulardaten im Request extrahieren und Ihnen das von Ihnen definierte Pydantic-Modell übergeben.

Deklarieren Sie für HTML-Checkboxen boolesche Felder mit dem Defaultwert False.

Die Dokumentation testen¶

Sie können dies in der Dokumentations-UI unter /docs testen:

Zusätzliche Formularfelder verbieten¶

In einigen speziellen Anwendungsfällen (wahrscheinlich nicht sehr häufig) möchten Sie möglicherweise die Formularfelder auf nur diejenigen beschränken, die im Pydantic-Modell deklariert sind. Und jegliche zusätzlichen Felder verbieten.

Sie können Pydantics Modellkonfiguration verwenden, um jegliche extra-Felder auf forbid zu setzen:

from typing import Annotated

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str
    model_config = {"extra": "forbid"}


@app.post("/login/")
async def login(data: Annotated[FormData, Form()]):
    return data

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str
    model_config = {"extra": "forbid"}


@app.post("/login/")
async def login(data: FormData = Form()):
    return data

Wenn ein Client versucht, einige zusätzliche Daten zu senden, erhält er eine Error-Response.

Zum Beispiel, wenn der Client versucht, folgende Formularfelder zu senden:

• username: Rick
• password: Portal Gun
• extra: Mr. Poopybutthole

Er erhält eine Error-Response, die ihm mitteilt, dass das Feld extra nicht erlaubt ist:

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["body", "extra"],
            "msg": "Extra inputs are not permitted",
            "input": "Mr. Poopybutthole"
        }
    ]
}

Formularmodelle kombinieren¶

Sie können mehrere Formularmodelle mit einzelnen Form-Parametern kombinieren.

from typing import Annotated

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class Profile(BaseModel):
    name: str


class Preferences(BaseModel):
    tags: list[str] = []


@app.post("/profiles/")
async def create_profile(
    profile: Annotated[Profile, Form()],
    preferences: Annotated[Preferences, Form()],
    token: Annotated[str, Form()],
):
    return {"profile": profile, "preferences": preferences, "token": token}

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class Profile(BaseModel):
    name: str


class Preferences(BaseModel):
    tags: list[str] = []


@app.post("/profiles/")
async def create_profile(
    profile: Profile = Form(),
    preferences: Preferences = Form(),
    token: str = Form(),
):
    return {"profile": profile, "preferences": preferences, "token": token}

Der Client sendet name, tags und token als Formularfelder. Jedes Modell validiert die Formularfelder unabhängig.

Die extra-Konfiguration jedes Modells gilt für alle Formularfelder, einschließlich der Felder und Dateien, die in anderen Parametern oder Abhängigkeiten deklariert sind. Mit extra="forbid" wird jedes Feld außerhalb dieses Modells abgelehnt. Mit extra="allow" werden diese Felder als zusätzliche Felder im Modell aufgenommen.

Wenn mehrere Deklarationen denselben Formularfeldnamen verwenden, validiert jede den Wert dieses Feldes. Verwenden Sie kompatible Typen und Einschränkungen für gemeinsam genutzte Felder, damit das OpenAPI-Schema sie konsistent beschreiben kann.

Optionale Formularmodelle¶

Deklarieren Sie ein Formularmodell mit | None und dem Defaultwert None, um die Gruppe optional zu machen.

from typing import Annotated

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class Profile(BaseModel):
    name: str
    age: int


@app.post("/profiles/")
async def create_profile(
    token: Annotated[str, Form()],
    profile: Annotated[Profile | None, Form()] = None,
):
    return {"token": token, "profile": profile}

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class Profile(BaseModel):
    name: str
    age: int


@app.post("/profiles/")
async def create_profile(
    token: str = Form(),
    profile: Profile | None = Form(default=None),
):
    return {"token": token, "profile": profile}

Wenn weder name noch age gesendet wird, ist profile gleich None. Wenn eines der beiden gesendet wird, validiert FastAPI das Modell und erfordert beide Felder. Auch ein übermittelter leerer Wert zählt als Angabe eines Feldes.

Die Verwendung von | None ohne Defaultwert macht den Parameter weiterhin erforderlich.

Zusätzliche Felder folgen der extra-Konfiguration des Modells. Ignorierte zusätzliche Felder führen nicht dazu, dass das Modell als vorhanden gilt.

Ein optionales Modell, das nur nicht aktivierte Checkboxen enthält, wird weggelassen. Senden Sie einen Wert wie enabled=false, um es explizit anzugeben.

Optionale Unions von Formularmodellen¶

Sie können auch eine optionale Union von Modellen verwenden.

from typing import Annotated, Literal

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class Person(BaseModel):
    kind: Literal["person"]
    name: str


class Company(BaseModel):
    kind: Literal["company"]
    company_name: str


@app.post("/contacts/")
async def create_contact(
    contact: Annotated[Person | Company | None, Form(discriminator="kind")] = None,
):
    return contact

from typing import Literal

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class Person(BaseModel):
    kind: Literal["person"]
    name: str


class Company(BaseModel):
    kind: Literal["company"]
    company_name: str


@app.post("/contacts/")
async def create_contact(
    contact: Person | Company | None = Form(default=None, discriminator="kind"),
):
    return contact

Wenn keine Formularfelder gesendet werden, ist contact gleich None. Senden Sie kind=person mit name oder kind=company mit company_name. Der Diskriminator wählt aus, welches Modell validiert werden soll.

Unions von Formularmodellen kombinieren¶

Sie können Unions mit anderen Formularmodellen, einzelnen Form-Parametern und File-Parametern kombinieren. Jede Union wird unabhängig validiert.

from typing import Annotated, Literal

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class Person(BaseModel):
    contact_type: Literal["person"]
    name: str


class Company(BaseModel):
    contact_type: Literal["company"]
    company_name: str


class Email(BaseModel):
    notification_type: Literal["email"]
    email: str


class SMS(BaseModel):
    notification_type: Literal["sms"]
    phone: str


@app.post("/contacts/")
async def create_contact(
    contact: Annotated[Person | Company, Form(discriminator="contact_type")],
    token: Annotated[str, Form()],
    notification: Annotated[
        Email | SMS | None, Form(discriminator="notification_type")
    ] = None,
):
    return {"contact": contact, "notification": notification, "token": token}

from typing import Literal

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class Person(BaseModel):
    contact_type: Literal["person"]
    name: str


class Company(BaseModel):
    contact_type: Literal["company"]
    company_name: str


class Email(BaseModel):
    notification_type: Literal["email"]
    email: str


class SMS(BaseModel):
    notification_type: Literal["sms"]
    phone: str


@app.post("/contacts/")
async def create_contact(
    contact: Person | Company = Form(discriminator="contact_type"),
    token: str = Form(),
    notification: Email | SMS | None = Form(
        default=None, discriminator="notification_type"
    ),
):
    return {"contact": contact, "notification": notification, "token": token}

Senden Sie alle Felder im selben Formular. Senden Sie beispielsweise contact_type=person, name=Rick, notification_type=email, email=rick@example.com und token=secret.

Lassen Sie die Benachrichtigungsfelder weg, damit notification gleich None bleibt.

Formularmodelle und Dateien¶

Sie können ein Formularmodell auch mit Dateiparametern kombinieren.

from typing import Annotated

from fastapi import FastAPI, Form, UploadFile
from pydantic import BaseModel

app = FastAPI()


class Profile(BaseModel):
    name: str


@app.post("/profiles/")
async def create_profile(profile: Annotated[Profile, Form()], avatar: UploadFile):
    return {"profile": profile, "filename": avatar.filename}

from fastapi import FastAPI, File, Form, UploadFile
from pydantic import BaseModel

app = FastAPI()


class Profile(BaseModel):
    name: str


@app.post("/profiles/")
async def create_profile(profile: Profile = Form(), avatar: UploadFile = File()):
    return {"profile": profile, "filename": avatar.filename}

Hier sendet der Client das Feld name und die Datei avatar mittels multipart/form-data.

Zusammenfassung¶

Sie können Pydantic-Modelle verwenden, um Formularfelder in FastAPI zu deklarieren. 😎