Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit d1215ff

Browse files
tiangolos-rigaud
tiangolo
authored and
s-rigaud
committed
✨ Add support for Pydantic models for parameters using Query, Cookie, Header (fastapi#12199)
1 parent d6b861b commit d1215ff

72 files changed

Lines changed: 3253 additions & 45 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/en/docs/img/tutorial/cookie-param-models/image01.png‎

44.2 KB
Loading

‎docs/en/docs/img/tutorial/header-param-models/image01.png‎

60.8 KB
Loading

‎docs/en/docs/img/tutorial/query-param-models/image01.png‎

44.5 KB
Loading

‎docs/en/docs/tutorial/cookie-param-models.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Cookie Parameter Models
2+
3+
If you have a group of **cookies** that are related, you can create a **Pydantic model** to declare them. 🍪
4+
5+
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. 😎
6+
7+
/// note
8+
9+
This is supported since FastAPI version `0.115.0`. 🤓
10+
11+
///
12+
13+
/// tip
14+
15+
This same technique applies to `Query`, `Cookie`, and `Header`. 😎
16+
17+
///
18+
19+
## Cookies with a Pydantic Model
20+
21+
Declare the **cookie** parameters that you need in a **Pydantic model**, and then declare the parameter as `Cookie`:
22+
23+
//// tab | Python 3.10+
24+
25+
```Python hl_lines="9-12 16"
26+
{!> ../../../docs_src/cookie_param_models/tutorial001_an_py310.py!}
27+
```
28+
29+
////
30+
31+
//// tab | Python 3.9+
32+
33+
```Python hl_lines="9-12 16"
34+
{!> ../../../docs_src/cookie_param_models/tutorial001_an_py39.py!}
35+
```
36+
37+
////
38+
39+
//// tab | Python 3.8+
40+
41+
```Python hl_lines="10-13 17"
42+
{!> ../../../docs_src/cookie_param_models/tutorial001_an.py!}
43+
```
44+
45+
////
46+
47+
//// tab | Python 3.10+ non-Annotated
48+
49+
/// tip
50+
51+
Prefer to use the `Annotated` version if possible.
52+
53+
///
54+
55+
```Python hl_lines="7-10 14"
56+
{!> ../../../docs_src/cookie_param_models/tutorial001_py310.py!}
57+
```
58+
59+
////
60+
61+
//// tab | Python 3.8+ non-Annotated
62+
63+
/// tip
64+
65+
Prefer to use the `Annotated` version if possible.
66+
67+
///
68+
69+
```Python hl_lines="9-12 16"
70+
{!> ../../../docs_src/cookie_param_models/tutorial001.py!}
71+
```
72+
73+
////
74+
75+
**FastAPI** will **extract** the data for **each field** from the **cookies** received in the request and give you the Pydantic model you defined.
76+
77+
## Check the Docs
78+
79+
You can see the defined cookies in the docs UI at `/docs`:
80+
81+
<div class="screenshot">
82+
<img src="/img/tutorial/cookie-param-models/image01.png">
83+
</div>
84+
85+
/// info
86+
87+
Have in mind that, as **browsers handle cookies** in special ways and behind the scenes, they **don't** easily allow **JavaScript** to touch them.
88+
89+
If you go to the **API docs UI** at `/docs` you will be able to see the **documentation** for cookies for your *path operations*.
90+
91+
But even if you **fill the data** and click "Execute", because the docs UI works with **JavaScript**, the cookies won't be sent, and you will see an **error** message as if you didn't write any values.
92+
93+
///
94+
95+
## Forbid Extra Cookies
96+
97+
In some special use cases (probably not very common), you might want to **restrict** the cookies that you want to receive.
98+
99+
Your API now has the power to control its own <abbr title="This is a joke, just in case. It has nothing to do with cookie consents, but it's funny that even the API can now reject the poor cookies. Have a cookie. 🍪">cookie consent</abbr>. 🤪🍪
100+
101+
You can use Pydantic's model configuration to `forbid` any `extra` fields:
102+
103+
//// tab | Python 3.9+
104+
105+
```Python hl_lines="10"
106+
{!> ../../../docs_src/cookie_param_models/tutorial002_an_py39.py!}
107+
```
108+
109+
////
110+
111+
//// tab | Python 3.8+
112+
113+
```Python hl_lines="11"
114+
{!> ../../../docs_src/cookie_param_models/tutorial002_an.py!}
115+
```
116+
117+
////
118+
119+
//// tab | Python 3.8+ non-Annotated
120+
121+
/// tip
122+
123+
Prefer to use the `Annotated` version if possible.
124+
125+
///
126+
127+
```Python hl_lines="10"
128+
{!> ../../../docs_src/cookie_param_models/tutorial002.py!}
129+
```
130+
131+
////
132+
133+
If a client tries to send some **extra cookies**, they will receive an **error** response.
134+
135+
Poor cookie banners with all their effort to get your consent for the <abbr title="This is another joke. Don't pay attention to me. Have some coffee for your cookie. ☕">API to reject it</abbr>. 🍪
136+
137+
For example, if the client tries to send a `santa_tracker` cookie with a value of `good-list-please`, the client will receive an **error** response telling them that the `santa_tracker` <abbr title="Santa disapproves the lack of cookies. 🎅 Okay, no more cookie jokes.">cookie is not allowed</abbr>:
138+
139+
```json
140+
{
141+
"detail": [
142+
{
143+
"type": "extra_forbidden",
144+
"loc": ["cookie", "santa_tracker"],
145+
"msg": "Extra inputs are not permitted",
146+
"input": "good-list-please",
147+
}
148+
]
149+
}
150+
```
151+
152+
## Summary
153+
154+
You can use **Pydantic models** to declare <abbr title="Have a last cookie before you go. 🍪">**cookies**</abbr> in **FastAPI**. 😎

‎docs/en/docs/tutorial/header-param-models.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Header Parameter Models
2+
3+
If you have a group of related **header parameters**, you can create a **Pydantic model** to declare them.
4+
5+
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. 😎
6+
7+
/// note
8+
9+
This is supported since FastAPI version `0.115.0`. 🤓
10+
11+
///
12+
13+
## Header Parameters with a Pydantic Model
14+
15+
Declare the **header parameters** that you need in a **Pydantic model**, and then declare the parameter as `Header`:
16+
17+
//// tab | Python 3.10+
18+
19+
```Python hl_lines="9-14 18"
20+
{!> ../../../docs_src/header_param_models/tutorial001_an_py310.py!}
21+
```
22+
23+
////
24+
25+
//// tab | Python 3.9+
26+
27+
```Python hl_lines="9-14 18"
28+
{!> ../../../docs_src/header_param_models/tutorial001_an_py39.py!}
29+
```
30+
31+
////
32+
33+
//// tab | Python 3.8+
34+
35+
```Python hl_lines="10-15 19"
36+
{!> ../../../docs_src/header_param_models/tutorial001_an.py!}
37+
```
38+
39+
////
40+
41+
//// tab | Python 3.10+ non-Annotated
42+
43+
/// tip
44+
45+
Prefer to use the `Annotated` version if possible.
46+
47+
///
48+
49+
```Python hl_lines="7-12 16"
50+
{!> ../../../docs_src/header_param_models/tutorial001_py310.py!}
51+
```
52+
53+
////
54+
55+
//// tab | Python 3.9+ non-Annotated
56+
57+
/// tip
58+
59+
Prefer to use the `Annotated` version if possible.
60+
61+
///
62+
63+
```Python hl_lines="9-14 18"
64+
{!> ../../../docs_src/header_param_models/tutorial001_py39.py!}
65+
```
66+
67+
////
68+
69+
//// tab | Python 3.8+ non-Annotated
70+
71+
/// tip
72+
73+
Prefer to use the `Annotated` version if possible.
74+
75+
///
76+
77+
```Python hl_lines="7-12 16"
78+
{!> ../../../docs_src/header_param_models/tutorial001_py310.py!}
79+
```
80+
81+
////
82+
83+
**FastAPI** will **extract** the data for **each field** from the **headers** in the request and give you the Pydantic model you defined.
84+
85+
## Check the Docs
86+
87+
You can see the required headers in the docs UI at `/docs`:
88+
89+
<div class="screenshot">
90+
<img src="/img/tutorial/header-param-models/image01.png">
91+
</div>
92+
93+
## Forbid Extra Headers
94+
95+
In some special use cases (probably not very common), you might want to **restrict** the headers that you want to receive.
96+
97+
You can use Pydantic's model configuration to `forbid` any `extra` fields:
98+
99+
//// tab | Python 3.10+
100+
101+
```Python hl_lines="10"
102+
{!> ../../../docs_src/header_param_models/tutorial002_an_py310.py!}
103+
```
104+
105+
////
106+
107+
//// tab | Python 3.9+
108+
109+
```Python hl_lines="10"
110+
{!> ../../../docs_src/header_param_models/tutorial002_an_py39.py!}
111+
```
112+
113+
////
114+
115+
//// tab | Python 3.8+
116+
117+
```Python hl_lines="11"
118+
{!> ../../../docs_src/header_param_models/tutorial002_an.py!}
119+
```
120+
121+
////
122+
123+
//// tab | Python 3.10+ non-Annotated
124+
125+
/// tip
126+
127+
Prefer to use the `Annotated` version if possible.
128+
129+
///
130+
131+
```Python hl_lines="8"
132+
{!> ../../../docs_src/header_param_models/tutorial002_py310.py!}
133+
```
134+
135+
////
136+
137+
//// tab | Python 3.9+ non-Annotated
138+
139+
/// tip
140+
141+
Prefer to use the `Annotated` version if possible.
142+
143+
///
144+
145+
```Python hl_lines="10"
146+
{!> ../../../docs_src/header_param_models/tutorial002_py39.py!}
147+
```
148+
149+
////
150+
151+
//// tab | Python 3.8+ non-Annotated
152+
153+
/// tip
154+
155+
Prefer to use the `Annotated` version if possible.
156+
157+
///
158+
159+
```Python hl_lines="10"
160+
{!> ../../../docs_src/header_param_models/tutorial002.py!}
161+
```
162+
163+
////
164+
165+
If a client tries to send some **extra headers**, they will receive an **error** response.
166+
167+
For example, if the client tries to send a `tool` header with a value of `plumbus`, they will receive an **error** response telling them that the header parameter `tool` is not allowed:
168+
169+
```json
170+
{
171+
"detail": [
172+
{
173+
"type": "extra_forbidden",
174+
"loc": ["header", "tool"],
175+
"msg": "Extra inputs are not permitted",
176+
"input": "plumbus",
177+
}
178+
]
179+
}
180+
```
181+
182+
## Summary
183+
184+
You can use **Pydantic models** to declare **headers** in **FastAPI**. 😎

0 commit comments

Comments
 (0)