diff --git a/docs/en/docs/tutorial/testing.md b/docs/en/docs/tutorial/testing.md
index 95c8c5bef..06a87e92e 100644
--- a/docs/en/docs/tutorial/testing.md
+++ b/docs/en/docs/tutorial/testing.md
@@ -12,7 +12,11 @@ With it, you can use
.
-E.g. `pip install httpx`.
+Make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install it, for example:
+
+```console
+$ pip install httpx
+```
///
@@ -206,7 +210,9 @@ If you have a Pydantic model in your test and you want to send its data to the a
## Run it
-After that, you just need to install `pytest`:
+After that, you just need to install `pytest`.
+
+Make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install it, for example:
diff --git a/docs/ja/docs/learn/index.md b/docs/ja/docs/learn/index.md
new file mode 100644
index 000000000..2f24c670a
--- /dev/null
+++ b/docs/ja/docs/learn/index.md
@@ -0,0 +1,5 @@
+# ๅญฆ็ฟ
+
+ใใใงใฏใ**FastAPI** ใๅญฆ็ฟใใใใใฎๅ
ฅ้ใปใฏใทใงใณใจใใฅใผใใชใขใซใ็ดนไปใใพใใ
+
+ใใใฏใFastAPIใๅญฆ็ฟใใใซใใใฃใฆใฎ**ๆธ็ฑ**ใ**ใณใผใน**ใงใใใ**ๅ
ฌๅผ**ใใคๆจๅฅจใใใๆนๆณใจใฟใชใใใจใใงใใพใ ๐
diff --git a/docs/ko/docs/project-generation.md b/docs/ko/docs/project-generation.md
new file mode 100644
index 000000000..019919f77
--- /dev/null
+++ b/docs/ko/docs/project-generation.md
@@ -0,0 +1,28 @@
+# Full Stack FastAPI ํ
ํ๋ฆฟ
+
+ํ
ํ๋ฆฟ์ ์ผ๋ฐ์ ์ผ๋ก ํน์ ์ค์ ๊ณผ ํจ๊ป ์ ๊ณต๋์ง๋ง, ์ ์ฐํ๊ณ ์ปค์คํฐ๋ง์ด์ง์ด ๊ฐ๋ฅํ๊ฒ ๋์์ธ ๋์์ต๋๋ค. ์ด ํน์ฑ๋ค์ ์ฌ๋ฌ๋ถ์ด ํ๋ก์ ํธ์ ์๊ตฌ์ฌํญ์ ๋ง์ถฐ ์์ , ์ ์ฉ์ ํ ์ ์๊ฒ ํด์ฃผ๊ณ , ํ
ํ๋ฆฟ์ด ์๋ฒฝํ ์์์ ์ด ๋๊ฒ ํด์ค๋๋ค. ๐
+
+๋ง์ ์ด๊ธฐ ์ค์ , ๋ณด์, ๋ฐ์ดํฐ๋ฒ ์ด์ค ๋ฐ ์ผ๋ถ API ์๋ํฌ์ธํธ๊ฐ ์ด๋ฏธ ์ค๋น๋์ด ์์ผ๋ฏ๋ก, ์ฌ๋ฌ๋ถ์ ์ด ํ
ํ๋ฆฟ์ (ํ๋ก์ ํธ๋ฅผ) ์์ํ๋ ๋ฐ ์ฌ์ฉํ ์ ์์ต๋๋ค.
+
+GitHub ์ ์ฅ์: Full Stack FastAPI ํ
ํ๋ฆฟ
+
+## Full Stack FastAPI ํ
ํ๋ฆฟ - ๊ธฐ์ ์คํ๊ณผ ๊ธฐ๋ฅ๋ค
+
+- โก [**FastAPI**](https://fastapi.tiangolo.com): Python ๋ฐฑ์๋ API.
+ - ๐งฐ [SQLModel](https://sqlmodel.tiangolo.com): Python SQL ๋ฐ์ดํฐ ์ํธ์์ฉ์ ์ํ (ORM).
+ - ๐ [Pydantic](https://docs.pydantic.dev): FastAPI์ ์ํด ์ฌ์ฉ๋๋, ๋ฐ์ดํฐ ๊ฒ์ฆ๊ณผ ์ค์ ๊ด๋ฆฌ.
+ - ๐พ [PostgreSQL](https://www.postgresql.org): SQL ๋ฐ์ดํฐ๋ฒ ์ด์ค.
+- ๐ [React](https://react.dev): ํ๋ก ํธ์๋.
+ - ๐ TypeScript, hooks, Vite ๋ฐ ๊ธฐํ ํ๋์ ์ธ ํ๋ก ํธ์๋ ์คํ์ ์ฌ์ฉ.
+ - ๐จ [Chakra UI](https://chakra-ui.com): ํ๋ก ํธ์๋ ์ปดํฌ๋ํธ.
+ - ๐ค ์๋์ผ๋ก ์์ฑ๋ ํ๋ก ํธ์๋ ํด๋ผ์ด์ธํธ.
+ - ๐งช E2E ํ
์คํธ๋ฅผ ์ํ Playwright.
+ - ๐ฆ ๋คํฌ ๋ชจ๋ ์ง์.
+- ๐ [Docker Compose](https://www.docker.com): ๊ฐ๋ฐ ํ๊ฒฝ๊ณผ ํ๋ก๋์
(์ด์).
+- ๐ ๊ธฐ๋ณธ์ผ๋ก ์ง์๋๋ ์์ ํ ๋น๋ฐ๋ฒํธ ํด์ฑ.
+- ๐ JWT ํ ํฐ ์ธ์ฆ.
+- ๐ซ ์ด๋ฉ์ผ ๊ธฐ๋ฐ ๋น๋ฐ๋ฒํธ ๋ณต๊ตฌ.
+- โ
[Pytest]๋ฅผ ์ด์ฉํ ํ
์คํธ(https://pytest.org).
+- ๐ [Traefik](https://traefik.io): ๋ฆฌ๋ฒ์ค ํ๋ก์ / ๋ก๋ ๋ฐธ๋ฐ์.
+- ๐ข Docker Compose๋ฅผ ์ด์ฉํ ๋ฐฐํฌ ์ง์นจ: ์๋ HTTPS ์ธ์ฆ์๋ฅผ ์ฒ๋ฆฌํ๊ธฐ ์ํ ํ๋ก ํธ์๋ Traefik ํ๋ก์ ์ค์ ๋ฐฉ๋ฒ์ ํฌํจ.
+- ๐ญ GitHub Actions๋ฅผ ๊ธฐ๋ฐ์ผ๋ก CI (์ง์์ ์ธ ํตํฉ) ๋ฐ CD (์ง์์ ์ธ ๋ฐฐํฌ).
diff --git a/docs/nl/docs/features.md b/docs/nl/docs/features.md
new file mode 100644
index 000000000..848b155ec
--- /dev/null
+++ b/docs/nl/docs/features.md
@@ -0,0 +1,201 @@
+# Functionaliteit
+
+## FastAPI functionaliteit
+
+**FastAPI** biedt je het volgende:
+
+### Gebaseerd op open standaarden
+
+*
OpenAPI voor het maken van API's, inclusief declaraties van
padbewerkingen, parameters, request bodies, beveiliging, enz.
+* Automatische datamodel documentatie met
JSON Schema (aangezien OpenAPI zelf is gebaseerd op JSON Schema).
+* Ontworpen op basis van deze standaarden, na zorgvuldig onderzoek. In plaats van achteraf deze laag er bovenop te bouwen.
+* Dit maakt het ook mogelijk om automatisch **clientcode te genereren** in verschillende programmeertalen.
+
+### Automatische documentatie
+
+Interactieve API-documentatie en verkenning van webgebruikersinterfaces. Aangezien dit framework is gebaseerd op OpenAPI, zijn er meerdere documentatie opties mogelijk, waarvan er standaard 2 zijn inbegrepen.
+
+*
Swagger UI, met interactieve interface, maakt het mogelijk je API rechtstreeks vanuit de browser aan te roepen en te testen.
+
+
+
+* Alternatieve API-documentatie met
ReDoc.
+
+
+
+### Gewoon Moderne Python
+
+Het is allemaal gebaseerd op standaard **Python type** declaraties (dankzij Pydantic). Je hoeft dus geen nieuwe syntax te leren. Het is gewoon standaard moderne Python.
+
+Als je een opfriscursus van 2 minuten nodig hebt over het gebruik van Python types (zelfs als je FastAPI niet gebruikt), bekijk dan deze korte tutorial: [Python Types](python-types.md){.internal-link target=_blank}.
+
+Je schrijft gewoon standaard Python met types:
+
+```Python
+from datetime import date
+
+from pydantic import BaseModel
+
+# Declareer een variabele als een str
+# en krijg editorondersteuning in de functie
+def main(user_id: str):
+ return user_id
+
+
+# Een Pydantic model
+class User(BaseModel):
+ id: int
+ name: str
+ joined: date
+```
+
+Vervolgens kan je het op deze manier gebruiken:
+
+```Python
+my_user: User = User(id=3, name="John Doe", joined="2018-07-19")
+
+second_user_data = {
+ "id": 4,
+ "name": "Mary",
+ "joined": "2018-11-30",
+}
+
+my_second_user: User = User(**second_user_data)
+```
+
+/// info
+
+`**second_user_data` betekent:
+
+Geef de sleutels (keys) en waarden (values) van de `second_user_data` dict direct door als sleutel-waarden argumenten, gelijk aan: `User(id=4, name=โMaryโ, joined=โ2018-11-30โ)`
+
+///
+
+### Editor-ondersteuning
+
+Het gehele framework is ontworpen om eenvoudig en intuรฏtief te zijn in gebruik. Alle beslissingen zijn getest op meerdere code-editors nog voordat het daadwerkelijke ontwikkelen begon, om zo de beste ontwikkelervaring te garanderen.
+
+Uit enquรชtes onder Python ontwikkelaars blijkt maar al te duidelijk dat "(automatische) code aanvulling"
een van de meest gebruikte functionaliteiten is.
+
+Het hele **FastAPI** framework is daarop gebaseerd. Automatische code aanvulling werkt overal.
+
+Je hoeft zelden terug te vallen op de documentatie.
+
+Zo kan je editor je helpen:
+
+* in
Visual Studio Code:
+
+
+
+* in
PyCharm:
+
+
+
+Je krijgt autocomletion die je voorheen misschien zelfs voor onmogelijk had gehouden. Zoals bijvoorbeeld de `price` key in een JSON body (die genest had kunnen zijn) die afkomstig is van een request.
+
+Je hoeft niet langer de verkeerde keys in te typen, op en neer te gaan tussen de documentatie, of heen en weer te scrollen om te checken of je `username` of toch `user_name` had gebruikt.
+
+### Kort
+
+Dit framework heeft voor alles verstandige **standaardinstellingen**, met overal optionele configuraties. Alle parameters kunnen worden verfijnd zodat het past bij wat je nodig hebt, om zo de API te kunnen definiรซren die jij nodig hebt.
+
+Maar standaard werkt alles **โgewoonโ**.
+
+### Validatie
+
+* Validatie voor de meeste (of misschien wel alle?) Python **datatypes**, inclusief:
+ * JSON objecten (`dict`).
+ * JSON array (`list`) die itemtypes definiรซren.
+ * String (`str`) velden, die min en max lengtes hebben.
+ * Getallen (`int`, `float`) met min en max waarden, enz.
+
+* Validatie voor meer exotische typen, zoals:
+ * URL.
+ * E-mail.
+ * UUID.
+ * ...en anderen.
+
+Alle validatie wordt uitgevoerd door het beproefde en robuuste **Pydantic**.
+
+### Beveiliging en authenticatie
+
+Beveiliging en authenticatie is geรฏntegreerd. Zonder compromissen te doen naar databases of datamodellen.
+
+Alle beveiligingsschema's gedefinieerd in OpenAPI, inclusief:
+
+* HTTP Basic.
+* **OAuth2** (ook met **JWT tokens**). Bekijk de tutorial over [OAuth2 with JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}.
+* API keys in:
+ * Headers.
+ * Query parameters.
+ * Cookies, enz.
+
+Plus alle beveiligingsfuncties van Starlette (inclusief **sessiecookies**).
+
+Gebouwd als een herbruikbare tool met componenten die makkelijk te integreren zijn in en met je systemen, datastores, relationele en NoSQL databases, enz.
+
+### Dependency Injection
+
+FastAPI bevat een uiterst eenvoudig, maar uiterst krachtig
Dependency Injection systeem.
+
+* Zelfs dependencies kunnen dependencies hebben, waardoor een hiรซrarchie of **โgraphโ van dependencies** ontstaat.
+* Allemaal **automatisch afgehandeld** door het framework.
+* Alle dependencies kunnen data nodig hebben van request, de vereiste **padoperaties veranderen** en automatische documentatie verstrekken.
+* **Automatische validatie** zelfs voor *padoperatie* parameters gedefinieerd in dependencies.
+* Ondersteuning voor complexe gebruikersauthenticatiesystemen, **databaseverbindingen**, enz.
+* **Geen compromisen** met databases, gebruikersinterfaces, enz. Maar eenvoudige integratie met ze allemaal.
+
+### Ongelimiteerde "plug-ins"
+
+Of anders gezegd, je hebt ze niet nodig, importeer en gebruik de code die je nodig hebt.
+
+Elke integratie is ontworpen om eenvoudig te gebruiken (met afhankelijkheden), zodat je een โplug-in" kunt maken in 2 regels code, met dezelfde structuur en syntax die wordt gebruikt voor je *padbewerkingen*.
+
+### Getest
+
+* 100%
van de code is getest.
+* 100%
type geannoteerde codebase.
+* Wordt gebruikt in productietoepassingen.
+
+## Starlette functies
+
+**FastAPI** is volledig verenigbaar met (en gebaseerd op)
Starlette.
+
+`FastAPI` is eigenlijk een subklasse van `Starlette`. Dus als je Starlette al kent of gebruikt, zal de meeste functionaliteit op dezelfde manier werken.
+
+Met **FastAPI** krijg je alle functies van **Starlette** (FastAPI is gewoon Starlette op steroรฏden):
+
+* Zeer indrukwekkende prestaties. Het is
een van de snelste Python frameworks, vergelijkbaar met **NodeJS** en **Go**.
+* **WebSocket** ondersteuning.
+* Taken in de achtergrond tijdens het proces.
+* Opstart- en afsluit events.
+* Test client gebouwd op HTTPX.
+* **CORS**, GZip, Statische bestanden, Streaming reacties.
+* **Sessie en Cookie** ondersteuning.
+* 100% van de code is getest.
+* 100% type geannoteerde codebase.
+
+## Pydantic functionaliteit
+
+**FastAPI** is volledig verenigbaar met (en gebaseerd op) Pydantic. Dus alle extra
Pydantic code die je nog hebt werkt ook.
+
+Inclusief externe pakketten die ook gebaseerd zijn op Pydantic, zoals
ORMs,
ODMs voor databases.
+
+Dit betekent ook dat je in veel gevallen het object dat je van een request krijgt **direct naar je database** kunt sturen, omdat alles automatisch wordt gevalideerd.
+
+Hetzelfde geldt ook andersom, in veel gevallen kun je dus het object dat je krijgt van de database **direct doorgeven aan de client**.
+
+Met **FastAPI** krijg je alle functionaliteit van **Pydantic** (omdat FastAPI is gebaseerd op Pydantic voor alle dataverwerking):
+
+* **Geen brainfucks**:
+ * Je hoeft geen nieuwe microtaal voor schemadefinities te leren.
+ * Als je bekend bent Python types, weet je hoe je Pydantic moet gebruiken.
+* Werkt goed samen met je **
IDE/
linter/hersenen**:
+ * Doordat pydantic's datastructuren enkel instanties zijn van klassen, die je definieert, werkt automatische aanvulling, linting, mypy en je intuรฏtie allemaal goed met je gevalideerde data.
+* Valideer **complexe structuren**:
+ * Gebruik van hiรซrarchische Pydantic modellen, Python `typing`'s `List` en `Dict`, enz.
+ * Met validators kunnen complexe dataschema's duidelijk en eenvoudig worden gedefinieerd, gecontroleerd en gedocumenteerd als JSON Schema.
+ * Je kunt diep **geneste JSON** objecten laten valideren en annoteren.
+* **Uitbreidbaar**:
+ * Met Pydantic kunnen op maat gemaakte datatypen worden gedefinieerd of je kunt validatie uitbreiden met methoden op een model dat is ingericht met de decorator validator.
+* 100% van de code is getest.
diff --git a/docs/nl/docs/index.md b/docs/nl/docs/index.md
new file mode 100644
index 000000000..8edc3ba0c
--- /dev/null
+++ b/docs/nl/docs/index.md
@@ -0,0 +1,494 @@
+# FastAPI
+
+
+
+
+ 
+
+
+ FastAPI framework, zeer goede prestaties, eenvoudig te leren, snel te programmeren, klaar voor productie
+
+
+
+ 
+
+
+ 
+
+
+ 
+
+
+ 
+
+
+
+---
+
+**Documentatie**:
https://fastapi.tiangolo.com
+
+**Broncode**:
https://github.com/tiangolo/fastapi
+
+---
+
+FastAPI is een modern, snel (zeer goede prestaties), web framework voor het bouwen van API's in Python, gebruikmakend van standaard Python type-hints.
+
+De belangrijkste kenmerken zijn:
+
+* **Snel**: Zeer goede prestaties, vergelijkbaar met **NodeJS** en **Go** (dankzij Starlette en Pydantic). [Een van de snelste beschikbare Python frameworks](#prestaties).
+* **Snel te programmeren**: Verhoog de snelheid om functionaliteit te ontwikkelen met ongeveer 200% tot 300%. *
+* **Minder bugs**: Verminder ongeveer 40% van de door mensen (ontwikkelaars) veroorzaakte fouten. *
+* **Intuรฏtief**: Buitengewoon goede ondersteuning voor editors.
Overal automische code aanvulling. Minder tijd kwijt aan debuggen.
+* **Eenvoudig**: Ontworpen om gemakkelijk te gebruiken en te leren. Minder tijd nodig om documentatie te lezen.
+* **Kort**: Minimaliseer codeduplicatie. Elke parameterdeclaratie ondersteunt meerdere functionaliteiten. Minder bugs.
+* **Robust**: Code gereed voor productie. Met automatische interactieve documentatie.
+* **Standards-based**: Gebaseerd op (en volledig verenigbaar met) open standaarden voor API's:
OpenAPI (voorheen bekend als Swagger) en
JSON Schema.
+
+
* schatting op basis van testen met een intern ontwikkelteam en bouwen van productieapplicaties.
+
+## Sponsors
+
+
+
+{% if sponsors %}
+{% for sponsor in sponsors.gold -%}
+
+{% endfor -%}
+{%- for sponsor in sponsors.silver -%}
+
+{% endfor %}
+{% endif %}
+
+
+
+
Overige sponsoren
+
+## Meningen
+
+"_[...] Ik gebruik **FastAPI** heel vaak tegenwoordig. [...] Ik ben van plan om het te gebruiken voor alle **ML-services van mijn team bij Microsoft**. Sommige van deze worden geรฏntegreerd in het kernproduct van **Windows** en sommige **Office**-producten._"
+
+
Kabir Khan -
Microsoft (ref)
+
+---
+
+"_We hebben de **FastAPI** library gebruikt om een **REST** server te maken die bevraagd kan worden om **voorspellingen** te maken. [voor Ludwig]_"
+
+
Piero Molino, Yaroslav Dudin en Sai Sumanth Miryala -
Uber (ref)
+
+---
+
+"_**Netflix** is verheugd om een open-source release aan te kondigen van ons **crisismanagement**-orkestratieframework: **Dispatch**! [gebouwd met **FastAPI**]_"
+
+
Kevin Glisson, Marc Vilanova, Forest Monsen -
Netflix (ref)
+
+---
+
+"_Ik ben super enthousiast over **FastAPI**. Het is zo leuk!_"
+
+
+
+---
+
+"_Wat je hebt gebouwd ziet er echt super solide en gepolijst uit. In veel opzichten is het wat ik wilde dat **Hug** kon zijn - het is echt inspirerend om iemand dit te zien bouwen._"
+
+
+
+---
+
+"Wie geรฏnteresseerd is in een **modern framework** voor het bouwen van REST API's, bekijkt best eens **FastAPI** [...] Het is snel, gebruiksvriendelijk en gemakkelijk te leren [...]_"
+
+"_We zijn overgestapt naar **FastAPI** voor onze **API's** [...] Het gaat jou vast ook bevallen [...]_"
+
+
+
+---
+
+"_Wie een Python API wil bouwen voor productie, kan ik ten stelligste **FastAPI** aanraden. Het is **prachtig ontworpen**, **eenvoudig te gebruiken** en **gemakkelijk schaalbaar**, het is een **cruciale component** geworden in onze strategie om API's centraal te zetten, en het vereenvoudigt automatisering en diensten zoals onze Virtual TAC Engineer._"
+
+
Deon Pillsbury -
Cisco (ref)
+
+---
+
+## **Typer**, de FastAPI van CLIs
+
+
+
+Als je een
CLI-app bouwt die in de terminal moet worden gebruikt in plaats van een web-API, gebruik dan
**Typer**.
+
+**Typer** is het kleine broertje van FastAPI. En het is bedoeld als de **FastAPI van CLI's**. ๏ธ
+
+## Vereisten
+
+FastAPI staat op de schouders van reuzen:
+
+*
Starlette voor de webonderdelen.
+*
Pydantic voor de datadelen.
+
+## Installatie
+
+
+
+```console
+$ pip install "fastapi[standard]"
+
+---> 100%
+```
+
+
+
+**Opmerking**: Zet `"fastapi[standard]"` tussen aanhalingstekens om ervoor te zorgen dat het werkt in alle terminals.
+
+## Voorbeeld
+
+### Creรซer het
+
+* Maak het bestand `main.py` aan met daarin:
+
+```Python
+from typing import Union
+
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+def read_root():
+ return {"Hello": "World"}
+
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int, q: Union[str, None] = None):
+ return {"item_id": item_id, "q": q}
+```
+
+
+Of maak gebruik van async def...
+
+Als je code gebruik maakt van `async` / `await`, gebruik dan `async def`:
+
+```Python hl_lines="9 14"
+from typing import Union
+
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+async def read_root():
+ return {"Hello": "World"}
+
+
+@app.get("/items/{item_id}")
+async def read_item(item_id: int, q: Union[str, None] = None):
+ return {"item_id": item_id, "q": q}
+```
+
+**Opmerking**:
+
+Als je het niet weet, kijk dan in het gedeelte _"Heb je haast?"_ over `async` en `await` in de documentatie.
+
+
+
+### Voer het uit
+
+Run de server met:
+
+
+
+```console
+$ fastapi dev main.py
+
+ โญโโโโโโโโโโ FastAPI CLI - Development mode โโโโโโโโโโโโฎ
+ โ โ
+ โ Serving at: http://127.0.0.1:8000 โ
+ โ โ
+ โ API docs: http://127.0.0.1:8000/docs โ
+ โ โ
+ โ Running in development mode, for production use: โ
+ โ โ
+ โ fastapi run โ
+ โ โ
+ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
+
+INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp']
+INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+INFO: Started reloader process [2248755] using WatchFiles
+INFO: Started server process [2248757]
+INFO: Waiting for application startup.
+INFO: Application startup complete.
+```
+
+
+
+
+Over het commando fastapi dev main.py...
+
+Het commando `fastapi dev` leest het `main.py` bestand, detecteert de **FastAPI** app, en start een server met Uvicorn.
+
+Standaard zal dit commando `fastapi dev` starten met "auto-reload" geactiveerd voor ontwikkeling op het lokale systeem.
+
+Je kan hier meer over lezen in de FastAPI CLI documentatie.
+
+
+
+### Controleer het
+
+Open je browser op
http://127.0.0.1:8000/items/5?q=somequery.
+
+Je zult een JSON response zien:
+
+```JSON
+{"item_id": 5, "q": "somequery"}
+```
+
+Je hebt een API gemaakt die:
+
+* HTTP verzoeken kan ontvangen op de _paden_ `/` en `/items/{item_id}`.
+* Beide _paden_ hebben `GET`
operaties (ook bekend als HTTP _methoden_).
+* Het _pad_ `/items/{item_id}` heeft een _pad parameter_ `item_id` dat een `int` moet zijn.
+* Het _pad_ `/items/{item_id}` heeft een optionele `str` _query parameter_ `q`.
+
+### Interactieve API documentatie
+
+Ga naar
http://127.0.0.1:8000/docs.
+
+Je ziet de automatische interactieve API documentatie (verstrekt door
Swagger UI):
+
+
+
+### Alternatieve API documentatie
+
+Ga vervolgens naar
http://127.0.0.1:8000/redoc.
+
+Je ziet de automatische interactieve API documentatie (verstrekt door
ReDoc):
+
+
+
+## Voorbeeld upgrade
+
+Pas nu het bestand `main.py` aan om de body van een `PUT` request te ontvangen.
+
+Dankzij Pydantic kunnen we de body declareren met standaard Python types.
+
+```Python hl_lines="4 9-12 25-27"
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+ name: str
+ price: float
+ is_offer: Union[bool, None] = None
+
+
+@app.get("/")
+def read_root():
+ return {"Hello": "World"}
+
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int, q: Union[str, None] = None):
+ return {"item_id": item_id, "q": q}
+
+
+@app.put("/items/{item_id}")
+def update_item(item_id: int, item: Item):
+ return {"item_name": item.name, "item_id": item_id}
+```
+
+De `fastapi dev` server zou automatisch moeten herladen.
+
+### Interactieve API documentatie upgrade
+
+Ga nu naar
http://127.0.0.1:8000/docs.
+
+* De interactieve API-documentatie wordt automatisch bijgewerkt, inclusief de nieuwe body:
+
+
+
+* Klik op de knop "Try it out", hiermee kan je de parameters invullen en direct met de API interacteren:
+
+
+
+* Klik vervolgens op de knop "Execute", de gebruikersinterface zal communiceren met jouw API, de parameters verzenden, de resultaten ophalen en deze op het scherm tonen:
+
+
+
+### Alternatieve API documentatie upgrade
+
+Ga vervolgens naar
http://127.0.0.1:8000/redoc.
+
+* De alternatieve documentatie zal ook de nieuwe queryparameter en body weergeven:
+
+
+
+### Samenvatting
+
+Samengevat declareer je **eenmalig** de types van parameters, body, etc. als functieparameters.
+
+Dat doe je met standaard moderne Python types.
+
+Je hoeft geen nieuwe syntax te leren, de methods of klassen van een specifieke bibliotheek, etc.
+
+Gewoon standaard **Python**.
+
+Bijvoorbeeld, voor een `int`:
+
+```Python
+item_id: int
+```
+
+of voor een complexer `Item` model:
+
+```Python
+item: Item
+```
+
+...en met die ene verklaring krijg je:
+
+* Editor ondersteuning, inclusief:
+ * Code aanvulling.
+ * Type validatie.
+* Validatie van data:
+ * Automatische en duidelijke foutboodschappen wanneer de data ongeldig is.
+ * Validatie zelfs voor diep geneste JSON objecten.
+*
Conversie van invoergegevens: afkomstig van het netwerk naar Python-data en -types. Zoals:
+ * JSON.
+ * Pad parameters.
+ * Query parameters.
+ * Cookies.
+ * Headers.
+ * Formulieren.
+ * Bestanden.
+*
Conversie van uitvoergegevens: converstie van Python-data en -types naar netwerkgegevens (zoals JSON):
+ * Converteer Python types (`str`, `int`, `float`, `bool`, `list`, etc).
+ * `datetime` objecten.
+ * `UUID` objecten.
+ * Database modellen.
+ * ...en nog veel meer.
+* Automatische interactieve API-documentatie, inclusief 2 alternatieve gebruikersinterfaces:
+ * Swagger UI.
+ * ReDoc.
+
+---
+
+Terugkomend op het vorige code voorbeeld, **FastAPI** zal:
+
+* Valideren dat er een `item_id` bestaat in het pad voor `GET` en `PUT` verzoeken.
+* Valideren dat het `item_id` van het type `int` is voor `GET` en `PUT` verzoeken.
+ * Wanneer dat niet het geval is, krijgt de cliรซnt een nuttige, duidelijke foutmelding.
+* Controleren of er een optionele query parameter is met de naam `q` (zoals in `http://127.0.0.1:8000/items/foo?q=somequery`) voor `GET` verzoeken.
+ * Aangezien de `q` parameter werd gedeclareerd met `= None`, is deze optioneel.
+ * Zonder de `None` declaratie zou deze verplicht zijn (net als bij de body in het geval met `PUT`).
+* Voor `PUT` verzoeken naar `/items/{item_id}`, lees de body als JSON:
+ * Controleer of het een verplicht attribuut `naam` heeft en dat dat een `str` is.
+ * Controleer of het een verplicht attribuut `price` heeft en dat dat een`float` is.
+ * Controleer of het een optioneel attribuut `is_offer` heeft, dat een `bool` is wanneer het aanwezig is.
+ * Dit alles werkt ook voor diep geneste JSON objecten.
+* Converteer automatisch van en naar JSON.
+* Documenteer alles met OpenAPI, dat gebruikt kan worden door:
+ * Interactieve documentatiesystemen.
+ * Automatische client code generatie systemen, voor vele talen.
+* Biedt 2 interactieve documentatie-webinterfaces aan.
+
+---
+
+Dit was nog maar een snel overzicht, maar je zou nu toch al een idee moeten hebben over hoe het allemaal werkt.
+
+Probeer deze regel te veranderen:
+
+```Python
+ return {"item_name": item.name, "item_id": item_id}
+```
+
+...van:
+
+```Python
+ ... "item_name": item.name ...
+```
+
+...naar:
+
+```Python
+ ... "item_price": item.price ...
+```
+
+...en zie hoe je editor de attributen automatisch invult en hun types herkent:
+
+
+
+Voor een vollediger voorbeeld met meer mogelijkheden, zie de
Tutorial - Gebruikershandleiding.
+
+**Spoiler alert**: de tutorial - gebruikershandleiding bevat:
+
+* Declaratie van **parameters** op andere plaatsen zoals: **headers**, **cookies**, **formuliervelden** en **bestanden**.
+* Hoe stel je **validatie restricties** in zoals `maximum_length` of een `regex`.
+* Een zeer krachtig en eenvoudig te gebruiken **
Dependency Injection** systeem.
+* Beveiliging en authenticatie, inclusief ondersteuning voor **OAuth2** met **JWT-tokens** en **HTTP Basic** auth.
+* Meer geavanceerde (maar even eenvoudige) technieken voor het declareren van **diep geneste JSON modellen** (dankzij Pydantic).
+* **GraphQL** integratie met
Strawberry en andere packages.
+* Veel extra functies (dankzij Starlette) zoals:
+ * **WebSockets**
+ * uiterst gemakkelijke tests gebaseerd op HTTPX en `pytest`
+ * **CORS**
+ * **Cookie Sessions**
+ * ...en meer.
+
+## Prestaties
+
+Onafhankelijke TechEmpower benchmarks tonen **FastAPI** applicaties draaiend onder Uvicorn aan als
een van de snelste Python frameworks beschikbaar, alleen onder Starlette en Uvicorn zelf (intern gebruikt door FastAPI). (*)
+
+Zie de sectie
Benchmarks om hier meer over te lezen.
+
+## Afhankelijkheden
+
+FastAPI maakt gebruik van Pydantic en Starlette.
+
+### `standard` Afhankelijkheden
+
+Wanneer je FastAPI installeert met `pip install "fastapi[standard]"`, worden de volgende `standard` optionele afhankelijkheden geรฏnstalleerd:
+
+Gebruikt door Pydantic:
+
+*
email_validator - voor email validatie.
+
+Gebruikt door Starlette:
+
+*
httpx - Vereist indien je de `TestClient` wil gebruiken.
+*
jinja2 - Vereist als je de standaard templateconfiguratie wil gebruiken.
+*
python-multipart - Vereist indien je
"parsen" van formulieren wil ondersteunen met `requests.form()`.
+
+Gebruikt door FastAPI / Starlette:
+
+*
uvicorn - voor de server die jouw applicatie laadt en bedient.
+* `fastapi-cli` - om het `fastapi` commando te voorzien.
+
+### Zonder `standard` Afhankelijkheden
+
+Indien je de optionele `standard` afhankelijkheden niet wenst te installeren, kan je installeren met `pip install fastapi` in plaats van `pip install "fastapi[standard]"`.
+
+### Bijkomende Optionele Afhankelijkheden
+
+Er zijn nog een aantal bijkomende afhankelijkheden die je eventueel kan installeren.
+
+Bijkomende optionele afhankelijkheden voor Pydantic:
+
+*
pydantic-settings - voor het beheren van settings.
+*
pydantic-extra-types - voor extra data types die gebruikt kunnen worden met Pydantic.
+
+Bijkomende optionele afhankelijkheden voor FastAPI:
+
+*
orjson - Vereist indien je `ORJSONResponse` wil gebruiken.
+*
ujson - Vereist indien je `UJSONResponse` wil gebruiken.
+
+## Licentie
+
+Dit project is gelicenseerd onder de voorwaarden van de MIT licentie.
diff --git a/docs/nl/docs/python-types.md b/docs/nl/docs/python-types.md
new file mode 100644
index 000000000..a5562b795
--- /dev/null
+++ b/docs/nl/docs/python-types.md
@@ -0,0 +1,597 @@
+# Introductie tot Python Types
+
+Python biedt ondersteuning voor optionele "type hints" (ook wel "type annotaties" genoemd).
+
+Deze **"type hints"** of annotaties zijn een speciale syntax waarmee het
type van een variabele kan worden gedeclareerd.
+
+Door types voor je variabelen te declareren, kunnen editors en hulpmiddelen je beter ondersteunen.
+
+Dit is slechts een **korte tutorial/opfrisser** over Python type hints. Het behandelt enkel het minimum dat nodig is om ze te gebruiken met **FastAPI**... en dat is relatief weinig.
+
+**FastAPI** is helemaal gebaseerd op deze type hints, ze geven veel voordelen.
+
+Maar zelfs als je **FastAPI** nooit gebruikt, heb je er baat bij om er iets over te leren.
+
+/// note
+
+Als je een Python expert bent en alles al weet over type hints, sla dan dit hoofdstuk over.
+
+///
+
+## Motivatie
+
+Laten we beginnen met een eenvoudig voorbeeld:
+
+```Python
+{!../../../docs_src/python_types/tutorial001.py!}
+```
+
+Het aanroepen van dit programma leidt tot het volgende resultaat:
+
+```
+John Doe
+```
+
+De functie voert het volgende uit:
+
+* Neem een `first_name` en een `last_name`
+* Converteer de eerste letter van elk naar een hoofdletter met `title()`.
+``
+*
Voeg samen met een spatie in het midden.
+
+```Python hl_lines="2"
+{!../../../docs_src/python_types/tutorial001.py!}
+```
+
+### Bewerk het
+
+Dit is een heel eenvoudig programma.
+
+Maar stel je nu voor dat je het vanaf nul zou moeten maken.
+
+Op een gegeven moment zou je aan de definitie van de functie zijn begonnen, je had de parameters klaar...
+
+Maar dan moet je โdie methode die de eerste letter naar hoofdletters converteertโ aanroepen.
+
+Was het `upper`? Was het `uppercase`? `first_uppercase`? `capitalize`?
+
+Dan roep je de hulp in van je oude programmeursvriend, (automatische) code aanvulling in je editor.
+
+Je typt de eerste parameter van de functie, `first_name`, dan een punt (`.`) en drukt dan op `Ctrl+Spatie` om de aanvulling te activeren.
+
+Maar helaas krijg je niets bruikbaars:
+
+
+
+### Types toevoegen
+
+Laten we een enkele regel uit de vorige versie aanpassen.
+
+We zullen precies dit fragment, de parameters van de functie, wijzigen van:
+
+```Python
+ first_name, last_name
+```
+
+naar:
+
+```Python
+ first_name: str, last_name: str
+```
+
+Dat is alles.
+
+Dat zijn de "type hints":
+
+```Python hl_lines="1"
+{!../../../docs_src/python_types/tutorial002.py!}
+```
+
+Dit is niet hetzelfde als het declareren van standaardwaarden zoals bij:
+
+```Python
+ first_name="john", last_name="doe"
+```
+
+Het is iets anders.
+
+We gebruiken dubbele punten (`:`), geen gelijkheidstekens (`=`).
+
+Het toevoegen van type hints verandert normaal gesproken niet wat er gebeurt in je programma t.o.v. wat er zonder type hints zou gebeuren.
+
+Maar stel je voor dat je weer bezig bent met het maken van een functie, maar deze keer met type hints.
+
+Op hetzelfde moment probeer je de automatische aanvulling te activeren met `Ctrl+Spatie` en je ziet:
+
+
+
+Nu kun je de opties bekijken en er doorheen scrollen totdat je de optie vindt die โeen belletje doet rinkelenโ:
+
+
+
+### Meer motivatie
+
+Bekijk deze functie, deze heeft al type hints:
+
+```Python hl_lines="1"
+{!../../../docs_src/python_types/tutorial003.py!}
+```
+
+Omdat de editor de types van de variabelen kent, krijgt u niet alleen aanvulling, maar ook controles op fouten:
+
+
+
+Nu weet je hoe je het moet oplossen, converteer `age` naar een string met `str(age)`:
+
+```Python hl_lines="2"
+{!../../../docs_src/python_types/tutorial004.py!}
+```
+
+## Types declareren
+
+Je hebt net de belangrijkste plek om type hints te declareren gezien. Namelijk als functieparameters.
+
+Dit is ook de belangrijkste plek waar je ze gebruikt met **FastAPI**.
+
+### Eenvoudige types
+
+Je kunt alle standaard Python types declareren, niet alleen `str`.
+
+Je kunt bijvoorbeeld het volgende gebruiken:
+
+* `int`
+* `float`
+* `bool`
+* `bytes`
+
+```Python hl_lines="1"
+{!../../../docs_src/python_types/tutorial005.py!}
+```
+
+### Generieke types met typeparameters
+
+Er zijn enkele datastructuren die andere waarden kunnen bevatten, zoals `dict`, `list`, `set` en `tuple` en waar ook de interne waarden hun eigen type kunnen hebben.
+
+Deze types die interne types hebben worden โ**generieke**โ types genoemd. Het is mogelijk om ze te declareren, zelfs met hun interne types.
+
+Om deze types en de interne types te declareren, kun je de standaard Python module `typing` gebruiken. Deze module is speciaal gemaakt om deze type hints te ondersteunen.
+
+#### Nieuwere versies van Python
+
+De syntax met `typing` is **verenigbaar** met alle versies, van Python 3.6 tot aan de nieuwste, inclusief Python 3.9, Python 3.10, enz.
+
+Naarmate Python zich ontwikkelt, worden **nieuwere versies**, met verbeterde ondersteuning voor deze type annotaties, beschikbaar. In veel gevallen hoef je niet eens de `typing` module te importeren en te gebruiken om de type annotaties te declareren.
+
+Als je een recentere versie van Python kunt kiezen voor je project, kun je profiteren van die extra eenvoud.
+
+In alle documentatie staan voorbeelden die compatibel zijn met elke versie van Python (als er een verschil is).
+
+Bijvoorbeeld โ**Python 3.6+**โ betekent dat het compatibel is met Python 3.6 of hoger (inclusief 3.7, 3.8, 3.9, 3.10, etc). En โ**Python 3.9+**โ betekent dat het compatibel is met Python 3.9 of hoger (inclusief 3.10, etc).
+
+Als je de **laatste versies van Python** kunt gebruiken, gebruik dan de voorbeelden voor de laatste versie, die hebben de **beste en eenvoudigste syntax**, bijvoorbeeld โ**Python 3.10+**โ.
+
+#### List
+
+Laten we bijvoorbeeld een variabele definiรซren als een `list` van `str`.
+
+//// tab | Python 3.9+
+
+Declareer de variabele met dezelfde dubbele punt (`:`) syntax.
+
+Als type, vul `list` in.
+
+Doordat de list een type is dat enkele interne types bevat, zet je ze tussen vierkante haakjes:
+
+```Python hl_lines="1"
+{!> ../../../docs_src/python_types/tutorial006_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+Van `typing`, importeer `List` (met een hoofdletter `L`):
+
+```Python hl_lines="1"
+{!> ../../../docs_src/python_types/tutorial006.py!}
+```
+
+Declareer de variabele met dezelfde dubbele punt (`:`) syntax.
+
+Zet als type de `List` die je hebt geรฏmporteerd uit `typing`.
+
+Doordat de list een type is dat enkele interne types bevat, zet je ze tussen vierkante haakjes:
+
+```Python hl_lines="4"
+{!> ../../../docs_src/python_types/tutorial006.py!}
+```
+
+////
+
+/// info
+
+De interne types tussen vierkante haakjes worden โtypeparametersโ genoemd.
+
+In dit geval is `str` de typeparameter die wordt doorgegeven aan `List` (of `list` in Python 3.9 en hoger).
+
+///
+
+Dat betekent: โde variabele `items` is een `list`, en elk van de items in deze list is een `str`โ.
+
+/// tip
+
+Als je Python 3.9 of hoger gebruikt, hoef je `List` niet te importeren uit `typing`, je kunt in plaats daarvan hetzelfde reguliere `list` type gebruiken.
+
+///
+
+Door dat te doen, kan je editor ondersteuning bieden, zelfs tijdens het verwerken van items uit de list:
+
+
+
+Zonder types is dat bijna onmogelijk om te bereiken.
+
+Merk op dat de variabele `item` een van de elementen is in de lijst `items`.
+
+Toch weet de editor dat het een `str` is, en biedt daar vervolgens ondersteuning voor aan.
+
+#### Tuple en Set
+
+Je kunt hetzelfde doen om `tuple`s en `set`s te declareren:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="1"
+{!> ../../../docs_src/python_types/tutorial007_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../../docs_src/python_types/tutorial007.py!}
+```
+
+////
+
+Dit betekent:
+
+* De variabele `items_t` is een `tuple` met 3 items, een `int`, nog een `int`, en een `str`.
+* De variabele `items_s` is een `set`, en elk van de items is van het type `bytes`.
+
+#### Dict
+
+Om een `dict` te definiรซren, geef je 2 typeparameters door, gescheiden door komma's.
+
+De eerste typeparameter is voor de sleutels (keys) van de `dict`.
+
+De tweede typeparameter is voor de waarden (values) van het `dict`:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="1"
+{!> ../../../docs_src/python_types/tutorial008_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../../docs_src/python_types/tutorial008.py!}
+```
+
+////
+
+Dit betekent:
+
+* De variabele `prices` is een `dict`:
+ * De sleutels van dit `dict` zijn van het type `str` (bijvoorbeeld de naam van elk item).
+ * De waarden van dit `dict` zijn van het type `float` (bijvoorbeeld de prijs van elk item).
+
+#### Union
+
+Je kunt een variable declareren die van **verschillende types** kan zijn, bijvoorbeeld een `int` of een `str`.
+
+In Python 3.6 en hoger (inclusief Python 3.10) kun je het `Union`-type van `typing` gebruiken en de mogelijke types die je wilt accepteren, tussen de vierkante haakjes zetten.
+
+In Python 3.10 is er ook een **nieuwe syntax** waarin je de mogelijke types kunt scheiden door een
verticale balk (`|`).
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../../docs_src/python_types/tutorial008b_py310.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../../docs_src/python_types/tutorial008b.py!}
+```
+
+////
+
+In beide gevallen betekent dit dat `item` een `int` of een `str` kan zijn.
+
+#### Mogelijk `None`
+
+Je kunt declareren dat een waarde een type kan hebben, zoals `str`, maar dat het ook `None` kan zijn.
+
+In Python 3.6 en hoger (inclusief Python 3.10) kun je het declareren door `Optional` te importeren en te gebruiken vanuit de `typing`-module.
+
+```Python hl_lines="1 4"
+{!../../../docs_src/python_types/tutorial009.py!}
+```
+
+Door `Optional[str]` te gebruiken in plaats van alleen `str`, kan de editor je helpen fouten te detecteren waarbij je ervan uit zou kunnen gaan dat een waarde altijd een `str` is, terwijl het in werkelijkheid ook `None` zou kunnen zijn.
+
+`Optional[EenType]` is eigenlijk een snelkoppeling voor `Union[EenType, None]`, ze zijn equivalent.
+
+Dit betekent ook dat je in Python 3.10 `EenType | None` kunt gebruiken:
+
+//// tab | Python 3.10+
+
+```Python hl_lines="1"
+{!> ../../../docs_src/python_types/tutorial009_py310.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 4"
+{!> ../../../docs_src/python_types/tutorial009.py!}
+```
+
+////
+
+//// tab | Python 3.8+ alternative
+
+```Python hl_lines="1 4"
+{!> ../../../docs_src/python_types/tutorial009b.py!}
+```
+
+////
+
+#### Gebruik van `Union` of `Optional`
+
+Als je een Python versie lager dan 3.10 gebruikt, is dit een tip vanuit mijn **subjectieve** standpunt:
+
+* ๐จ Vermijd het gebruik van `Optional[EenType]`.
+* Gebruik in plaats daarvan **`Union[EenType, None]`** โจ.
+
+Beide zijn gelijkwaardig en onderliggend zijn ze hetzelfde, maar ik zou `Union` aanraden in plaats van `Optional` omdat het woord โ**optional**โ lijkt te impliceren dat de waarde optioneel is, en het eigenlijk betekent โhet kan `None` zijnโ, zelfs als het niet optioneel is en nog steeds vereist is.
+
+Ik denk dat `Union[SomeType, None]` explicieter is over wat het betekent.
+
+Het gaat alleen om de woorden en naamgeving. Maar die naamgeving kan invloed hebben op hoe jij en je teamgenoten over de code denken.
+
+Laten we als voorbeeld deze functie nemen:
+
+```Python hl_lines="1 4"
+{!../../../docs_src/python_types/tutorial009c.py!}
+```
+
+De parameter `name` is gedefinieerd als `Optional[str]`, maar is **niet optioneel**, je kunt de functie niet aanroepen zonder de parameter:
+
+```Python
+say_hi() # Oh, nee, dit geeft een foutmelding! ๐ฑ
+```
+
+De `name` parameter is **nog steeds vereist** (niet *optioneel*) omdat het geen standaardwaarde heeft. Toch accepteert `name` `None` als waarde:
+
+```Python
+say_hi(name=None) # Dit werkt, None is geldig ๐
+```
+
+Het goede nieuws is dat als je eenmaal Python 3.10 gebruikt, je je daar geen zorgen meer over hoeft te maken, omdat je dan gewoon `|` kunt gebruiken om unions van types te definiรซren:
+
+```Python hl_lines="1 4"
+{!../../../docs_src/python_types/tutorial009c_py310.py!}
+```
+
+Dan hoef je je geen zorgen te maken over namen als `Optional` en `Union`. ๐
+
+#### Generieke typen
+
+De types die typeparameters in vierkante haakjes gebruiken, worden **Generieke types** of **Generics** genoemd, bijvoorbeeld:
+
+//// tab | Python 3.10+
+
+Je kunt dezelfde ingebouwde types gebruiken als generics (met vierkante haakjes en types erin):
+
+* `list`
+* `tuple`
+* `set`
+* `dict`
+
+Hetzelfde als bij Python 3.8, uit de `typing`-module:
+
+* `Union`
+* `Optional` (hetzelfde als bij Python 3.8)
+* ...en anderen.
+
+In Python 3.10 kun je , als alternatief voor de generieke `Union` en `Optional`, de
verticale lijn (`|`) gebruiken om unions van typen te voorzien, dat is veel beter en eenvoudiger.
+
+////
+
+//// tab | Python 3.9+
+
+Je kunt dezelfde ingebouwde types gebruiken als generieke types (met vierkante haakjes en types erin):
+
+* `list`
+* `tuple`
+* `set`
+* `dict`
+
+En hetzelfde als met Python 3.8, vanuit de `typing`-module:
+
+* `Union`
+* `Optional`
+* ...en anderen.
+
+////
+
+//// tab | Python 3.8+
+
+* `List`
+* `Tuple`
+* `Set`
+* `Dict`
+* `Union`
+* `Optional`
+* ...en anderen.
+
+////
+
+### Klassen als types
+
+Je kunt een klasse ook declareren als het type van een variabele.
+
+Stel dat je een klasse `Person` hebt, met een naam:
+
+```Python hl_lines="1-3"
+{!../../../docs_src/python_types/tutorial010.py!}
+```
+
+Vervolgens kun je een variabele van het type `Persoon` declareren:
+
+```Python hl_lines="6"
+{!../../../docs_src/python_types/tutorial010.py!}
+```
+
+Dan krijg je ook nog eens volledige editorondersteuning:
+
+
+
+Merk op dat dit betekent dat "`one_person` een **instantie** is van de klasse `Person`".
+
+Dit betekent niet dat `one_person` de **klasse** is met de naam `Person`.
+
+## Pydantic modellen
+
+
Pydantic is een Python-pakket voor het uitvoeren van datavalidatie.
+
+Je declareert de "vorm" van de data als klassen met attributen.
+
+Elk attribuut heeft een type.
+
+Vervolgens maak je een instantie van die klasse met een aantal waarden en het valideert de waarden, converteert ze naar het juiste type (als dat het geval is) en geeft je een object met alle data terug.
+
+Daarnaast krijg je volledige editorondersteuning met dat resulterende object.
+
+Een voorbeeld uit de officiรซle Pydantic-documentatie:
+
+//// tab | Python 3.10+
+
+```Python
+{!> ../../../docs_src/python_types/tutorial011_py310.py!}
+```
+
+////
+
+//// tab | Python 3.9+
+
+```Python
+{!> ../../../docs_src/python_types/tutorial011_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python
+{!> ../../../docs_src/python_types/tutorial011.py!}
+```
+
+////
+
+/// info
+
+Om meer te leren over
Pydantic, bekijk de documentatie.
+
+///
+
+**FastAPI** is volledig gebaseerd op Pydantic.
+
+Je zult veel meer van dit alles in de praktijk zien in de [Tutorial - Gebruikershandleiding](tutorial/index.md){.internal-link target=_blank}.
+
+/// tip
+
+Pydantic heeft een speciaal gedrag wanneer je `Optional` of `Union[EenType, None]` gebruikt zonder een standaardwaarde, je kunt er meer over lezen in de Pydantic-documentatie over
Verplichte optionele velden.
+
+///
+
+## Type Hints met Metadata Annotaties
+
+Python heeft ook een functie waarmee je **extra
metadata** in deze type hints kunt toevoegen met behulp van `Annotated`.
+
+//// tab | Python 3.9+
+
+In Python 3.9 is `Annotated` onderdeel van de standaardpakket, dus je kunt het importeren vanuit `typing`.
+
+```Python hl_lines="1 4"
+{!> ../../../docs_src/python_types/tutorial013_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+In versies lager dan Python 3.9 importeer je `Annotated` vanuit `typing_extensions`.
+
+Het wordt al geรฏnstalleerd met **FastAPI**.
+
+```Python hl_lines="1 4"
+{!> ../../../docs_src/python_types/tutorial013.py!}
+```
+
+////
+
+Python zelf doet niets met deze `Annotated` en voor editors en andere hulpmiddelen is het type nog steeds een `str`.
+
+Maar je kunt deze ruimte in `Annotated` gebruiken om **FastAPI** te voorzien van extra metadata over hoe je wilt dat je applicatie zich gedraagt.
+
+Het belangrijkste om te onthouden is dat **de eerste *typeparameter*** die je doorgeeft aan `Annotated` het **werkelijke type** is. De rest is gewoon metadata voor andere hulpmiddelen.
+
+Voor nu hoef je alleen te weten dat `Annotated` bestaat en dat het standaard Python is. ๐
+
+Later zul je zien hoe **krachtig** het kan zijn.
+
+/// tip
+
+Het feit dat dit **standaard Python** is, betekent dat je nog steeds de **best mogelijke ontwikkelaarservaring** krijgt in je editor, met de hulpmiddelen die je gebruikt om je code te analyseren en te refactoren, enz. โจ
+
+Daarnaast betekent het ook dat je code zeer verenigbaar zal zijn met veel andere Python-hulpmiddelen en -pakketten. ๐
+
+///
+
+## Type hints in **FastAPI**
+
+**FastAPI** maakt gebruik van type hints om verschillende dingen te doen.
+
+Met **FastAPI** declareer je parameters met type hints en krijg je:
+
+* **Editor ondersteuning**.
+* **Type checks**.
+
+...en **FastAPI** gebruikt dezelfde declaraties om:
+
+* **Vereisten te definรฏeren **: van request pad parameters, query parameters, headers, bodies, dependencies, enz.
+* **Data te converteren**: van de request naar het vereiste type.
+* **Data te valideren**: afkomstig van elke request:
+ * **Automatische foutmeldingen** te genereren die naar de client worden geretourneerd wanneer de data ongeldig is.
+* De API met OpenAPI te **documenteren**:
+ * die vervolgens wordt gebruikt door de automatische interactieve documentatie gebruikersinterfaces.
+
+Dit klinkt misschien allemaal abstract. Maak je geen zorgen. Je ziet dit allemaal in actie in de [Tutorial - Gebruikershandleiding](tutorial/index.md){.internal-link target=_blank}.
+
+Het belangrijkste is dat door standaard Python types te gebruiken, op รฉรฉn plek (in plaats van meer klassen, decorators, enz. toe te voegen), **FastAPI** een groot deel van het werk voor je doet.
+
+/// info
+
+Als je de hele tutorial al hebt doorgenomen en terug bent gekomen om meer te weten te komen over types, is een goede bron
het "cheat sheet" van `mypy`.
+
+///
diff --git a/docs/nl/mkdocs.yml b/docs/nl/mkdocs.yml
new file mode 100644
index 000000000..de18856f4
--- /dev/null
+++ b/docs/nl/mkdocs.yml
@@ -0,0 +1 @@
+INHERIT: ../en/mkdocs.yml
diff --git a/docs/pt/docs/advanced/async-tests.md b/docs/pt/docs/advanced/async-tests.md
index ab5bfa648..7cac26262 100644
--- a/docs/pt/docs/advanced/async-tests.md
+++ b/docs/pt/docs/advanced/async-tests.md
@@ -72,7 +72,7 @@ Note que a funรงรฃo de teste รฉ `async def` agora, no lugar de apenas `def` como
Entรฃo podemos criar um `AsyncClient` com a aplicaรงรฃo, e enviar requisiรงรตes assรญncronas para ela utilizando `await`.
-```Python hl_lines="9-10"
+```Python hl_lines="9-12"
{!../../../docs_src/async_tests/test_main.py!}
```
diff --git a/docs/pt/docs/advanced/security/http-basic-auth.md b/docs/pt/docs/advanced/security/http-basic-auth.md
new file mode 100644
index 000000000..12b8ab01c
--- /dev/null
+++ b/docs/pt/docs/advanced/security/http-basic-auth.md
@@ -0,0 +1,192 @@
+# HTTP Basic Auth
+
+Para os casos mais simples, vocรช pode utilizar o HTTP Basic Auth.
+
+No HTTP Basic Auth, a aplicaรงรฃo espera um cabeรงalho que contรฉm um usuรกrio e uma senha.
+
+Caso ela nรฃo receba, ela retorna um erro HTTP 401 "Unauthorized" (*Nรฃo Autorizado*).
+
+E retorna um cabeรงalho `WWW-Authenticate` com o valor `Basic`, e um parรขmetro opcional `realm`.
+
+Isso sinaliza ao navegador para mostrar o prompt integrado para um usuรกrio e senha.
+
+Entรฃo, quando vocรช digitar o usuรกrio e senha, o navegador os envia automaticamente no cabeรงalho.
+
+## HTTP Basic Auth Simples
+
+* Importe `HTTPBasic` e `HTTPBasicCredentials`.
+* Crie um "esquema `security`" utilizando `HTTPBasic`.
+* Utilize o `security` com uma dependรชncia em sua *operaรงรฃo de rota*.
+* Isso retorna um objeto do tipo `HTTPBasicCredentials`:
+ * Isto contรฉm o `username` e o `password` enviado.
+
+//// tab | Python 3.9+
+
+```Python hl_lines="4 8 12"
+{!> ../../../docs_src/security/tutorial006_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="2 7 11"
+{!> ../../../docs_src/security/tutorial006_an.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | "Dica"
+
+Prefira utilizar a versรฃo `Annotated` se possรญvel.
+
+///
+
+```Python hl_lines="2 6 10"
+{!> ../../../docs_src/security/tutorial006.py!}
+```
+
+////
+
+Quando vocรช tentar abrir a URL pela primeira vez (ou clicar no botรฃo "Executar" nos documentos) o navegador vai pedir pelo seu usuรกrio e senha:
+
+
+
+## Verifique o usuรกrio
+
+Aqui estรก um exemplo mais completo.
+
+Utilize uma dependรชncia para verificar se o usuรกrio e a senha estรฃo corretos.
+
+Para isso, utilize o mรณdulo padrรฃo do Python
`secrets` para verificar o usuรกrio e senha.
+
+O `secrets.compare_digest()` necessita receber `bytes` ou `str` que possuem apenas caracteres ASCII (os em Inglรชs). Isso significa que nรฃo funcionaria com caracteres como o `รก`, como em `Sebastiรกn`.
+
+Para lidar com isso, primeiramente nรณs convertemos o `username` e o `password` para `bytes`, codificando-os com UTF-8.
+
+Entรฃo nรณs podemos utilizar o `secrets.compare_digest()` para garantir que o `credentials.username` รฉ `"stanleyjobson"`, e que o `credentials.password` รฉ `"swordfish"`.
+
+//// tab | Python 3.9+
+
+```Python hl_lines="1 12-24"
+{!> ../../../docs_src/security/tutorial007_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1 12-24"
+{!> ../../../docs_src/security/tutorial007_an.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | "Dica"
+
+Prefira utilizar a versรฃo `Annotated` se possรญvel.
+
+///
+
+```Python hl_lines="1 11-21"
+{!> ../../../docs_src/security/tutorial007.py!}
+```
+
+////
+
+Isso seria parecido com:
+
+```Python
+if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"):
+ # Return some error
+ ...
+```
+
+Porรฉm ao utilizar o `secrets.compare_digest()`, isso estarรก seguro contra um tipo de ataque chamado "ataque de temporizaรงรฃo (timing attacks)".
+
+### Ataques de Temporizaรงรฃo
+
+Mas o que รฉ um "ataque de temporizaรงรฃo"?
+
+Vamos imaginar que alguns invasores estรฃo tentando adivinhar o usuรกrio e a senha.
+
+E eles enviam uma requisiรงรฃo com um usuรกrio `johndoe` e uma senha `love123`.
+
+Entรฃo o cรณdigo Python em sua aplicaรงรฃo seria equivalente a algo como:
+
+```Python
+if "johndoe" == "stanleyjobson" and "love123" == "swordfish":
+ ...
+```
+
+Mas no exato momento que o Python compara o primeiro `j` em `johndoe` contra o primeiro `s` em `stanleyjobson`, ele retornarรก `False`, porque ele jรก sabe que aquelas duas strings nรฃo sรฃo a mesma, pensando que "nรฃo existe a necessidade de desperdiรงar mais poder computacional comparando o resto das letras". E a sua aplicaรงรฃo dirรก "Usuรกrio ou senha incorretos".
+
+Mas entรฃo os invasores vรฃo tentar com o usuรกrio `stanleyjobsox` e a senha `love123`.
+
+E a sua aplicaรงรฃo faz algo como:
+
+```Python
+if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish":
+ ...
+```
+
+O Python terรก que comparar todo o `stanleyjobso` tanto em `stanleyjobsox` como em `stanleyjobson` antes de perceber que as strings nรฃo sรฃo a mesma. Entรฃo isso levarรก alguns microsegundos a mais para retornar "Usuรกrio ou senha incorretos".
+
+#### O tempo para responder ajuda os invasores
+
+Neste ponto, ao perceber que o servidor demorou alguns microsegundos a mais para enviar o retorno "Usuรกrio ou senha incorretos", os invasores irรฃo saber que eles acertaram _alguma coisa_, algumas das letras iniciais estavam certas.
+
+E eles podem tentar de novo sabendo que provavelmente รฉ algo mais parecido com `stanleyjobsox` do que com `johndoe`.
+
+#### Um ataque "profissional"
+
+Claro, os invasores nรฃo tentariam tudo isso de forma manual, eles escreveriam um programa para fazer isso, possivelmente com milhares ou milhรตes de testes por segundo. E obteriam apenas uma letra a mais por vez.
+
+Mas fazendo isso, em alguns minutos ou horas os invasores teriam adivinhado o usuรกrio e senha corretos, com a "ajuda" da nossa aplicaรงรฃo, apenas usando o tempo levado para responder.
+
+#### Corrija com o `secrets.compare_digest()`
+
+Mas em nosso cรณdigo nรณs estamos utilizando o `secrets.compare_digest()`.
+
+Resumindo, levarรก o mesmo tempo para comparar `stanleyjobsox` com `stanleyjobson` do que comparar `johndoe` com `stanleyjobson`. E o mesmo para a senha.
+
+Deste modo, ao utilizar `secrets.compare_digest()` no cรณdigo de sua aplicaรงรฃo, ela esterรก a salvo contra toda essa gama de ataques de seguranรงa.
+
+
+### Retorne o erro
+
+Depois de detectar que as credenciais estรฃo incorretas, retorne um `HTTPException` com o status 401 (o mesmo retornado quando nenhuma credencial foi informada) e adicione o cabeรงalho `WWW-Authenticate` para fazer com que o navegador mostre o prompt de login novamente:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="26-30"
+{!> ../../../docs_src/security/tutorial007_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="26-30"
+{!> ../../../docs_src/security/tutorial007_an.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | "Dica"
+
+Prefira utilizar a versรฃo `Annotated` se possรญvel.
+
+///
+
+```Python hl_lines="23-27"
+{!> ../../../docs_src/security/tutorial007.py!}
+```
+
+////
diff --git a/docs/pt/docs/advanced/security/index.md b/docs/pt/docs/advanced/security/index.md
new file mode 100644
index 000000000..ae63f1c96
--- /dev/null
+++ b/docs/pt/docs/advanced/security/index.md
@@ -0,0 +1,19 @@
+# Seguranรงa Avanรงada
+
+## Funcionalidades Adicionais
+
+Existem algumas funcionalidades adicionais para lidar com seguranรงa alรฉm das cobertas em [Tutorial - Guia de Usuรกrio: Seguranรงa](../../tutorial/security/index.md){.internal-link target=_blank}.
+
+/// tip | "Dica"
+
+As prรณximas seรงรตes **nรฃo sรฃo necessariamente "avanรงadas"**.
+
+E รฉ possรญvel que para o seu caso de uso, a soluรงรฃo estรก em uma delas.
+
+///
+
+## Leia o Tutorial primeiro
+
+As prรณximas seรงรตes pressupรตem que vocรช jรก leu o principal [Tutorial - Guia de Usuรกrio: Seguranรงa](../../tutorial/security/index.md){.internal-link target=_blank}.
+
+Todas elas sรฃo baseadas nos mesmos conceitos, mas permitem algumas funcionalidades extras.
diff --git a/docs/pt/docs/advanced/testing-events.md b/docs/pt/docs/advanced/testing-events.md
new file mode 100644
index 000000000..392fb741c
--- /dev/null
+++ b/docs/pt/docs/advanced/testing-events.md
@@ -0,0 +1,7 @@
+# Testando Eventos: inicializaรงรฃo - encerramento
+
+Quando vocรช precisa que os seus manipuladores de eventos (`startup` e `shutdown`) sejam executados em seus testes, vocรช pode utilizar o `TestClient` usando a instruรงรฃo `with`:
+
+```Python hl_lines="9-12 20-24"
+{!../../../docs_src/app_testing/tutorial003.py!}
+```
diff --git a/docs/pt/docs/environment-variables.md b/docs/pt/docs/environment-variables.md
new file mode 100644
index 000000000..360d1c496
--- /dev/null
+++ b/docs/pt/docs/environment-variables.md
@@ -0,0 +1,298 @@
+# Variรกveis de Ambiente
+
+/// tip | "Dica"
+
+Se vocรช jรก sabe o que sรฃo "variรกveis de ambiente" e como usรก-las, pode pular esta seรงรฃo.
+
+///
+
+Uma variรกvel de ambiente (tambรฉm conhecida como "**env var**") รฉ uma variรกvel que existe **fora** do cรณdigo Python, no **sistema operacional**, e pode ser lida pelo seu cรณdigo Python (ou por outros programas tambรฉm).
+
+Variรกveis de ambiente podem ser รบteis para lidar com **configuraรงรตes** do aplicativo, como parte da **instalaรงรฃo** do Python, etc.
+
+## Criar e Usar Variรกveis de Ambiente
+
+Vocรช pode **criar** e usar variรกveis de ambiente no **shell (terminal)**, sem precisar do Python:
+
+//// tab | Linux, macOS, Windows Bash
+
+
+
+```console
+// Vocรช pode criar uma variรกvel de ambiente MY_NAME com
+$ export MY_NAME="Wade Wilson"
+
+// Entรฃo vocรช pode usรก-la com outros programas, como
+$ echo "Hello $MY_NAME"
+
+Hello Wade Wilson
+```
+
+
+
+////
+
+//// tab | Windows PowerShell
+
+
+
+```console
+// Criar uma variรกvel de ambiente MY_NAME
+$ $Env:MY_NAME = "Wade Wilson"
+
+// Usรก-la com outros programas, como
+$ echo "Hello $Env:MY_NAME"
+
+Hello Wade Wilson
+```
+
+
+
+////
+
+## Ler Variรกveis de Ambiente no Python
+
+Vocรช tambรฉm pode criar variรกveis de ambiente **fora** do Python, no terminal (ou com qualquer outro mรฉtodo) e depois **lรช-las no Python**.
+
+Por exemplo, vocรช poderia ter um arquivo `main.py` com:
+
+```Python hl_lines="3"
+import os
+
+name = os.getenv("MY_NAME", "World")
+print(f"Hello {name} from Python")
+```
+
+/// tip | "Dica"
+
+O segundo argumento para
`os.getenv()` รฉ o valor padrรฃo a ser retornado.
+
+Se nรฃo for fornecido, รฉ `None` por padrรฃo, Aqui fornecemos `"World"` como o valor padrรฃo a ser usado.
+
+///
+
+Entรฃo vocรช poderia chamar esse programa Python:
+
+//// tab | Linux, macOS, Windows Bash
+
+
+
+```console
+// Aqui ainda nรฃo definimos a variรกvel de ambiente
+$ python main.py
+
+// Como nรฃo definimos a variรกvel de ambiente, obtemos o valor padrรฃo
+
+Hello World from Python
+
+// Mas se criarmos uma variรกvel de ambiente primeiro
+$ export MY_NAME="Wade Wilson"
+
+// E entรฃo chamar o programa novamente
+$ python main.py
+
+// Agora ele pode ler a variรกvel de ambiente
+
+Hello Wade Wilson from Python
+```
+
+
+
+////
+
+//// tab | Windows PowerShell
+
+
+
+```console
+// Aqui ainda nรฃo definimos a variรกvel de ambiente
+$ python main.py
+
+// Como nรฃo definimos a variรกvel de ambiente, obtemos o valor padrรฃo
+
+Hello World from Python
+
+// Mas se criarmos uma variรกvel de ambiente primeiro
+$ $Env:MY_NAME = "Wade Wilson"
+
+// E entรฃo chamar o programa novamente
+$ python main.py
+
+// Agora ele pode ler a variรกvel de ambiente
+
+Hello Wade Wilson from Python
+```
+
+
+
+////
+
+Como as variรกveis de ambiente podem ser definidas fora do cรณdigo, mas podem ser lidas pelo cรณdigo e nรฃo precisam ser armazenadas (com versรฃo no `git`) com o restante dos arquivos, รฉ comum usรก-las para configuraรงรตes ou **definiรงรตes**.
+
+Vocรช tambรฉm pode criar uma variรกvel de ambiente apenas para uma **invocaรงรฃo especรญfica do programa**, que sรณ estรก disponรญvel para aquele programa e apenas pela duraรงรฃo dele.
+
+Para fazer isso, crie-a na mesma linha, antes do prรณprio programa:
+
+
+
+```console
+// Criar uma variรกvel de ambiente MY_NAME para esta chamada de programa
+$ MY_NAME="Wade Wilson" python main.py
+
+// Agora ele pode ler a variรกvel de ambiente
+
+Hello Wade Wilson from Python
+
+// A variรกvel de ambiente nรฃo existe mais depois
+$ python main.py
+
+Hello World from Python
+```
+
+
+
+/// tip | "Dica"
+
+Vocรช pode ler mais sobre isso em
The Twelve-Factor App: Config.
+
+///
+
+## Tipos e Validaรงรฃo
+
+Essas variรกveis de ambiente sรณ podem lidar com **strings de texto**, pois sรฃo externas ao Python e precisam ser compatรญveis com outros programas e com o resto do sistema (e atรฉ mesmo com diferentes sistemas operacionais, como Linux, Windows, macOS).
+
+Isso significa que **qualquer valor** lido em Python de uma variรกvel de ambiente **serรก uma `str`**, e qualquer conversรฃo para um tipo diferente ou qualquer validaรงรฃo precisa ser feita no cรณdigo.
+
+Vocรช aprenderรก mais sobre como usar variรกveis de ambiente para lidar com **configuraรงรตes do aplicativo** no [Guia do Usuรกrio Avanรงado - Configuraรงรตes e Variรกveis de Ambiente](./advanced/settings.md){.internal-link target=_blank}.
+
+## Variรกvel de Ambiente `PATH`
+
+Existe uma variรกvel de ambiente **especial** chamada **`PATH`** que รฉ usada pelos sistemas operacionais (Linux, macOS, Windows) para encontrar programas para executar.
+
+O valor da variรกvel `PATH` รฉ uma longa string composta por diretรณrios separados por dois pontos `:` no Linux e macOS, e por ponto e vรญrgula `;` no Windows.
+
+Por exemplo, a variรกvel de ambiente `PATH` poderia ter esta aparรชncia:
+
+//// tab | Linux, macOS
+
+```plaintext
+/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+Isso significa que o sistema deve procurar programas nos diretรณrios:
+
+* `/usr/local/bin`
+* `/usr/bin`
+* `/bin`
+* `/usr/sbin`
+* `/sbin`
+
+////
+
+//// tab | Windows
+
+```plaintext
+C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32
+```
+
+Isso significa que o sistema deve procurar programas nos diretรณrios:
+
+* `C:\Program Files\Python312\Scripts`
+* `C:\Program Files\Python312`
+* `C:\Windows\System32`
+
+////
+
+Quando vocรช digita um **comando** no terminal, o sistema operacional **procura** o programa em **cada um dos diretรณrios** listados na variรกvel de ambiente `PATH`.
+
+Por exemplo, quando vocรช digita `python` no terminal, o sistema operacional procura um programa chamado `python` no **primeiro diretรณrio** dessa lista.
+
+Se ele o encontrar, entรฃo ele o **usarรก**. Caso contrรกrio, ele continua procurando nos **outros diretรณrios**.
+
+### Instalando o Python e Atualizando o `PATH`
+
+Durante a instalaรงรฃo do Python, vocรช pode ser questionado sobre a atualizaรงรฃo da variรกvel de ambiente `PATH`.
+
+//// tab | Linux, macOS
+
+Vamos supor que vocรช instale o Python e ele fique em um diretรณrio `/opt/custompython/bin`.
+
+Se vocรช concordar em atualizar a variรกvel de ambiente `PATH`, o instalador adicionarรก `/opt/custompython/bin` para a variรกvel de ambiente `PATH`.
+
+Poderia parecer assim:
+
+```plaintext
+/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin
+```
+
+Dessa forma, ao digitar `python` no terminal, o sistema encontrarรก o programa Python em `/opt/custompython/bin` (รบltimo diretรณrio) e o utilizarรก.
+
+////
+
+//// tab | Windows
+
+Digamos que vocรช instala o Python e ele acaba em um diretรณrio `C:\opt\custompython\bin`.
+
+Se vocรช disser sim para atualizar a variรกvel de ambiente `PATH`, o instalador adicionarรก `C:\opt\custompython\bin` ร variรกvel de ambiente `PATH`.
+
+```plaintext
+C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin
+```
+
+Dessa forma, quando vocรช digitar `python` no terminal, o sistema encontrarรก o programa Python em `C:\opt\custompython\bin` (o รบltimo diretรณrio) e o utilizarรก.
+
+////
+
+Entรฃo, se vocรช digitar:
+
+
+
+```console
+$ python
+```
+
+
+
+//// tab | Linux, macOS
+
+O sistema **encontrarรก** o programa `python` em `/opt/custompython/bin` e o executarรก.
+
+Seria aproximadamente equivalente a digitar:
+
+
+
+```console
+$ /opt/custompython/bin/python
+```
+
+
+
+////
+
+//// tab | Windows
+
+O sistema **encontrarรก** o programa `python` em `C:\opt\custompython\bin\python` e o executarรก.
+
+Seria aproximadamente equivalente a digitar:
+
+
+
+```console
+$ C:\opt\custompython\bin\python
+```
+
+
+
+////
+
+Essas informaรงรตes serรฃo รบteis ao aprender sobre [Ambientes Virtuais](virtual-environments.md){.internal-link target=_blank}.
+
+## Conclusรฃo
+
+Com isso, vocรช deve ter uma compreensรฃo bรกsica do que sรฃo **variรกveis โโde ambiente** e como usรก-las em Python.
+
+Vocรช tambรฉm pode ler mais sobre elas na
Wikipedia para Variรกveis โโde Ambiente.
+
+Em muitos casos, nรฃo รฉ muito รณbvio como as variรกveis โโde ambiente seriam รบteis e aplicรกveis โโimediatamente. Mas elas continuam aparecendo em muitos cenรกrios diferentes quando vocรช estรก desenvolvendo, entรฃo รฉ bom saber sobre elas.
+
+Por exemplo, vocรช precisarรก dessas informaรงรตes na prรณxima seรงรฃo, sobre [Ambientes Virtuais](virtual-environments.md).
diff --git a/docs/pt/docs/tutorial/debugging.md b/docs/pt/docs/tutorial/debugging.md
new file mode 100644
index 000000000..54582fcbc
--- /dev/null
+++ b/docs/pt/docs/tutorial/debugging.md
@@ -0,0 +1,115 @@
+# Depuraรงรฃo
+
+Vocรช pode conectar o depurador no seu editor, por exemplo, com o Visual Studio Code ou PyCharm.
+
+## Chamar `uvicorn`
+
+Em seu aplicativo FastAPI, importe e execute `uvicorn` diretamente:
+
+```Python hl_lines="1 15"
+{!../../../docs_src/debugging/tutorial001.py!}
+```
+
+### Sobre `__name__ == "__main__"`
+
+O objetivo principal de `__name__ == "__main__"` รฉ ter algum cรณdigo que seja executado quando seu arquivo for chamado com:
+
+
+
+```console
+$ python myapp.py
+```
+
+
+
+mas nรฃo รฉ chamado quando outro arquivo o importa, como em:
+
+```Python
+from myapp import app
+```
+
+#### Mais detalhes
+
+Digamos que seu arquivo se chama `myapp.py`.
+
+Se vocรช executรก-lo com:
+
+
+
+```console
+$ python myapp.py
+```
+
+
+
+entรฃo a variรกvel interna `__name__` no seu arquivo, criada automaticamente pelo Python, terรก como valor a string `"__main__"`.
+
+Entรฃo, a seรงรฃo:
+
+```Python
+ uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+vai executar.
+
+---
+
+Isso nรฃo acontecerรก se vocรช importar esse mรณdulo (arquivo).
+
+Entรฃo, se vocรช tiver outro arquivo `importer.py` com:
+
+```Python
+from myapp import app
+
+# Mais um pouco de cรณdigo
+```
+
+nesse caso, a variรกvel criada automaticamente dentro de `myapp.py` nรฃo terรก a variรกvel `__name__` com o valor `"__main__"`.
+
+Entรฃo, a linha:
+
+```Python
+ uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+nรฃo serรก executada.
+
+/// info | "Informaรงรฃo"
+
+Para mais informaรงรตes, consulte
a documentaรงรฃo oficial do Python.
+
+///
+
+## Execute seu cรณdigo com seu depurador
+
+Como vocรช estรก executando o servidor Uvicorn diretamente do seu cรณdigo, vocรช pode chamar seu programa Python (seu aplicativo FastAPI) diretamente do depurador.
+
+---
+
+Por exemplo, no Visual Studio Code, vocรช pode:
+
+* Ir para o painel "Debug".
+* "Add configuration...".
+* Selecionar "Python"
+* Executar o depurador com a opรงรฃo "`Python: Current File (Integrated Terminal)`".
+
+Em seguida, ele iniciarรก o servidor com seu cรณdigo **FastAPI**, pararรก em seus pontos de interrupรงรฃo, etc.
+
+Veja como pode parecer:
+
+
+
+---
+
+Se vocรช usar o Pycharm, vocรช pode:
+
+* Abrir o menu "Executar".
+* Selecionar a opรงรฃo "Depurar...".
+* Entรฃo um menu de contexto aparece.
+* Selecionar o arquivo para depurar (neste caso, `main.py`).
+
+Em seguida, ele iniciarรก o servidor com seu cรณdigo **FastAPI**, pararรก em seus pontos de interrupรงรฃo, etc.
+
+Veja como pode parecer:
+
+
diff --git a/docs/pt/docs/tutorial/request-form-models.md b/docs/pt/docs/tutorial/request-form-models.md
new file mode 100644
index 000000000..a9db18e9d
--- /dev/null
+++ b/docs/pt/docs/tutorial/request-form-models.md
@@ -0,0 +1,134 @@
+# Modelos de Formulรกrios
+
+Vocรช pode utilizar **Modelos Pydantic** para declarar **campos de formulรกrios** no FastAPI.
+
+/// info | "Informaรงรฃo"
+
+Para utilizar formulรกrios, instale primeiramente o
`python-multipart`.
+
+Certifique-se de criar um [ambiente virtual](../virtual-environments.md){.internal-link target=_blank}, ativรก-lo, e entรฃo instalar. Por exemplo:
+
+```console
+$ pip install python-multipart
+```
+
+///
+
+/// note | "Nota"
+
+Isto รฉ suportado desde a versรฃo `0.113.0` do FastAPI. ๐ค
+
+///
+
+## Modelos Pydantic para Formulรกrios
+
+Vocรช precisa apenas declarar um **modelo Pydantic** com os campos que deseja receber como **campos de formulรกrios**, e entรฃo declarar o parรขmetro como um `Form`:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="9-11 15"
+{!> ../../../docs_src/request_form_models/tutorial001_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="8-10 14"
+{!> ../../../docs_src/request_form_models/tutorial001_an.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | "Dica"
+
+Prefira utilizar a versรฃo `Annotated` se possรญvel.
+
+///
+
+```Python hl_lines="7-9 13"
+{!> ../../../docs_src/request_form_models/tutorial001.py!}
+```
+
+////
+
+O **FastAPI** irรก **extrair** as informaรงรตes para **cada campo** dos **dados do formulรกrio** na requisiรงรฃo e dar para vocรช o modelo Pydantic que vocรช definiu.
+
+## Confira os Documentos
+
+Vocรช pode verificar na UI de documentaรงรฃo em `/docs`:
+
+
+
+
+
+## Proibir Campos Extras de Formulรกrios
+
+Em alguns casos de uso especiais (provavelmente nรฃo muito comum), vocรช pode desejar **restringir** os campos do formulรกrio para aceitar apenas os declarados no modelo Pydantic. E **proibir** qualquer campo **extra**.
+
+/// note | "Nota"
+
+Isso รฉ suportado deste a versรฃo `0.114.0` do FastAPI. ๐ค
+
+///
+
+Vocรช pode utilizar a configuraรงรฃo de modelo do Pydantic para `proibir` qualquer campo `extra`:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="12"
+{!> ../../../docs_src/request_form_models/tutorial002_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="11"
+{!> ../../../docs_src/request_form_models/tutorial002_an.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip
+
+Prefira utilizar a versรฃo `Annotated` se possรญvel.
+
+///
+
+```Python hl_lines="10"
+{!> ../../../docs_src/request_form_models/tutorial002.py!}
+```
+
+////
+
+Caso um cliente tente enviar informaรงรตes adicionais, ele receberรก um retorno de **erro**.
+
+Por exemplo, se o cliente tentar enviar os campos de formulรกrio:
+
+* `username`: `Rick`
+* `password`: `Portal Gun`
+* `extra`: `Mr. Poopybutthole`
+
+Ele receberรก um retorno de erro informando-o que o campo `extra` nรฃo รฉ permitido:
+
+```json
+{
+ "detail": [
+ {
+ "type": "extra_forbidden",
+ "loc": ["body", "extra"],
+ "msg": "Extra inputs are not permitted",
+ "input": "Mr. Poopybutthole"
+ }
+ ]
+}
+```
+
+## Resumo
+
+Vocรช pode utilizar modelos Pydantic para declarar campos de formulรกrios no FastAPI. ๐
diff --git a/docs/pt/docs/tutorial/request_files.md b/docs/pt/docs/tutorial/request_files.md
new file mode 100644
index 000000000..60e4ecb26
--- /dev/null
+++ b/docs/pt/docs/tutorial/request_files.md
@@ -0,0 +1,418 @@
+# Arquivos de Requisiรงรฃo
+
+Vocรช pode definir arquivos para serem enviados para o cliente utilizando `File`.
+
+/// info
+
+Para receber arquivos compartilhados, primeiro instale
`python-multipart`.
+
+E.g. `pip install python-multipart`.
+
+Isso se deve por que arquivos enviados sรฃo enviados como "dados de formulรกrio".
+
+///
+
+## Importe `File`
+
+Importe `File` e `UploadFile` do `fastapi`:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="3"
+{!> ../../../docs_src/request_files/tutorial001_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1"
+{!> ../../../docs_src/request_files/tutorial001_an.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | Dica
+
+Utilize a versรฃo com `Annotated` se possรญvel.
+
+///
+
+```Python hl_lines="1"
+{!> ../../../docs_src/request_files/tutorial001.py!}
+```
+
+////
+
+## Defina os parรขmetros de `File`
+
+Cria os parรขmetros do arquivo da mesma forma que vocรช faria para `Body` ou `Form`:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="9"
+{!> ../../../docs_src/request_files/tutorial001_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="8"
+{!> ../../../docs_src/request_files/tutorial001_an.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | Dica
+
+Utilize a versรฃo com `Annotated` se possรญvel.
+
+///
+
+```Python hl_lines="7"
+{!> ../../../docs_src/request_files/tutorial001.py!}
+```
+
+////
+
+/// info | Informaรงรฃo
+
+`File` รฉ uma classe que herda diretamente de `Form`.
+
+Mas lembre-se que quando vocรช importa `Query`,`Path`, `File`, entre outros, do `fastapi`, essas sรฃo na verdade funรงรตes que retornam classes especiais.
+
+///
+
+/// tip | Dica
+
+Para declarar o corpo de arquivos, vocรช precisa utilizar `File`, do contrรกrio os parรขmetros seriam interpretados como parรขmetros de consulta ou corpo (JSON) da requisiรงรฃo.
+
+///
+
+Os arquivos serรฃo enviados como "form data".
+
+Se vocรช declarar o tipo do seu parรขmetro na sua *funรงรฃo de operaรงรฃo de rota* como `bytes`, o **FastAPI** irรก ler o arquivo para vocรช e vocรช receberรก o conteรบdo como `bytes`.
+
+Lembre-se que isso significa que o conteรบdo inteiro serรก armazenado em memรณria. Isso funciona bem para arquivos pequenos.
+
+Mas existem vรกrios casos em que vocรช pode se beneficiar ao usar `UploadFile`.
+
+## Parรขmetros de arquivo com `UploadFile`
+
+Defina um parรขmetro de arquivo com o tipo `UploadFile`
+
+//// tab | Python 3.9+
+
+```Python hl_lines="14"
+{!> ../../../docs_src/request_files/tutorial001_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="13"
+{!> ../../../docs_src/request_files/tutorial001_an.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | Dica
+
+Utilize a versรฃo com `Annotated` se possรญvel.
+
+///
+
+```Python hl_lines="12"
+{!> ../../../docs_src/request_files/tutorial001.py!}
+```
+
+////
+
+Utilizando `UploadFile` tem vรกrias vantagens sobre `bytes`:
+
+* Vocรช nรฃo precisa utilizar `File()` como o valor padrรฃo do parรขmetro.
+* A classe utiliza um arquivo em "spool":
+ * Um arquivo guardado em memรณria atรฉ um tamanho mรกximo, depois desse limite ele รฉ guardado em disco.
+* Isso significa que a classe funciona bem com arquivos grandes como imagens, vรญdeos, binรกrios extensos, etc. Sem consumir toda a memรณria.
+* Vocรช pode obter metadados do arquivo enviado.
+* Ela possui uma interface
semelhante a arquivos `async`.
+* Ela expรตe um objeto python
`SpooledTemporaryFile` que vocรช pode repassar para bibliotecas que esperam um objeto com comportamento de arquivo.
+
+### `UploadFile`
+
+`UploadFile` tem os seguintes atributos:
+
+* `filename`: Uma string (`str`) com o nome original do arquivo enviado (e.g. `myimage.jpg`).
+* `content-type`: Uma `str` com o tipo do conteรบdo (tipo MIME / media) (e.g. `image/jpeg`).
+* `file`: Um objeto do tipo
`SpooledTemporaryFile` (um objeto
file-like). O arquivo propriamente dito que vocรช pode passar diretamente para outras funรงรตes ou bibliotecas que esperam um objeto "file-like".
+
+`UploadFile` tem os seguintes mรฉtodos `async`. Todos eles chamam os mรฉtodos de arquivos por baixo dos panos (usando o objeto `SpooledTemporaryFile` interno).
+
+* `write(data)`: escreve dados (`data`) em `str` ou `bytes` no arquivo.
+* `read(size)`: Lรช um nรบmero de bytes/caracteres de acordo com a quantidade `size` (`int`).
+* `seek(offset)`: Navega para o byte na posiรงรฃo `offset` (`int`) do arquivo.
+ * E.g., `await myfile.seek(0)` navegaria para o รญnicio do arquivo.
+ * Isso รฉ especialmente รบtil se vocรช executar `await myfile.read()` uma vez e depois precisar ler os conteรบdos do arquivo de novo.
+* `close()`: Fecha o arquivo.
+
+Como todos esses mรฉtodos sรฃo assรญncronos (`async`) vocรช precisa esperar ("await") por eles.
+
+Por exemplo, dentro de uma *funรงรฃo de operaรงรฃo de rota* assรญncrona vocรช pode obter os conteรบdos com:
+
+```Python
+contents = await myfile.read()
+```
+
+Se vocรช estiver dentro de uma *funรงรฃo de operaรงรฃo de rota* definida normalmente com `def`, vocรช pode acessar `UploadFile.file` diretamente, por exemplo:
+
+```Python
+contents = myfile.file.read()
+```
+
+/// note | Detalhes tรฉcnicos do `async`
+
+Quando vocรช utiliza mรฉtodos assรญncronos, o **FastAPI** executa os mรฉtodos do arquivo em uma threadpool e espera por eles.
+
+///
+
+/// note | Detalhes tรฉcnicos do Starlette
+
+O `UploadFile` do **FastAPI** herda diretamente do `UploadFile` do **Starlette**, mas adiciona algumas funcionalidades necessรกrias para ser compatรญvel com o **Pydantic**
+
+///
+
+## O que รฉ "Form Data"
+
+A forma como formulรกrios HTML(`
`) enviam dados para o servidor normalmente utilizam uma codificaรงรฃo "especial" para esses dados, que รฉ diferente do JSON.
+
+O **FastAPI** garante que os dados serรฃo lidos da forma correta, em vez do JSON.
+
+/// note | Detalhes Tรฉcnicos
+
+Dados vindos de formulรกrios geralmente tem a codificaรงรฃo com o "media type" `application/x-www-form-urlencoded` quando estes nรฃo incluem arquivos.
+
+Mas quando os dados incluem arquivos, eles sรฃo codificados como `multipart/form-data`. Se vocรช utilizar `File`, **FastAPI** saberรก que deve receber os arquivos da parte correta do corpo da requisiรงรฃo.
+
+Se vocรช quer ler mais sobre essas codificaรงรตes e campos de formulรกrio, veja a documentaรงรฃo online da
MDN sobre POST .
+
+///
+
+/// warning | Aviso
+
+Vocรช pode declarar mรบltiplos parรขmetros `File` e `Form` em uma *operaรงรฃo de rota*, mas vocรช nรฃo pode declarar campos `Body`que seriam recebidos como JSON junto desses parรขmetros, por que a codificaรงรฃo do corpo da requisiรงรฃo serรก `multipart/form-data` em vez de `application/json`.
+
+Isso nรฃo รฉ uma limitaรงรฃo do **FastAPI**, รฉ uma parte do protocolo HTTP.
+
+///
+
+## Arquivo de upload opcional
+
+Vocรช pode definir um arquivo como opcional utilizando as anotaรงรตes de tipo padrรฃo e definindo o valor padrรฃo como `None`:
+
+//// tab | Python 3.10+
+
+```Python hl_lines="9 17"
+{!> ../../../docs_src/request_files/tutorial001_02_an_py310.py!}
+```
+
+////
+
+//// tab | Python 3.9+
+
+```Python hl_lines="9 17"
+{!> ../../../docs_src/request_files/tutorial001_02_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="10 18"
+{!> ../../../docs_src/request_files/tutorial001_02_an.py!}
+```
+
+////
+
+//// tab | Python 3.10+ non-Annotated
+
+/// tip | Dica
+
+Utilize a versรฃo com `Annotated`, se possรญvel
+
+///
+
+```Python hl_lines="7 15"
+{!> ../../../docs_src/request_files/tutorial001_02_py310.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | Dica
+
+Utilize a versรฃo com `Annotated`, se possรญvel
+
+///
+
+```Python hl_lines="9 17"
+{!> ../../../docs_src/request_files/tutorial001_02.py!}
+```
+
+////
+
+## `UploadFile` com Metadados Adicionais
+
+Vocรช tambรฉm pode utilizar `File()` com `UploadFile`, por exemplo, para definir metadados adicionais:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="9 15"
+{!> ../../../docs_src/request_files/tutorial001_03_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="8 14"
+{!> ../../../docs_src/request_files/tutorial001_03_an.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | Dica
+
+Utilize a versรฃo com `Annotated` se possรญvel
+
+///
+
+```Python hl_lines="7 13"
+{!> ../../../docs_src/request_files/tutorial001_03.py!}
+```
+
+////
+
+## Envio de Mรบltiplos Arquivos
+
+ร possรญvel enviar mรบltiplos arquivos ao mesmo tmepo.
+
+Ele ficam associados ao mesmo "campo do formulรกrio" enviado com "form data".
+
+Para usar isso, declare uma lista de `bytes` ou `UploadFile`:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="10 15"
+{!> ../../../docs_src/request_files/tutorial002_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="11 16"
+{!> ../../../docs_src/request_files/tutorial002_an.py!}
+```
+
+////
+
+//// tab | Python 3.9+ non-Annotated
+
+/// tip | Dica
+
+Utilize a versรฃo com `Annotated` se possรญvel
+
+///
+
+```Python hl_lines="8 13"
+{!> ../../../docs_src/request_files/tutorial002_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | Dica
+
+Utilize a versรฃo com `Annotated` se possรญvel
+
+///
+
+```Python hl_lines="10 15"
+{!> ../../../docs_src/request_files/tutorial002.py!}
+```
+
+////
+
+Vocรช irรก receber, como delcarado uma lista (`list`) de `bytes` ou `UploadFile`s,
+
+/// note | Detalhes Tรฉcnicos
+
+Vocรช tambรฉm poderia utilizar `from starlette.responses import HTMLResponse`.
+
+O **FastAPI** fornece as mesmas `starlette.responses` como `fastapi.responses` apenas como um facilitador para vocรช, desenvolvedor. Mas a maior parte das respostas vem diretamente do Starlette.
+
+///
+
+### Enviando Mรบltiplos Arquivos com Metadados Adicionais
+
+E da mesma forma que antes, vocรช pode utilizar `File()` para definir parรขmetros adicionais, atรฉ mesmo para `UploadFile`:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="11 18-20"
+{!> ../../../docs_src/request_files/tutorial003_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="12 19-21"
+{!> ../../../docs_src/request_files/tutorial003_an.py!}
+```
+
+////
+
+//// tab | Python 3.9+ non-Annotated
+
+/// tip | Dica
+
+Utilize a versรฃo com `Annotated` se possรญvel.
+
+///
+
+```Python hl_lines="9 16"
+{!> ../../../docs_src/request_files/tutorial003_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | Dica
+
+Utilize a versรฃo com `Annotated` se possรญvel.
+
+///
+
+```Python hl_lines="11 18"
+{!> ../../../docs_src/request_files/tutorial003.py!}
+```
+
+////
+
+## Recapitulando
+
+Use `File`, `bytes` e `UploadFile` para declarar arquivos que serรฃo enviados na requisiรงรฃo, enviados como dados do formulรกrio.
diff --git a/docs/pt/docs/tutorial/testing.md b/docs/pt/docs/tutorial/testing.md
new file mode 100644
index 000000000..f734a7d9a
--- /dev/null
+++ b/docs/pt/docs/tutorial/testing.md
@@ -0,0 +1,249 @@
+# Testando
+
+Graรงas ao
Starlette, testar aplicativos **FastAPI** รฉ fรกcil e agradรกvel.
+
+Ele รฉ baseado no
HTTPX, que por sua vez รฉ projetado com base em Requests, por isso รฉ muito familiar e intuitivo.
+
+Com ele, vocรช pode usar o
pytest diretamente com **FastAPI**.
+
+## Usando `TestClient`
+
+/// info | "Informaรงรฃo"
+
+Para usar o `TestClient`, primeiro instale o
`httpx`.
+
+Certifique-se de criar um [ambiente virtual](../virtual-environments.md){.internal-link target=_blank}, ativรก-lo e instalรก-lo, por exemplo:
+
+```console
+$ pip install httpx
+```
+
+///
+
+Importe `TestClient`.
+
+Crie um `TestClient` passando seu aplicativo **FastAPI** para ele.
+
+Crie funรงรตes com um nome que comece com `test_` (essa รฉ a convenรงรฃo padrรฃo do `pytest`).
+
+Use o objeto `TestClient` da mesma forma que vocรช faz com `httpx`.
+
+Escreva instruรงรตes `assert` simples com as expressรตes Python padrรฃo que vocรช precisa verificar (novamente, `pytest` padrรฃo).
+
+```Python hl_lines="2 12 15-18"
+{!../../../docs_src/app_testing/tutorial001.py!}
+```
+
+/// tip | "Dica"
+
+Observe que as funรงรตes de teste sรฃo `def` normais, nรฃo `async def`.
+
+E as chamadas para o cliente tambรฉm sรฃo chamadas normais, nรฃo usando `await`.
+
+Isso permite que vocรช use `pytest` diretamente sem complicaรงรตes.
+
+///
+
+/// note | "Detalhes tรฉcnicos"
+
+Vocรช tambรฉm pode usar `from starlette.testclient import TestClient`.
+
+**FastAPI** fornece o mesmo `starlette.testclient` que `fastapi.testclient` apenas como uma conveniรชncia para vocรช, o desenvolvedor. Mas ele vem diretamente da Starlette.
+
+///
+
+/// tip | "Dica"
+
+Se vocรช quiser chamar funรงรตes `async` em seus testes alรฉm de enviar solicitaรงรตes ao seu aplicativo FastAPI (por exemplo, funรงรตes de banco de dados assรญncronas), dรช uma olhada em [Testes assรญncronos](../advanced/async-tests.md){.internal-link target=_blank} no tutorial avanรงado.
+
+///
+
+## Separando testes
+
+Em uma aplicaรงรฃo real, vocรช provavelmente teria seus testes em um arquivo diferente.
+
+E seu aplicativo **FastAPI** tambรฉm pode ser composto de vรกrios arquivos/mรณdulos, etc.
+
+### Arquivo do aplicativo **FastAPI**
+
+Digamos que vocรช tenha uma estrutura de arquivo conforme descrito em [Aplicativos maiores](bigger-applications.md){.internal-link target=_blank}:
+
+```
+.
+โโโ app
+โย ย โโโ __init__.py
+โย ย โโโ main.py
+```
+
+No arquivo `main.py` vocรช tem seu aplicativo **FastAPI**:
+
+
+```Python
+{!../../../docs_src/app_testing/main.py!}
+```
+
+### Arquivo de teste
+
+Entรฃo vocรช poderia ter um arquivo `test_main.py` com seus testes. Ele poderia estar no mesmo pacote Python (o mesmo diretรณrio com um arquivo `__init__.py`):
+
+``` hl_lines="5"
+.
+โโโ app
+โย ย โโโ __init__.py
+โย ย โโโ main.py
+โย ย โโโ test_main.py
+```
+
+Como esse arquivo estรก no mesmo pacote, vocรช pode usar importaรงรตes relativas para importar o objeto `app` do mรณdulo `main` (`main.py`):
+
+```Python hl_lines="3"
+{!../../../docs_src/app_testing/test_main.py!}
+```
+
+...e ter o cรณdigo para os testes como antes.
+
+## Testando: exemplo estendido
+
+Agora vamos estender este exemplo e adicionar mais detalhes para ver como testar diferentes partes.
+
+### Arquivo de aplicativo **FastAPI** estendido
+
+Vamos continuar com a mesma estrutura de arquivo de antes:
+
+```
+.
+โโโ app
+โย ย โโโ __init__.py
+โย ย โโโ main.py
+โย ย โโโ test_main.py
+```
+
+Digamos que agora o arquivo `main.py` com seu aplicativo **FastAPI** tenha algumas outras **operaรงรตes de rotas**.
+
+Ele tem uma operaรงรฃo `GET` que pode retornar um erro.
+
+Ele tem uma operaรงรฃo `POST` que pode retornar vรกrios erros.
+
+Ambas as *operaรงรตes de rotas* requerem um cabeรงalho `X-Token`.
+
+//// tab | Python 3.10+
+
+```Python
+{!> ../../../docs_src/app_testing/app_b_an_py310/main.py!}
+```
+
+////
+
+//// tab | Python 3.9+
+
+```Python
+{!> ../../../docs_src/app_testing/app_b_an_py39/main.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python
+{!> ../../../docs_src/app_testing/app_b_an/main.py!}
+```
+
+////
+
+//// tab | Python 3.10+ non-Annotated
+
+/// tip | "Dica"
+
+Prefira usar a versรฃo `Annotated` se possรญvel.
+
+///
+
+```Python
+{!> ../../../docs_src/app_testing/app_b_py310/main.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | "Dica"
+
+Prefira usar a versรฃo `Annotated` se possรญvel.
+
+///
+
+```Python
+{!> ../../../docs_src/app_testing/app_b/main.py!}
+```
+
+////
+
+### Arquivo de teste estendido
+
+Vocรช pode entรฃo atualizar `test_main.py` com os testes estendidos:
+
+```Python
+{!> ../../../docs_src/app_testing/app_b/test_main.py!}
+```
+
+Sempre que vocรช precisar que o cliente passe informaรงรตes na requisiรงรฃo e nรฃo souber como, vocรช pode pesquisar (no Google) como fazer isso no `httpx`, ou atรฉ mesmo como fazer isso com `requests`, jรก que o design do HTTPX รฉ baseado no design do Requests.
+
+Depois รฉ sรณ fazer o mesmo nos seus testes.
+
+Por exemplo:
+
+* Para passar um parรขmetro *path* ou *query*, adicione-o ร prรณpria URL.
+* Para passar um corpo JSON, passe um objeto Python (por exemplo, um `dict`) para o parรขmetro `json`.
+* Se vocรช precisar enviar *Dados de Formulรกrio* em vez de JSON, use o parรขmetro `data`.
+* Para passar *headers*, use um `dict` no parรขmetro `headers`.
+* Para *cookies*, um `dict` no parรขmetro `cookies`.
+
+Para mais informaรงรตes sobre como passar dados para o backend (usando `httpx` ou `TestClient`), consulte a
documentaรงรฃo do HTTPX.
+
+/// info | "Informaรงรฃo"
+
+Observe que o `TestClient` recebe dados que podem ser convertidos para JSON, nรฃo para modelos Pydantic.
+
+Se vocรช tiver um modelo Pydantic em seu teste e quiser enviar seus dados para o aplicativo durante o teste, poderรก usar o `jsonable_encoder` descrito em [Codificador compatรญvel com JSON](encoder.md){.internal-link target=_blank}.
+
+///
+
+## Execute-o
+
+Depois disso, vocรช sรณ precisa instalar o `pytest`.
+
+Certifique-se de criar um [ambiente virtual](../virtual-environments.md){.internal-link target=_blank}, ativรก-lo e instalรก-lo, por exemplo:
+
+
+
+```console
+$ pip install pytest
+
+---> 100%
+```
+
+
+
+Ele detectarรก os arquivos e os testes automaticamente, os executarรก e informarรก os resultados para vocรช.
+
+Execute os testes com:
+
+
+
+```console
+$ pytest
+
+================ test session starts ================
+platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1
+rootdir: /home/user/code/superawesome-cli/app
+plugins: forked-1.1.3, xdist-1.31.0, cov-2.8.1
+collected 6 items
+
+---> 100%
+
+test_main.py ...... [100%]
+
+================= 1 passed in 0.03s =================
+```
+
+
diff --git a/docs/pt/docs/virtual-environments.md b/docs/pt/docs/virtual-environments.md
new file mode 100644
index 000000000..863c8d65e
--- /dev/null
+++ b/docs/pt/docs/virtual-environments.md
@@ -0,0 +1,844 @@
+# Ambientes Virtuais
+
+Ao trabalhar em projetos Python, vocรช provavelmente deve usar um **ambiente virtual** (ou um mecanismo similar) para isolar os pacotes que vocรช instala para cada projeto.
+
+/// info | "Informaรงรฃo"
+
+Se vocรช jรก sabe sobre ambientes virtuais, como criรก-los e usรก-los, talvez seja melhor pular esta seรงรฃo. ๐ค
+
+///
+
+/// tip | "Dica"
+
+Um **ambiente virtual** รฉ diferente de uma **variรกvel de ambiente**.
+
+Uma **variรกvel de ambiente** รฉ uma variรกvel no sistema que pode ser usada por programas.
+
+Um **ambiente virtual** รฉ um diretรณrio com alguns arquivos.
+
+///
+
+/// info | "Informaรงรฃo"
+
+Esta pรกgina lhe ensinarรก como usar **ambientes virtuais** e como eles funcionam.
+
+Se vocรช estiver pronto para adotar uma **ferramenta que gerencia tudo** para vocรช (incluindo a instalaรงรฃo do Python), experimente
uv.
+
+///
+
+## Criar um Projeto
+
+Primeiro, crie um diretรณrio para seu projeto.
+
+O que normalmente faรงo รฉ criar um diretรณrio chamado `code` dentro do meu diretรณrio home/user.
+
+E dentro disso eu crio um diretรณrio por projeto.
+
+
+
+```console
+// Vรก para o diretรณrio inicial
+$ cd
+// Crie um diretรณrio para todos os seus projetos de cรณdigo
+$ mkdir code
+// Entre nesse diretรณrio de cรณdigo
+$ cd code
+// Crie um diretรณrio para este projeto
+$ mkdir awesome-project
+// Entre no diretรณrio do projeto
+$ cd awesome-project
+```
+
+
+
+## Crie um ambiente virtual
+
+Ao comeรงar a trabalhar em um projeto Python **pela primeira vez**, crie um ambiente virtual **
dentro do seu projeto**.
+
+/// tip | "Dica"
+
+Vocรช sรณ precisa fazer isso **uma vez por projeto**, nรฃo toda vez que trabalhar.
+
+///
+
+//// tab | `venv`
+
+Para criar um ambiente virtual, vocรช pode usar o mรณdulo `venv` que vem com o Python.
+
+
+
+```console
+$ python -m venv .venv
+```
+
+
+
+/// details | O que esse comando significa
+
+* `python`: usa o programa chamado `python`
+* `-m`: chama um mรณdulo como um script, nรณs diremos a ele qual mรณdulo vem em seguida
+* `venv`: usa o mรณdulo chamado `venv` que normalmente vem instalado com o Python
+* `.venv`: cria o ambiente virtual no novo diretรณrio `.venv`
+
+///
+
+////
+
+//// tab | `uv`
+
+Se vocรช tiver o
`uv` instalado, poderรก usรก-lo para criar um ambiente virtual.
+
+
+
+```console
+$ uv venv
+```
+
+
+
+/// tip | "Dica"
+
+Por padrรฃo, `uv` criarรก um ambiente virtual em um diretรณrio chamado `.venv`.
+
+Mas vocรช pode personalizรก-lo passando um argumento adicional com o nome do diretรณrio.
+
+///
+
+////
+
+Esse comando cria um novo ambiente virtual em um diretรณrio chamado `.venv`.
+
+/// details | `.venv` ou outro nome
+
+Vocรช pode criar o ambiente virtual em um diretรณrio diferente, mas hรก uma convenรงรฃo para chamรก-lo de `.venv`.
+
+///
+
+## Ative o ambiente virtual
+
+Ative o novo ambiente virtual para que qualquer comando Python que vocรช executar ou pacote que vocรช instalar o utilize.
+
+/// tip | "Dica"
+
+Faรงa isso **toda vez** que iniciar uma **nova sessรฃo de terminal** para trabalhar no projeto.
+
+///
+
+//// tab | Linux, macOS
+
+
+
+```console
+$ source .venv/bin/activate
+```
+
+
+
+////
+
+//// tab | Windows PowerShell
+
+
+
+```console
+$ .venv\Scripts\Activate.ps1
+```
+
+
+
+////
+
+//// tab | Windows Bash
+
+Ou se vocรช usa o Bash para Windows (por exemplo,
Git Bash):
+
+
+
+```console
+$ source .venv/Scripts/activate
+```
+
+
+
+////
+
+/// tip | "Dica"
+
+Toda vez que vocรช instalar um **novo pacote** naquele ambiente, **ative** o ambiente novamente.
+
+Isso garante que, se vocรช usar um **programa de terminal (
CLI)** instalado por esse pacote, vocรช usarรก aquele do seu ambiente virtual e nรฃo qualquer outro que possa ser instalado globalmente, provavelmente com uma versรฃo diferente do que vocรช precisa.
+
+///
+
+## Verifique se o ambiente virtual estรก ativo
+
+Verifique se o ambiente virtual estรก ativo (o comando anterior funcionou).
+
+/// tip | "Dica"
+
+Isso รฉ **opcional**, mas รฉ uma boa maneira de **verificar** se tudo estรก funcionando conforme o esperado e se vocรช estรก usando o ambiente virtual pretendido.
+
+///
+
+//// tab | Linux, macOS, Windows Bash
+
+
+
+```console
+$ which python
+
+/home/user/code/awesome-project/.venv/bin/python
+```
+
+
+
+Se ele mostrar o binรกrio `python` em `.venv/bin/python`, dentro do seu projeto (neste caso `awesome-project`), entรฃo funcionou. ๐
+
+////
+
+//// tab | Windows PowerShell
+
+
+
+```console
+$ Get-Command python
+
+C:\Users\user\code\awesome-project\.venv\Scripts\python
+```
+
+
+
+Se ele mostrar o binรกrio `python` em `.venv\Scripts\python`, dentro do seu projeto (neste caso `awesome-project`), entรฃo funcionou. ๐
+
+////
+
+## Atualizar `pip`
+
+/// tip | "Dica"
+
+Se vocรช usar
`uv`, vocรช o usarรก para instalar coisas em vez do `pip`, entรฃo nรฃo precisarรก atualizar o `pip`. ๐
+
+///
+
+Se vocรช estiver usando `pip` para instalar pacotes (ele vem por padrรฃo com o Python), vocรช deve **atualizรก-lo** para a versรฃo mais recente.
+
+Muitos erros exรณticos durante a instalaรงรฃo de um pacote sรฃo resolvidos apenas atualizando o `pip` primeiro.
+
+/// tip | "Dica"
+
+Normalmente, vocรช faria isso **uma vez**, logo apรณs criar o ambiente virtual.
+
+///
+
+Certifique-se de que o ambiente virtual esteja ativo (com o comando acima) e execute:
+
+
+
+```console
+$ python -m pip install --upgrade pip
+
+---> 100%
+```
+
+
+
+## Adicionar `.gitignore`
+
+Se vocรช estiver usando **Git** (vocรช deveria), adicione um arquivo `.gitignore` para excluir tudo em seu `.venv` do Git.
+
+/// tip | "Dica"
+
+Se vocรช usou
`uv` para criar o ambiente virtual, ele jรก fez isso para vocรช, vocรช pode pular esta etapa. ๐
+
+///
+
+/// tip | "Dica"
+
+Faรงa isso **uma vez**, logo apรณs criar o ambiente virtual.
+
+///
+
+
+
+```console
+$ echo "*" > .venv/.gitignore
+```
+
+
+
+/// details | O que esse comando significa
+
+* `echo "*"`: irรก "imprimir" o texto `*` no terminal (a prรณxima parte muda isso um pouco)
+* `>`: qualquer coisa impressa no terminal pelo comando ร esquerda de `>` nรฃo deve ser impressa, mas sim escrita no arquivo que vai ร direita de `>`
+* `.gitignore`: o nome do arquivo onde o texto deve ser escrito
+
+E `*` para Git significa "tudo". Entรฃo, ele ignorarรก tudo no diretรณrio `.venv`.
+
+Esse comando criarรก um arquivo `.gitignore` com o conteรบdo:
+
+```gitignore
+*
+```
+
+///
+
+## Instalar Pacotes
+
+Apรณs ativar o ambiente, vocรช pode instalar pacotes nele.
+
+/// tip | "Dica"
+
+Faรงa isso **uma vez** ao instalar ou atualizar os pacotes que seu projeto precisa.
+
+Se precisar atualizar uma versรฃo ou adicionar um novo pacote, vocรช **farรก isso novamente**.
+
+///
+
+### Instalar pacotes diretamente
+
+Se estiver com pressa e nรฃo quiser usar um arquivo para declarar os requisitos de pacote do seu projeto, vocรช pode instalรก-los diretamente.
+
+/// tip | "Dica"
+
+ร uma (muito) boa ideia colocar os pacotes e versรตes que seu programa precisa em um arquivo (por exemplo `requirements.txt` ou `pyproject.toml`).
+
+///
+
+//// tab | `pip`
+
+
+
+```console
+$ pip install "fastapi[standard]"
+
+---> 100%
+```
+
+
+
+////
+
+//// tab | `uv`
+
+Se vocรช tem o
`uv`:
+
+
+
+```console
+$ uv pip install "fastapi[standard]"
+---> 100%
+```
+
+
+
+////
+
+### Instalar a partir de `requirements.txt`
+
+Se vocรช tiver um `requirements.txt`, agora poderรก usรก-lo para instalar seus pacotes.
+
+//// tab | `pip`
+
+
+
+```console
+$ pip install -r requirements.txt
+---> 100%
+```
+
+
+
+////
+
+//// tab | `uv`
+
+Se vocรช tem o
`uv`:
+
+
+
+```console
+$ uv pip install -r requirements.txt
+---> 100%
+```
+
+
+
+////
+
+/// details | `requirements.txt`
+
+Um `requirements.txt` com alguns pacotes poderia se parecer com:
+
+```requirements.txt
+fastapi[standard]==0.113.0
+pydantic==2.8.0
+```
+
+///
+
+## Execute seu programa
+
+Depois de ativar o ambiente virtual, vocรช pode executar seu programa, e ele usarรก o Python dentro do seu ambiente virtual com os pacotes que vocรช instalou lรก.
+
+
+
+```console
+$ python main.py
+
+Hello World
+```
+
+
+
+## Configure seu editor
+
+Vocรช provavelmente usaria um editor. Certifique-se de configurรก-lo para usar o mesmo ambiente virtual que vocรช criou (ele provavelmente o detectarรก automaticamente) para que vocรช possa obter erros de preenchimento automรกtico e em linha.
+
+Por exemplo:
+
+*
VS Code
+*
PyCharm
+
+/// tip | "Dica"
+
+Normalmente, vocรช sรณ precisa fazer isso **uma vez**, ao criar o ambiente virtual.
+
+///
+
+## Desativar o ambiente virtual
+
+Quando terminar de trabalhar no seu projeto, vocรช pode **desativar** o ambiente virtual.
+
+
+
+```console
+$ deactivate
+```
+
+
+
+Dessa forma, quando vocรช executar `python`, ele nรฃo tentarรก executรก-lo naquele ambiente virtual com os pacotes instalados nele.
+
+## Pronto para trabalhar
+
+Agora vocรช estรก pronto para comeรงar a trabalhar no seu projeto.
+
+
+
+/// tip | "Dica"
+
+Vocรช quer entender o que รฉ tudo isso acima?
+
+Continue lendo. ๐๐ค
+
+///
+
+## Por que ambientes virtuais
+
+Para trabalhar com o FastAPI, vocรช precisa instalar o
Python.
+
+Depois disso, vocรช precisarรก **instalar** o FastAPI e quaisquer outros **pacotes** que queira usar.
+
+Para instalar pacotes, vocรช normalmente usaria o comando `pip` que vem com o Python (ou alternativas semelhantes).
+
+No entanto, se vocรช usar `pip` diretamente, os pacotes serรฃo instalados no seu **ambiente Python global** (a instalaรงรฃo global do Python).
+
+### O Problema
+
+Entรฃo, qual รฉ o problema em instalar pacotes no ambiente global do Python?
+
+Em algum momento, vocรช provavelmente acabarรก escrevendo muitos programas diferentes que dependem de **pacotes diferentes**. E alguns desses projetos em que vocรช trabalha dependerรฃo de **versรตes diferentes** do mesmo pacote. ๐ฑ
+
+Por exemplo, vocรช pode criar um projeto chamado `philosophers-stone`, este programa depende de outro pacote chamado **`harry`, usando a versรฃo `1`**. Entรฃo, vocรช precisa instalar `harry`.
+
+```mermaid
+flowchart LR
+ stone(philosophers-stone) -->|requires| harry-1[harry v1]
+```
+
+Entรฃo, em algum momento depois, vocรช cria outro projeto chamado `prisoner-of-azkaban`, e esse projeto tambรฉm depende de `harry`, mas esse projeto precisa do **`harry` versรฃo `3`**.
+
+```mermaid
+flowchart LR
+ azkaban(prisoner-of-azkaban) --> |requires| harry-3[harry v3]
+```
+
+Mas agora o problema รฉ que, se vocรช instalar os pacotes globalmente (no ambiente global) em vez de em um **ambiente virtual** local, vocรช terรก que escolher qual versรฃo do `harry` instalar.
+
+Se vocรช quiser executar `philosophers-stone`, precisarรก primeiro instalar `harry` versรฃo `1`, por exemplo com:
+
+
+
+```console
+$ pip install "harry==1"
+```
+
+
+
+E entรฃo vocรช acabaria com `harry` versรฃo `1` instalado em seu ambiente Python global.
+
+```mermaid
+flowchart LR
+ subgraph global[global env]
+ harry-1[harry v1]
+ end
+ subgraph stone-project[philosophers-stone project]
+ stone(philosophers-stone) -->|requires| harry-1
+ end
+```
+
+Mas se vocรช quiser executar `prisoner-of-azkaban`, vocรช precisarรก desinstalar `harry` versรฃo `1` e instalar `harry` versรฃo `3` (ou apenas instalar a versรฃo `3` desinstalaria automaticamente a versรฃo `1`).
+
+
+
+```console
+$ pip install "harry==3"
+```
+
+
+
+E entรฃo vocรช acabaria com `harry` versรฃo `3` instalado em seu ambiente Python global.
+
+E se vocรช tentar executar `philosophers-stone` novamente, hรก uma chance de que **nรฃo funcione** porque ele precisa de `harry` versรฃo `1`.
+
+```mermaid
+flowchart LR
+ subgraph global[global env]
+ harry-1[
harry v1]
+ style harry-1 fill:#ccc,stroke-dasharray: 5 5
+ harry-3[harry v3]
+ end
+ subgraph stone-project[philosophers-stone project]
+ stone(philosophers-stone) -.-x|โ๏ธ| harry-1
+ end
+ subgraph azkaban-project[prisoner-of-azkaban project]
+ azkaban(prisoner-of-azkaban) --> |requires| harry-3
+ end
+```
+
+/// tip | "Dica"
+
+ร muito comum em pacotes Python tentar ao mรกximo **evitar alteraรงรตes drรกsticas** em **novas versรตes**, mas รฉ melhor prevenir do que remediar e instalar versรตes mais recentes intencionalmente e, quando possรญvel, executar os testes para verificar se tudo estรก funcionando corretamente.
+
+///
+
+Agora, imagine isso com **muitos** outros **pacotes** dos quais todos os seus **projetos dependem**. Isso รฉ muito difรญcil de gerenciar. E vocรช provavelmente acabaria executando alguns projetos com algumas **versรตes incompatรญveis** dos pacotes, e nรฃo saberia por que algo nรฃo estรก funcionando.
+
+Alรฉm disso, dependendo do seu sistema operacional (por exemplo, Linux, Windows, macOS), ele pode ter vindo com o Python jรก instalado. E, nesse caso, provavelmente tinha alguns pacotes prรฉ-instalados com algumas versรตes especรญficas **necessรกrias para o seu sistema**. Se vocรช instalar pacotes no ambiente global do Python, poderรก acabar **quebrando** alguns dos programas que vieram com seu sistema operacional.
+
+## Onde os pacotes sรฃo instalados
+
+Quando vocรช instala o Python, ele cria alguns diretรณrios com alguns arquivos no seu computador.
+
+Alguns desses diretรณrios sรฃo os responsรกveis โโpor ter todos os pacotes que vocรช instala.
+
+Quando vocรช executa:
+
+
+
+```console
+// Nรฃo execute isso agora, รฉ apenas um exemplo ๐ค
+$ pip install "fastapi[standard]"
+---> 100%
+```
+
+
+
+Isso farรก o download de um arquivo compactado com o cรณdigo FastAPI, normalmente do
PyPI.
+
+Ele tambรฉm farรก o **download** de arquivos para outros pacotes dos quais o FastAPI depende.
+
+Em seguida, ele **extrairรก** todos esses arquivos e os colocarรก em um diretรณrio no seu computador.
+
+Por padrรฃo, ele colocarรก os arquivos baixados e extraรญdos no diretรณrio que vem com a instalaรงรฃo do Python, que รฉ o **ambiente global**.
+
+## O que sรฃo ambientes virtuais
+
+A soluรงรฃo para os problemas de ter todos os pacotes no ambiente global รฉ usar um **ambiente virtual para cada projeto** em que vocรช trabalha.
+
+Um ambiente virtual รฉ um **diretรณrio**, muito semelhante ao global, onde vocรช pode instalar os pacotes para um projeto.
+
+Dessa forma, cada projeto terรก seu prรณprio ambiente virtual (diretรณrio `.venv`) com seus prรณprios pacotes.
+
+```mermaid
+flowchart TB
+ subgraph stone-project[philosophers-stone project]
+ stone(philosophers-stone) --->|requires| harry-1
+ subgraph venv1[.venv]
+ harry-1[harry v1]
+ end
+ end
+ subgraph azkaban-project[prisoner-of-azkaban project]
+ azkaban(prisoner-of-azkaban) --->|requires| harry-3
+ subgraph venv2[.venv]
+ harry-3[harry v3]
+ end
+ end
+ stone-project ~~~ azkaban-project
+```
+
+## O que significa ativar um ambiente virtual
+
+Quando vocรช ativa um ambiente virtual, por exemplo com:
+
+//// tab | Linux, macOS
+
+
+
+```console
+$ source .venv/bin/activate
+```
+
+
+
+////
+
+//// tab | Windows PowerShell
+
+
+
+```console
+$ .venv\Scripts\Activate.ps1
+```
+
+
+
+////
+
+//// tab | Windows Bash
+
+Ou se vocรช usa o Bash para Windows (por exemplo,
Git Bash):
+
+
+
+```console
+$ source .venv/Scripts/activate
+```
+
+
+
+////
+
+Esse comando criarรก ou modificarรก algumas [variรกveis โโde ambiente](environment-variables.md){.internal-link target=_blank} que estarรฃo disponรญveis para os prรณximos comandos.
+
+Uma dessas variรกveis โโรฉ a variรกvel `PATH`.
+
+/// tip | "Dica"
+
+Vocรช pode aprender mais sobre a variรกvel de ambiente `PATH` na seรงรฃo [Variรกveis โโde ambiente](environment-variables.md#path-environment-variable){.internal-link target=_blank}.
+
+///
+
+A ativaรงรฃo de um ambiente virtual adiciona seu caminho `.venv/bin` (no Linux e macOS) ou `.venv\Scripts` (no Windows) ร variรกvel de ambiente `PATH`.
+
+Digamos que antes de ativar o ambiente, a variรกvel `PATH` estava assim:
+
+//// tab | Linux, macOS
+
+```plaintext
+/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+Isso significa que o sistema procuraria programas em:
+
+* `/usr/bin`
+* `/bin`
+* `/usr/sbin`
+* `/sbin`
+
+////
+
+//// tab | Windows
+
+```plaintext
+C:\Windows\System32
+```
+
+Isso significa que o sistema procuraria programas em:
+
+* `C:\Windows\System32`
+
+////
+
+Apรณs ativar o ambiente virtual, a variรกvel `PATH` ficaria mais ou menos assim:
+
+//// tab | Linux, macOS
+
+```plaintext
+/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+Isso significa que o sistema agora comeรงarรก a procurar primeiro por programas em:
+
+```plaintext
+/home/user/code/awesome-project/.venv/bin
+```
+
+antes de procurar nos outros diretรณrios.
+
+Entรฃo, quando vocรช digita `python` no terminal, o sistema encontrarรก o programa Python em
+
+```plaintext
+/home/user/code/awesome-project/.venv/bin/python
+```
+
+e usa esse.
+
+////
+
+//// tab | Windows
+
+```plaintext
+C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32
+```
+
+Isso significa que o sistema agora comeรงarรก a procurar primeiro por programas em:
+
+```plaintext
+C:\Users\user\code\awesome-project\.venv\Scripts
+```
+
+antes de procurar nos outros diretรณrios.
+
+Entรฃo, quando vocรช digita `python` no terminal, o sistema encontrarรก o programa Python em
+
+```plaintext
+C:\Users\user\code\awesome-project\.venv\Scripts\python
+```
+
+e usa esse.
+
+////
+
+Um detalhe importante รฉ que ele colocarรก o caminho do ambiente virtual no **inรญcio** da variรกvel `PATH`. O sistema o encontrarรก **antes** de encontrar qualquer outro Python disponรญvel. Dessa forma, quando vocรช executar `python`, ele usarรก o Python **do ambiente virtual** em vez de qualquer outro `python` (por exemplo, um `python` de um ambiente global).
+
+Ativar um ambiente virtual tambรฉm muda algumas outras coisas, mas esta รฉ uma das mais importantes.
+
+## Verificando um ambiente virtual
+
+Ao verificar se um ambiente virtual estรก ativo, por exemplo com:
+
+//// tab | Linux, macOS, Windows Bash
+
+
+
+```console
+$ which python
+
+/home/user/code/awesome-project/.venv/bin/python
+```
+
+
+
+////
+
+//// tab | Windows PowerShell
+
+
+
+```console
+$ Get-Command python
+
+C:\Users\user\code\awesome-project\.venv\Scripts\python
+```
+
+
+
+////
+
+Isso significa que o programa `python` que serรก usado รฉ aquele **no ambiente virtual**.
+
+vocรช usa `which` no Linux e macOS e `Get-Command` no Windows PowerShell.
+
+A maneira como esse comando funciona รฉ que ele vai e verifica na variรกvel de ambiente `PATH`, passando por **cada caminho em ordem**, procurando pelo programa chamado `python`. Uma vez que ele o encontre, ele **mostrarรก o caminho** para esse programa.
+
+A parte mais importante รฉ que quando vocรช chama ``python`, esse รฉ exatamente o "`python`" que serรก executado.
+
+Assim, vocรช pode confirmar se estรก no ambiente virtual correto.
+
+/// tip | "Dica"
+
+ร fรกcil ativar um ambiente virtual, obter um Python e entรฃo **ir para outro projeto**.
+
+E o segundo projeto **nรฃo funcionaria** porque vocรช estรก usando o **Python incorreto**, de um ambiente virtual para outro projeto.
+
+ร รบtil poder verificar qual `python` estรก sendo usado. ๐ค
+
+///
+
+## Por que desativar um ambiente virtual
+
+Por exemplo, vocรช pode estar trabalhando em um projeto `philosophers-stone`, **ativar esse ambiente virtual**, instalar pacotes e trabalhar com esse ambiente.
+
+E entรฃo vocรช quer trabalhar em **outro projeto** `prisoner-of-azkaban`.
+
+Vocรช vai para aquele projeto:
+
+
+
+```console
+$ cd ~/code/prisoner-of-azkaban
+```
+
+
+
+Se vocรช nรฃo desativar o ambiente virtual para `philosophers-stone`, quando vocรช executar `python` no terminal, ele tentarรก usar o Python de `philosophers-stone`.
+
+
+
+```console
+$ cd ~/code/prisoner-of-azkaban
+
+$ python main.py
+
+// Erro ao importar o Sirius, ele nรฃo estรก instalado ๐ฑ
+Traceback (most recent call last):
+ File "main.py", line 1, in
+ import sirius
+```
+
+
+
+Mas se vocรช desativar o ambiente virtual e ativar o novo para `prisoner-of-askaban`, quando vocรช executar `python`, ele usarรก o Python do ambiente virtual em `prisoner-of-azkaban`.
+
+
+
+```console
+$ cd ~/code/prisoner-of-azkaban
+
+// Vocรช nรฃo precisa estar no diretรณrio antigo para desativar, vocรช pode fazer isso de onde estiver, mesmo depois de ir para o outro projeto ๐
+$ deactivate
+
+// Ative o ambiente virtual em prisoner-of-azkaban/.venv ๐
+$ source .venv/bin/activate
+
+// Agora, quando vocรช executar o python, ele encontrarรก o pacote sirius instalado neste ambiente virtual โจ
+$ python main.py
+
+Eu juro solenemente ๐บ
+```
+
+
+
+## Alternativas
+
+Este รฉ um guia simples para vocรช comeรงar e lhe ensinar como tudo funciona **por baixo**.
+
+Existem muitas **alternativas** para gerenciar ambientes virtuais, dependรชncias de pacotes (requisitos) e projetos.
+
+Quando estiver pronto e quiser usar uma ferramenta para **gerenciar todo o projeto**, dependรชncias de pacotes, ambientes virtuais, etc., sugiro que vocรช experimente o
uv.
+
+`uv` pode fazer muitas coisas, ele pode:
+
+* **Instalar o Python** para vocรช, incluindo versรตes diferentes
+* Gerenciar o **ambiente virtual** para seus projetos
+* Instalar **pacotes**
+* Gerenciar **dependรชncias e versรตes** de pacotes para seu projeto
+* Certifique-se de ter um conjunto **exato** de pacotes e versรตes para instalar, incluindo suas dependรชncias, para que vocรช possa ter certeza de que pode executar seu projeto em produรงรฃo exatamente da mesma forma que em seu computador durante o desenvolvimento, isso รฉ chamado de **bloqueio**
+* E muitas outras coisas
+
+## Conclusรฃo
+
+Se vocรช leu e entendeu tudo isso, agora **vocรช sabe muito mais** sobre ambientes virtuais do que muitos desenvolvedores por aรญ. ๐ค
+
+Saber esses detalhes provavelmente serรก รบtil no futuro, quando vocรช estiver depurando algo que parece complexo, mas vocรช saberรก **como tudo funciona**. ๐
diff --git a/docs/zh/docs/how-to/index.md b/docs/zh/docs/how-to/index.md
index 262dcfaee..ac097618b 100644
--- a/docs/zh/docs/how-to/index.md
+++ b/docs/zh/docs/how-to/index.md
@@ -6,7 +6,7 @@
ๅฆๆๆไบๅ
ๅฎน็่ตทๆฅๅฏนไฝ ็้กน็ฎๆ็จ๏ผ่ฏท็ปง็ปญๆฅ้
๏ผๅฆๅ่ฏท็ดๆฅ่ทณ่ฟๅฎไปฌใ
-/// ๅฐๆๅทง
+/// tip | ๅฐๆๅทง
ๅฆๆไฝ ๆณไปฅ็ณป็ป็ๆนๅผ**ๅญฆไน FastAPI**๏ผๆจ่๏ผ๏ผ่ฏท้
่ฏป [ๆ็จ - ็จๆทๆๅ](../tutorial/index.md){.internal-link target=_blank} ็ๆฏไธ็ซ ่ใ
diff --git a/docs/zh/docs/project-generation.md b/docs/zh/docs/project-generation.md
index 0655cb0a9..9b3735539 100644
--- a/docs/zh/docs/project-generation.md
+++ b/docs/zh/docs/project-generation.md
@@ -1,84 +1,28 @@
-# ้กน็ฎ็ๆ - ๆจกๆฟ
-
-้กน็ฎ็ๆๅจไธ่ฌ้ฝไผๆไพๅพๅคๅๅง่ฎพ็ฝฎใๅฎๅ
จๆชๆฝใๆฐๆฎๅบ๏ผ็่ณ่ฟๅๅคๅฅฝไบ็ฌฌไธไธช API ็ซฏ็น๏ผ่ฝๅธฎๅฉๆจๅฟซ้ไธๆใ
-
-้กน็ฎ็ๆๅจ็่ฎพ็ฝฎ้ๅธธ้ฝๅพไธป่ง๏ผๆจๅฏไปฅๆ้ๆดๆฐๆไฟฎๆน๏ผไฝๅฏนไบๆจ็้กน็ฎๆฅ่ฏด๏ผๅฎๆฏ้ๅธธๅฅฝ็่ตท็นใ
-
-## ๅ
จๆ FastAPI + PostgreSQL
-
-GitHub๏ผ
https://github.com/tiangolo/full-stack-fastapi-postgresql
-
-### ๅ
จๆ FastAPI + PostgreSQL - ๅ่ฝ
-
-* ๅฎๆด็ **Docker** ้ๆ๏ผๅบไบ Docker๏ผ
-* Docker Swarm ๅผๅๆจกๅผ
-* **Docker Compose** ๆฌๅฐๅผๅ้ๆไธไผๅ
-* **็ไบงๅฏ็จ**็ Python ็ฝ็ปๆๅกๅจ๏ผไฝฟ็จ Uvicorn ๆ Gunicorn
-* Python
**FastAPI** ๅ็ซฏ๏ผ
-* * **้ๅบฆๅฟซ**๏ผๅฏไธ **NodeJS** ๅ **Go** ๆฏ่ฉ็ๆ้ซๆง่ฝ๏ผๅฝๅไบ Starlette ๅ Pydantic๏ผ
- * **็ด่ง**๏ผๅผบๅคง็็ผ่พๅจๆฏๆ๏ผๅคๅค็ๅฏ
่ชๅจ่กฅๅ
จ๏ผๅๅฐ่ฐ่ฏๆถ้ด
- * **็ฎๅ**๏ผๆๅญฆใๆ็จ๏ผ้
่ฏปๆๆกฃๆ้ๆถ้ดๆด็ญ
- * **็ฎ็ญ**๏ผไปฃ็ ้ๅคๆๅฐๅ๏ผๆฏๆฌกๅๆฐๅฃฐๆ้ฝๅฏไปฅๅฎ็ฐๅคไธชๅ่ฝ
- * **ๅฅๅฃฎ**๏ผ ็ไบง็บงๅซ็ไปฃ็ ๏ผ่ฟๆ่ชๅจไบคไบๆๆกฃ
- * **ๅบไบๆ ๅ**๏ผๅฎๅ
จๅ
ผๅฎนๅนถๅบไบ API ๅผๆพๆ ๅ๏ผ
OpenAPI ๅ
JSON Schema
- *
**ๆดๅคๅ่ฝ**ๅ
ๆฌ่ชๅจ้ช่ฏใๅบๅๅใไบคไบๆๆกฃใOAuth2 JWT ไปค็่บซไปฝ้ช่ฏ็ญ
-* **ๅฎๅ
จๅฏ็ **๏ผ้ป่ฎคไฝฟ็จๅฏ็ ๅๅธ
-* **JWT ไปค็**่บซไปฝ้ช่ฏ
-* **SQLAlchemy** ๆจกๅ๏ผ็ฌ็ซไบ Flask ๆฉๅฑ๏ผๅฏ็ดๆฅ็จไบ Celery Worker๏ผ
-* ๅบ็ก็็จๆทๆจกๅ๏ผๅฏๆ้ไฟฎๆนๆๅ ้ค๏ผ
-* **Alembic** ่ฟ็งป
-* **CORS**๏ผ่ทจๅ่ตๆบๅ
ฑไบซ๏ผ
-* **Celery** Worker ๅฏไปๅ็ซฏๅ
ถๅฎ้จๅๆ้ๆฉๅฐๅฏผๅ
ฅๅนถไฝฟ็จๆจกๅๅไปฃ็
-* REST ๅ็ซฏๆต่ฏๅบไบ Pytest๏ผๅนถไธ Docker ้ๆ๏ผๅฏ็ฌ็ซไบๆฐๆฎๅบๅฎ็ฐๅฎๆด็ API ไบคไบๆต่ฏใๅ ไธบๆฏๅจ Docker ไธญ่ฟ่ก๏ผๆฏๆฌก้ฝๅฏไปๅคดๆๅปบๆฐ็ๆฐๆฎๅญๅจ๏ผไฝฟ็จ ElasticSearchใMongoDBใCouchDB ็ญๆฐๆฎๅบ๏ผไป
ๆต่ฏ API ่ฟ่ก๏ผ
-* Python ไธ **Jupyter Kernels** ้ๆ๏ผ็จไบ่ฟ็จๆ Docker ๅฎนๅจๅ
้จๅผๅ๏ผไฝฟ็จ Atom Hydrogen ๆ Visual Studio Code ็ Jupyter ๆไปถ
-* **Vue** ๅ็ซฏ๏ผ
- * ็ฑ Vue CLI ็ๆ
- * **JWT ่บซไปฝ้ช่ฏ**ๅค็
- * ็ปๅฝ่งๅพ
- * ็ปๅฝๅๆพ็คบไธปไปช่กจ็่งๅพ
- * ไธปไปช่กจ็ๆฏๆ็จๆทๅๅปบไธ็ผ่พ
- * ็จๆทไฟกๆฏ็ผ่พ
- * **Vuex**
- * **Vue-router**
- * **Vuetify** ็พๅ็ปไปถ
- * **TypeScript**
- * ๅบไบ **Nginx** ็ Docker ๆๅกๅจ๏ผไผๅไบ Vue-router ้
็ฝฎ๏ผ
- * Docker ๅค้ถๆฎตๆๅปบ๏ผๆ ้ไฟๅญๆๆไบค็ผ่ฏ็ไปฃ็
- * ๅจๆๅปบๆถ่ฟ่กๅ็ซฏๆต่ฏ๏ผๅฏ็ฆ็จ๏ผ
- * ๅฐฝ้ๆจกๅๅ๏ผๅผ็ฎฑๅณ็จ๏ผไฝไปๅฏไฝฟ็จ Vue CLI ้ๆฐ็ๆๆๅๅปบๆ้้กน็ฎ๏ผๆๅค็จๆ้ๅ
ๅฎน
-* ไฝฟ็จ **PGAdmin** ็ฎก็ PostgreSQL ๆฐๆฎๅบ๏ผๅฏ่ฝปๆพๆฟๆขไธบ PHPMyAdmin ๆ MySQL
-* ไฝฟ็จ **Flower** ็ๆง Celery ไปปๅก
-* ไฝฟ็จ **Traefik** ๅค็ๅๅ็ซฏ่ด่ฝฝๅนณ่กก๏ผๅฏๆๅๅ็ซฏๆพๅจๅไธไธชๅไธ๏ผๆ่ทฏๅพๅ้๏ผไฝๅจไธๅๅฎนๅจไธญๆไพๆๅก
-* Traefik ้ๆ๏ผๅ
ๆฌ่ชๅจ็ๆ Let's Encrypt **HTTPS** ๅญ่ฏ
-* GitLab **CI**๏ผๆ็ปญ้ๆ๏ผ๏ผๅ
ๆฌๅๅ็ซฏๆต่ฏ
-
-## ๅ
จๆ FastAPI + Couchbase
-
-GitHub๏ผ
https://github.com/tiangolo/full-stack-fastapi-couchbase
-
-โ ๏ธ **่ญฆๅ** โ ๏ธ
-
-ๅฆๆๆจๆณไปๅคดๅผๅงๅๅปบๆฐ้กน็ฎ๏ผๅปบ่ฎฎไฝฟ็จไปฅไธๅค้ๆนๆกใ
-
-ไพๅฆ๏ผ้กน็ฎ็ๆๅจ
ๅ
จๆ FastAPI + PostgreSQLย ไผๆด้็จ๏ผ่ฟไธช้กน็ฎ็็ปดๆค็งฏๆ๏ผ็จ็ไบบไนๅค๏ผ่ฟๅ
ๆฌไบๆๆๆฐๅ่ฝๅๆน่ฟๅ
ๅฎนใ
-
-ๅฝ็ถ๏ผๆจไนๅฏไปฅๆพๅฟไฝฟ็จ่ฟไธชๅบไบ Couchbase ็็ๆๅจ๏ผๅฎไน่ฝๆญฃๅธธไฝฟ็จใๅฐฑ็ฎ็จๅฎ็ๆ้กน็ฎไนๆฒกๆไปปไฝ้ฎ้ข๏ผไธบไบๆดๅฅฝๅฐๆปก่ถณ้ๆฑ๏ผๆจๅฏไปฅ่ช่กๆดๆฐ่ฟไธช้กน็ฎ๏ผใ
-
-่ฏฆ่ง่ตๆบไปๅบไธญ็ๆๆกฃใ
-
-## ๅ
จๆ FastAPI + MongoDB
-
-โฆโฆๆฌ่ฏทๆๅพ
๏ผๅพ็ๆๆๆฒกๆๆถ้ดๅ่ฟไธช้กน็ฎใ๐
๐
-
-## FastAPI + spaCy ๆบๅจๅญฆไน ๆจกๅ
-
-GitHub๏ผ
https://github.com/microsoft/cookiecutter-spacy-fastapi
-
-### FastAPI + spaCy ๆบๅจๅญฆไน ๆจกๅ - ๅ่ฝ
-
-* ้ๆ **spaCy** NER ๆจกๅ
-* ๅ
็ฝฎ **Azure ่ฎค็ฅๆ็ดข**่ฏทๆฑๆ ผๅผ
-* **็ไบงๅฏ็จ**็ Python ็ฝ็ปๆๅกๅจ๏ผไฝฟ็จ Uvicorn ไธ Gunicorn
-* ๅ
็ฝฎ **Azure DevOps** Kubernetes (AKS) CI/CD ๅผๅ
-* **ๅค่ฏญ**ๆฏๆ๏ผๅฏๅจ้กน็ฎ่ฎพ็ฝฎๆถ้ๆฉ spaCy ๅ
็ฝฎ็่ฏญ่จ
-* ไธไป
ๅฑ้ไบ spaCy๏ผๅฏ**่ฝปๆพๆฉๅฑ**่ณๅ
ถๅฎๆจกๅๆกๆถ๏ผPytorchใTensorFlow๏ผ
+# FastAPIๅ
จๆ ๆจกๆฟ
+
+ๆจกๆฟ้ๅธธๅธฆๆ็นๅฎ็่ฎพ็ฝฎ๏ผ่ไธ่ขซ่ฎพ่ฎกไธบ็ตๆดปๅๅฏๅฎๅถ็ใ่ฟๅ
่ฎธๆจๆ นๆฎ้กน็ฎ็้ๆฑไฟฎๆนๅ่ฐๆดๅฎไปฌ๏ผไฝฟๅฎไปฌๆไธบไธไธชๅพๅฅฝ็่ตท็นใ๐
+
+ๆจๅฏไปฅไฝฟ็จๆญคๆจกๆฟๅผๅง๏ผๅ ไธบๅฎๅ
ๅซไบ่ฎธๅคๅทฒ็ปไธบๆจๅฎๆ็ๅๅง่ฎพ็ฝฎใๅฎๅ
จๆงใๆฐๆฎๅบๅไธไบAPI็ซฏ็นใ
+
+ไปฃ็ ไป๏ผ
Full Stack FastAPI Template
+
+## FastAPIๅ
จๆ ๆจกๆฟ - ๆๆฏๆ ๅ็นๆง
+
+- โก [**FastAPI**](https://fastapi.tiangolo.com) ็จไบPythonๅ็ซฏAPI.
+ - ๐งฐ [SQLModel](https://sqlmodel.tiangolo.com) ็จไบPythonๅSQLๆฐๆฎๅบ็้ๆ๏ผORM๏ผใ
+ - ๐ [Pydantic](https://docs.pydantic.dev) FastAPI็ไพ่ต้กนไนไธ๏ผ็จไบๆฐๆฎ้ช่ฏๅ้
็ฝฎ็ฎก็ใ
+ - ๐พ [PostgreSQL](https://www.postgresql.org) ไฝไธบSQLๆฐๆฎๅบใ
+- ๐ [React](https://react.dev) ็จไบๅ็ซฏใ
+ - ๐ ไฝฟ็จไบTypeScriptใhooksใViteๅๅ
ถไปไธไบ็ฐไปฃๅ็ๅ็ซฏๆๆฏๆ ใ
+ - ๐จ [Chakra UI](https://chakra-ui.com) ็จไบๅ็ซฏ็ปไปถใ
+ - ๐ค ไธไธช่ชๅจๅ็ๆ็ๅ็ซฏๅฎขๆท็ซฏใ
+ - ๐งช Playwright็จไบ็ซฏๅฐ็ซฏๆต่ฏใ
+ - ๐ฆ ๆฏๆๆ้ปไธป้ข๏ผDark mode๏ผใ
+- ๐ [Docker Compose](https://www.docker.com) ็จไบๅผๅ็ฏๅขๅ็ไบง็ฏๅขใ
+- ๐ ้ป่ฎคไฝฟ็จๅฏ็ ๅๅธๆฅไฟ่ฏๅฎๅ
จใ
+- ๐ JWTไปค็็จไบๆ้้ช่ฏใ
+- ๐ซ ไฝฟ็จ้ฎ็ฎฑๆฅ่ฟ่กๅฏ็ ๆขๅคใ
+- โ
ๅๅ
ๆต่ฏ็จไบ[Pytest](https://pytest.org).
+- ๐ [Traefik](https://traefik.io) ็จไบๅๅไปฃ็ๅ่ด่ฝฝๅ่กกใ
+- ๐ข ้จ็ฝฒๆๅ๏ผDocker Compose๏ผๅ
ๅซไบๅฆไฝ่ตทไธไธชTraefikๅ็ซฏไปฃ็ๆฅ่ชๅจๅHTTPS่ฎค่ฏใ
+- ๐ญ CI๏ผๆ็ปญ้ๆ๏ผๅ CD๏ผๆ็ปญ้จ็ฝฒ๏ผๅบไบGitHub Actionsใ
diff --git a/docs_src/async_tests/test_main.py b/docs_src/async_tests/test_main.py
index 9f1527d5f..a57a31f7d 100644
--- a/docs_src/async_tests/test_main.py
+++ b/docs_src/async_tests/test_main.py
@@ -1,12 +1,14 @@
import pytest
-from httpx import AsyncClient
+from httpx import ASGITransport, AsyncClient
from .main import app
@pytest.mark.anyio
async def test_root():
- async with AsyncClient(app=app, base_url="http://test") as ac:
+ async with AsyncClient(
+ transport=ASGITransport(app=app), base_url="http://test"
+ ) as ac:
response = await ac.get("/")
assert response.status_code == 200
assert response.json() == {"message": "Tomato"}
diff --git a/docs_src/cookie_param_models/tutorial001.py b/docs_src/cookie_param_models/tutorial001.py
new file mode 100644
index 000000000..cc65c43e1
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial001.py
@@ -0,0 +1,17 @@
+from typing import Union
+
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ session_id: str
+ fatebook_tracker: Union[str, None] = None
+ googall_tracker: Union[str, None] = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Cookies = Cookie()):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial001_an.py b/docs_src/cookie_param_models/tutorial001_an.py
new file mode 100644
index 000000000..e5839ffd5
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial001_an.py
@@ -0,0 +1,18 @@
+from typing import Union
+
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ session_id: str
+ fatebook_tracker: Union[str, None] = None
+ googall_tracker: Union[str, None] = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Annotated[Cookies, Cookie()]):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial001_an_py310.py b/docs_src/cookie_param_models/tutorial001_an_py310.py
new file mode 100644
index 000000000..24cc889a9
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial001_an_py310.py
@@ -0,0 +1,17 @@
+from typing import Annotated
+
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ session_id: str
+ fatebook_tracker: str | None = None
+ googall_tracker: str | None = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Annotated[Cookies, Cookie()]):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial001_an_py39.py b/docs_src/cookie_param_models/tutorial001_an_py39.py
new file mode 100644
index 000000000..3d90c2007
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial001_an_py39.py
@@ -0,0 +1,17 @@
+from typing import Annotated, Union
+
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ session_id: str
+ fatebook_tracker: Union[str, None] = None
+ googall_tracker: Union[str, None] = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Annotated[Cookies, Cookie()]):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial001_py310.py b/docs_src/cookie_param_models/tutorial001_py310.py
new file mode 100644
index 000000000..7cdee5a92
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial001_py310.py
@@ -0,0 +1,15 @@
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ session_id: str
+ fatebook_tracker: str | None = None
+ googall_tracker: str | None = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Cookies = Cookie()):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial002.py b/docs_src/cookie_param_models/tutorial002.py
new file mode 100644
index 000000000..9679e890f
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial002.py
@@ -0,0 +1,19 @@
+from typing import Union
+
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ session_id: str
+ fatebook_tracker: Union[str, None] = None
+ googall_tracker: Union[str, None] = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Cookies = Cookie()):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_an.py b/docs_src/cookie_param_models/tutorial002_an.py
new file mode 100644
index 000000000..ce5644b7b
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial002_an.py
@@ -0,0 +1,20 @@
+from typing import Union
+
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ session_id: str
+ fatebook_tracker: Union[str, None] = None
+ googall_tracker: Union[str, None] = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Annotated[Cookies, Cookie()]):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_an_py310.py b/docs_src/cookie_param_models/tutorial002_an_py310.py
new file mode 100644
index 000000000..7fa70fe92
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial002_an_py310.py
@@ -0,0 +1,19 @@
+from typing import Annotated
+
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ session_id: str
+ fatebook_tracker: str | None = None
+ googall_tracker: str | None = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Annotated[Cookies, Cookie()]):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_an_py39.py b/docs_src/cookie_param_models/tutorial002_an_py39.py
new file mode 100644
index 000000000..a906ce6a1
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial002_an_py39.py
@@ -0,0 +1,19 @@
+from typing import Annotated, Union
+
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ session_id: str
+ fatebook_tracker: Union[str, None] = None
+ googall_tracker: Union[str, None] = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Annotated[Cookies, Cookie()]):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_pv1.py b/docs_src/cookie_param_models/tutorial002_pv1.py
new file mode 100644
index 000000000..13f78b850
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial002_pv1.py
@@ -0,0 +1,20 @@
+from typing import Union
+
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ session_id: str
+ fatebook_tracker: Union[str, None] = None
+ googall_tracker: Union[str, None] = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Cookies = Cookie()):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_pv1_an.py b/docs_src/cookie_param_models/tutorial002_pv1_an.py
new file mode 100644
index 000000000..ddfda9b6f
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial002_pv1_an.py
@@ -0,0 +1,21 @@
+from typing import Union
+
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ session_id: str
+ fatebook_tracker: Union[str, None] = None
+ googall_tracker: Union[str, None] = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Annotated[Cookies, Cookie()]):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_pv1_an_py310.py b/docs_src/cookie_param_models/tutorial002_pv1_an_py310.py
new file mode 100644
index 000000000..ac00360b6
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial002_pv1_an_py310.py
@@ -0,0 +1,20 @@
+from typing import Annotated
+
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ session_id: str
+ fatebook_tracker: str | None = None
+ googall_tracker: str | None = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Annotated[Cookies, Cookie()]):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_pv1_an_py39.py b/docs_src/cookie_param_models/tutorial002_pv1_an_py39.py
new file mode 100644
index 000000000..573caea4b
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial002_pv1_an_py39.py
@@ -0,0 +1,20 @@
+from typing import Annotated, Union
+
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ session_id: str
+ fatebook_tracker: Union[str, None] = None
+ googall_tracker: Union[str, None] = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Annotated[Cookies, Cookie()]):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_pv1_py310.py b/docs_src/cookie_param_models/tutorial002_pv1_py310.py
new file mode 100644
index 000000000..2c59aad12
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial002_pv1_py310.py
@@ -0,0 +1,18 @@
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ session_id: str
+ fatebook_tracker: str | None = None
+ googall_tracker: str | None = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Cookies = Cookie()):
+ return cookies
diff --git a/docs_src/cookie_param_models/tutorial002_py310.py b/docs_src/cookie_param_models/tutorial002_py310.py
new file mode 100644
index 000000000..f011aa1af
--- /dev/null
+++ b/docs_src/cookie_param_models/tutorial002_py310.py
@@ -0,0 +1,17 @@
+from fastapi import Cookie, FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Cookies(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ session_id: str
+ fatebook_tracker: str | None = None
+ googall_tracker: str | None = None
+
+
+@app.get("/items/")
+async def read_items(cookies: Cookies = Cookie()):
+ return cookies
diff --git a/docs_src/header_param_models/tutorial001.py b/docs_src/header_param_models/tutorial001.py
new file mode 100644
index 000000000..4caaba87b
--- /dev/null
+++ b/docs_src/header_param_models/tutorial001.py
@@ -0,0 +1,19 @@
+from typing import List, Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: CommonHeaders = Header()):
+ return headers
diff --git a/docs_src/header_param_models/tutorial001_an.py b/docs_src/header_param_models/tutorial001_an.py
new file mode 100644
index 000000000..b55c6b56b
--- /dev/null
+++ b/docs_src/header_param_models/tutorial001_an.py
@@ -0,0 +1,20 @@
+from typing import List, Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: Annotated[CommonHeaders, Header()]):
+ return headers
diff --git a/docs_src/header_param_models/tutorial001_an_py310.py b/docs_src/header_param_models/tutorial001_an_py310.py
new file mode 100644
index 000000000..acfb6b9bf
--- /dev/null
+++ b/docs_src/header_param_models/tutorial001_an_py310.py
@@ -0,0 +1,19 @@
+from typing import Annotated
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ host: str
+ save_data: bool
+ if_modified_since: str | None = None
+ traceparent: str | None = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: Annotated[CommonHeaders, Header()]):
+ return headers
diff --git a/docs_src/header_param_models/tutorial001_an_py39.py b/docs_src/header_param_models/tutorial001_an_py39.py
new file mode 100644
index 000000000..51a5f94fc
--- /dev/null
+++ b/docs_src/header_param_models/tutorial001_an_py39.py
@@ -0,0 +1,19 @@
+from typing import Annotated, Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: Annotated[CommonHeaders, Header()]):
+ return headers
diff --git a/docs_src/header_param_models/tutorial001_py310.py b/docs_src/header_param_models/tutorial001_py310.py
new file mode 100644
index 000000000..7239c64ce
--- /dev/null
+++ b/docs_src/header_param_models/tutorial001_py310.py
@@ -0,0 +1,17 @@
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ host: str
+ save_data: bool
+ if_modified_since: str | None = None
+ traceparent: str | None = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: CommonHeaders = Header()):
+ return headers
diff --git a/docs_src/header_param_models/tutorial001_py39.py b/docs_src/header_param_models/tutorial001_py39.py
new file mode 100644
index 000000000..4c1137813
--- /dev/null
+++ b/docs_src/header_param_models/tutorial001_py39.py
@@ -0,0 +1,19 @@
+from typing import Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: CommonHeaders = Header()):
+ return headers
diff --git a/docs_src/header_param_models/tutorial002.py b/docs_src/header_param_models/tutorial002.py
new file mode 100644
index 000000000..3f9aac58d
--- /dev/null
+++ b/docs_src/header_param_models/tutorial002.py
@@ -0,0 +1,21 @@
+from typing import List, Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: CommonHeaders = Header()):
+ return headers
diff --git a/docs_src/header_param_models/tutorial002_an.py b/docs_src/header_param_models/tutorial002_an.py
new file mode 100644
index 000000000..771135d77
--- /dev/null
+++ b/docs_src/header_param_models/tutorial002_an.py
@@ -0,0 +1,22 @@
+from typing import List, Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: Annotated[CommonHeaders, Header()]):
+ return headers
diff --git a/docs_src/header_param_models/tutorial002_an_py310.py b/docs_src/header_param_models/tutorial002_an_py310.py
new file mode 100644
index 000000000..e9535f045
--- /dev/null
+++ b/docs_src/header_param_models/tutorial002_an_py310.py
@@ -0,0 +1,21 @@
+from typing import Annotated
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ host: str
+ save_data: bool
+ if_modified_since: str | None = None
+ traceparent: str | None = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: Annotated[CommonHeaders, Header()]):
+ return headers
diff --git a/docs_src/header_param_models/tutorial002_an_py39.py b/docs_src/header_param_models/tutorial002_an_py39.py
new file mode 100644
index 000000000..ca5208c9d
--- /dev/null
+++ b/docs_src/header_param_models/tutorial002_an_py39.py
@@ -0,0 +1,21 @@
+from typing import Annotated, Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: Annotated[CommonHeaders, Header()]):
+ return headers
diff --git a/docs_src/header_param_models/tutorial002_pv1.py b/docs_src/header_param_models/tutorial002_pv1.py
new file mode 100644
index 000000000..7e56cd993
--- /dev/null
+++ b/docs_src/header_param_models/tutorial002_pv1.py
@@ -0,0 +1,22 @@
+from typing import List, Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: CommonHeaders = Header()):
+ return headers
diff --git a/docs_src/header_param_models/tutorial002_pv1_an.py b/docs_src/header_param_models/tutorial002_pv1_an.py
new file mode 100644
index 000000000..236778231
--- /dev/null
+++ b/docs_src/header_param_models/tutorial002_pv1_an.py
@@ -0,0 +1,23 @@
+from typing import List, Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: Annotated[CommonHeaders, Header()]):
+ return headers
diff --git a/docs_src/header_param_models/tutorial002_pv1_an_py310.py b/docs_src/header_param_models/tutorial002_pv1_an_py310.py
new file mode 100644
index 000000000..e99e24ea5
--- /dev/null
+++ b/docs_src/header_param_models/tutorial002_pv1_an_py310.py
@@ -0,0 +1,22 @@
+from typing import Annotated
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ host: str
+ save_data: bool
+ if_modified_since: str | None = None
+ traceparent: str | None = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: Annotated[CommonHeaders, Header()]):
+ return headers
diff --git a/docs_src/header_param_models/tutorial002_pv1_an_py39.py b/docs_src/header_param_models/tutorial002_pv1_an_py39.py
new file mode 100644
index 000000000..18398b726
--- /dev/null
+++ b/docs_src/header_param_models/tutorial002_pv1_an_py39.py
@@ -0,0 +1,22 @@
+from typing import Annotated, Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: Annotated[CommonHeaders, Header()]):
+ return headers
diff --git a/docs_src/header_param_models/tutorial002_pv1_py310.py b/docs_src/header_param_models/tutorial002_pv1_py310.py
new file mode 100644
index 000000000..3dbff9d7b
--- /dev/null
+++ b/docs_src/header_param_models/tutorial002_pv1_py310.py
@@ -0,0 +1,20 @@
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ host: str
+ save_data: bool
+ if_modified_since: str | None = None
+ traceparent: str | None = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: CommonHeaders = Header()):
+ return headers
diff --git a/docs_src/header_param_models/tutorial002_pv1_py39.py b/docs_src/header_param_models/tutorial002_pv1_py39.py
new file mode 100644
index 000000000..86e19be0d
--- /dev/null
+++ b/docs_src/header_param_models/tutorial002_pv1_py39.py
@@ -0,0 +1,22 @@
+from typing import Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: CommonHeaders = Header()):
+ return headers
diff --git a/docs_src/header_param_models/tutorial002_py310.py b/docs_src/header_param_models/tutorial002_py310.py
new file mode 100644
index 000000000..3d2296345
--- /dev/null
+++ b/docs_src/header_param_models/tutorial002_py310.py
@@ -0,0 +1,19 @@
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ host: str
+ save_data: bool
+ if_modified_since: str | None = None
+ traceparent: str | None = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: CommonHeaders = Header()):
+ return headers
diff --git a/docs_src/header_param_models/tutorial002_py39.py b/docs_src/header_param_models/tutorial002_py39.py
new file mode 100644
index 000000000..f8ce559a7
--- /dev/null
+++ b/docs_src/header_param_models/tutorial002_py39.py
@@ -0,0 +1,21 @@
+from typing import Union
+
+from fastapi import FastAPI, Header
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class CommonHeaders(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ host: str
+ save_data: bool
+ if_modified_since: Union[str, None] = None
+ traceparent: Union[str, None] = None
+ x_tag: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(headers: CommonHeaders = Header()):
+ return headers
diff --git a/docs_src/middleware/tutorial001.py b/docs_src/middleware/tutorial001.py
index 6bab3410a..e65a7dade 100644
--- a/docs_src/middleware/tutorial001.py
+++ b/docs_src/middleware/tutorial001.py
@@ -7,8 +7,8 @@ app = FastAPI()
@app.middleware("http")
async def add_process_time_header(request: Request, call_next):
- start_time = time.time()
+ start_time = time.perf_counter()
response = await call_next(request)
- process_time = time.time() - start_time
+ process_time = time.perf_counter() - start_time
response.headers["X-Process-Time"] = str(process_time)
return response
diff --git a/docs_src/path_params_numeric_validations/tutorial006.py b/docs_src/path_params_numeric_validations/tutorial006.py
index 0ea32694a..f07629aa0 100644
--- a/docs_src/path_params_numeric_validations/tutorial006.py
+++ b/docs_src/path_params_numeric_validations/tutorial006.py
@@ -13,4 +13,6 @@ async def read_items(
results = {"item_id": item_id}
if q:
results.update({"q": q})
+ if size:
+ results.update({"size": size})
return results
diff --git a/docs_src/path_params_numeric_validations/tutorial006_an.py b/docs_src/path_params_numeric_validations/tutorial006_an.py
index 22a143623..ac4732573 100644
--- a/docs_src/path_params_numeric_validations/tutorial006_an.py
+++ b/docs_src/path_params_numeric_validations/tutorial006_an.py
@@ -14,4 +14,6 @@ async def read_items(
results = {"item_id": item_id}
if q:
results.update({"q": q})
+ if size:
+ results.update({"size": size})
return results
diff --git a/docs_src/path_params_numeric_validations/tutorial006_an_py39.py b/docs_src/path_params_numeric_validations/tutorial006_an_py39.py
index 804751893..426ec3776 100644
--- a/docs_src/path_params_numeric_validations/tutorial006_an_py39.py
+++ b/docs_src/path_params_numeric_validations/tutorial006_an_py39.py
@@ -15,4 +15,6 @@ async def read_items(
results = {"item_id": item_id}
if q:
results.update({"q": q})
+ if size:
+ results.update({"size": size})
return results
diff --git a/docs_src/query_param_models/tutorial001.py b/docs_src/query_param_models/tutorial001.py
new file mode 100644
index 000000000..0c0ab315e
--- /dev/null
+++ b/docs_src/query_param_models/tutorial001.py
@@ -0,0 +1,19 @@
+from typing import List
+
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Literal
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: FilterParams = Query()):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial001_an.py b/docs_src/query_param_models/tutorial001_an.py
new file mode 100644
index 000000000..28375057c
--- /dev/null
+++ b/docs_src/query_param_models/tutorial001_an.py
@@ -0,0 +1,19 @@
+from typing import List
+
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated, Literal
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: Annotated[FilterParams, Query()]):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial001_an_py310.py b/docs_src/query_param_models/tutorial001_an_py310.py
new file mode 100644
index 000000000..71427acae
--- /dev/null
+++ b/docs_src/query_param_models/tutorial001_an_py310.py
@@ -0,0 +1,18 @@
+from typing import Annotated, Literal
+
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: Annotated[FilterParams, Query()]):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial001_an_py39.py b/docs_src/query_param_models/tutorial001_an_py39.py
new file mode 100644
index 000000000..ba690d3e3
--- /dev/null
+++ b/docs_src/query_param_models/tutorial001_an_py39.py
@@ -0,0 +1,17 @@
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated, Literal
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: Annotated[FilterParams, Query()]):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial001_py310.py b/docs_src/query_param_models/tutorial001_py310.py
new file mode 100644
index 000000000..3ebf9f4d7
--- /dev/null
+++ b/docs_src/query_param_models/tutorial001_py310.py
@@ -0,0 +1,18 @@
+from typing import Literal
+
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: FilterParams = Query()):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial001_py39.py b/docs_src/query_param_models/tutorial001_py39.py
new file mode 100644
index 000000000..54b52a054
--- /dev/null
+++ b/docs_src/query_param_models/tutorial001_py39.py
@@ -0,0 +1,17 @@
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Literal
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: FilterParams = Query()):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial002.py b/docs_src/query_param_models/tutorial002.py
new file mode 100644
index 000000000..1633bc464
--- /dev/null
+++ b/docs_src/query_param_models/tutorial002.py
@@ -0,0 +1,21 @@
+from typing import List
+
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Literal
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: FilterParams = Query()):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial002_an.py b/docs_src/query_param_models/tutorial002_an.py
new file mode 100644
index 000000000..69705d4b4
--- /dev/null
+++ b/docs_src/query_param_models/tutorial002_an.py
@@ -0,0 +1,21 @@
+from typing import List
+
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated, Literal
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: Annotated[FilterParams, Query()]):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial002_an_py310.py b/docs_src/query_param_models/tutorial002_an_py310.py
new file mode 100644
index 000000000..975956502
--- /dev/null
+++ b/docs_src/query_param_models/tutorial002_an_py310.py
@@ -0,0 +1,20 @@
+from typing import Annotated, Literal
+
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: Annotated[FilterParams, Query()]):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial002_an_py39.py b/docs_src/query_param_models/tutorial002_an_py39.py
new file mode 100644
index 000000000..2d4c1a62b
--- /dev/null
+++ b/docs_src/query_param_models/tutorial002_an_py39.py
@@ -0,0 +1,19 @@
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated, Literal
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: Annotated[FilterParams, Query()]):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial002_pv1.py b/docs_src/query_param_models/tutorial002_pv1.py
new file mode 100644
index 000000000..71ccd961d
--- /dev/null
+++ b/docs_src/query_param_models/tutorial002_pv1.py
@@ -0,0 +1,22 @@
+from typing import List
+
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Literal
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: FilterParams = Query()):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial002_pv1_an.py b/docs_src/query_param_models/tutorial002_pv1_an.py
new file mode 100644
index 000000000..1dd29157a
--- /dev/null
+++ b/docs_src/query_param_models/tutorial002_pv1_an.py
@@ -0,0 +1,22 @@
+from typing import List
+
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated, Literal
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: List[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: Annotated[FilterParams, Query()]):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial002_pv1_an_py310.py b/docs_src/query_param_models/tutorial002_pv1_an_py310.py
new file mode 100644
index 000000000..d635aae88
--- /dev/null
+++ b/docs_src/query_param_models/tutorial002_pv1_an_py310.py
@@ -0,0 +1,21 @@
+from typing import Annotated, Literal
+
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: Annotated[FilterParams, Query()]):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial002_pv1_an_py39.py b/docs_src/query_param_models/tutorial002_pv1_an_py39.py
new file mode 100644
index 000000000..494fef11f
--- /dev/null
+++ b/docs_src/query_param_models/tutorial002_pv1_an_py39.py
@@ -0,0 +1,20 @@
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated, Literal
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: Annotated[FilterParams, Query()]):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial002_pv1_py310.py b/docs_src/query_param_models/tutorial002_pv1_py310.py
new file mode 100644
index 000000000..9ffdeefc0
--- /dev/null
+++ b/docs_src/query_param_models/tutorial002_pv1_py310.py
@@ -0,0 +1,21 @@
+from typing import Literal
+
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: FilterParams = Query()):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial002_pv1_py39.py b/docs_src/query_param_models/tutorial002_pv1_py39.py
new file mode 100644
index 000000000..7fa456a79
--- /dev/null
+++ b/docs_src/query_param_models/tutorial002_pv1_py39.py
@@ -0,0 +1,20 @@
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Literal
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ class Config:
+ extra = "forbid"
+
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: FilterParams = Query()):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial002_py310.py b/docs_src/query_param_models/tutorial002_py310.py
new file mode 100644
index 000000000..6ec418499
--- /dev/null
+++ b/docs_src/query_param_models/tutorial002_py310.py
@@ -0,0 +1,20 @@
+from typing import Literal
+
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: FilterParams = Query()):
+ return filter_query
diff --git a/docs_src/query_param_models/tutorial002_py39.py b/docs_src/query_param_models/tutorial002_py39.py
new file mode 100644
index 000000000..f9bba028c
--- /dev/null
+++ b/docs_src/query_param_models/tutorial002_py39.py
@@ -0,0 +1,19 @@
+from fastapi import FastAPI, Query
+from pydantic import BaseModel, Field
+from typing_extensions import Literal
+
+app = FastAPI()
+
+
+class FilterParams(BaseModel):
+ model_config = {"extra": "forbid"}
+
+ limit: int = Field(100, gt=0, le=100)
+ offset: int = Field(0, ge=0)
+ order_by: Literal["created_at", "updated_at"] = "created_at"
+ tags: list[str] = []
+
+
+@app.get("/items/")
+async def read_items(filter_query: FilterParams = Query()):
+ return filter_query
diff --git a/docs_src/request_form_models/tutorial001.py b/docs_src/request_form_models/tutorial001.py
new file mode 100644
index 000000000..98feff0b9
--- /dev/null
+++ b/docs_src/request_form_models/tutorial001.py
@@ -0,0 +1,14 @@
+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
diff --git a/docs_src/request_form_models/tutorial001_an.py b/docs_src/request_form_models/tutorial001_an.py
new file mode 100644
index 000000000..30483d445
--- /dev/null
+++ b/docs_src/request_form_models/tutorial001_an.py
@@ -0,0 +1,15 @@
+from fastapi import FastAPI, Form
+from pydantic import BaseModel
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+class FormData(BaseModel):
+ username: str
+ password: str
+
+
+@app.post("/login/")
+async def login(data: Annotated[FormData, Form()]):
+ return data
diff --git a/docs_src/request_form_models/tutorial001_an_py39.py b/docs_src/request_form_models/tutorial001_an_py39.py
new file mode 100644
index 000000000..7cc81aae9
--- /dev/null
+++ b/docs_src/request_form_models/tutorial001_an_py39.py
@@ -0,0 +1,16 @@
+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
diff --git a/docs_src/request_form_models/tutorial002.py b/docs_src/request_form_models/tutorial002.py
new file mode 100644
index 000000000..59b329e8d
--- /dev/null
+++ b/docs_src/request_form_models/tutorial002.py
@@ -0,0 +1,15 @@
+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
diff --git a/docs_src/request_form_models/tutorial002_an.py b/docs_src/request_form_models/tutorial002_an.py
new file mode 100644
index 000000000..bcb022795
--- /dev/null
+++ b/docs_src/request_form_models/tutorial002_an.py
@@ -0,0 +1,16 @@
+from fastapi import FastAPI, Form
+from pydantic import BaseModel
+from typing_extensions import Annotated
+
+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
diff --git a/docs_src/request_form_models/tutorial002_an_py39.py b/docs_src/request_form_models/tutorial002_an_py39.py
new file mode 100644
index 000000000..3004e0852
--- /dev/null
+++ b/docs_src/request_form_models/tutorial002_an_py39.py
@@ -0,0 +1,17 @@
+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
diff --git a/docs_src/request_form_models/tutorial002_pv1.py b/docs_src/request_form_models/tutorial002_pv1.py
new file mode 100644
index 000000000..d5f7db2a6
--- /dev/null
+++ b/docs_src/request_form_models/tutorial002_pv1.py
@@ -0,0 +1,17 @@
+from fastapi import FastAPI, Form
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class FormData(BaseModel):
+ username: str
+ password: str
+
+ class Config:
+ extra = "forbid"
+
+
+@app.post("/login/")
+async def login(data: FormData = Form()):
+ return data
diff --git a/docs_src/request_form_models/tutorial002_pv1_an.py b/docs_src/request_form_models/tutorial002_pv1_an.py
new file mode 100644
index 000000000..fe9dbc344
--- /dev/null
+++ b/docs_src/request_form_models/tutorial002_pv1_an.py
@@ -0,0 +1,18 @@
+from fastapi import FastAPI, Form
+from pydantic import BaseModel
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+class FormData(BaseModel):
+ username: str
+ password: str
+
+ class Config:
+ extra = "forbid"
+
+
+@app.post("/login/")
+async def login(data: Annotated[FormData, Form()]):
+ return data
diff --git a/docs_src/request_form_models/tutorial002_pv1_an_py39.py b/docs_src/request_form_models/tutorial002_pv1_an_py39.py
new file mode 100644
index 000000000..942d5d411
--- /dev/null
+++ b/docs_src/request_form_models/tutorial002_pv1_an_py39.py
@@ -0,0 +1,19 @@
+from typing import Annotated
+
+from fastapi import FastAPI, Form
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class FormData(BaseModel):
+ username: str
+ password: str
+
+ class Config:
+ extra = "forbid"
+
+
+@app.post("/login/")
+async def login(data: Annotated[FormData, Form()]):
+ return data
diff --git a/fastapi/__init__.py b/fastapi/__init__.py
index 0b79d45ef..7dd74c28f 100644
--- a/fastapi/__init__.py
+++ b/fastapi/__init__.py
@@ -1,6 +1,6 @@
"""FastAPI framework, high performance, easy to learn, fast to code, ready for production"""
-__version__ = "0.112.1"
+__version__ = "0.115.0"
from starlette import status as status
diff --git a/fastapi/_compat.py b/fastapi/_compat.py
index 06b847b4f..4b07b44fa 100644
--- a/fastapi/_compat.py
+++ b/fastapi/_compat.py
@@ -2,6 +2,7 @@ from collections import deque
from copy import copy
from dataclasses import dataclass, is_dataclass
from enum import Enum
+from functools import lru_cache
from typing import (
Any,
Callable,
@@ -279,6 +280,12 @@ if PYDANTIC_V2:
BodyModel: Type[BaseModel] = create_model(model_name, **field_params) # type: ignore[call-overload]
return BodyModel
+ def get_model_fields(model: Type[BaseModel]) -> List[ModelField]:
+ return [
+ ModelField(field_info=field_info, name=name)
+ for name, field_info in model.model_fields.items()
+ ]
+
else:
from fastapi.openapi.constants import REF_PREFIX as REF_PREFIX
from pydantic import AnyUrl as Url # noqa: F401
@@ -513,6 +520,9 @@ else:
BodyModel.__fields__[f.name] = f # type: ignore[index]
return BodyModel
+ def get_model_fields(model: Type[BaseModel]) -> List[ModelField]:
+ return list(model.__fields__.values()) # type: ignore[attr-defined]
+
def _regenerate_error_with_loc(
*, errors: Sequence[Any], loc_prefix: Tuple[Union[str, int], ...]
@@ -532,6 +542,12 @@ def _annotation_is_sequence(annotation: Union[Type[Any], None]) -> bool:
def field_annotation_is_sequence(annotation: Union[Type[Any], None]) -> bool:
+ origin = get_origin(annotation)
+ if origin is Union or origin is UnionType:
+ for arg in get_args(annotation):
+ if field_annotation_is_sequence(arg):
+ return True
+ return False
return _annotation_is_sequence(annotation) or _annotation_is_sequence(
get_origin(annotation)
)
@@ -634,3 +650,8 @@ def is_uploadfile_sequence_annotation(annotation: Any) -> bool:
is_uploadfile_or_nonable_uploadfile_annotation(sub_annotation)
for sub_annotation in get_args(annotation)
)
+
+
+@lru_cache
+def get_cached_model_fields(model: Type[BaseModel]) -> List[ModelField]:
+ return get_model_fields(model)
diff --git a/fastapi/dependencies/models.py b/fastapi/dependencies/models.py
index 61ef00638..418c11725 100644
--- a/fastapi/dependencies/models.py
+++ b/fastapi/dependencies/models.py
@@ -1,58 +1,37 @@
-from typing import Any, Callable, List, Optional, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Callable, List, Optional, Sequence, Tuple
from fastapi._compat import ModelField
from fastapi.security.base import SecurityBase
+@dataclass
class SecurityRequirement:
- def __init__(
- self, security_scheme: SecurityBase, scopes: Optional[Sequence[str]] = None
- ):
- self.security_scheme = security_scheme
- self.scopes = scopes
+ security_scheme: SecurityBase
+ scopes: Optional[Sequence[str]] = None
+@dataclass
class Dependant:
- def __init__(
- self,
- *,
- path_params: Optional[List[ModelField]] = None,
- query_params: Optional[List[ModelField]] = None,
- header_params: Optional[List[ModelField]] = None,
- cookie_params: Optional[List[ModelField]] = None,
- body_params: Optional[List[ModelField]] = None,
- dependencies: Optional[List["Dependant"]] = None,
- security_schemes: Optional[List[SecurityRequirement]] = None,
- name: Optional[str] = None,
- call: Optional[Callable[..., Any]] = None,
- request_param_name: Optional[str] = None,
- websocket_param_name: Optional[str] = None,
- http_connection_param_name: Optional[str] = None,
- response_param_name: Optional[str] = None,
- background_tasks_param_name: Optional[str] = None,
- security_scopes_param_name: Optional[str] = None,
- security_scopes: Optional[List[str]] = None,
- use_cache: bool = True,
- path: Optional[str] = None,
- ) -> None:
- self.path_params = path_params or []
- self.query_params = query_params or []
- self.header_params = header_params or []
- self.cookie_params = cookie_params or []
- self.body_params = body_params or []
- self.dependencies = dependencies or []
- self.security_requirements = security_schemes or []
- self.request_param_name = request_param_name
- self.websocket_param_name = websocket_param_name
- self.http_connection_param_name = http_connection_param_name
- self.response_param_name = response_param_name
- self.background_tasks_param_name = background_tasks_param_name
- self.security_scopes = security_scopes
- self.security_scopes_param_name = security_scopes_param_name
- self.name = name
- self.call = call
- self.use_cache = use_cache
- # Store the path to be able to re-generate a dependable from it in overrides
- self.path = path
- # Save the cache key at creation to optimize performance
+ path_params: List[ModelField] = field(default_factory=list)
+ query_params: List[ModelField] = field(default_factory=list)
+ header_params: List[ModelField] = field(default_factory=list)
+ cookie_params: List[ModelField] = field(default_factory=list)
+ body_params: List[ModelField] = field(default_factory=list)
+ dependencies: List["Dependant"] = field(default_factory=list)
+ security_requirements: List[SecurityRequirement] = field(default_factory=list)
+ name: Optional[str] = None
+ call: Optional[Callable[..., Any]] = None
+ request_param_name: Optional[str] = None
+ websocket_param_name: Optional[str] = None
+ http_connection_param_name: Optional[str] = None
+ response_param_name: Optional[str] = None
+ background_tasks_param_name: Optional[str] = None
+ security_scopes_param_name: Optional[str] = None
+ security_scopes: Optional[List[str]] = None
+ use_cache: bool = True
+ path: Optional[str] = None
+ cache_key: Tuple[Optional[Callable[..., Any]], Tuple[str, ...]] = field(init=False)
+
+ def __post_init__(self) -> None:
self.cache_key = (self.call, tuple(sorted(set(self.security_scopes or []))))
diff --git a/fastapi/dependencies/utils.py b/fastapi/dependencies/utils.py
index 3e8e7b410..5cebbf00f 100644
--- a/fastapi/dependencies/utils.py
+++ b/fastapi/dependencies/utils.py
@@ -1,6 +1,7 @@
import inspect
from contextlib import AsyncExitStack, contextmanager
from copy import copy, deepcopy
+from dataclasses import dataclass
from typing import (
Any,
Callable,
@@ -31,6 +32,7 @@ from fastapi._compat import (
evaluate_forwardref,
field_annotation_is_scalar,
get_annotation_from_field_info,
+ get_cached_model_fields,
get_missing_field_error,
is_bytes_field,
is_bytes_sequence_field,
@@ -54,11 +56,18 @@ from fastapi.logger import logger
from fastapi.security.base import SecurityBase
from fastapi.security.oauth2 import OAuth2, SecurityScopes
from fastapi.security.open_id_connect_url import OpenIdConnect
-from fastapi.utils import create_response_field, get_path_param_names
+from fastapi.utils import create_model_field, get_path_param_names
+from pydantic import BaseModel
from pydantic.fields import FieldInfo
from starlette.background import BackgroundTasks as StarletteBackgroundTasks
from starlette.concurrency import run_in_threadpool
-from starlette.datastructures import FormData, Headers, QueryParams, UploadFile
+from starlette.datastructures import (
+ FormData,
+ Headers,
+ ImmutableMultiDict,
+ QueryParams,
+ UploadFile,
+)
from starlette.requests import HTTPConnection, Request
from starlette.responses import Response
from starlette.websockets import WebSocket
@@ -79,25 +88,23 @@ multipart_incorrect_install_error = (
)
-def check_file_field(field: ModelField) -> None:
- field_info = field.field_info
- if isinstance(field_info, params.Form):
- try:
- # __version__ is available in both multiparts, and can be mocked
- from multipart import __version__ # type: ignore
+def ensure_multipart_is_installed() -> None:
+ try:
+ # __version__ is available in both multiparts, and can be mocked
+ from multipart import __version__ # type: ignore
- assert __version__
- try:
- # parse_options_header is only available in the right multipart
- from multipart.multipart import parse_options_header # type: ignore
+ assert __version__
+ try:
+ # parse_options_header is only available in the right multipart
+ from multipart.multipart import parse_options_header # type: ignore
- assert parse_options_header
- except ImportError:
- logger.error(multipart_incorrect_install_error)
- raise RuntimeError(multipart_incorrect_install_error) from None
+ assert parse_options_header
except ImportError:
- logger.error(multipart_not_installed_error)
- raise RuntimeError(multipart_not_installed_error) from None
+ logger.error(multipart_incorrect_install_error)
+ raise RuntimeError(multipart_incorrect_install_error) from None
+ except ImportError:
+ logger.error(multipart_not_installed_error)
+ raise RuntimeError(multipart_not_installed_error) from None
def get_param_sub_dependant(
@@ -175,7 +182,7 @@ def get_flat_dependant(
header_params=dependant.header_params.copy(),
cookie_params=dependant.cookie_params.copy(),
body_params=dependant.body_params.copy(),
- security_schemes=dependant.security_requirements.copy(),
+ security_requirements=dependant.security_requirements.copy(),
use_cache=dependant.use_cache,
path=dependant.path,
)
@@ -194,14 +201,23 @@ def get_flat_dependant(
return flat_dependant
+def _get_flat_fields_from_params(fields: List[ModelField]) -> List[ModelField]:
+ if not fields:
+ return fields
+ first_field = fields[0]
+ if len(fields) == 1 and lenient_issubclass(first_field.type_, BaseModel):
+ fields_to_extract = get_cached_model_fields(first_field.type_)
+ return fields_to_extract
+ return fields
+
+
def get_flat_params(dependant: Dependant) -> List[ModelField]:
flat_dependant = get_flat_dependant(dependant, skip_repeats=True)
- return (
- flat_dependant.path_params
- + flat_dependant.query_params
- + flat_dependant.header_params
- + flat_dependant.cookie_params
- )
+ path_params = _get_flat_fields_from_params(flat_dependant.path_params)
+ query_params = _get_flat_fields_from_params(flat_dependant.query_params)
+ header_params = _get_flat_fields_from_params(flat_dependant.header_params)
+ cookie_params = _get_flat_fields_from_params(flat_dependant.cookie_params)
+ return path_params + query_params + header_params + cookie_params
def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
@@ -258,16 +274,16 @@ def get_dependant(
)
for param_name, param in signature_params.items():
is_path_param = param_name in path_param_names
- type_annotation, depends, param_field = analyze_param(
+ param_details = analyze_param(
param_name=param_name,
annotation=param.annotation,
value=param.default,
is_path_param=is_path_param,
)
- if depends is not None:
+ if param_details.depends is not None:
sub_dependant = get_param_sub_dependant(
param_name=param_name,
- depends=depends,
+ depends=param_details.depends,
path=path,
security_scopes=security_scopes,
)
@@ -275,18 +291,18 @@ def get_dependant(
continue
if add_non_field_param_to_dependency(
param_name=param_name,
- type_annotation=type_annotation,
+ type_annotation=param_details.type_annotation,
dependant=dependant,
):
assert (
- param_field is None
+ param_details.field is None
), f"Cannot specify multiple FastAPI annotations for {param_name!r}"
continue
- assert param_field is not None
- if is_body_param(param_field=param_field, is_path_param=is_path_param):
- dependant.body_params.append(param_field)
+ assert param_details.field is not None
+ if isinstance(param_details.field.field_info, params.Body):
+ dependant.body_params.append(param_details.field)
else:
- add_param_to_fields(field=param_field, dependant=dependant)
+ add_param_to_fields(field=param_details.field, dependant=dependant)
return dependant
@@ -314,13 +330,20 @@ def add_non_field_param_to_dependency(
return None
+@dataclass
+class ParamDetails:
+ type_annotation: Any
+ depends: Optional[params.Depends]
+ field: Optional[ModelField]
+
+
def analyze_param(
*,
param_name: str,
annotation: Any,
value: Any,
is_path_param: bool,
-) -> Tuple[Any, Optional[params.Depends], Optional[ModelField]]:
+) -> ParamDetails:
field_info = None
depends = None
type_annotation: Any = Any
@@ -328,6 +351,7 @@ def analyze_param(
if annotation is not inspect.Signature.empty:
use_annotation = annotation
type_annotation = annotation
+ # Extract Annotated info
if get_origin(use_annotation) is Annotated:
annotated_args = get_args(annotation)
type_annotation = annotated_args[0]
@@ -347,6 +371,7 @@ def analyze_param(
)
else:
fastapi_annotation = None
+ # Set default for Annotated FieldInfo
if isinstance(fastapi_annotation, FieldInfo):
# Copy `field_info` because we mutate `field_info.default` below.
field_info = copy_field_info(
@@ -361,9 +386,10 @@ def analyze_param(
field_info.default = value
else:
field_info.default = Required
+ # Get Annotated Depends
elif isinstance(fastapi_annotation, params.Depends):
depends = fastapi_annotation
-
+ # Get Depends from default value
if isinstance(value, params.Depends):
assert depends is None, (
"Cannot specify `Depends` in `Annotated` and default value"
@@ -374,6 +400,7 @@ def analyze_param(
f" default value together for {param_name!r}"
)
depends = value
+ # Get FieldInfo from default value
elif isinstance(value, FieldInfo):
assert field_info is None, (
"Cannot specify FastAPI annotations in `Annotated` and default value"
@@ -383,11 +410,13 @@ def analyze_param(
if PYDANTIC_V2:
field_info.annotation = type_annotation
+ # Get Depends from type annotation
if depends is not None and depends.dependency is None:
# Copy `depends` before mutating it
depends = copy(depends)
depends.dependency = type_annotation
+ # Handle non-param type annotations like Request
if lenient_issubclass(
type_annotation,
(
@@ -403,6 +432,7 @@ def analyze_param(
assert (
field_info is None
), f"Cannot specify FastAPI annotation for type {type_annotation!r}"
+ # Handle default assignations, neither field_info nor depends was not found in Annotated nor default value
elif field_info is None and depends is None:
default_value = value if value is not inspect.Signature.empty else Required
if is_path_param:
@@ -420,7 +450,9 @@ def analyze_param(
field_info = params.Query(annotation=use_annotation, default=default_value)
field = None
+ # It's a field_info, not a dependency
if field_info is not None:
+ # Handle field_info.in_
if is_path_param:
assert isinstance(field_info, params.Path), (
f"Cannot use `{field_info.__class__.__name__}` for path param"
@@ -436,12 +468,14 @@ def analyze_param(
field_info,
param_name,
)
+ if isinstance(field_info, params.Form):
+ ensure_multipart_is_installed()
if not field_info.alias and getattr(field_info, "convert_underscores", None):
alias = param_name.replace("_", "-")
else:
alias = field_info.alias or param_name
field_info.alias = alias
- field = create_response_field(
+ field = create_model_field(
name=param_name,
type_=use_annotation_from_field_info,
default=field_info.default,
@@ -449,27 +483,22 @@ def analyze_param(
required=field_info.default in (Required, Undefined),
field_info=field_info,
)
+ if is_path_param:
+ assert is_scalar_field(
+ field=field
+ ), "Path params must be of one of the supported types"
+ elif isinstance(field_info, params.Query):
+ assert (
+ is_scalar_field(field)
+ or is_scalar_sequence_field(field)
+ or (
+ lenient_issubclass(field.type_, BaseModel)
+ # For Pydantic v1
+ and getattr(field, "shape", 1) == 1
+ )
+ )
- return type_annotation, depends, field
-
-
-def is_body_param(*, param_field: ModelField, is_path_param: bool) -> bool:
- if is_path_param:
- assert is_scalar_field(
- field=param_field
- ), "Path params must be of one of the supported types"
- return False
- elif is_scalar_field(field=param_field):
- return False
- elif isinstance(
- param_field.field_info, (params.Query, params.Header)
- ) and is_scalar_sequence_field(param_field):
- return False
- else:
- assert isinstance(
- param_field.field_info, params.Body
- ), f"Param: {param_field.name} can only be a request body, using Body()"
- return True
+ return ParamDetails(type_annotation=type_annotation, depends=depends, field=field)
def add_param_to_fields(*, field: ModelField, dependant: Dependant) -> None:
@@ -521,6 +550,15 @@ async def solve_generator(
return await stack.enter_async_context(cm)
+@dataclass
+class SolvedDependency:
+ values: Dict[str, Any]
+ errors: List[Any]
+ background_tasks: Optional[StarletteBackgroundTasks]
+ response: Response
+ dependency_cache: Dict[Tuple[Callable[..., Any], Tuple[str]], Any]
+
+
async def solve_dependencies(
*,
request: Union[Request, WebSocket],
@@ -531,13 +569,8 @@ async def solve_dependencies(
dependency_overrides_provider: Optional[Any] = None,
dependency_cache: Optional[Dict[Tuple[Callable[..., Any], Tuple[str]], Any]] = None,
async_exit_stack: AsyncExitStack,
-) -> Tuple[
- Dict[str, Any],
- List[Any],
- Optional[StarletteBackgroundTasks],
- Response,
- Dict[Tuple[Callable[..., Any], Tuple[str]], Any],
-]:
+ embed_body_fields: bool,
+) -> SolvedDependency:
values: Dict[str, Any] = {}
errors: List[Any] = []
if response is None:
@@ -578,28 +611,23 @@ async def solve_dependencies(
dependency_overrides_provider=dependency_overrides_provider,
dependency_cache=dependency_cache,
async_exit_stack=async_exit_stack,
+ embed_body_fields=embed_body_fields,
)
- (
- sub_values,
- sub_errors,
- background_tasks,
- _, # the subdependency returns the same response we have
- sub_dependency_cache,
- ) = solved_result
- dependency_cache.update(sub_dependency_cache)
- if sub_errors:
- errors.extend(sub_errors)
+ background_tasks = solved_result.background_tasks
+ dependency_cache.update(solved_result.dependency_cache)
+ if solved_result.errors:
+ errors.extend(solved_result.errors)
continue
if sub_dependant.use_cache and sub_dependant.cache_key in dependency_cache:
solved = dependency_cache[sub_dependant.cache_key]
elif is_gen_callable(call) or is_async_gen_callable(call):
solved = await solve_generator(
- call=call, stack=async_exit_stack, sub_values=sub_values
+ call=call, stack=async_exit_stack, sub_values=solved_result.values
)
elif is_coroutine_callable(call):
- solved = await call(**sub_values)
+ solved = await call(**solved_result.values)
else:
- solved = await run_in_threadpool(call, **sub_values)
+ solved = await run_in_threadpool(call, **solved_result.values)
if sub_dependant.name is not None:
values[sub_dependant.name] = solved
if sub_dependant.cache_key not in dependency_cache:
@@ -626,7 +654,9 @@ async def solve_dependencies(
body_values,
body_errors,
) = await request_body_to_args( # body_params checked above
- required_params=dependant.body_params, received_body=body
+ body_fields=dependant.body_params,
+ received_body=body,
+ embed_body_fields=embed_body_fields,
)
values.update(body_values)
errors.extend(body_errors)
@@ -646,142 +676,257 @@ async def solve_dependencies(
values[dependant.security_scopes_param_name] = SecurityScopes(
scopes=dependant.security_scopes
)
- return values, errors, background_tasks, response, dependency_cache
+ return SolvedDependency(
+ values=values,
+ errors=errors,
+ background_tasks=background_tasks,
+ response=response,
+ dependency_cache=dependency_cache,
+ )
+
+
+def _validate_value_with_model_field(
+ *, field: ModelField, value: Any, values: Dict[str, Any], loc: Tuple[str, ...]
+) -> Tuple[Any, List[Any]]:
+ if value is None:
+ if field.required:
+ return None, [get_missing_field_error(loc=loc)]
+ else:
+ return deepcopy(field.default), []
+ v_, errors_ = field.validate(value, values, loc=loc)
+ if isinstance(errors_, ErrorWrapper):
+ return None, [errors_]
+ elif isinstance(errors_, list):
+ new_errors = _regenerate_error_with_loc(errors=errors_, loc_prefix=())
+ return None, new_errors
+ else:
+ return v_, []
+
+
+def _get_multidict_value(
+ field: ModelField, values: Mapping[str, Any], alias: Union[str, None] = None
+) -> Any:
+ alias = alias or field.alias
+ if is_sequence_field(field) and isinstance(values, (ImmutableMultiDict, Headers)):
+ value = values.getlist(alias)
+ else:
+ value = values.get(alias, None)
+ if (
+ value is None
+ or (
+ isinstance(field.field_info, params.Form)
+ and isinstance(value, str) # For type checks
+ and value == ""
+ )
+ or (is_sequence_field(field) and len(value) == 0)
+ ):
+ if field.required:
+ return
+ else:
+ return deepcopy(field.default)
+ return value
def request_params_to_args(
- required_params: Sequence[ModelField],
+ fields: Sequence[ModelField],
received_params: Union[Mapping[str, Any], QueryParams, Headers],
) -> Tuple[Dict[str, Any], List[Any]]:
- values = {}
- errors = []
- for field in required_params:
- if is_scalar_sequence_field(field) and isinstance(
- received_params, (QueryParams, Headers)
- ):
- value = received_params.getlist(field.alias) or field.default
- else:
- value = received_params.get(field.alias)
+ values: Dict[str, Any] = {}
+ errors: List[Dict[str, Any]] = []
+
+ if not fields:
+ return values, errors
+
+ first_field = fields[0]
+ fields_to_extract = fields
+ single_not_embedded_field = False
+ if len(fields) == 1 and lenient_issubclass(first_field.type_, BaseModel):
+ fields_to_extract = get_cached_model_fields(first_field.type_)
+ single_not_embedded_field = True
+
+ params_to_process: Dict[str, Any] = {}
+
+ processed_keys = set()
+
+ for field in fields_to_extract:
+ alias = None
+ if isinstance(received_params, Headers):
+ # Handle fields extracted from a Pydantic Model for a header, each field
+ # doesn't have a FieldInfo of type Header with the default convert_underscores=True
+ convert_underscores = getattr(field.field_info, "convert_underscores", True)
+ if convert_underscores:
+ alias = (
+ field.alias
+ if field.alias != field.name
+ else field.name.replace("_", "-")
+ )
+ value = _get_multidict_value(field, received_params, alias=alias)
+ if value is not None:
+ params_to_process[field.name] = value
+ processed_keys.add(alias or field.alias)
+ processed_keys.add(field.name)
+
+ for key, value in received_params.items():
+ if key not in processed_keys:
+ params_to_process[key] = value
+
+ if single_not_embedded_field:
+ field_info = first_field.field_info
+ assert isinstance(
+ field_info, params.Param
+ ), "Params must be subclasses of Param"
+ loc: Tuple[str, ...] = (field_info.in_.value,)
+ v_, errors_ = _validate_value_with_model_field(
+ field=first_field, value=params_to_process, values=values, loc=loc
+ )
+ return {first_field.name: v_}, errors_
+
+ for field in fields:
+ value = _get_multidict_value(field, received_params)
field_info = field.field_info
assert isinstance(
field_info, params.Param
), "Params must be subclasses of Param"
loc = (field_info.in_.value, field.alias)
- if value is None:
- if field.required:
- errors.append(get_missing_field_error(loc=loc))
- else:
- values[field.name] = deepcopy(field.default)
- continue
- v_, errors_ = field.validate(value, values, loc=loc)
- if isinstance(errors_, ErrorWrapper):
- errors.append(errors_)
- elif isinstance(errors_, list):
- new_errors = _regenerate_error_with_loc(errors=errors_, loc_prefix=())
- errors.extend(new_errors)
+ v_, errors_ = _validate_value_with_model_field(
+ field=field, value=value, values=values, loc=loc
+ )
+ if errors_:
+ errors.extend(errors_)
else:
values[field.name] = v_
return values, errors
+def _should_embed_body_fields(fields: List[ModelField]) -> bool:
+ if not fields:
+ return False
+ # More than one dependency could have the same field, it would show up as multiple
+ # fields but it's the same one, so count them by name
+ body_param_names_set = {field.name for field in fields}
+ # A top level field has to be a single field, not multiple
+ if len(body_param_names_set) > 1:
+ return True
+ first_field = fields[0]
+ # If it explicitly specifies it is embedded, it has to be embedded
+ if getattr(first_field.field_info, "embed", None):
+ return True
+ # If it's a Form (or File) field, it has to be a BaseModel to be top level
+ # otherwise it has to be embedded, so that the key value pair can be extracted
+ if isinstance(first_field.field_info, params.Form) and not lenient_issubclass(
+ first_field.type_, BaseModel
+ ):
+ return True
+ return False
+
+
+async def _extract_form_body(
+ body_fields: List[ModelField],
+ received_body: FormData,
+) -> Dict[str, Any]:
+ values = {}
+ first_field = body_fields[0]
+ first_field_info = first_field.field_info
+
+ for field in body_fields:
+ value = _get_multidict_value(field, received_body)
+ if (
+ isinstance(first_field_info, params.File)
+ and is_bytes_field(field)
+ and isinstance(value, UploadFile)
+ ):
+ value = await value.read()
+ elif (
+ is_bytes_sequence_field(field)
+ and isinstance(first_field_info, params.File)
+ and value_is_sequence(value)
+ ):
+ # For types
+ assert isinstance(value, sequence_types) # type: ignore[arg-type]
+ results: List[Union[bytes, str]] = []
+
+ async def process_fn(
+ fn: Callable[[], Coroutine[Any, Any, Any]],
+ ) -> None:
+ result = await fn()
+ results.append(result) # noqa: B023
+
+ async with anyio.create_task_group() as tg:
+ for sub_value in value:
+ tg.start_soon(process_fn, sub_value.read)
+ value = serialize_sequence_value(field=field, value=results)
+ if value is not None:
+ values[field.alias] = value
+ for key, value in received_body.items():
+ if key not in values:
+ values[key] = value
+ return values
+
+
async def request_body_to_args(
- required_params: List[ModelField],
+ body_fields: List[ModelField],
received_body: Optional[Union[Dict[str, Any], FormData]],
+ embed_body_fields: bool,
) -> Tuple[Dict[str, Any], List[Dict[str, Any]]]:
- values = {}
+ values: Dict[str, Any] = {}
errors: List[Dict[str, Any]] = []
- if required_params:
- field = required_params[0]
- field_info = field.field_info
- embed = getattr(field_info, "embed", None)
- field_alias_omitted = len(required_params) == 1 and not embed
- if field_alias_omitted:
- received_body = {field.alias: received_body}
-
- for field in required_params:
- loc: Tuple[str, ...]
- if field_alias_omitted:
- loc = ("body",)
- else:
- loc = ("body", field.alias)
-
- value: Optional[Any] = None
- if received_body is not None:
- if (is_sequence_field(field)) and isinstance(received_body, FormData):
- value = received_body.getlist(field.alias)
- else:
- try:
- value = received_body.get(field.alias)
- except AttributeError:
- errors.append(get_missing_field_error(loc))
- continue
- if (
- value is None
- or (isinstance(field_info, params.Form) and value == "")
- or (
- isinstance(field_info, params.Form)
- and is_sequence_field(field)
- and len(value) == 0
- )
- ):
- if field.required:
- errors.append(get_missing_field_error(loc))
- else:
- values[field.name] = deepcopy(field.default)
+ assert body_fields, "request_body_to_args() should be called with fields"
+ single_not_embedded_field = len(body_fields) == 1 and not embed_body_fields
+ first_field = body_fields[0]
+ body_to_process = received_body
+
+ fields_to_extract: List[ModelField] = body_fields
+
+ if single_not_embedded_field and lenient_issubclass(first_field.type_, BaseModel):
+ fields_to_extract = get_cached_model_fields(first_field.type_)
+
+ if isinstance(received_body, FormData):
+ body_to_process = await _extract_form_body(fields_to_extract, received_body)
+
+ if single_not_embedded_field:
+ loc: Tuple[str, ...] = ("body",)
+ v_, errors_ = _validate_value_with_model_field(
+ field=first_field, value=body_to_process, values=values, loc=loc
+ )
+ return {first_field.name: v_}, errors_
+ for field in body_fields:
+ loc = ("body", field.alias)
+ value: Optional[Any] = None
+ if body_to_process is not None:
+ try:
+ value = body_to_process.get(field.alias)
+ # If the received body is a list, not a dict
+ except AttributeError:
+ errors.append(get_missing_field_error(loc))
continue
- if (
- isinstance(field_info, params.File)
- and is_bytes_field(field)
- and isinstance(value, UploadFile)
- ):
- value = await value.read()
- elif (
- is_bytes_sequence_field(field)
- and isinstance(field_info, params.File)
- and value_is_sequence(value)
- ):
- # For types
- assert isinstance(value, sequence_types) # type: ignore[arg-type]
- results: List[Union[bytes, str]] = []
-
- async def process_fn(
- fn: Callable[[], Coroutine[Any, Any, Any]],
- ) -> None:
- result = await fn()
- results.append(result) # noqa: B023
-
- async with anyio.create_task_group() as tg:
- for sub_value in value:
- tg.start_soon(process_fn, sub_value.read)
- value = serialize_sequence_value(field=field, value=results)
-
- v_, errors_ = field.validate(value, values, loc=loc)
-
- if isinstance(errors_, list):
- errors.extend(errors_)
- elif errors_:
- errors.append(errors_)
- else:
- values[field.name] = v_
+ v_, errors_ = _validate_value_with_model_field(
+ field=field, value=value, values=values, loc=loc
+ )
+ if errors_:
+ errors.extend(errors_)
+ else:
+ values[field.name] = v_
return values, errors
-def get_body_field(*, dependant: Dependant, name: str) -> Optional[ModelField]:
- flat_dependant = get_flat_dependant(dependant)
+def get_body_field(
+ *, flat_dependant: Dependant, name: str, embed_body_fields: bool
+) -> Optional[ModelField]:
+ """
+ Get a ModelField representing the request body for a path operation, combining
+ all body parameters into a single field if necessary.
+
+ Used to check if it's form data (with `isinstance(body_field, params.Form)`)
+ or JSON and to generate the JSON Schema for a request body.
+
+ This is **not** used to validate/parse the request body, that's done with each
+ individual body parameter.
+ """
if not flat_dependant.body_params:
return None
first_param = flat_dependant.body_params[0]
- field_info = first_param.field_info
- embed = getattr(field_info, "embed", None)
- body_param_names_set = {param.name for param in flat_dependant.body_params}
- if len(body_param_names_set) == 1 and not embed:
- check_file_field(first_param)
+ if not embed_body_fields:
return first_param
- # If one field requires to embed, all have to be embedded
- # in case a sub-dependency is evaluated with a single unique body field
- # That is combined (embedded) with other body fields
- for param in flat_dependant.body_params:
- setattr(param.field_info, "embed", True) # noqa: B010
model_name = "Body_" + name
BodyModel = create_body_model(
fields=flat_dependant.body_params, model_name=model_name
@@ -807,12 +952,11 @@ def get_body_field(*, dependant: Dependant, name: str) -> Optional[ModelField]:
]
if len(set(body_param_media_types)) == 1:
BodyFieldInfo_kwargs["media_type"] = body_param_media_types[0]
- final_field = create_response_field(
+ final_field = create_model_field(
name="body",
type_=BodyModel,
required=required,
alias="body",
field_info=BodyFieldInfo(**BodyFieldInfo_kwargs),
)
- check_file_field(final_field)
return final_field
diff --git a/fastapi/openapi/utils.py b/fastapi/openapi/utils.py
index 79ad9f83f..947eca948 100644
--- a/fastapi/openapi/utils.py
+++ b/fastapi/openapi/utils.py
@@ -16,11 +16,15 @@ from fastapi._compat import (
)
from fastapi.datastructures import DefaultPlaceholder
from fastapi.dependencies.models import Dependant
-from fastapi.dependencies.utils import get_flat_dependant, get_flat_params
+from fastapi.dependencies.utils import (
+ _get_flat_fields_from_params,
+ get_flat_dependant,
+ get_flat_params,
+)
from fastapi.encoders import jsonable_encoder
from fastapi.openapi.constants import METHODS_WITH_BODY, REF_PREFIX, REF_TEMPLATE
from fastapi.openapi.models import OpenAPI
-from fastapi.params import Body, Param
+from fastapi.params import Body, ParamTypes
from fastapi.responses import Response
from fastapi.types import ModelNameMap
from fastapi.utils import (
@@ -87,9 +91,9 @@ def get_openapi_security_definitions(
return security_definitions, operation_security
-def get_openapi_operation_parameters(
+def _get_openapi_operation_parameters(
*,
- all_route_params: Sequence[ModelField],
+ dependant: Dependant,
schema_generator: GenerateJsonSchema,
model_name_map: ModelNameMap,
field_mapping: Dict[
@@ -98,33 +102,47 @@ def get_openapi_operation_parameters(
separate_input_output_schemas: bool = True,
) -> List[Dict[str, Any]]:
parameters = []
- for param in all_route_params:
- field_info = param.field_info
- field_info = cast(Param, field_info)
- if not field_info.include_in_schema:
- continue
- param_schema = get_schema_from_model_field(
- field=param,
- schema_generator=schema_generator,
- model_name_map=model_name_map,
- field_mapping=field_mapping,
- separate_input_output_schemas=separate_input_output_schemas,
- )
- parameter = {
- "name": param.alias,
- "in": field_info.in_.value,
- "required": param.required,
- "schema": param_schema,
- }
- if field_info.description:
- parameter["description"] = field_info.description
- if field_info.openapi_examples:
- parameter["examples"] = jsonable_encoder(field_info.openapi_examples)
- elif field_info.example != Undefined:
- parameter["example"] = jsonable_encoder(field_info.example)
- if field_info.deprecated:
- parameter["deprecated"] = True
- parameters.append(parameter)
+ flat_dependant = get_flat_dependant(dependant, skip_repeats=True)
+ path_params = _get_flat_fields_from_params(flat_dependant.path_params)
+ query_params = _get_flat_fields_from_params(flat_dependant.query_params)
+ header_params = _get_flat_fields_from_params(flat_dependant.header_params)
+ cookie_params = _get_flat_fields_from_params(flat_dependant.cookie_params)
+ parameter_groups = [
+ (ParamTypes.path, path_params),
+ (ParamTypes.query, query_params),
+ (ParamTypes.header, header_params),
+ (ParamTypes.cookie, cookie_params),
+ ]
+ for param_type, param_group in parameter_groups:
+ for param in param_group:
+ field_info = param.field_info
+ # field_info = cast(Param, field_info)
+ if not getattr(field_info, "include_in_schema", True):
+ continue
+ param_schema = get_schema_from_model_field(
+ field=param,
+ schema_generator=schema_generator,
+ model_name_map=model_name_map,
+ field_mapping=field_mapping,
+ separate_input_output_schemas=separate_input_output_schemas,
+ )
+ parameter = {
+ "name": param.alias,
+ "in": param_type.value,
+ "required": param.required,
+ "schema": param_schema,
+ }
+ if field_info.description:
+ parameter["description"] = field_info.description
+ openapi_examples = getattr(field_info, "openapi_examples", None)
+ example = getattr(field_info, "example", None)
+ if openapi_examples:
+ parameter["examples"] = jsonable_encoder(openapi_examples)
+ elif example != Undefined:
+ parameter["example"] = jsonable_encoder(example)
+ if getattr(field_info, "deprecated", None):
+ parameter["deprecated"] = True
+ parameters.append(parameter)
return parameters
@@ -247,9 +265,8 @@ def get_openapi_path(
operation.setdefault("security", []).extend(operation_security)
if security_definitions:
security_schemes.update(security_definitions)
- all_route_params = get_flat_params(route.dependant)
- operation_parameters = get_openapi_operation_parameters(
- all_route_params=all_route_params,
+ operation_parameters = _get_openapi_operation_parameters(
+ dependant=route.dependant,
schema_generator=schema_generator,
model_name_map=model_name_map,
field_mapping=field_mapping,
@@ -379,6 +396,7 @@ def get_openapi_path(
deep_dict_update(openapi_response, process_response)
openapi_response["description"] = description
http422 = str(HTTP_422_UNPROCESSABLE_ENTITY)
+ all_route_params = get_flat_params(route.dependant)
if (all_route_params or route.body_field) and not any(
status in operation["responses"]
for status in [http422, "4XX", "default"]
diff --git a/fastapi/param_functions.py b/fastapi/param_functions.py
index 0d5f27af4..7ddaace25 100644
--- a/fastapi/param_functions.py
+++ b/fastapi/param_functions.py
@@ -1282,7 +1282,7 @@ def Body( # noqa: N802
),
] = _Unset,
embed: Annotated[
- bool,
+ Union[bool, None],
Doc(
"""
When `embed` is `True`, the parameter will be expected in a JSON body as a
@@ -1294,7 +1294,7 @@ def Body( # noqa: N802
[FastAPI docs for Body - Multiple Parameters](https://fastapi.tiangolo.com/tutorial/body-multiple-params/#embed-a-single-body-parameter).
"""
),
- ] = False,
+ ] = None,
media_type: Annotated[
str,
Doc(
diff --git a/fastapi/params.py b/fastapi/params.py
index 860146531..90ca7cb01 100644
--- a/fastapi/params.py
+++ b/fastapi/params.py
@@ -91,7 +91,7 @@ class Param(FieldInfo):
max_length=max_length,
discriminator=discriminator,
multiple_of=multiple_of,
- allow_nan=allow_inf_nan,
+ allow_inf_nan=allow_inf_nan,
max_digits=max_digits,
decimal_places=decimal_places,
**extra,
@@ -479,7 +479,7 @@ class Body(FieldInfo):
*,
default_factory: Union[Callable[[], Any], None] = _Unset,
annotation: Optional[Any] = None,
- embed: bool = False,
+ embed: Union[bool, None] = None,
media_type: str = "application/json",
alias: Optional[str] = None,
alias_priority: Union[int, None] = _Unset,
@@ -547,7 +547,7 @@ class Body(FieldInfo):
max_length=max_length,
discriminator=discriminator,
multiple_of=multiple_of,
- allow_nan=allow_inf_nan,
+ allow_inf_nan=allow_inf_nan,
max_digits=max_digits,
decimal_places=decimal_places,
**extra,
@@ -556,7 +556,7 @@ class Body(FieldInfo):
kwargs["examples"] = examples
if regex is not None:
warnings.warn(
- "`regex` has been depreacated, please use `pattern` instead",
+ "`regex` has been deprecated, please use `pattern` instead",
category=DeprecationWarning,
stacklevel=4,
)
@@ -642,7 +642,6 @@ class Form(Body):
default=default,
default_factory=default_factory,
annotation=annotation,
- embed=True,
media_type=media_type,
alias=alias,
alias_priority=alias_priority,
diff --git a/fastapi/routing.py b/fastapi/routing.py
index 2e7959f3d..86e303602 100644
--- a/fastapi/routing.py
+++ b/fastapi/routing.py
@@ -3,14 +3,16 @@ import dataclasses
import email.message
import inspect
import json
-from contextlib import AsyncExitStack
+from contextlib import AsyncExitStack, asynccontextmanager
from enum import Enum, IntEnum
from typing import (
Any,
+ AsyncIterator,
Callable,
Coroutine,
Dict,
List,
+ Mapping,
Optional,
Sequence,
Set,
@@ -31,8 +33,10 @@ from fastapi._compat import (
from fastapi.datastructures import Default, DefaultPlaceholder
from fastapi.dependencies.models import Dependant
from fastapi.dependencies.utils import (
+ _should_embed_body_fields,
get_body_field,
get_dependant,
+ get_flat_dependant,
get_parameterless_sub_dependant,
get_typed_return_annotation,
solve_dependencies,
@@ -47,7 +51,7 @@ from fastapi.exceptions import (
from fastapi.types import DecoratedCallable, IncEx
from fastapi.utils import (
create_cloned_field,
- create_response_field,
+ create_model_field,
generate_unique_id,
get_value_or_default,
is_body_allowed_for_status_code,
@@ -67,7 +71,7 @@ from starlette.routing import (
websocket_session,
)
from starlette.routing import Mount as Mount # noqa
-from starlette.types import ASGIApp, Lifespan, Scope
+from starlette.types import AppType, ASGIApp, Lifespan, Scope
from starlette.websockets import WebSocket
from typing_extensions import Annotated, Doc, deprecated
@@ -119,6 +123,23 @@ def _prepare_response_content(
return res
+def _merge_lifespan_context(
+ original_context: Lifespan[Any], nested_context: Lifespan[Any]
+) -> Lifespan[Any]:
+ @asynccontextmanager
+ async def merged_lifespan(
+ app: AppType,
+ ) -> AsyncIterator[Optional[Mapping[str, Any]]]:
+ async with original_context(app) as maybe_original_state:
+ async with nested_context(app) as maybe_nested_state:
+ if maybe_nested_state is None and maybe_original_state is None:
+ yield None # old ASGI compatibility
+ else:
+ yield {**(maybe_nested_state or {}), **(maybe_original_state or {})}
+
+ return merged_lifespan # type: ignore[return-value]
+
+
async def serialize_response(
*,
field: Optional[ModelField] = None,
@@ -206,6 +227,7 @@ def get_request_handler(
response_model_exclude_defaults: bool = False,
response_model_exclude_none: bool = False,
dependency_overrides_provider: Optional[Any] = None,
+ embed_body_fields: bool = False,
) -> Callable[[Request], Coroutine[Any, Any, Response]]:
assert dependant.call is not None, "dependant.call must be a function"
is_coroutine = asyncio.iscoroutinefunction(dependant.call)
@@ -272,27 +294,36 @@ def get_request_handler(
body=body,
dependency_overrides_provider=dependency_overrides_provider,
async_exit_stack=async_exit_stack,
+ embed_body_fields=embed_body_fields,
)
- values, errors, background_tasks, sub_response, _ = solved_result
+ errors = solved_result.errors
if not errors:
raw_response = await run_endpoint_function(
- dependant=dependant, values=values, is_coroutine=is_coroutine
+ dependant=dependant,
+ values=solved_result.values,
+ is_coroutine=is_coroutine,
)
if isinstance(raw_response, Response):
if raw_response.background is None:
- raw_response.background = background_tasks
+ raw_response.background = solved_result.background_tasks
response = raw_response
else:
- response_args: Dict[str, Any] = {"background": background_tasks}
+ response_args: Dict[str, Any] = {
+ "background": solved_result.background_tasks
+ }
# If status_code was set, use it, otherwise use the default from the
# response class, in the case of redirect it's 307
current_status_code = (
- status_code if status_code else sub_response.status_code
+ status_code
+ if status_code
+ else solved_result.response.status_code
)
if current_status_code is not None:
response_args["status_code"] = current_status_code
- if sub_response.status_code:
- response_args["status_code"] = sub_response.status_code
+ if solved_result.response.status_code:
+ response_args["status_code"] = (
+ solved_result.response.status_code
+ )
content = await serialize_response(
field=response_field,
response_content=raw_response,
@@ -307,7 +338,7 @@ def get_request_handler(
response = actual_response_class(content, **response_args)
if not is_body_allowed_for_status_code(response.status_code):
response.body = b""
- response.headers.raw.extend(sub_response.headers.raw)
+ response.headers.raw.extend(solved_result.response.headers.raw)
if errors:
validation_error = RequestValidationError(
_normalize_errors(errors), body=body
@@ -327,7 +358,9 @@ def get_request_handler(
def get_websocket_app(
- dependant: Dependant, dependency_overrides_provider: Optional[Any] = None
+ dependant: Dependant,
+ dependency_overrides_provider: Optional[Any] = None,
+ embed_body_fields: bool = False,
) -> Callable[[WebSocket], Coroutine[Any, Any, Any]]:
async def app(websocket: WebSocket) -> None:
async with AsyncExitStack() as async_exit_stack:
@@ -340,12 +373,14 @@ def get_websocket_app(
dependant=dependant,
dependency_overrides_provider=dependency_overrides_provider,
async_exit_stack=async_exit_stack,
+ embed_body_fields=embed_body_fields,
)
- values, errors, _, _2, _3 = solved_result
- if errors:
- raise WebSocketRequestValidationError(_normalize_errors(errors))
+ if solved_result.errors:
+ raise WebSocketRequestValidationError(
+ _normalize_errors(solved_result.errors)
+ )
assert dependant.call is not None, "dependant.call must be a function"
- await dependant.call(**values)
+ await dependant.call(**solved_result.values)
return app
@@ -371,11 +406,15 @@ class APIWebSocketRoute(routing.WebSocketRoute):
0,
get_parameterless_sub_dependant(depends=depends, path=self.path_format),
)
-
+ self._flat_dependant = get_flat_dependant(self.dependant)
+ self._embed_body_fields = _should_embed_body_fields(
+ self._flat_dependant.body_params
+ )
self.app = websocket_session(
get_websocket_app(
dependant=self.dependant,
dependency_overrides_provider=dependency_overrides_provider,
+ embed_body_fields=self._embed_body_fields,
)
)
@@ -469,7 +508,7 @@ class APIRoute(routing.Route):
status_code
), f"Status code {status_code} must not have a response body"
response_name = "Response_" + self.unique_id
- self.response_field = create_response_field(
+ self.response_field = create_model_field(
name=response_name,
type_=self.response_model,
mode="serialization",
@@ -502,7 +541,7 @@ class APIRoute(routing.Route):
additional_status_code
), f"Status code {additional_status_code} must not have a response body"
response_name = f"Response_{additional_status_code}_{self.unique_id}"
- response_field = create_response_field(name=response_name, type_=model)
+ response_field = create_model_field(name=response_name, type_=model)
response_fields[additional_status_code] = response_field
if response_fields:
self.response_fields: Dict[Union[int, str], ModelField] = response_fields
@@ -516,7 +555,15 @@ class APIRoute(routing.Route):
0,
get_parameterless_sub_dependant(depends=depends, path=self.path_format),
)
- self.body_field = get_body_field(dependant=self.dependant, name=self.unique_id)
+ self._flat_dependant = get_flat_dependant(self.dependant)
+ self._embed_body_fields = _should_embed_body_fields(
+ self._flat_dependant.body_params
+ )
+ self.body_field = get_body_field(
+ flat_dependant=self._flat_dependant,
+ name=self.unique_id,
+ embed_body_fields=self._embed_body_fields,
+ )
self.app = request_response(self.get_route_handler())
def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]:
@@ -533,6 +580,7 @@ class APIRoute(routing.Route):
response_model_exclude_defaults=self.response_model_exclude_defaults,
response_model_exclude_none=self.response_model_exclude_none,
dependency_overrides_provider=self.dependency_overrides_provider,
+ embed_body_fields=self._embed_body_fields,
)
def matches(self, scope: Scope) -> Tuple[Match, Scope]:
@@ -1308,6 +1356,10 @@ class APIRouter(routing.Router):
self.add_event_handler("startup", handler)
for handler in router.on_shutdown:
self.add_event_handler("shutdown", handler)
+ self.lifespan_context = _merge_lifespan_context(
+ self.lifespan_context,
+ router.lifespan_context,
+ )
def get(
self,
diff --git a/fastapi/utils.py b/fastapi/utils.py
index fb44d729c..46f2c98c3 100644
--- a/fastapi/utils.py
+++ b/fastapi/utils.py
@@ -60,9 +60,9 @@ def get_path_param_names(path: str) -> Set[str]:
return set(re.findall("{(.*?)}", path))
-def create_response_field(
+def create_model_field(
name: str,
- type_: Type[Any],
+ type_: Any,
class_validators: Optional[Dict[str, Validator]] = None,
default: Optional[Any] = Undefined,
required: Union[bool, UndefinedType] = Undefined,
@@ -71,9 +71,6 @@ def create_response_field(
alias: Optional[str] = None,
mode: Literal["validation", "serialization"] = "validation",
) -> ModelField:
- """
- Create a new response field. Raises if type_ is invalid.
- """
class_validators = class_validators or {}
if PYDANTIC_V2:
field_info = field_info or FieldInfo(
@@ -135,7 +132,7 @@ def create_cloned_field(
use_type.__fields__[f.name] = create_cloned_field(
f, cloned_types=cloned_types
)
- new_field = create_response_field(name=field.name, type_=use_type)
+ new_field = create_model_field(name=field.name, type_=use_type)
new_field.has_alias = field.has_alias # type: ignore[attr-defined]
new_field.alias = field.alias # type: ignore[misc]
new_field.class_validators = field.class_validators # type: ignore[attr-defined]
diff --git a/pyproject.toml b/pyproject.toml
index bb87be470..1be2817a1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -241,3 +241,7 @@ known-third-party = ["fastapi", "pydantic", "starlette"]
[tool.ruff.lint.pyupgrade]
# Preserve types, even if a file imports `from __future__ import annotations`.
keep-runtime-typing = true
+
+[tool.inline-snapshot]
+# default-flags=["fix"]
+# default-flags=["create"]
diff --git a/requirements-docs.txt b/requirements-docs.txt
index ab2b0165b..332fd1857 100644
--- a/requirements-docs.txt
+++ b/requirements-docs.txt
@@ -8,7 +8,7 @@ pyyaml >=5.3.1,<7.0.0
# For Material for MkDocs, Chinese search
jieba==0.42.1
# For image processing by Material for MkDocs
-pillow==10.3.0
+pillow==10.4.0
# For image processing by Material for MkDocs
cairosvg==2.7.1
mkdocstrings[python]==0.25.1
diff --git a/requirements-tests.txt b/requirements-tests.txt
index 08561d23a..2f2576dd5 100644
--- a/requirements-tests.txt
+++ b/requirements-tests.txt
@@ -3,7 +3,7 @@
pytest >=7.1.3,<8.0.0
coverage[toml] >= 6.5.0,< 8.0
mypy ==1.8.0
-ruff ==0.6.1
+ruff ==0.6.4
dirty-equals ==0.6.0
# TODO: once removing databases from tutorial, upgrade SQLAlchemy
# probably when including SQLModel
@@ -14,7 +14,7 @@ anyio[trio] >=3.2.1,<4.0.0
PyJWT==2.8.0
pyyaml >=5.3.1,<7.0.0
passlib[bcrypt] >=1.7.2,<2.0.0
-
+inline-snapshot==0.13.0
# types
types-ujson ==5.7.0.1
types-orjson ==3.6.2
diff --git a/scripts/playwright/cookie_param_models/image01.py b/scripts/playwright/cookie_param_models/image01.py
new file mode 100644
index 000000000..77c91bfe2
--- /dev/null
+++ b/scripts/playwright/cookie_param_models/image01.py
@@ -0,0 +1,39 @@
+import subprocess
+import time
+
+import httpx
+from playwright.sync_api import Playwright, sync_playwright
+
+
+# Run playwright codegen to generate the code below, copy paste the sections in run()
+def run(playwright: Playwright) -> None:
+ browser = playwright.chromium.launch(headless=False)
+ # Update the viewport manually
+ context = browser.new_context(viewport={"width": 960, "height": 1080})
+ browser = playwright.chromium.launch(headless=False)
+ context = browser.new_context()
+ page = context.new_page()
+ page.goto("http://localhost:8000/docs")
+ page.get_by_role("link", name="/items/").click()
+ # Manually add the screenshot
+ page.screenshot(path="docs/en/docs/img/tutorial/cookie-param-models/image01.png")
+
+ # ---------------------
+ context.close()
+ browser.close()
+
+
+process = subprocess.Popen(
+ ["fastapi", "run", "docs_src/cookie_param_models/tutorial001.py"]
+)
+try:
+ for _ in range(3):
+ try:
+ response = httpx.get("http://localhost:8000/docs")
+ except httpx.ConnectError:
+ time.sleep(1)
+ break
+ with sync_playwright() as playwright:
+ run(playwright)
+finally:
+ process.terminate()
diff --git a/scripts/playwright/header_param_models/image01.py b/scripts/playwright/header_param_models/image01.py
new file mode 100644
index 000000000..53914251e
--- /dev/null
+++ b/scripts/playwright/header_param_models/image01.py
@@ -0,0 +1,38 @@
+import subprocess
+import time
+
+import httpx
+from playwright.sync_api import Playwright, sync_playwright
+
+
+# Run playwright codegen to generate the code below, copy paste the sections in run()
+def run(playwright: Playwright) -> None:
+ browser = playwright.chromium.launch(headless=False)
+ # Update the viewport manually
+ context = browser.new_context(viewport={"width": 960, "height": 1080})
+ page = context.new_page()
+ page.goto("http://localhost:8000/docs")
+ page.get_by_role("button", name="GET /items/ Read Items").click()
+ page.get_by_role("button", name="Try it out").click()
+ # Manually add the screenshot
+ page.screenshot(path="docs/en/docs/img/tutorial/header-param-models/image01.png")
+
+ # ---------------------
+ context.close()
+ browser.close()
+
+
+process = subprocess.Popen(
+ ["fastapi", "run", "docs_src/header_param_models/tutorial001.py"]
+)
+try:
+ for _ in range(3):
+ try:
+ response = httpx.get("http://localhost:8000/docs")
+ except httpx.ConnectError:
+ time.sleep(1)
+ break
+ with sync_playwright() as playwright:
+ run(playwright)
+finally:
+ process.terminate()
diff --git a/scripts/playwright/query_param_models/image01.py b/scripts/playwright/query_param_models/image01.py
new file mode 100644
index 000000000..0ea1d0df4
--- /dev/null
+++ b/scripts/playwright/query_param_models/image01.py
@@ -0,0 +1,41 @@
+import subprocess
+import time
+
+import httpx
+from playwright.sync_api import Playwright, sync_playwright
+
+
+# Run playwright codegen to generate the code below, copy paste the sections in run()
+def run(playwright: Playwright) -> None:
+ browser = playwright.chromium.launch(headless=False)
+ # Update the viewport manually
+ context = browser.new_context(viewport={"width": 960, "height": 1080})
+ browser = playwright.chromium.launch(headless=False)
+ context = browser.new_context()
+ page = context.new_page()
+ page.goto("http://localhost:8000/docs")
+ page.get_by_role("button", name="GET /items/ Read Items").click()
+ page.get_by_role("button", name="Try it out").click()
+ page.get_by_role("heading", name="Servers").click()
+ # Manually add the screenshot
+ page.screenshot(path="docs/en/docs/img/tutorial/query-param-models/image01.png")
+
+ # ---------------------
+ context.close()
+ browser.close()
+
+
+process = subprocess.Popen(
+ ["fastapi", "run", "docs_src/query_param_models/tutorial001.py"]
+)
+try:
+ for _ in range(3):
+ try:
+ response = httpx.get("http://localhost:8000/docs")
+ except httpx.ConnectError:
+ time.sleep(1)
+ break
+ with sync_playwright() as playwright:
+ run(playwright)
+finally:
+ process.terminate()
diff --git a/scripts/playwright/request_form_models/image01.py b/scripts/playwright/request_form_models/image01.py
new file mode 100644
index 000000000..fe4da32fc
--- /dev/null
+++ b/scripts/playwright/request_form_models/image01.py
@@ -0,0 +1,38 @@
+import subprocess
+import time
+
+import httpx
+from playwright.sync_api import Playwright, sync_playwright
+
+
+# Run playwright codegen to generate the code below, copy paste the sections in run()
+def run(playwright: Playwright) -> None:
+ browser = playwright.chromium.launch(headless=False)
+ # Update the viewport manually
+ context = browser.new_context(viewport={"width": 960, "height": 1080})
+ page = context.new_page()
+ page.goto("http://localhost:8000/docs")
+ page.get_by_role("button", name="POST /login/ Login").click()
+ page.get_by_role("button", name="Try it out").click()
+ # Manually add the screenshot
+ page.screenshot(path="docs/en/docs/img/tutorial/request-form-models/image01.png")
+
+ # ---------------------
+ context.close()
+ browser.close()
+
+
+process = subprocess.Popen(
+ ["fastapi", "run", "docs_src/request_form_models/tutorial001.py"]
+)
+try:
+ for _ in range(3):
+ try:
+ response = httpx.get("http://localhost:8000/docs")
+ except httpx.ConnectError:
+ time.sleep(1)
+ break
+ with sync_playwright() as playwright:
+ run(playwright)
+finally:
+ process.terminate()
diff --git a/scripts/playwright/separate_openapi_schemas/image01.py b/scripts/playwright/separate_openapi_schemas/image01.py
index 0b40f3bbc..0eb55fb73 100644
--- a/scripts/playwright/separate_openapi_schemas/image01.py
+++ b/scripts/playwright/separate_openapi_schemas/image01.py
@@ -3,13 +3,16 @@ import subprocess
from playwright.sync_api import Playwright, sync_playwright
+# Run playwright codegen to generate the code below, copy paste the sections in run()
def run(playwright: Playwright) -> None:
browser = playwright.chromium.launch(headless=False)
+ # Update the viewport manually
context = browser.new_context(viewport={"width": 960, "height": 1080})
page = context.new_page()
page.goto("http://localhost:8000/docs")
page.get_by_text("POST/items/Create Item").click()
page.get_by_role("tab", name="Schema").first.click()
+ # Manually add the screenshot
page.screenshot(
path="docs/en/docs/img/tutorial/separate-openapi-schemas/image01.png"
)
diff --git a/scripts/playwright/separate_openapi_schemas/image02.py b/scripts/playwright/separate_openapi_schemas/image02.py
index f76af7ee2..0eb6c3c79 100644
--- a/scripts/playwright/separate_openapi_schemas/image02.py
+++ b/scripts/playwright/separate_openapi_schemas/image02.py
@@ -3,14 +3,17 @@ import subprocess
from playwright.sync_api import Playwright, sync_playwright
+# Run playwright codegen to generate the code below, copy paste the sections in run()
def run(playwright: Playwright) -> None:
browser = playwright.chromium.launch(headless=False)
+ # Update the viewport manually
context = browser.new_context(viewport={"width": 960, "height": 1080})
page = context.new_page()
page.goto("http://localhost:8000/docs")
page.get_by_text("GET/items/Read Items").click()
page.get_by_role("button", name="Try it out").click()
page.get_by_role("button", name="Execute").click()
+ # Manually add the screenshot
page.screenshot(
path="docs/en/docs/img/tutorial/separate-openapi-schemas/image02.png"
)
diff --git a/scripts/playwright/separate_openapi_schemas/image03.py b/scripts/playwright/separate_openapi_schemas/image03.py
index 127f5c428..b68e9d7db 100644
--- a/scripts/playwright/separate_openapi_schemas/image03.py
+++ b/scripts/playwright/separate_openapi_schemas/image03.py
@@ -3,14 +3,17 @@ import subprocess
from playwright.sync_api import Playwright, sync_playwright
+# Run playwright codegen to generate the code below, copy paste the sections in run()
def run(playwright: Playwright) -> None:
browser = playwright.chromium.launch(headless=False)
+ # Update the viewport manually
context = browser.new_context(viewport={"width": 960, "height": 1080})
page = context.new_page()
page.goto("http://localhost:8000/docs")
page.get_by_text("GET/items/Read Items").click()
page.get_by_role("tab", name="Schema").click()
page.get_by_label("Schema").get_by_role("button", name="Expand all").click()
+ # Manually add the screenshot
page.screenshot(
path="docs/en/docs/img/tutorial/separate-openapi-schemas/image03.png"
)
diff --git a/scripts/playwright/separate_openapi_schemas/image04.py b/scripts/playwright/separate_openapi_schemas/image04.py
index 208eaf8a0..a36c2f6b2 100644
--- a/scripts/playwright/separate_openapi_schemas/image04.py
+++ b/scripts/playwright/separate_openapi_schemas/image04.py
@@ -3,14 +3,17 @@ import subprocess
from playwright.sync_api import Playwright, sync_playwright
+# Run playwright codegen to generate the code below, copy paste the sections in run()
def run(playwright: Playwright) -> None:
browser = playwright.chromium.launch(headless=False)
+ # Update the viewport manually
context = browser.new_context(viewport={"width": 960, "height": 1080})
page = context.new_page()
page.goto("http://localhost:8000/docs")
page.get_by_role("button", name="Item-Input").click()
page.get_by_role("button", name="Item-Output").click()
page.set_viewport_size({"width": 960, "height": 820})
+ # Manually add the screenshot
page.screenshot(
path="docs/en/docs/img/tutorial/separate-openapi-schemas/image04.png"
)
diff --git a/scripts/playwright/separate_openapi_schemas/image05.py b/scripts/playwright/separate_openapi_schemas/image05.py
index 83966b449..0da5db0cf 100644
--- a/scripts/playwright/separate_openapi_schemas/image05.py
+++ b/scripts/playwright/separate_openapi_schemas/image05.py
@@ -3,13 +3,16 @@ import subprocess
from playwright.sync_api import Playwright, sync_playwright
+# Run playwright codegen to generate the code below, copy paste the sections in run()
def run(playwright: Playwright) -> None:
browser = playwright.chromium.launch(headless=False)
+ # Update the viewport manually
context = browser.new_context(viewport={"width": 960, "height": 1080})
page = context.new_page()
page.goto("http://localhost:8000/docs")
page.get_by_role("button", name="Item", exact=True).click()
page.set_viewport_size({"width": 960, "height": 700})
+ # Manually add the screenshot
page.screenshot(
path="docs/en/docs/img/tutorial/separate-openapi-schemas/image05.png"
)
diff --git a/tests/test_allow_inf_nan_in_enforcing.py b/tests/test_allow_inf_nan_in_enforcing.py
new file mode 100644
index 000000000..9e855fdf8
--- /dev/null
+++ b/tests/test_allow_inf_nan_in_enforcing.py
@@ -0,0 +1,83 @@
+import pytest
+from fastapi import Body, FastAPI, Query
+from fastapi.testclient import TestClient
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+@app.post("/")
+async def get(
+ x: Annotated[float, Query(allow_inf_nan=True)] = 0,
+ y: Annotated[float, Query(allow_inf_nan=False)] = 0,
+ z: Annotated[float, Query()] = 0,
+ b: Annotated[float, Body(allow_inf_nan=False)] = 0,
+) -> str:
+ return "OK"
+
+
+client = TestClient(app)
+
+
+@pytest.mark.parametrize(
+ "value,code",
+ [
+ ("-1", 200),
+ ("inf", 200),
+ ("-inf", 200),
+ ("nan", 200),
+ ("0", 200),
+ ("342", 200),
+ ],
+)
+def test_allow_inf_nan_param_true(value: str, code: int):
+ response = client.post(f"/?x={value}")
+ assert response.status_code == code, response.text
+
+
+@pytest.mark.parametrize(
+ "value,code",
+ [
+ ("-1", 200),
+ ("inf", 422),
+ ("-inf", 422),
+ ("nan", 422),
+ ("0", 200),
+ ("342", 200),
+ ],
+)
+def test_allow_inf_nan_param_false(value: str, code: int):
+ response = client.post(f"/?y={value}")
+ assert response.status_code == code, response.text
+
+
+@pytest.mark.parametrize(
+ "value,code",
+ [
+ ("-1", 200),
+ ("inf", 200),
+ ("-inf", 200),
+ ("nan", 200),
+ ("0", 200),
+ ("342", 200),
+ ],
+)
+def test_allow_inf_nan_param_default(value: str, code: int):
+ response = client.post(f"/?z={value}")
+ assert response.status_code == code, response.text
+
+
+@pytest.mark.parametrize(
+ "value,code",
+ [
+ ("-1", 200),
+ ("inf", 422),
+ ("-inf", 422),
+ ("nan", 422),
+ ("0", 200),
+ ("342", 200),
+ ],
+)
+def test_allow_inf_nan_body(value: str, code: int):
+ response = client.post("/", json=value)
+ assert response.status_code == code, response.text
diff --git a/tests/test_compat.py b/tests/test_compat.py
index bf268b860..f4a3093c5 100644
--- a/tests/test_compat.py
+++ b/tests/test_compat.py
@@ -1,11 +1,14 @@
-from typing import List, Union
+from typing import Any, Dict, List, Union
from fastapi import FastAPI, UploadFile
from fastapi._compat import (
ModelField,
Undefined,
_get_model_config,
+ get_cached_model_fields,
+ get_model_fields,
is_bytes_sequence_annotation,
+ is_scalar_field,
is_uploadfile_sequence_annotation,
)
from fastapi.testclient import TestClient
@@ -91,3 +94,27 @@ def test_is_uploadfile_sequence_annotation():
# and other types, but I'm not even sure it's a good idea to support it as a first
# class "feature"
assert is_uploadfile_sequence_annotation(Union[List[str], List[UploadFile]])
+
+
+def test_is_pv1_scalar_field():
+ # For coverage
+ class Model(BaseModel):
+ foo: Union[str, Dict[str, Any]]
+
+ fields = get_model_fields(Model)
+ assert not is_scalar_field(fields[0])
+
+
+def test_get_model_fields_cached():
+ class Model(BaseModel):
+ foo: str
+
+ non_cached_fields = get_model_fields(Model)
+ non_cached_fields2 = get_model_fields(Model)
+ cached_fields = get_cached_model_fields(Model)
+ cached_fields2 = get_cached_model_fields(Model)
+ for f1, f2 in zip(cached_fields, cached_fields2):
+ assert f1 is f2
+
+ assert non_cached_fields is not non_cached_fields2
+ assert cached_fields is cached_fields2
diff --git a/tests/test_forms_single_model.py b/tests/test_forms_single_model.py
new file mode 100644
index 000000000..880ab3820
--- /dev/null
+++ b/tests/test_forms_single_model.py
@@ -0,0 +1,133 @@
+from typing import List, Optional
+
+from dirty_equals import IsDict
+from fastapi import FastAPI, Form
+from fastapi.testclient import TestClient
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+class FormModel(BaseModel):
+ username: str
+ lastname: str
+ age: Optional[int] = None
+ tags: List[str] = ["foo", "bar"]
+ alias_with: str = Field(alias="with", default="nothing")
+
+
+@app.post("/form/")
+def post_form(user: Annotated[FormModel, Form()]):
+ return user
+
+
+client = TestClient(app)
+
+
+def test_send_all_data():
+ response = client.post(
+ "/form/",
+ data={
+ "username": "Rick",
+ "lastname": "Sanchez",
+ "age": "70",
+ "tags": ["plumbus", "citadel"],
+ "with": "something",
+ },
+ )
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "username": "Rick",
+ "lastname": "Sanchez",
+ "age": 70,
+ "tags": ["plumbus", "citadel"],
+ "with": "something",
+ }
+
+
+def test_defaults():
+ response = client.post("/form/", data={"username": "Rick", "lastname": "Sanchez"})
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "username": "Rick",
+ "lastname": "Sanchez",
+ "age": None,
+ "tags": ["foo", "bar"],
+ "with": "nothing",
+ }
+
+
+def test_invalid_data():
+ response = client.post(
+ "/form/",
+ data={
+ "username": "Rick",
+ "lastname": "Sanchez",
+ "age": "seventy",
+ "tags": ["plumbus", "citadel"],
+ },
+ )
+ assert response.status_code == 422, response.text
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "int_parsing",
+ "loc": ["body", "age"],
+ "msg": "Input should be a valid integer, unable to parse string as an integer",
+ "input": "seventy",
+ }
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "age"],
+ "msg": "value is not a valid integer",
+ "type": "type_error.integer",
+ }
+ ]
+ }
+ )
+
+
+def test_no_data():
+ response = client.post("/form/")
+ assert response.status_code == 422, response.text
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {"tags": ["foo", "bar"], "with": "nothing"},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "lastname"],
+ "msg": "Field required",
+ "input": {"tags": ["foo", "bar"], "with": "nothing"},
+ },
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "username"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ {
+ "loc": ["body", "lastname"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ ]
+ }
+ )
diff --git a/tests/test_forms_single_param.py b/tests/test_forms_single_param.py
new file mode 100644
index 000000000..3bb951441
--- /dev/null
+++ b/tests/test_forms_single_param.py
@@ -0,0 +1,99 @@
+from fastapi import FastAPI, Form
+from fastapi.testclient import TestClient
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+@app.post("/form/")
+def post_form(username: Annotated[str, Form()]):
+ return username
+
+
+client = TestClient(app)
+
+
+def test_single_form_field():
+ response = client.post("/form/", data={"username": "Rick"})
+ assert response.status_code == 200, response.text
+ assert response.json() == "Rick"
+
+
+def test_openapi_schema():
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/form/": {
+ "post": {
+ "summary": "Post Form",
+ "operationId": "post_form_form__post",
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {
+ "$ref": "#/components/schemas/Body_post_form_form__post"
+ }
+ }
+ },
+ "required": True,
+ },
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "Body_post_form_form__post": {
+ "properties": {"username": {"type": "string", "title": "Username"}},
+ "type": "object",
+ "required": ["username"],
+ "title": "Body_post_form_form__post",
+ },
+ "HTTPValidationError": {
+ "properties": {
+ "detail": {
+ "items": {"$ref": "#/components/schemas/ValidationError"},
+ "type": "array",
+ "title": "Detail",
+ }
+ },
+ "type": "object",
+ "title": "HTTPValidationError",
+ },
+ "ValidationError": {
+ "properties": {
+ "loc": {
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ "type": "array",
+ "title": "Location",
+ },
+ "msg": {"type": "string", "title": "Message"},
+ "type": {"type": "string", "title": "Error Type"},
+ },
+ "type": "object",
+ "required": ["loc", "msg", "type"],
+ "title": "ValidationError",
+ },
+ }
+ },
+ }
diff --git a/tests/test_openapi_examples.py b/tests/test_openapi_examples.py
index 6597e5058..b3f83ae23 100644
--- a/tests/test_openapi_examples.py
+++ b/tests/test_openapi_examples.py
@@ -155,13 +155,26 @@ def test_openapi_schema():
"requestBody": {
"content": {
"application/json": {
- "schema": {
- "allOf": [{"$ref": "#/components/schemas/Item"}],
- "title": "Item",
- "examples": [
- {"data": "Data in Body examples, example1"}
- ],
- },
+ "schema": IsDict(
+ {
+ "$ref": "#/components/schemas/Item",
+ "examples": [
+ {"data": "Data in Body examples, example1"}
+ ],
+ }
+ )
+ | IsDict(
+ {
+ # TODO: remove when deprecating Pydantic v1
+ "allOf": [
+ {"$ref": "#/components/schemas/Item"}
+ ],
+ "title": "Item",
+ "examples": [
+ {"data": "Data in Body examples, example1"}
+ ],
+ }
+ ),
"examples": {
"Example One": {
"summary": "Example One Summary",
diff --git a/tests/test_router_events.py b/tests/test_router_events.py
index 1b9de18ae..dd7ff3314 100644
--- a/tests/test_router_events.py
+++ b/tests/test_router_events.py
@@ -1,8 +1,8 @@
from contextlib import asynccontextmanager
-from typing import AsyncGenerator, Dict
+from typing import AsyncGenerator, Dict, Union
import pytest
-from fastapi import APIRouter, FastAPI
+from fastapi import APIRouter, FastAPI, Request
from fastapi.testclient import TestClient
from pydantic import BaseModel
@@ -109,3 +109,134 @@ def test_app_lifespan_state(state: State) -> None:
assert response.json() == {"message": "Hello World"}
assert state.app_startup is True
assert state.app_shutdown is True
+
+
+def test_router_nested_lifespan_state(state: State) -> None:
+ @asynccontextmanager
+ async def lifespan(app: FastAPI) -> AsyncGenerator[Dict[str, bool], None]:
+ state.app_startup = True
+ yield {"app": True}
+ state.app_shutdown = True
+
+ @asynccontextmanager
+ async def router_lifespan(app: FastAPI) -> AsyncGenerator[Dict[str, bool], None]:
+ state.router_startup = True
+ yield {"router": True}
+ state.router_shutdown = True
+
+ @asynccontextmanager
+ async def subrouter_lifespan(app: FastAPI) -> AsyncGenerator[Dict[str, bool], None]:
+ state.sub_router_startup = True
+ yield {"sub_router": True}
+ state.sub_router_shutdown = True
+
+ sub_router = APIRouter(lifespan=subrouter_lifespan)
+
+ router = APIRouter(lifespan=router_lifespan)
+ router.include_router(sub_router)
+
+ app = FastAPI(lifespan=lifespan)
+ app.include_router(router)
+
+ @app.get("/")
+ def main(request: Request) -> Dict[str, str]:
+ assert request.state.app
+ assert request.state.router
+ assert request.state.sub_router
+ return {"message": "Hello World"}
+
+ assert state.app_startup is False
+ assert state.router_startup is False
+ assert state.sub_router_startup is False
+ assert state.app_shutdown is False
+ assert state.router_shutdown is False
+ assert state.sub_router_shutdown is False
+
+ with TestClient(app) as client:
+ assert state.app_startup is True
+ assert state.router_startup is True
+ assert state.sub_router_startup is True
+ assert state.app_shutdown is False
+ assert state.router_shutdown is False
+ assert state.sub_router_shutdown is False
+ response = client.get("/")
+ assert response.status_code == 200, response.text
+ assert response.json() == {"message": "Hello World"}
+
+ assert state.app_startup is True
+ assert state.router_startup is True
+ assert state.sub_router_startup is True
+ assert state.app_shutdown is True
+ assert state.router_shutdown is True
+ assert state.sub_router_shutdown is True
+
+
+def test_router_nested_lifespan_state_overriding_by_parent() -> None:
+ @asynccontextmanager
+ async def lifespan(
+ app: FastAPI,
+ ) -> AsyncGenerator[Dict[str, Union[str, bool]], None]:
+ yield {
+ "app_specific": True,
+ "overridden": "app",
+ }
+
+ @asynccontextmanager
+ async def router_lifespan(
+ app: FastAPI,
+ ) -> AsyncGenerator[Dict[str, Union[str, bool]], None]:
+ yield {
+ "router_specific": True,
+ "overridden": "router", # should override parent
+ }
+
+ router = APIRouter(lifespan=router_lifespan)
+ app = FastAPI(lifespan=lifespan)
+ app.include_router(router)
+
+ with TestClient(app) as client:
+ assert client.app_state == {
+ "app_specific": True,
+ "router_specific": True,
+ "overridden": "app",
+ }
+
+
+def test_merged_no_return_lifespans_return_none() -> None:
+ @asynccontextmanager
+ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+ yield
+
+ @asynccontextmanager
+ async def router_lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+ yield
+
+ router = APIRouter(lifespan=router_lifespan)
+ app = FastAPI(lifespan=lifespan)
+ app.include_router(router)
+
+ with TestClient(app) as client:
+ assert not client.app_state
+
+
+def test_merged_mixed_state_lifespans() -> None:
+ @asynccontextmanager
+ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+ yield
+
+ @asynccontextmanager
+ async def router_lifespan(app: FastAPI) -> AsyncGenerator[Dict[str, bool], None]:
+ yield {"router": True}
+
+ @asynccontextmanager
+ async def sub_router_lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+ yield
+
+ sub_router = APIRouter(lifespan=sub_router_lifespan)
+ router = APIRouter(lifespan=router_lifespan)
+ app = FastAPI(lifespan=lifespan)
+ router.include_router(sub_router)
+ app.include_router(router)
+
+ with TestClient(app) as client:
+ assert client.app_state == {"router": True}
diff --git a/tests/test_tutorial/test_cookie_param_models/__init__.py b/tests/test_tutorial/test_cookie_param_models/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/test_tutorial/test_cookie_param_models/test_tutorial001.py b/tests/test_tutorial/test_cookie_param_models/test_tutorial001.py
new file mode 100644
index 000000000..60643185a
--- /dev/null
+++ b/tests/test_tutorial/test_cookie_param_models/test_tutorial001.py
@@ -0,0 +1,205 @@
+import importlib
+
+import pytest
+from dirty_equals import IsDict
+from fastapi.testclient import TestClient
+from inline_snapshot import snapshot
+
+from tests.utils import needs_py39, needs_py310
+
+
+@pytest.fixture(
+ name="client",
+ params=[
+ "tutorial001",
+ pytest.param("tutorial001_py310", marks=needs_py310),
+ "tutorial001_an",
+ pytest.param("tutorial001_an_py39", marks=needs_py39),
+ pytest.param("tutorial001_an_py310", marks=needs_py310),
+ ],
+)
+def get_client(request: pytest.FixtureRequest):
+ mod = importlib.import_module(f"docs_src.cookie_param_models.{request.param}")
+
+ client = TestClient(mod.app)
+ return client
+
+
+def test_cookie_param_model(client: TestClient):
+ with client as c:
+ c.cookies.set("session_id", "123")
+ c.cookies.set("fatebook_tracker", "456")
+ c.cookies.set("googall_tracker", "789")
+ response = c.get("/items/")
+ assert response.status_code == 200
+ assert response.json() == {
+ "session_id": "123",
+ "fatebook_tracker": "456",
+ "googall_tracker": "789",
+ }
+
+
+def test_cookie_param_model_defaults(client: TestClient):
+ with client as c:
+ c.cookies.set("session_id", "123")
+ response = c.get("/items/")
+ assert response.status_code == 200
+ assert response.json() == {
+ "session_id": "123",
+ "fatebook_tracker": None,
+ "googall_tracker": None,
+ }
+
+
+def test_cookie_param_model_invalid(client: TestClient):
+ response = client.get("/items/")
+ assert response.status_code == 422
+ assert response.json() == snapshot(
+ IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["cookie", "session_id"],
+ "msg": "Field required",
+ "input": {},
+ }
+ ]
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["cookie", "session_id"],
+ "msg": "field required",
+ }
+ ]
+ }
+ )
+ )
+
+
+def test_cookie_param_model_extra(client: TestClient):
+ with client as c:
+ c.cookies.set("session_id", "123")
+ c.cookies.set("extra", "track-me-here-too")
+ response = c.get("/items/")
+ assert response.status_code == 200
+ assert response.json() == snapshot(
+ {"session_id": "123", "fatebook_tracker": None, "googall_tracker": None}
+ )
+
+
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == snapshot(
+ {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/items/": {
+ "get": {
+ "summary": "Read Items",
+ "operationId": "read_items_items__get",
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "cookie",
+ "required": True,
+ "schema": {"type": "string", "title": "Session Id"},
+ },
+ {
+ "name": "fatebook_tracker",
+ "in": "cookie",
+ "required": False,
+ "schema": IsDict(
+ {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Fatebook Tracker",
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "string",
+ "title": "Fatebook Tracker",
+ }
+ ),
+ },
+ {
+ "name": "googall_tracker",
+ "in": "cookie",
+ "required": False,
+ "schema": IsDict(
+ {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Googall Tracker",
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "string",
+ "title": "Googall Tracker",
+ }
+ ),
+ },
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "HTTPValidationError": {
+ "properties": {
+ "detail": {
+ "items": {
+ "$ref": "#/components/schemas/ValidationError"
+ },
+ "type": "array",
+ "title": "Detail",
+ }
+ },
+ "type": "object",
+ "title": "HTTPValidationError",
+ },
+ "ValidationError": {
+ "properties": {
+ "loc": {
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ "type": "array",
+ "title": "Location",
+ },
+ "msg": {"type": "string", "title": "Message"},
+ "type": {"type": "string", "title": "Error Type"},
+ },
+ "type": "object",
+ "required": ["loc", "msg", "type"],
+ "title": "ValidationError",
+ },
+ }
+ },
+ }
+ )
diff --git a/tests/test_tutorial/test_cookie_param_models/test_tutorial002.py b/tests/test_tutorial/test_cookie_param_models/test_tutorial002.py
new file mode 100644
index 000000000..30adadc8a
--- /dev/null
+++ b/tests/test_tutorial/test_cookie_param_models/test_tutorial002.py
@@ -0,0 +1,233 @@
+import importlib
+
+import pytest
+from dirty_equals import IsDict
+from fastapi.testclient import TestClient
+from inline_snapshot import snapshot
+
+from tests.utils import needs_py39, needs_py310, needs_pydanticv1, needs_pydanticv2
+
+
+@pytest.fixture(
+ name="client",
+ params=[
+ pytest.param("tutorial002", marks=needs_pydanticv2),
+ pytest.param("tutorial002_py310", marks=[needs_py310, needs_pydanticv2]),
+ pytest.param("tutorial002_an", marks=needs_pydanticv2),
+ pytest.param("tutorial002_an_py39", marks=[needs_py39, needs_pydanticv2]),
+ pytest.param("tutorial002_an_py310", marks=[needs_py310, needs_pydanticv2]),
+ pytest.param("tutorial002_pv1", marks=[needs_pydanticv1, needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_py310", marks=[needs_py310, needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_an", marks=[needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_an_py39", marks=[needs_py39, needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_an_py310", marks=[needs_py310, needs_pydanticv1]),
+ ],
+)
+def get_client(request: pytest.FixtureRequest):
+ mod = importlib.import_module(f"docs_src.cookie_param_models.{request.param}")
+
+ client = TestClient(mod.app)
+ return client
+
+
+def test_cookie_param_model(client: TestClient):
+ with client as c:
+ c.cookies.set("session_id", "123")
+ c.cookies.set("fatebook_tracker", "456")
+ c.cookies.set("googall_tracker", "789")
+ response = c.get("/items/")
+ assert response.status_code == 200
+ assert response.json() == {
+ "session_id": "123",
+ "fatebook_tracker": "456",
+ "googall_tracker": "789",
+ }
+
+
+def test_cookie_param_model_defaults(client: TestClient):
+ with client as c:
+ c.cookies.set("session_id", "123")
+ response = c.get("/items/")
+ assert response.status_code == 200
+ assert response.json() == {
+ "session_id": "123",
+ "fatebook_tracker": None,
+ "googall_tracker": None,
+ }
+
+
+def test_cookie_param_model_invalid(client: TestClient):
+ response = client.get("/items/")
+ assert response.status_code == 422
+ assert response.json() == snapshot(
+ IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["cookie", "session_id"],
+ "msg": "Field required",
+ "input": {},
+ }
+ ]
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["cookie", "session_id"],
+ "msg": "field required",
+ }
+ ]
+ }
+ )
+ )
+
+
+def test_cookie_param_model_extra(client: TestClient):
+ with client as c:
+ c.cookies.set("session_id", "123")
+ c.cookies.set("extra", "track-me-here-too")
+ response = c.get("/items/")
+ assert response.status_code == 422
+ assert response.json() == snapshot(
+ IsDict(
+ {
+ "detail": [
+ {
+ "type": "extra_forbidden",
+ "loc": ["cookie", "extra"],
+ "msg": "Extra inputs are not permitted",
+ "input": "track-me-here-too",
+ }
+ ]
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "type": "value_error.extra",
+ "loc": ["cookie", "extra"],
+ "msg": "extra fields not permitted",
+ }
+ ]
+ }
+ )
+ )
+
+
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == snapshot(
+ {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/items/": {
+ "get": {
+ "summary": "Read Items",
+ "operationId": "read_items_items__get",
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "cookie",
+ "required": True,
+ "schema": {"type": "string", "title": "Session Id"},
+ },
+ {
+ "name": "fatebook_tracker",
+ "in": "cookie",
+ "required": False,
+ "schema": IsDict(
+ {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Fatebook Tracker",
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "string",
+ "title": "Fatebook Tracker",
+ }
+ ),
+ },
+ {
+ "name": "googall_tracker",
+ "in": "cookie",
+ "required": False,
+ "schema": IsDict(
+ {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Googall Tracker",
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "string",
+ "title": "Googall Tracker",
+ }
+ ),
+ },
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "HTTPValidationError": {
+ "properties": {
+ "detail": {
+ "items": {
+ "$ref": "#/components/schemas/ValidationError"
+ },
+ "type": "array",
+ "title": "Detail",
+ }
+ },
+ "type": "object",
+ "title": "HTTPValidationError",
+ },
+ "ValidationError": {
+ "properties": {
+ "loc": {
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ "type": "array",
+ "title": "Location",
+ },
+ "msg": {"type": "string", "title": "Message"},
+ "type": {"type": "string", "title": "Error Type"},
+ },
+ "type": "object",
+ "required": ["loc", "msg", "type"],
+ "title": "ValidationError",
+ },
+ }
+ },
+ }
+ )
diff --git a/tests/test_tutorial/test_header_param_models/__init__.py b/tests/test_tutorial/test_header_param_models/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/test_tutorial/test_header_param_models/test_tutorial001.py b/tests/test_tutorial/test_header_param_models/test_tutorial001.py
new file mode 100644
index 000000000..06b2404cf
--- /dev/null
+++ b/tests/test_tutorial/test_header_param_models/test_tutorial001.py
@@ -0,0 +1,238 @@
+import importlib
+
+import pytest
+from dirty_equals import IsDict
+from fastapi.testclient import TestClient
+from inline_snapshot import snapshot
+
+from tests.utils import needs_py39, needs_py310
+
+
+@pytest.fixture(
+ name="client",
+ params=[
+ "tutorial001",
+ pytest.param("tutorial001_py39", marks=needs_py39),
+ pytest.param("tutorial001_py310", marks=needs_py310),
+ "tutorial001_an",
+ pytest.param("tutorial001_an_py39", marks=needs_py39),
+ pytest.param("tutorial001_an_py310", marks=needs_py310),
+ ],
+)
+def get_client(request: pytest.FixtureRequest):
+ mod = importlib.import_module(f"docs_src.header_param_models.{request.param}")
+
+ client = TestClient(mod.app)
+ return client
+
+
+def test_header_param_model(client: TestClient):
+ response = client.get(
+ "/items/",
+ headers=[
+ ("save-data", "true"),
+ ("if-modified-since", "yesterday"),
+ ("traceparent", "123"),
+ ("x-tag", "one"),
+ ("x-tag", "two"),
+ ],
+ )
+ assert response.status_code == 200
+ assert response.json() == {
+ "host": "testserver",
+ "save_data": True,
+ "if_modified_since": "yesterday",
+ "traceparent": "123",
+ "x_tag": ["one", "two"],
+ }
+
+
+def test_header_param_model_defaults(client: TestClient):
+ response = client.get("/items/", headers=[("save-data", "true")])
+ assert response.status_code == 200
+ assert response.json() == {
+ "host": "testserver",
+ "save_data": True,
+ "if_modified_since": None,
+ "traceparent": None,
+ "x_tag": [],
+ }
+
+
+def test_header_param_model_invalid(client: TestClient):
+ response = client.get("/items/")
+ assert response.status_code == 422
+ assert response.json() == snapshot(
+ {
+ "detail": [
+ IsDict(
+ {
+ "type": "missing",
+ "loc": ["header", "save_data"],
+ "msg": "Field required",
+ "input": {
+ "x_tag": [],
+ "host": "testserver",
+ "accept": "*/*",
+ "accept-encoding": "gzip, deflate",
+ "connection": "keep-alive",
+ "user-agent": "testclient",
+ },
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "value_error.missing",
+ "loc": ["header", "save_data"],
+ "msg": "field required",
+ }
+ )
+ ]
+ }
+ )
+
+
+def test_header_param_model_extra(client: TestClient):
+ response = client.get(
+ "/items/", headers=[("save-data", "true"), ("tool", "plumbus")]
+ )
+ assert response.status_code == 200, response.text
+ assert response.json() == snapshot(
+ {
+ "host": "testserver",
+ "save_data": True,
+ "if_modified_since": None,
+ "traceparent": None,
+ "x_tag": [],
+ }
+ )
+
+
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == snapshot(
+ {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/items/": {
+ "get": {
+ "summary": "Read Items",
+ "operationId": "read_items_items__get",
+ "parameters": [
+ {
+ "name": "host",
+ "in": "header",
+ "required": True,
+ "schema": {"type": "string", "title": "Host"},
+ },
+ {
+ "name": "save_data",
+ "in": "header",
+ "required": True,
+ "schema": {"type": "boolean", "title": "Save Data"},
+ },
+ {
+ "name": "if_modified_since",
+ "in": "header",
+ "required": False,
+ "schema": IsDict(
+ {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "If Modified Since",
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "string",
+ "title": "If Modified Since",
+ }
+ ),
+ },
+ {
+ "name": "traceparent",
+ "in": "header",
+ "required": False,
+ "schema": IsDict(
+ {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Traceparent",
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "string",
+ "title": "Traceparent",
+ }
+ ),
+ },
+ {
+ "name": "x_tag",
+ "in": "header",
+ "required": False,
+ "schema": {
+ "type": "array",
+ "items": {"type": "string"},
+ "default": [],
+ "title": "X Tag",
+ },
+ },
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "HTTPValidationError": {
+ "properties": {
+ "detail": {
+ "items": {
+ "$ref": "#/components/schemas/ValidationError"
+ },
+ "type": "array",
+ "title": "Detail",
+ }
+ },
+ "type": "object",
+ "title": "HTTPValidationError",
+ },
+ "ValidationError": {
+ "properties": {
+ "loc": {
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ "type": "array",
+ "title": "Location",
+ },
+ "msg": {"type": "string", "title": "Message"},
+ "type": {"type": "string", "title": "Error Type"},
+ },
+ "type": "object",
+ "required": ["loc", "msg", "type"],
+ "title": "ValidationError",
+ },
+ }
+ },
+ }
+ )
diff --git a/tests/test_tutorial/test_header_param_models/test_tutorial002.py b/tests/test_tutorial/test_header_param_models/test_tutorial002.py
new file mode 100644
index 000000000..e07655a0c
--- /dev/null
+++ b/tests/test_tutorial/test_header_param_models/test_tutorial002.py
@@ -0,0 +1,249 @@
+import importlib
+
+import pytest
+from dirty_equals import IsDict
+from fastapi.testclient import TestClient
+from inline_snapshot import snapshot
+
+from tests.utils import needs_py39, needs_py310, needs_pydanticv1, needs_pydanticv2
+
+
+@pytest.fixture(
+ name="client",
+ params=[
+ pytest.param("tutorial002", marks=needs_pydanticv2),
+ pytest.param("tutorial002_py310", marks=[needs_py310, needs_pydanticv2]),
+ pytest.param("tutorial002_an", marks=needs_pydanticv2),
+ pytest.param("tutorial002_an_py39", marks=[needs_py39, needs_pydanticv2]),
+ pytest.param("tutorial002_an_py310", marks=[needs_py310, needs_pydanticv2]),
+ pytest.param("tutorial002_pv1", marks=[needs_pydanticv1, needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_py310", marks=[needs_py310, needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_an", marks=[needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_an_py39", marks=[needs_py39, needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_an_py310", marks=[needs_py310, needs_pydanticv1]),
+ ],
+)
+def get_client(request: pytest.FixtureRequest):
+ mod = importlib.import_module(f"docs_src.header_param_models.{request.param}")
+
+ client = TestClient(mod.app)
+ client.headers.clear()
+ return client
+
+
+def test_header_param_model(client: TestClient):
+ response = client.get(
+ "/items/",
+ headers=[
+ ("save-data", "true"),
+ ("if-modified-since", "yesterday"),
+ ("traceparent", "123"),
+ ("x-tag", "one"),
+ ("x-tag", "two"),
+ ],
+ )
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "host": "testserver",
+ "save_data": True,
+ "if_modified_since": "yesterday",
+ "traceparent": "123",
+ "x_tag": ["one", "two"],
+ }
+
+
+def test_header_param_model_defaults(client: TestClient):
+ response = client.get("/items/", headers=[("save-data", "true")])
+ assert response.status_code == 200
+ assert response.json() == {
+ "host": "testserver",
+ "save_data": True,
+ "if_modified_since": None,
+ "traceparent": None,
+ "x_tag": [],
+ }
+
+
+def test_header_param_model_invalid(client: TestClient):
+ response = client.get("/items/")
+ assert response.status_code == 422
+ assert response.json() == snapshot(
+ {
+ "detail": [
+ IsDict(
+ {
+ "type": "missing",
+ "loc": ["header", "save_data"],
+ "msg": "Field required",
+ "input": {"x_tag": [], "host": "testserver"},
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "value_error.missing",
+ "loc": ["header", "save_data"],
+ "msg": "field required",
+ }
+ )
+ ]
+ }
+ )
+
+
+def test_header_param_model_extra(client: TestClient):
+ response = client.get(
+ "/items/", headers=[("save-data", "true"), ("tool", "plumbus")]
+ )
+ assert response.status_code == 422, response.text
+ assert response.json() == snapshot(
+ {
+ "detail": [
+ IsDict(
+ {
+ "type": "extra_forbidden",
+ "loc": ["header", "tool"],
+ "msg": "Extra inputs are not permitted",
+ "input": "plumbus",
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "value_error.extra",
+ "loc": ["header", "tool"],
+ "msg": "extra fields not permitted",
+ }
+ )
+ ]
+ }
+ )
+
+
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == snapshot(
+ {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/items/": {
+ "get": {
+ "summary": "Read Items",
+ "operationId": "read_items_items__get",
+ "parameters": [
+ {
+ "name": "host",
+ "in": "header",
+ "required": True,
+ "schema": {"type": "string", "title": "Host"},
+ },
+ {
+ "name": "save_data",
+ "in": "header",
+ "required": True,
+ "schema": {"type": "boolean", "title": "Save Data"},
+ },
+ {
+ "name": "if_modified_since",
+ "in": "header",
+ "required": False,
+ "schema": IsDict(
+ {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "If Modified Since",
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "string",
+ "title": "If Modified Since",
+ }
+ ),
+ },
+ {
+ "name": "traceparent",
+ "in": "header",
+ "required": False,
+ "schema": IsDict(
+ {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Traceparent",
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "string",
+ "title": "Traceparent",
+ }
+ ),
+ },
+ {
+ "name": "x_tag",
+ "in": "header",
+ "required": False,
+ "schema": {
+ "type": "array",
+ "items": {"type": "string"},
+ "default": [],
+ "title": "X Tag",
+ },
+ },
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "HTTPValidationError": {
+ "properties": {
+ "detail": {
+ "items": {
+ "$ref": "#/components/schemas/ValidationError"
+ },
+ "type": "array",
+ "title": "Detail",
+ }
+ },
+ "type": "object",
+ "title": "HTTPValidationError",
+ },
+ "ValidationError": {
+ "properties": {
+ "loc": {
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ "type": "array",
+ "title": "Location",
+ },
+ "msg": {"type": "string", "title": "Message"},
+ "type": {"type": "string", "title": "Error Type"},
+ },
+ "type": "object",
+ "required": ["loc", "msg", "type"],
+ "title": "ValidationError",
+ },
+ }
+ },
+ }
+ )
diff --git a/tests/test_tutorial/test_query_param_models/__init__.py b/tests/test_tutorial/test_query_param_models/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/test_tutorial/test_query_param_models/test_tutorial001.py b/tests/test_tutorial/test_query_param_models/test_tutorial001.py
new file mode 100644
index 000000000..5b7bc7b42
--- /dev/null
+++ b/tests/test_tutorial/test_query_param_models/test_tutorial001.py
@@ -0,0 +1,260 @@
+import importlib
+
+import pytest
+from dirty_equals import IsDict
+from fastapi.testclient import TestClient
+from inline_snapshot import snapshot
+
+from tests.utils import needs_py39, needs_py310
+
+
+@pytest.fixture(
+ name="client",
+ params=[
+ "tutorial001",
+ pytest.param("tutorial001_py39", marks=needs_py39),
+ pytest.param("tutorial001_py310", marks=needs_py310),
+ "tutorial001_an",
+ pytest.param("tutorial001_an_py39", marks=needs_py39),
+ pytest.param("tutorial001_an_py310", marks=needs_py310),
+ ],
+)
+def get_client(request: pytest.FixtureRequest):
+ mod = importlib.import_module(f"docs_src.query_param_models.{request.param}")
+
+ client = TestClient(mod.app)
+ return client
+
+
+def test_query_param_model(client: TestClient):
+ response = client.get(
+ "/items/",
+ params={
+ "limit": 10,
+ "offset": 5,
+ "order_by": "updated_at",
+ "tags": ["tag1", "tag2"],
+ },
+ )
+ assert response.status_code == 200
+ assert response.json() == {
+ "limit": 10,
+ "offset": 5,
+ "order_by": "updated_at",
+ "tags": ["tag1", "tag2"],
+ }
+
+
+def test_query_param_model_defaults(client: TestClient):
+ response = client.get("/items/")
+ assert response.status_code == 200
+ assert response.json() == {
+ "limit": 100,
+ "offset": 0,
+ "order_by": "created_at",
+ "tags": [],
+ }
+
+
+def test_query_param_model_invalid(client: TestClient):
+ response = client.get(
+ "/items/",
+ params={
+ "limit": 150,
+ "offset": -1,
+ "order_by": "invalid",
+ },
+ )
+ assert response.status_code == 422
+ assert response.json() == snapshot(
+ IsDict(
+ {
+ "detail": [
+ {
+ "type": "less_than_equal",
+ "loc": ["query", "limit"],
+ "msg": "Input should be less than or equal to 100",
+ "input": "150",
+ "ctx": {"le": 100},
+ },
+ {
+ "type": "greater_than_equal",
+ "loc": ["query", "offset"],
+ "msg": "Input should be greater than or equal to 0",
+ "input": "-1",
+ "ctx": {"ge": 0},
+ },
+ {
+ "type": "literal_error",
+ "loc": ["query", "order_by"],
+ "msg": "Input should be 'created_at' or 'updated_at'",
+ "input": "invalid",
+ "ctx": {"expected": "'created_at' or 'updated_at'"},
+ },
+ ]
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "type": "value_error.number.not_le",
+ "loc": ["query", "limit"],
+ "msg": "ensure this value is less than or equal to 100",
+ "ctx": {"limit_value": 100},
+ },
+ {
+ "type": "value_error.number.not_ge",
+ "loc": ["query", "offset"],
+ "msg": "ensure this value is greater than or equal to 0",
+ "ctx": {"limit_value": 0},
+ },
+ {
+ "type": "value_error.const",
+ "loc": ["query", "order_by"],
+ "msg": "unexpected value; permitted: 'created_at', 'updated_at'",
+ "ctx": {
+ "given": "invalid",
+ "permitted": ["created_at", "updated_at"],
+ },
+ },
+ ]
+ }
+ )
+ )
+
+
+def test_query_param_model_extra(client: TestClient):
+ response = client.get(
+ "/items/",
+ params={
+ "limit": 10,
+ "offset": 5,
+ "order_by": "updated_at",
+ "tags": ["tag1", "tag2"],
+ "tool": "plumbus",
+ },
+ )
+ assert response.status_code == 200
+ assert response.json() == {
+ "limit": 10,
+ "offset": 5,
+ "order_by": "updated_at",
+ "tags": ["tag1", "tag2"],
+ }
+
+
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == snapshot(
+ {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/items/": {
+ "get": {
+ "summary": "Read Items",
+ "operationId": "read_items_items__get",
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "required": False,
+ "schema": {
+ "type": "integer",
+ "maximum": 100,
+ "exclusiveMinimum": 0,
+ "default": 100,
+ "title": "Limit",
+ },
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "required": False,
+ "schema": {
+ "type": "integer",
+ "minimum": 0,
+ "default": 0,
+ "title": "Offset",
+ },
+ },
+ {
+ "name": "order_by",
+ "in": "query",
+ "required": False,
+ "schema": {
+ "enum": ["created_at", "updated_at"],
+ "type": "string",
+ "default": "created_at",
+ "title": "Order By",
+ },
+ },
+ {
+ "name": "tags",
+ "in": "query",
+ "required": False,
+ "schema": {
+ "type": "array",
+ "items": {"type": "string"},
+ "default": [],
+ "title": "Tags",
+ },
+ },
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "HTTPValidationError": {
+ "properties": {
+ "detail": {
+ "items": {
+ "$ref": "#/components/schemas/ValidationError"
+ },
+ "type": "array",
+ "title": "Detail",
+ }
+ },
+ "type": "object",
+ "title": "HTTPValidationError",
+ },
+ "ValidationError": {
+ "properties": {
+ "loc": {
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ "type": "array",
+ "title": "Location",
+ },
+ "msg": {"type": "string", "title": "Message"},
+ "type": {"type": "string", "title": "Error Type"},
+ },
+ "type": "object",
+ "required": ["loc", "msg", "type"],
+ "title": "ValidationError",
+ },
+ }
+ },
+ }
+ )
diff --git a/tests/test_tutorial/test_query_param_models/test_tutorial002.py b/tests/test_tutorial/test_query_param_models/test_tutorial002.py
new file mode 100644
index 000000000..4432c9d8a
--- /dev/null
+++ b/tests/test_tutorial/test_query_param_models/test_tutorial002.py
@@ -0,0 +1,282 @@
+import importlib
+
+import pytest
+from dirty_equals import IsDict
+from fastapi.testclient import TestClient
+from inline_snapshot import snapshot
+
+from tests.utils import needs_py39, needs_py310, needs_pydanticv1, needs_pydanticv2
+
+
+@pytest.fixture(
+ name="client",
+ params=[
+ pytest.param("tutorial002", marks=needs_pydanticv2),
+ pytest.param("tutorial002_py39", marks=[needs_py39, needs_pydanticv2]),
+ pytest.param("tutorial002_py310", marks=[needs_py310, needs_pydanticv2]),
+ pytest.param("tutorial002_an", marks=needs_pydanticv2),
+ pytest.param("tutorial002_an_py39", marks=[needs_py39, needs_pydanticv2]),
+ pytest.param("tutorial002_an_py310", marks=[needs_py310, needs_pydanticv2]),
+ pytest.param("tutorial002_pv1", marks=[needs_pydanticv1, needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_py39", marks=[needs_py39, needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_py310", marks=[needs_py310, needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_an", marks=[needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_an_py39", marks=[needs_py39, needs_pydanticv1]),
+ pytest.param("tutorial002_pv1_an_py310", marks=[needs_py310, needs_pydanticv1]),
+ ],
+)
+def get_client(request: pytest.FixtureRequest):
+ mod = importlib.import_module(f"docs_src.query_param_models.{request.param}")
+
+ client = TestClient(mod.app)
+ return client
+
+
+def test_query_param_model(client: TestClient):
+ response = client.get(
+ "/items/",
+ params={
+ "limit": 10,
+ "offset": 5,
+ "order_by": "updated_at",
+ "tags": ["tag1", "tag2"],
+ },
+ )
+ assert response.status_code == 200
+ assert response.json() == {
+ "limit": 10,
+ "offset": 5,
+ "order_by": "updated_at",
+ "tags": ["tag1", "tag2"],
+ }
+
+
+def test_query_param_model_defaults(client: TestClient):
+ response = client.get("/items/")
+ assert response.status_code == 200
+ assert response.json() == {
+ "limit": 100,
+ "offset": 0,
+ "order_by": "created_at",
+ "tags": [],
+ }
+
+
+def test_query_param_model_invalid(client: TestClient):
+ response = client.get(
+ "/items/",
+ params={
+ "limit": 150,
+ "offset": -1,
+ "order_by": "invalid",
+ },
+ )
+ assert response.status_code == 422
+ assert response.json() == snapshot(
+ IsDict(
+ {
+ "detail": [
+ {
+ "type": "less_than_equal",
+ "loc": ["query", "limit"],
+ "msg": "Input should be less than or equal to 100",
+ "input": "150",
+ "ctx": {"le": 100},
+ },
+ {
+ "type": "greater_than_equal",
+ "loc": ["query", "offset"],
+ "msg": "Input should be greater than or equal to 0",
+ "input": "-1",
+ "ctx": {"ge": 0},
+ },
+ {
+ "type": "literal_error",
+ "loc": ["query", "order_by"],
+ "msg": "Input should be 'created_at' or 'updated_at'",
+ "input": "invalid",
+ "ctx": {"expected": "'created_at' or 'updated_at'"},
+ },
+ ]
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "type": "value_error.number.not_le",
+ "loc": ["query", "limit"],
+ "msg": "ensure this value is less than or equal to 100",
+ "ctx": {"limit_value": 100},
+ },
+ {
+ "type": "value_error.number.not_ge",
+ "loc": ["query", "offset"],
+ "msg": "ensure this value is greater than or equal to 0",
+ "ctx": {"limit_value": 0},
+ },
+ {
+ "type": "value_error.const",
+ "loc": ["query", "order_by"],
+ "msg": "unexpected value; permitted: 'created_at', 'updated_at'",
+ "ctx": {
+ "given": "invalid",
+ "permitted": ["created_at", "updated_at"],
+ },
+ },
+ ]
+ }
+ )
+ )
+
+
+def test_query_param_model_extra(client: TestClient):
+ response = client.get(
+ "/items/",
+ params={
+ "limit": 10,
+ "offset": 5,
+ "order_by": "updated_at",
+ "tags": ["tag1", "tag2"],
+ "tool": "plumbus",
+ },
+ )
+ assert response.status_code == 422
+ assert response.json() == snapshot(
+ {
+ "detail": [
+ IsDict(
+ {
+ "type": "extra_forbidden",
+ "loc": ["query", "tool"],
+ "msg": "Extra inputs are not permitted",
+ "input": "plumbus",
+ }
+ )
+ | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "type": "value_error.extra",
+ "loc": ["query", "tool"],
+ "msg": "extra fields not permitted",
+ }
+ )
+ ]
+ }
+ )
+
+
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == snapshot(
+ {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/items/": {
+ "get": {
+ "summary": "Read Items",
+ "operationId": "read_items_items__get",
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "required": False,
+ "schema": {
+ "type": "integer",
+ "maximum": 100,
+ "exclusiveMinimum": 0,
+ "default": 100,
+ "title": "Limit",
+ },
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "required": False,
+ "schema": {
+ "type": "integer",
+ "minimum": 0,
+ "default": 0,
+ "title": "Offset",
+ },
+ },
+ {
+ "name": "order_by",
+ "in": "query",
+ "required": False,
+ "schema": {
+ "enum": ["created_at", "updated_at"],
+ "type": "string",
+ "default": "created_at",
+ "title": "Order By",
+ },
+ },
+ {
+ "name": "tags",
+ "in": "query",
+ "required": False,
+ "schema": {
+ "type": "array",
+ "items": {"type": "string"},
+ "default": [],
+ "title": "Tags",
+ },
+ },
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "HTTPValidationError": {
+ "properties": {
+ "detail": {
+ "items": {
+ "$ref": "#/components/schemas/ValidationError"
+ },
+ "type": "array",
+ "title": "Detail",
+ }
+ },
+ "type": "object",
+ "title": "HTTPValidationError",
+ },
+ "ValidationError": {
+ "properties": {
+ "loc": {
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ "type": "array",
+ "title": "Location",
+ },
+ "msg": {"type": "string", "title": "Message"},
+ "type": {"type": "string", "title": "Error Type"},
+ },
+ "type": "object",
+ "required": ["loc", "msg", "type"],
+ "title": "ValidationError",
+ },
+ }
+ },
+ }
+ )
diff --git a/tests/test_tutorial/test_request_form_models/__init__.py b/tests/test_tutorial/test_request_form_models/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/test_tutorial/test_request_form_models/test_tutorial001.py b/tests/test_tutorial/test_request_form_models/test_tutorial001.py
new file mode 100644
index 000000000..46c130ee8
--- /dev/null
+++ b/tests/test_tutorial/test_request_form_models/test_tutorial001.py
@@ -0,0 +1,232 @@
+import pytest
+from dirty_equals import IsDict
+from fastapi.testclient import TestClient
+
+
+@pytest.fixture(name="client")
+def get_client():
+ from docs_src.request_form_models.tutorial001 import app
+
+ client = TestClient(app)
+ return client
+
+
+def test_post_body_form(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo", "password": "secret"})
+ assert response.status_code == 200
+ assert response.json() == {"username": "Foo", "password": "secret"}
+
+
+def test_post_body_form_no_password(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo"})
+ assert response.status_code == 422
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {"username": "Foo"},
+ }
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "password"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ }
+ ]
+ }
+ )
+
+
+def test_post_body_form_no_username(client: TestClient):
+ response = client.post("/login/", data={"password": "secret"})
+ assert response.status_code == 422
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {"password": "secret"},
+ }
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "username"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ }
+ ]
+ }
+ )
+
+
+def test_post_body_form_no_data(client: TestClient):
+ response = client.post("/login/")
+ assert response.status_code == 422
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {},
+ },
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "username"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ {
+ "loc": ["body", "password"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ ]
+ }
+ )
+
+
+def test_post_body_json(client: TestClient):
+ response = client.post("/login/", json={"username": "Foo", "password": "secret"})
+ assert response.status_code == 422, response.text
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {},
+ },
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "username"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ {
+ "loc": ["body", "password"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ ]
+ }
+ )
+
+
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/login/": {
+ "post": {
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ "summary": "Login",
+ "operationId": "login_login__post",
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {"$ref": "#/components/schemas/FormData"}
+ }
+ },
+ "required": True,
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "FormData": {
+ "properties": {
+ "username": {"type": "string", "title": "Username"},
+ "password": {"type": "string", "title": "Password"},
+ },
+ "type": "object",
+ "required": ["username", "password"],
+ "title": "FormData",
+ },
+ "ValidationError": {
+ "title": "ValidationError",
+ "required": ["loc", "msg", "type"],
+ "type": "object",
+ "properties": {
+ "loc": {
+ "title": "Location",
+ "type": "array",
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ },
+ "msg": {"title": "Message", "type": "string"},
+ "type": {"title": "Error Type", "type": "string"},
+ },
+ },
+ "HTTPValidationError": {
+ "title": "HTTPValidationError",
+ "type": "object",
+ "properties": {
+ "detail": {
+ "title": "Detail",
+ "type": "array",
+ "items": {"$ref": "#/components/schemas/ValidationError"},
+ }
+ },
+ },
+ }
+ },
+ }
diff --git a/tests/test_tutorial/test_request_form_models/test_tutorial001_an.py b/tests/test_tutorial/test_request_form_models/test_tutorial001_an.py
new file mode 100644
index 000000000..4e14d89c8
--- /dev/null
+++ b/tests/test_tutorial/test_request_form_models/test_tutorial001_an.py
@@ -0,0 +1,232 @@
+import pytest
+from dirty_equals import IsDict
+from fastapi.testclient import TestClient
+
+
+@pytest.fixture(name="client")
+def get_client():
+ from docs_src.request_form_models.tutorial001_an import app
+
+ client = TestClient(app)
+ return client
+
+
+def test_post_body_form(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo", "password": "secret"})
+ assert response.status_code == 200
+ assert response.json() == {"username": "Foo", "password": "secret"}
+
+
+def test_post_body_form_no_password(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo"})
+ assert response.status_code == 422
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {"username": "Foo"},
+ }
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "password"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ }
+ ]
+ }
+ )
+
+
+def test_post_body_form_no_username(client: TestClient):
+ response = client.post("/login/", data={"password": "secret"})
+ assert response.status_code == 422
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {"password": "secret"},
+ }
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "username"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ }
+ ]
+ }
+ )
+
+
+def test_post_body_form_no_data(client: TestClient):
+ response = client.post("/login/")
+ assert response.status_code == 422
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {},
+ },
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "username"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ {
+ "loc": ["body", "password"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ ]
+ }
+ )
+
+
+def test_post_body_json(client: TestClient):
+ response = client.post("/login/", json={"username": "Foo", "password": "secret"})
+ assert response.status_code == 422, response.text
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {},
+ },
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "username"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ {
+ "loc": ["body", "password"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ ]
+ }
+ )
+
+
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/login/": {
+ "post": {
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ "summary": "Login",
+ "operationId": "login_login__post",
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {"$ref": "#/components/schemas/FormData"}
+ }
+ },
+ "required": True,
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "FormData": {
+ "properties": {
+ "username": {"type": "string", "title": "Username"},
+ "password": {"type": "string", "title": "Password"},
+ },
+ "type": "object",
+ "required": ["username", "password"],
+ "title": "FormData",
+ },
+ "ValidationError": {
+ "title": "ValidationError",
+ "required": ["loc", "msg", "type"],
+ "type": "object",
+ "properties": {
+ "loc": {
+ "title": "Location",
+ "type": "array",
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ },
+ "msg": {"title": "Message", "type": "string"},
+ "type": {"title": "Error Type", "type": "string"},
+ },
+ },
+ "HTTPValidationError": {
+ "title": "HTTPValidationError",
+ "type": "object",
+ "properties": {
+ "detail": {
+ "title": "Detail",
+ "type": "array",
+ "items": {"$ref": "#/components/schemas/ValidationError"},
+ }
+ },
+ },
+ }
+ },
+ }
diff --git a/tests/test_tutorial/test_request_form_models/test_tutorial001_an_py39.py b/tests/test_tutorial/test_request_form_models/test_tutorial001_an_py39.py
new file mode 100644
index 000000000..2e6426aa7
--- /dev/null
+++ b/tests/test_tutorial/test_request_form_models/test_tutorial001_an_py39.py
@@ -0,0 +1,240 @@
+import pytest
+from dirty_equals import IsDict
+from fastapi.testclient import TestClient
+
+from tests.utils import needs_py39
+
+
+@pytest.fixture(name="client")
+def get_client():
+ from docs_src.request_form_models.tutorial001_an_py39 import app
+
+ client = TestClient(app)
+ return client
+
+
+@needs_py39
+def test_post_body_form(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo", "password": "secret"})
+ assert response.status_code == 200
+ assert response.json() == {"username": "Foo", "password": "secret"}
+
+
+@needs_py39
+def test_post_body_form_no_password(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo"})
+ assert response.status_code == 422
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {"username": "Foo"},
+ }
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "password"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ }
+ ]
+ }
+ )
+
+
+@needs_py39
+def test_post_body_form_no_username(client: TestClient):
+ response = client.post("/login/", data={"password": "secret"})
+ assert response.status_code == 422
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {"password": "secret"},
+ }
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "username"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ }
+ ]
+ }
+ )
+
+
+@needs_py39
+def test_post_body_form_no_data(client: TestClient):
+ response = client.post("/login/")
+ assert response.status_code == 422
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {},
+ },
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "username"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ {
+ "loc": ["body", "password"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ ]
+ }
+ )
+
+
+@needs_py39
+def test_post_body_json(client: TestClient):
+ response = client.post("/login/", json={"username": "Foo", "password": "secret"})
+ assert response.status_code == 422, response.text
+ assert response.json() == IsDict(
+ {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {},
+ },
+ ]
+ }
+ ) | IsDict(
+ # TODO: remove when deprecating Pydantic v1
+ {
+ "detail": [
+ {
+ "loc": ["body", "username"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ {
+ "loc": ["body", "password"],
+ "msg": "field required",
+ "type": "value_error.missing",
+ },
+ ]
+ }
+ )
+
+
+@needs_py39
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/login/": {
+ "post": {
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ "summary": "Login",
+ "operationId": "login_login__post",
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {"$ref": "#/components/schemas/FormData"}
+ }
+ },
+ "required": True,
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "FormData": {
+ "properties": {
+ "username": {"type": "string", "title": "Username"},
+ "password": {"type": "string", "title": "Password"},
+ },
+ "type": "object",
+ "required": ["username", "password"],
+ "title": "FormData",
+ },
+ "ValidationError": {
+ "title": "ValidationError",
+ "required": ["loc", "msg", "type"],
+ "type": "object",
+ "properties": {
+ "loc": {
+ "title": "Location",
+ "type": "array",
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ },
+ "msg": {"title": "Message", "type": "string"},
+ "type": {"title": "Error Type", "type": "string"},
+ },
+ },
+ "HTTPValidationError": {
+ "title": "HTTPValidationError",
+ "type": "object",
+ "properties": {
+ "detail": {
+ "title": "Detail",
+ "type": "array",
+ "items": {"$ref": "#/components/schemas/ValidationError"},
+ }
+ },
+ },
+ }
+ },
+ }
diff --git a/tests/test_tutorial/test_request_form_models/test_tutorial002.py b/tests/test_tutorial/test_request_form_models/test_tutorial002.py
new file mode 100644
index 000000000..76f480001
--- /dev/null
+++ b/tests/test_tutorial/test_request_form_models/test_tutorial002.py
@@ -0,0 +1,196 @@
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.utils import needs_pydanticv2
+
+
+@pytest.fixture(name="client")
+def get_client():
+ from docs_src.request_form_models.tutorial002 import app
+
+ client = TestClient(app)
+ return client
+
+
+@needs_pydanticv2
+def test_post_body_form(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo", "password": "secret"})
+ assert response.status_code == 200
+ assert response.json() == {"username": "Foo", "password": "secret"}
+
+
+@needs_pydanticv2
+def test_post_body_extra_form(client: TestClient):
+ response = client.post(
+ "/login/", data={"username": "Foo", "password": "secret", "extra": "extra"}
+ )
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "extra_forbidden",
+ "loc": ["body", "extra"],
+ "msg": "Extra inputs are not permitted",
+ "input": "extra",
+ }
+ ]
+ }
+
+
+@needs_pydanticv2
+def test_post_body_form_no_password(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo"})
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {"username": "Foo"},
+ }
+ ]
+ }
+
+
+@needs_pydanticv2
+def test_post_body_form_no_username(client: TestClient):
+ response = client.post("/login/", data={"password": "secret"})
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {"password": "secret"},
+ }
+ ]
+ }
+
+
+@needs_pydanticv2
+def test_post_body_form_no_data(client: TestClient):
+ response = client.post("/login/")
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {},
+ },
+ ]
+ }
+
+
+@needs_pydanticv2
+def test_post_body_json(client: TestClient):
+ response = client.post("/login/", json={"username": "Foo", "password": "secret"})
+ assert response.status_code == 422, response.text
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {},
+ },
+ ]
+ }
+
+
+@needs_pydanticv2
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/login/": {
+ "post": {
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ "summary": "Login",
+ "operationId": "login_login__post",
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {"$ref": "#/components/schemas/FormData"}
+ }
+ },
+ "required": True,
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "FormData": {
+ "properties": {
+ "username": {"type": "string", "title": "Username"},
+ "password": {"type": "string", "title": "Password"},
+ },
+ "additionalProperties": False,
+ "type": "object",
+ "required": ["username", "password"],
+ "title": "FormData",
+ },
+ "ValidationError": {
+ "title": "ValidationError",
+ "required": ["loc", "msg", "type"],
+ "type": "object",
+ "properties": {
+ "loc": {
+ "title": "Location",
+ "type": "array",
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ },
+ "msg": {"title": "Message", "type": "string"},
+ "type": {"title": "Error Type", "type": "string"},
+ },
+ },
+ "HTTPValidationError": {
+ "title": "HTTPValidationError",
+ "type": "object",
+ "properties": {
+ "detail": {
+ "title": "Detail",
+ "type": "array",
+ "items": {"$ref": "#/components/schemas/ValidationError"},
+ }
+ },
+ },
+ }
+ },
+ }
diff --git a/tests/test_tutorial/test_request_form_models/test_tutorial002_an.py b/tests/test_tutorial/test_request_form_models/test_tutorial002_an.py
new file mode 100644
index 000000000..179b2977d
--- /dev/null
+++ b/tests/test_tutorial/test_request_form_models/test_tutorial002_an.py
@@ -0,0 +1,196 @@
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.utils import needs_pydanticv2
+
+
+@pytest.fixture(name="client")
+def get_client():
+ from docs_src.request_form_models.tutorial002_an import app
+
+ client = TestClient(app)
+ return client
+
+
+@needs_pydanticv2
+def test_post_body_form(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo", "password": "secret"})
+ assert response.status_code == 200
+ assert response.json() == {"username": "Foo", "password": "secret"}
+
+
+@needs_pydanticv2
+def test_post_body_extra_form(client: TestClient):
+ response = client.post(
+ "/login/", data={"username": "Foo", "password": "secret", "extra": "extra"}
+ )
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "extra_forbidden",
+ "loc": ["body", "extra"],
+ "msg": "Extra inputs are not permitted",
+ "input": "extra",
+ }
+ ]
+ }
+
+
+@needs_pydanticv2
+def test_post_body_form_no_password(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo"})
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {"username": "Foo"},
+ }
+ ]
+ }
+
+
+@needs_pydanticv2
+def test_post_body_form_no_username(client: TestClient):
+ response = client.post("/login/", data={"password": "secret"})
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {"password": "secret"},
+ }
+ ]
+ }
+
+
+@needs_pydanticv2
+def test_post_body_form_no_data(client: TestClient):
+ response = client.post("/login/")
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {},
+ },
+ ]
+ }
+
+
+@needs_pydanticv2
+def test_post_body_json(client: TestClient):
+ response = client.post("/login/", json={"username": "Foo", "password": "secret"})
+ assert response.status_code == 422, response.text
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {},
+ },
+ ]
+ }
+
+
+@needs_pydanticv2
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/login/": {
+ "post": {
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ "summary": "Login",
+ "operationId": "login_login__post",
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {"$ref": "#/components/schemas/FormData"}
+ }
+ },
+ "required": True,
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "FormData": {
+ "properties": {
+ "username": {"type": "string", "title": "Username"},
+ "password": {"type": "string", "title": "Password"},
+ },
+ "additionalProperties": False,
+ "type": "object",
+ "required": ["username", "password"],
+ "title": "FormData",
+ },
+ "ValidationError": {
+ "title": "ValidationError",
+ "required": ["loc", "msg", "type"],
+ "type": "object",
+ "properties": {
+ "loc": {
+ "title": "Location",
+ "type": "array",
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ },
+ "msg": {"title": "Message", "type": "string"},
+ "type": {"title": "Error Type", "type": "string"},
+ },
+ },
+ "HTTPValidationError": {
+ "title": "HTTPValidationError",
+ "type": "object",
+ "properties": {
+ "detail": {
+ "title": "Detail",
+ "type": "array",
+ "items": {"$ref": "#/components/schemas/ValidationError"},
+ }
+ },
+ },
+ }
+ },
+ }
diff --git a/tests/test_tutorial/test_request_form_models/test_tutorial002_an_py39.py b/tests/test_tutorial/test_request_form_models/test_tutorial002_an_py39.py
new file mode 100644
index 000000000..510ad9d7c
--- /dev/null
+++ b/tests/test_tutorial/test_request_form_models/test_tutorial002_an_py39.py
@@ -0,0 +1,203 @@
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.utils import needs_py39, needs_pydanticv2
+
+
+@pytest.fixture(name="client")
+def get_client():
+ from docs_src.request_form_models.tutorial002_an_py39 import app
+
+ client = TestClient(app)
+ return client
+
+
+@needs_pydanticv2
+@needs_py39
+def test_post_body_form(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo", "password": "secret"})
+ assert response.status_code == 200
+ assert response.json() == {"username": "Foo", "password": "secret"}
+
+
+@needs_pydanticv2
+@needs_py39
+def test_post_body_extra_form(client: TestClient):
+ response = client.post(
+ "/login/", data={"username": "Foo", "password": "secret", "extra": "extra"}
+ )
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "extra_forbidden",
+ "loc": ["body", "extra"],
+ "msg": "Extra inputs are not permitted",
+ "input": "extra",
+ }
+ ]
+ }
+
+
+@needs_pydanticv2
+@needs_py39
+def test_post_body_form_no_password(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo"})
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {"username": "Foo"},
+ }
+ ]
+ }
+
+
+@needs_pydanticv2
+@needs_py39
+def test_post_body_form_no_username(client: TestClient):
+ response = client.post("/login/", data={"password": "secret"})
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {"password": "secret"},
+ }
+ ]
+ }
+
+
+@needs_pydanticv2
+@needs_py39
+def test_post_body_form_no_data(client: TestClient):
+ response = client.post("/login/")
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {},
+ },
+ ]
+ }
+
+
+@needs_pydanticv2
+@needs_py39
+def test_post_body_json(client: TestClient):
+ response = client.post("/login/", json={"username": "Foo", "password": "secret"})
+ assert response.status_code == 422, response.text
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "missing",
+ "loc": ["body", "username"],
+ "msg": "Field required",
+ "input": {},
+ },
+ {
+ "type": "missing",
+ "loc": ["body", "password"],
+ "msg": "Field required",
+ "input": {},
+ },
+ ]
+ }
+
+
+@needs_pydanticv2
+@needs_py39
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/login/": {
+ "post": {
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ "summary": "Login",
+ "operationId": "login_login__post",
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {"$ref": "#/components/schemas/FormData"}
+ }
+ },
+ "required": True,
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "FormData": {
+ "properties": {
+ "username": {"type": "string", "title": "Username"},
+ "password": {"type": "string", "title": "Password"},
+ },
+ "additionalProperties": False,
+ "type": "object",
+ "required": ["username", "password"],
+ "title": "FormData",
+ },
+ "ValidationError": {
+ "title": "ValidationError",
+ "required": ["loc", "msg", "type"],
+ "type": "object",
+ "properties": {
+ "loc": {
+ "title": "Location",
+ "type": "array",
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ },
+ "msg": {"title": "Message", "type": "string"},
+ "type": {"title": "Error Type", "type": "string"},
+ },
+ },
+ "HTTPValidationError": {
+ "title": "HTTPValidationError",
+ "type": "object",
+ "properties": {
+ "detail": {
+ "title": "Detail",
+ "type": "array",
+ "items": {"$ref": "#/components/schemas/ValidationError"},
+ }
+ },
+ },
+ }
+ },
+ }
diff --git a/tests/test_tutorial/test_request_form_models/test_tutorial002_pv1.py b/tests/test_tutorial/test_request_form_models/test_tutorial002_pv1.py
new file mode 100644
index 000000000..249b9379d
--- /dev/null
+++ b/tests/test_tutorial/test_request_form_models/test_tutorial002_pv1.py
@@ -0,0 +1,189 @@
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.utils import needs_pydanticv1
+
+
+@pytest.fixture(name="client")
+def get_client():
+ from docs_src.request_form_models.tutorial002_pv1 import app
+
+ client = TestClient(app)
+ return client
+
+
+@needs_pydanticv1
+def test_post_body_form(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo", "password": "secret"})
+ assert response.status_code == 200
+ assert response.json() == {"username": "Foo", "password": "secret"}
+
+
+@needs_pydanticv1
+def test_post_body_extra_form(client: TestClient):
+ response = client.post(
+ "/login/", data={"username": "Foo", "password": "secret", "extra": "extra"}
+ )
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.extra",
+ "loc": ["body", "extra"],
+ "msg": "extra fields not permitted",
+ }
+ ]
+ }
+
+
+@needs_pydanticv1
+def test_post_body_form_no_password(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo"})
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "password"],
+ "msg": "field required",
+ }
+ ]
+ }
+
+
+@needs_pydanticv1
+def test_post_body_form_no_username(client: TestClient):
+ response = client.post("/login/", data={"password": "secret"})
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "username"],
+ "msg": "field required",
+ }
+ ]
+ }
+
+
+@needs_pydanticv1
+def test_post_body_form_no_data(client: TestClient):
+ response = client.post("/login/")
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "username"],
+ "msg": "field required",
+ },
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "password"],
+ "msg": "field required",
+ },
+ ]
+ }
+
+
+@needs_pydanticv1
+def test_post_body_json(client: TestClient):
+ response = client.post("/login/", json={"username": "Foo", "password": "secret"})
+ assert response.status_code == 422, response.text
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "username"],
+ "msg": "field required",
+ },
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "password"],
+ "msg": "field required",
+ },
+ ]
+ }
+
+
+@needs_pydanticv1
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/login/": {
+ "post": {
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ "summary": "Login",
+ "operationId": "login_login__post",
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {"$ref": "#/components/schemas/FormData"}
+ }
+ },
+ "required": True,
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "FormData": {
+ "properties": {
+ "username": {"type": "string", "title": "Username"},
+ "password": {"type": "string", "title": "Password"},
+ },
+ "additionalProperties": False,
+ "type": "object",
+ "required": ["username", "password"],
+ "title": "FormData",
+ },
+ "ValidationError": {
+ "title": "ValidationError",
+ "required": ["loc", "msg", "type"],
+ "type": "object",
+ "properties": {
+ "loc": {
+ "title": "Location",
+ "type": "array",
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ },
+ "msg": {"title": "Message", "type": "string"},
+ "type": {"title": "Error Type", "type": "string"},
+ },
+ },
+ "HTTPValidationError": {
+ "title": "HTTPValidationError",
+ "type": "object",
+ "properties": {
+ "detail": {
+ "title": "Detail",
+ "type": "array",
+ "items": {"$ref": "#/components/schemas/ValidationError"},
+ }
+ },
+ },
+ }
+ },
+ }
diff --git a/tests/test_tutorial/test_request_form_models/test_tutorial002_pv1_an.py b/tests/test_tutorial/test_request_form_models/test_tutorial002_pv1_an.py
new file mode 100644
index 000000000..44cb3c32b
--- /dev/null
+++ b/tests/test_tutorial/test_request_form_models/test_tutorial002_pv1_an.py
@@ -0,0 +1,196 @@
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.utils import needs_pydanticv1
+
+
+@pytest.fixture(name="client")
+def get_client():
+ from docs_src.request_form_models.tutorial002_pv1_an import app
+
+ client = TestClient(app)
+ return client
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+def test_post_body_form(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo", "password": "secret"})
+ assert response.status_code == 200
+ assert response.json() == {"username": "Foo", "password": "secret"}
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+def test_post_body_extra_form(client: TestClient):
+ response = client.post(
+ "/login/", data={"username": "Foo", "password": "secret", "extra": "extra"}
+ )
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.extra",
+ "loc": ["body", "extra"],
+ "msg": "extra fields not permitted",
+ }
+ ]
+ }
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+def test_post_body_form_no_password(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo"})
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "password"],
+ "msg": "field required",
+ }
+ ]
+ }
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+def test_post_body_form_no_username(client: TestClient):
+ response = client.post("/login/", data={"password": "secret"})
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "username"],
+ "msg": "field required",
+ }
+ ]
+ }
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+def test_post_body_form_no_data(client: TestClient):
+ response = client.post("/login/")
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "username"],
+ "msg": "field required",
+ },
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "password"],
+ "msg": "field required",
+ },
+ ]
+ }
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+def test_post_body_json(client: TestClient):
+ response = client.post("/login/", json={"username": "Foo", "password": "secret"})
+ assert response.status_code == 422, response.text
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "username"],
+ "msg": "field required",
+ },
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "password"],
+ "msg": "field required",
+ },
+ ]
+ }
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/login/": {
+ "post": {
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ "summary": "Login",
+ "operationId": "login_login__post",
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {"$ref": "#/components/schemas/FormData"}
+ }
+ },
+ "required": True,
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "FormData": {
+ "properties": {
+ "username": {"type": "string", "title": "Username"},
+ "password": {"type": "string", "title": "Password"},
+ },
+ "additionalProperties": False,
+ "type": "object",
+ "required": ["username", "password"],
+ "title": "FormData",
+ },
+ "ValidationError": {
+ "title": "ValidationError",
+ "required": ["loc", "msg", "type"],
+ "type": "object",
+ "properties": {
+ "loc": {
+ "title": "Location",
+ "type": "array",
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ },
+ "msg": {"title": "Message", "type": "string"},
+ "type": {"title": "Error Type", "type": "string"},
+ },
+ },
+ "HTTPValidationError": {
+ "title": "HTTPValidationError",
+ "type": "object",
+ "properties": {
+ "detail": {
+ "title": "Detail",
+ "type": "array",
+ "items": {"$ref": "#/components/schemas/ValidationError"},
+ }
+ },
+ },
+ }
+ },
+ }
diff --git a/tests/test_tutorial/test_request_form_models/test_tutorial002_pv1_an_p39.py b/tests/test_tutorial/test_request_form_models/test_tutorial002_pv1_an_p39.py
new file mode 100644
index 000000000..899549e40
--- /dev/null
+++ b/tests/test_tutorial/test_request_form_models/test_tutorial002_pv1_an_p39.py
@@ -0,0 +1,203 @@
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.utils import needs_py39, needs_pydanticv1
+
+
+@pytest.fixture(name="client")
+def get_client():
+ from docs_src.request_form_models.tutorial002_pv1_an_py39 import app
+
+ client = TestClient(app)
+ return client
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+@needs_py39
+def test_post_body_form(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo", "password": "secret"})
+ assert response.status_code == 200
+ assert response.json() == {"username": "Foo", "password": "secret"}
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+@needs_py39
+def test_post_body_extra_form(client: TestClient):
+ response = client.post(
+ "/login/", data={"username": "Foo", "password": "secret", "extra": "extra"}
+ )
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.extra",
+ "loc": ["body", "extra"],
+ "msg": "extra fields not permitted",
+ }
+ ]
+ }
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+@needs_py39
+def test_post_body_form_no_password(client: TestClient):
+ response = client.post("/login/", data={"username": "Foo"})
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "password"],
+ "msg": "field required",
+ }
+ ]
+ }
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+@needs_py39
+def test_post_body_form_no_username(client: TestClient):
+ response = client.post("/login/", data={"password": "secret"})
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "username"],
+ "msg": "field required",
+ }
+ ]
+ }
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+@needs_py39
+def test_post_body_form_no_data(client: TestClient):
+ response = client.post("/login/")
+ assert response.status_code == 422
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "username"],
+ "msg": "field required",
+ },
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "password"],
+ "msg": "field required",
+ },
+ ]
+ }
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+@needs_py39
+def test_post_body_json(client: TestClient):
+ response = client.post("/login/", json={"username": "Foo", "password": "secret"})
+ assert response.status_code == 422, response.text
+ assert response.json() == {
+ "detail": [
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "username"],
+ "msg": "field required",
+ },
+ {
+ "type": "value_error.missing",
+ "loc": ["body", "password"],
+ "msg": "field required",
+ },
+ ]
+ }
+
+
+# TODO: remove when deprecating Pydantic v1
+@needs_pydanticv1
+@needs_py39
+def test_openapi_schema(client: TestClient):
+ response = client.get("/openapi.json")
+ assert response.status_code == 200, response.text
+ assert response.json() == {
+ "openapi": "3.1.0",
+ "info": {"title": "FastAPI", "version": "0.1.0"},
+ "paths": {
+ "/login/": {
+ "post": {
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {"application/json": {"schema": {}}},
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ },
+ },
+ "summary": "Login",
+ "operationId": "login_login__post",
+ "requestBody": {
+ "content": {
+ "application/x-www-form-urlencoded": {
+ "schema": {"$ref": "#/components/schemas/FormData"}
+ }
+ },
+ "required": True,
+ },
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "FormData": {
+ "properties": {
+ "username": {"type": "string", "title": "Username"},
+ "password": {"type": "string", "title": "Password"},
+ },
+ "additionalProperties": False,
+ "type": "object",
+ "required": ["username", "password"],
+ "title": "FormData",
+ },
+ "ValidationError": {
+ "title": "ValidationError",
+ "required": ["loc", "msg", "type"],
+ "type": "object",
+ "properties": {
+ "loc": {
+ "title": "Location",
+ "type": "array",
+ "items": {
+ "anyOf": [{"type": "string"}, {"type": "integer"}]
+ },
+ },
+ "msg": {"title": "Message", "type": "string"},
+ "type": {"title": "Error Type", "type": "string"},
+ },
+ },
+ "HTTPValidationError": {
+ "title": "HTTPValidationError",
+ "type": "object",
+ "properties": {
+ "detail": {
+ "title": "Detail",
+ "type": "array",
+ "items": {"$ref": "#/components/schemas/ValidationError"},
+ }
+ },
+ },
+ }
+ },
+ }
-
+
-
@@ -132,6 +131,8 @@ FastAPI stands on the shoulders of giants:
## Installation
+Create and activate a virtual environment and then install FastAPI:
+
-And will be also used in the API docs inside each *path operation* that needs them:
+And will also be used in the API docs inside each *path operation* that needs them:
diff --git a/docs/en/docs/tutorial/cookie-param-models.md b/docs/en/docs/tutorial/cookie-param-models.md
new file mode 100644
index 000000000..2aa3a1f59
--- /dev/null
+++ b/docs/en/docs/tutorial/cookie-param-models.md
@@ -0,0 +1,154 @@
+# Cookie Parameter Models
+
+If you have a group of **cookies** that are related, you can create a **Pydantic model** to declare them. ๐ช
+
+This would allow you to **re-use the model** in **multiple places** and also to declare validations and metadata for all the parameters at once. ๐
+
+/// note
+
+This is supported since FastAPI version `0.115.0`. ๐ค
+
+///
+
+/// tip
+
+This same technique applies to `Query`, `Cookie`, and `Header`. ๐
+
+///
+
+## Cookies with a Pydantic Model
+
+Declare the **cookie** parameters that you need in a **Pydantic model**, and then declare the parameter as `Cookie`:
+
+//// tab | Python 3.10+
+
+```Python hl_lines="9-12 16"
+{!> ../../../docs_src/cookie_param_models/tutorial001_an_py310.py!}
+```
+
+////
+
+//// tab | Python 3.9+
+
+```Python hl_lines="9-12 16"
+{!> ../../../docs_src/cookie_param_models/tutorial001_an_py39.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="10-13 17"
+{!> ../../../docs_src/cookie_param_models/tutorial001_an.py!}
+```
+
+////
+
+//// tab | Python 3.10+ non-Annotated
+
+/// tip
+
+Prefer to use the `Annotated` version if possible.
+
+///
+
+```Python hl_lines="7-10 14"
+{!> ../../../docs_src/cookie_param_models/tutorial001_py310.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip
+
+Prefer to use the `Annotated` version if possible.
+
+///
+
+```Python hl_lines="9-12 16"
+{!> ../../../docs_src/cookie_param_models/tutorial001.py!}
+```
+
+////
+
+**FastAPI** will **extract** the data for **each field** from the **cookies** received in the request and give you the Pydantic model you defined.
+
+## Check the Docs
+
+You can see the defined cookies in the docs UI at `/docs`:
+
+
+
+
+
-
- 
