You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -132,6 +132,8 @@ FastAPI stands on the shoulders of giants:
132
132
133
133
## Installation
134
134
135
+
Create and activate a <ahref="https://fastapi.tiangolo.com/virtual-environments/"class="external-link"target="_blank">virtual environment</a> and then install FastAPI:
136
+
135
137
<divclass="termy">
136
138
137
139
```console
@@ -392,7 +394,7 @@ Coming back to the previous code example, **FastAPI** will:
392
394
* Check if there is an optional query parameter named `q` (as in `http://127.0.0.1:8000/items/foo?q=somequery`) for `GET` requests.
393
395
* As the `q` parameter is declared with `= None`, it is optional.
394
396
* Without the `None` it would be required (as is the body in the case with `PUT`).
395
-
* For `PUT` requests to `/items/{item_id}`, Read the body as JSON:
397
+
* For `PUT` requests to `/items/{item_id}`, read the body as JSON:
396
398
* Check that it has a required attribute `name` that should be a `str`.
397
399
* Check that it has a required attribute `price` that has to be a `float`.
398
400
* Check that it has an optional attribute `is_offer`, that should be a `bool`, if present.
Copy file name to clipboardExpand all lines: docs/en/docs/advanced/custom-response.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,9 @@ By default, **FastAPI** will return the responses using `JSONResponse`.
4
4
5
5
You can override it by returning a `Response` directly as seen in [Return a Response directly](response-directly.md){.internal-link target=_blank}.
6
6
7
-
But if you return a `Response` directly, the data won't be automatically converted, and the documentation won't be automatically generated (for example, including the specific "media type", in the HTTP header `Content-Type` as part of the generated OpenAPI).
7
+
But if you return a `Response` directly (or any subclass, like `JSONResponse`), the data won't be automatically converted (even if you declare a `response_model`), and the documentation won't be automatically generated (for example, including the specific "media type", in the HTTP header `Content-Type` as part of the generated OpenAPI).
8
8
9
-
But you can also declare the `Response` that you want to be used, in the *path operation decorator*.
9
+
But you can also declare the `Response` that you want to be used (e.g. any `Response` subclass), in the *path operation decorator* using the `response_class` parameter.
10
10
11
11
The contents that you return from your *path operation function* will be put inside of that `Response`.
Copy file name to clipboardExpand all lines: docs/en/docs/advanced/response-directly.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,7 +28,7 @@ This gives you a lot of flexibility. You can return any data type, override any
28
28
29
29
## Using the `jsonable_encoder` in a `Response`
30
30
31
-
Because **FastAPI** doesn't do any change to a `Response` you return, you have to make sure it's contents are ready for it.
31
+
Because **FastAPI** doesn't do any change to a `Response` you return, you have to make sure its contents are ready for it.
32
32
33
33
For example, you cannot put a Pydantic model in a `JSONResponse` without first converting it to a `dict` with all the data types (like `datetime`, `UUID`, etc) converted to JSON-compatible types.
Copy file name to clipboardExpand all lines: docs/en/docs/advanced/settings.md
+4-122Lines changed: 4 additions & 122 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,143 +6,25 @@ Most of these settings are variable (can change), like database URLs. And many c
6
6
7
7
For this reason it's common to provide them in environment variables that are read by the application.
8
8
9
-
## Environment Variables
10
-
11
-
/// tip
12
-
13
-
If you already know what "environment variables" are and how to use them, feel free to skip to the next section below.
14
-
15
-
///
16
-
17
-
An <ahref="https://en.wikipedia.org/wiki/Environment_variable"class="external-link"target="_blank">environment variable</a> (also known as "env var") is a variable that lives outside of the Python code, in the operating system, and could be read by your Python code (or by other programs as well).
18
-
19
-
You can create and use environment variables in the shell, without needing Python:
20
-
21
-
//// tab | Linux, macOS, Windows Bash
22
-
23
-
<divclass="termy">
24
-
25
-
```console
26
-
// You could create an env var MY_NAME with
27
-
$ export MY_NAME="Wade Wilson"
28
-
29
-
// Then you could use it with other programs, like
30
-
$ echo"Hello $MY_NAME"
31
-
32
-
Hello Wade Wilson
33
-
```
34
-
35
-
</div>
36
-
37
-
////
38
-
39
-
//// tab | Windows PowerShell
40
-
41
-
<divclass="termy">
42
-
43
-
```console
44
-
// Create an env var MY_NAME
45
-
$ $Env:MY_NAME = "Wade Wilson"
46
-
47
-
// Use it with other programs, like
48
-
$ echo"Hello $Env:MY_NAME"
49
-
50
-
Hello Wade Wilson
51
-
```
52
-
53
-
</div>
54
-
55
-
////
56
-
57
-
### Read env vars in Python
58
-
59
-
You could also create environment variables outside of Python, in the terminal (or with any other method), and then read them in Python.
60
-
61
-
For example you could have a file `main.py` with:
62
-
63
-
```Python hl_lines="3"
64
-
import os
65
-
66
-
name = os.getenv("MY_NAME", "World")
67
-
print(f"Hello {name} from Python")
68
-
```
69
-
70
-
/// tip
71
-
72
-
The second argument to <ahref="https://docs.python.org/3.8/library/os.html#os.getenv"class="external-link"target="_blank">`os.getenv()`</a> is the default value to return.
73
-
74
-
If not provided, it's `None` by default, here we provide `"World"` as the default value to use.
75
-
76
-
///
77
-
78
-
Then you could call that Python program:
79
-
80
-
<divclass="termy">
81
-
82
-
```console
83
-
// Here we don't set the env var yet
84
-
$ python main.py
85
-
86
-
// As we didn't set the env var, we get the default value
87
-
88
-
Hello World from Python
89
-
90
-
// But if we create an environment variable first
91
-
$ export MY_NAME="Wade Wilson"
92
-
93
-
// And then call the program again
94
-
$ python main.py
95
-
96
-
// Now it can read the environment variable
97
-
98
-
Hello Wade Wilson from Python
99
-
```
100
-
101
-
</div>
102
-
103
-
As environment variables can be set outside of the code, but can be read by the code, and don't have to be stored (committed to `git`) with the rest of the files, it's common to use them for configurations or settings.
104
-
105
-
You can also create an environment variable only for a specific program invocation, that is only available to that program, and only for its duration.
106
-
107
-
To do that, create it right before the program itself, on the same line:
108
-
109
-
<divclass="termy">
110
-
111
-
```console
112
-
// Create an env var MY_NAME in line for this program call
113
-
$ MY_NAME="Wade Wilson" python main.py
114
-
115
-
// Now it can read the environment variable
116
-
117
-
Hello Wade Wilson from Python
118
-
119
-
// The env var no longer exists afterwards
120
-
$ python main.py
121
-
122
-
Hello World from Python
123
-
```
124
-
125
-
</div>
126
-
127
9
/// tip
128
10
129
-
You can read more about it at <ahref="https://12factor.net/config"class="external-link"target="_blank">The Twelve-Factor App: Config</a>.
11
+
To understand environment variables you can read [Environment Variables](../environment-variables.md){.internal-link target=_blank}.
130
12
131
13
///
132
14
133
-
###Types and validation
15
+
## Types and validation
134
16
135
17
These environment variables can only handle text strings, as they are external to Python and have to be compatible with other programs and the rest of the system (and even with different operating systems, as Linux, Windows, macOS).
136
18
137
-
That means that any value read in Python from an environment variable will be a `str`, and any conversion to a different type or validation has to be done in code.
19
+
That means that any value read in Python from an environment variable will be a `str`, and any conversion to a different type or any validation has to be done in code.
138
20
139
21
## Pydantic `Settings`
140
22
141
23
Fortunately, Pydantic provides a great utility to handle these settings coming from environment variables with <ahref="https://docs.pydantic.dev/latest/concepts/pydantic_settings/"class="external-link"target="_blank">Pydantic: Settings management</a>.
142
24
143
25
### Install `pydantic-settings`
144
26
145
-
First, install the `pydantic-settings` package:
27
+
First, make sure you create your [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install the `pydantic-settings` package:
0 commit comments