@ -92,7 +92,7 @@ FastAPI stands on the shoulders of giants:
pip install fastapi
```
You will also need an ASGI server, for production such as <ahref="http://www.uvicorn.org"class="external-link"target="_blank">Uvicorn</a> or <ahref="https://gitlab.com/pgjones/hypercorn"target="_blank">Hypercorn</a>.
You will also need an ASGI server, for production such as <ahref="http://www.uvicorn.org"class="external-link"target="_blank">Uvicorn</a> or <ahref="https://gitlab.com/pgjones/hypercorn"class="external-link"target="_blank">Hypercorn</a>.
For a more complete example including more features, see the <ahref="https://fastapi.tiangolo.com/tutorial/intro/">Tutorial - User Guide</a>.
For a more complete example including more features, see the <ahref="https://fastapi.tiangolo.com/tutorial/">Tutorial - User Guide</a>.
**Spoiler alert**: the tutorial - user guide includes:
@ -375,7 +375,7 @@ For a more complete example including more features, see the <a href="https://fa
Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <ahref="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7"class="external-link"target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
To understand more about it, see the section <ahref="https://fastapi.tiangolo.com/benchmarks/"target="_blank">Benchmarks</a>.
To understand more about it, see the section <ahref="https://fastapi.tiangolo.com/benchmarks/"class="internal-link"target="_blank">Benchmarks</a>.
@ -27,4 +27,4 @@ To achieve that, import `JSONResponse`, and return your content there directly,
If you return additional status codes and responses directly, they won't be included in the OpenAPI schema (the API docs), because FastAPI doesn't have a way to know before hand what you are going to return.
But you can document that in your code, using: <ahref="https://fastapi.tiangolo.com/tutorial/additional-responses/"target="_blank">Additional Responses</a>.
But you can document that in your code, using: [Additional Responses](additional-responses.md){.internal-link target=_blank}.
@ -11,7 +11,7 @@ In this example, we'll use **SQLite**, because it uses a single file and Python
Later, for your production application, you might want to use a database server like **PostgreSQL**.
!!! tip
You could adopt ideas from the previous section about <ahref="/tutorial/sql-databases/"target="_blank">SQLAlchemy ORM</a>, like using utility functions to perform operations in the database, independent of your **FastAPI** code.
You could adopt ideas from the section about SQLAlchemy ORM ([SQL (Relational) Databases](../tutorial/sql-databases.md){.internal-link target=_blank}), like using utility functions to perform operations in the database, independent of your **FastAPI** code.
This section doesn't apply those ideas, to be equivalent to the counterpart in <ahref="https://www.starlette.io/database/"class="external-link"target="_blank">Starlette</a>.
@ -71,7 +71,7 @@ But because of our changes in `GzipRequest.body`, the request body will be autom
## Accessing the request body in an exception handler
!!! tip
To solve this same problem, it's probably a lot easier to [use the `body` in a custom handler for `RequestValidationError`](https://fastapi.tiangolo.com/tutorial/handling-errors/#use-the-requestvalidationerror-body).
To solve this same problem, it's probably a lot easier to use the `body` in a custom handler for `RequestValidationError` ([Handling Errors](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}).
But this example is still valid and it shows how to interact with the internal components.
By default, **FastAPI** will return the responses using Starlette's `JSONResponse`.
You can override it by returning a `Response` directly, <ahref="https://fastapi.tiangolo.com/tutorial/response-directly/"target="_blank">as seen in a previous section</a>.
You can override it by returning a `Response` directly as seen in [Return a Response directly](response-directly.md){.internal-link target=_blank}.
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`).
@ -43,7 +43,7 @@ Import the `Response` class (sub-class) you want to use and declare it in the *p
To return a response with HTML directly from **FastAPI**, use `HTMLResponse`.
* Import `HTMLResponse`.
* Pass `HTMLResponse` as the parameter `content_type` of your path operation.
* Pass `HTMLResponse` as the parameter `content_type` of your *path operation*.
```Python hl_lines="2 7"
{!./src/custom_response/tutorial002.py!}
@ -61,7 +61,7 @@ To return a response with HTML directly from **FastAPI**, use `HTMLResponse`.
### Return a Starlette `Response`
As seen in <ahref="https://fastapi.tiangolo.com/tutorial/response-directly/"target="_blank">another section</a>, you can also override the response directly in your path operation, by returning it.
As seen in [Return a Response directly](response-directly.md){.internal-link target=_blank}, you can also override the response directly in your *path operation*, by returning it.
The same example from above, returning an `HTMLResponse`, could look like:
@ -70,7 +70,7 @@ The same example from above, returning an `HTMLResponse`, could look like:
```
!!! warning
A `Response` returned directly by your path operation function won't be documented in OpenAPI (for example, the `Content-Type` won't be documented) and won't be visible in the automatic interactive docs.
A `Response` returned directly by your *path operation function* won't be documented in OpenAPI (for example, the `Content-Type` won't be documented) and won't be visible in the automatic interactive docs.
!!! info
Of course, the actual `Content-Type` header, status code, etc, will come from the `Response` object your returned.
@ -79,7 +79,7 @@ The same example from above, returning an `HTMLResponse`, could look like:
If you want to override the response from inside of the function but at the same time document the "media type" in OpenAPI, you can use the `response_class` parameter AND return a `Response` object.
The `response_class` will then be used only to document the OpenAPI path operation, but your `Response` will be used as is.
The `response_class` will then be used only to document the OpenAPI *path operation*, but your `Response` will be used as is.
#### Return an `HTMLResponse` directly
@ -99,4 +99,4 @@ But as you passed the `HTMLResponse` in the `response_class`, **FastAPI** will k
## Additional documentation
You can also declare the media type and many other details in OpenAPI using `responses`: <ahref="https://fastapi.tiangolo.com/tutorial/additional-responses/"target="_blank">Additional Responses in OpenAPI</a>.
You can also declare the media type and many other details in OpenAPI using `responses`: [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}.
The main [Tutorial - User Guide](../tutorial/){.internal-link target=_blank} should be enough to give you a tour through all the main features of **FastAPI**.
In the next sections you will see other options, configurations, and additional features.
!!! tip
The next sections are **not necessarily "advanced"**.
And it's possible that for your use case, the solution is in one of them.
## Read the Tutorial first
You could still use most of the features in **FastAPI** with the knowledge from the main [Tutorial - User Guide](../tutorial/){.internal-link target=_blank}.
And the next sections assume you already read it, and assume that you know those main ideas.
@ -68,7 +68,7 @@ First, let's create a `User` model:
{!./src/nosql_databases/tutorial001.py!}
```
We will use this model in our path operation function, so, we don't include in it the `hashed_password`.
We will use this model in our *path operation function*, so, we don't include in it the `hashed_password`.
### `UserInDB` model
@ -85,7 +85,7 @@ We don't create it as a subclass of Pydantic's `BaseModel` but as a subclass of
!!! note
Notice that we have a `hashed_password` and a `type` field that will be stored in the database.
But it is not part of the general `User` model (the one we will return in the path operation).
But it is not part of the general `User` model (the one we will return in the *path operation*).
## Get the user
@ -96,7 +96,7 @@ Now create a function that will:
* Get the document with that ID.
* Put the contents of the document in a `UserInDB` model.
By creating a function that is only dedicated to getting your user from a `username` (or any other parameter) independent of your path operation function, you can more easily re-use it in multiple parts and also add <abbrtitle="Automated test, written in code, that checks if another piece of code is working correctly.">unit tests</abbr> for it:
By creating a function that is only dedicated to getting your user from a `username` (or any other parameter) independent of your *path operation function*, you can more easily re-use it in multiple parts and also add <abbrtitle="Automated test, written in code, that checks if another piece of code is working correctly.">unit tests</abbr> for it:
As our code is calling Couchbase and we are not using the <ahref="https://docs.couchbase.com/python-sdk/2.5/async-programming.html#asyncio-python-3-5"class="external-link"target="_blank">experimental Python <code>await</code> support</a>, we should declare our function with normal `def` instead of `async def`.
@ -62,7 +62,7 @@ This example doesn't implement the callback itself (that could be just a line of
!!! tip
The actual callback is just an HTTP request.
When implementing the callback yourself, you could use something like <ahref="https://www.encode.io/httpx/"target="_blank">HTTPX</a> or <ahref="https://requests.readthedocs.io/"class="external-link"target="_blank">Requests</a>.
When implementing the callback yourself, you could use something like <ahref="https://www.encode.io/httpx/"class="external-link"target="_blank">HTTPX</a> or <ahref="https://requests.readthedocs.io/"class="external-link"target="_blank">Requests</a>.
If you are not an "expert" in OpenAPI, you probably don't need this.
You can set the OpenAPI `operationId` to be used in your path operation with the parameter `operation_id`.
You can set the OpenAPI `operationId` to be used in your *path operation* with the parameter `operation_id`.
You would have to make sure that it is unique for each operation.
@ -31,7 +31,7 @@ You should do it after adding all your *path operations*.
## Exclude from OpenAPI
To exclude a path operation from the generated OpenAPI schema (and thus, from the automatic documentation systems), use the parameter `include_in_schema` and set it to `False`;
To exclude a *path operation* from the generated OpenAPI schema (and thus, from the automatic documentation systems), use the parameter `include_in_schema` and set it to `False`;
You probably read before that you can set a <ahref="https://fastapi.tiangolo.com/tutorial/response-status-code/"target="_blank">default Response Status Code</a>.
You probably read before that you can set a default [Response Status Code](../tutorial/response-status-code.md){.internal-link target=_blank}.
But in some cases you need to return a different status code than the default.
You can declare a parameter of type `Response` in your *path operation function*, the same way you can declare a `Request` parameter.
You can declare a parameter of type `Response` in your *path operation function*.
And then you can set headers in that *temporal* response object.
@ -20,7 +20,7 @@ You can also declare the `Response` parameter in dependencies, and set cookies (
You can also create cookies when returning a `Response` directly in your code.
To do that, you can create a response as described in <ahref="https://fastapi.tiangolo.com/tutorial/response-directly/"target="_blank">Return a Response directly</a>.
To do that, you can create a response as described in [Return a Response Directly](response-directly.md){.internal-link target=_blank}.
When you create a **FastAPI***path operation* you can normally return any data from it: a `dict`, a `list`, a Pydantic model, a database model, etc.
By default, **FastAPI** would automatically convert that return value to JSON using the <ahref="https://fastapi.tiangolo.com/tutorial/encoder/"target="_blank">`jsonable_encoder`</a>.
By default, **FastAPI** would automatically convert that return value to JSON using the `jsonable_encoder` explained in [JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank}.
Then, behind the scenes, it would put that JSON-compatible data (e.g. a `dict`) inside of a Starlette `JSONResponse` that would be used to send the response to the client.
@ -56,8 +56,6 @@ You could put your XML content in a string, put it in a Starlette Response, and
When you return a `Response` directly its data is not validated, converted (serialized), nor documented automatically.
But you can still <ahref="https://fastapi.tiangolo.com/tutorial/additional-responses/"target="_blank">document it</a>.
But you can still document it as described in [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}.
In the next sections you will see how to use/declare these custom `Response`s while still having automatic data conversion, documentation, etc.
You will also see how to use them to set response Headers and Cookies.
You can see in later sections how to use/declare these custom `Response`s while still having automatic data conversion, documentation, etc.
You can declare a parameter of type `Response` in your *path operation function* (as you can do for cookies), the same way you can declare a `Request` parameter.
You can declare a parameter of type `Response` in your *path operation function* (as you can do for cookies).
And then you can set headers in that *temporal* response object.
@ -20,7 +20,7 @@ You can also declare the `Response` parameter in dependencies, and set headers (
You can also add headers when you return a `Response` directly.
Create a response as described in <ahref="https://fastapi.tiangolo.com/tutorial/response-directly/"target="_blank">Return a Response directly</a> and pass the headers as an additional parameter:
Create a response as described in [Return a Response Directly](response-directly.md){.internal-link target=_blank} and pass the headers as an additional parameter:
```Python hl_lines="10 11 12"
{!./src/response_headers/tutorial001.py!}
@ -30,4 +30,4 @@ Create a response as described in <a href="https://fastapi.tiangolo.com/tutorial
Have in mind that custom proprietary headers can be added <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers"class="external-link"target="_blank">using the 'X-' prefix</a>.
But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your <ahref="https://fastapi.tiangolo.com/tutorial/cors/"target="_blank">CORS configurations</a>, using the parameter `expose_headers` documented in <ahref="https://www.starlette.io/middleware/#corsmiddleware"class="external-link"target="_blank">Starlette's CORS docs</a>.
But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your CORS configurations (read more in [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md){.internal-link target=_blank}), using the parameter `expose_headers` documented in <ahref="https://www.starlette.io/middleware/#corsmiddleware"class="external-link"target="_blank">Starlette's CORS docs</a>.
There are some extra features to handle security apart from the ones covered in the [Tutorial - User Guide: Security](../../tutorial/security/){.internal-link target=_blank}.
!!! tip
The next sections are **not necessarily "advanced"**.
And it's possible that for your use case, the solution is in one of them.
## Read the Tutorial first
The next sections assume you already read the main [Tutorial - User Guide: Security](../../tutorial/security/){.internal-link target=_blank}.
They are all based on the same concepts, but allow some extra functionalities.
@ -29,13 +29,30 @@ The content of each of these strings can have any format, but should not contain
These scopes represent "permissions".
In OpenAPI (e.g. the API docs), you can define "security schemes", the same as you saw in the previous sections.
In OpenAPI (e.g. the API docs), you can define "security schemes".
When one of these security schemes uses OAuth2, you can also declare and use scopes.
Each "scope" is just a string (without spaces).
They are normally used to declare specific security permissions, for example:
* `users:read` or `users:write` are common examples.
* `instagram_basic` is used by Facebook / Instagram.
* `https://www.googleapis.com/auth/drive` is used by Google.
!!! info
In OAuth2 a "scope" is just a string that declares a specific permission required.
It doesn't matter if it has other characters like `:` or if it is a URL.
Those details are implementation specific.
For OAuth2 they are just strings.
## Global view
First, let's quickly see the parts that change from the previous section about OAuth2 and JWT. Now using OAuth2 scopes:
First, let's quickly see the parts that change from the examples in the main **Tutorial - User Guide** for [OAuth2 with Password (and hashing), Bearer with JWT tokens](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. Now using OAuth2 scopes:
@ -108,7 +125,7 @@ In this case, it requires the scope `me` (it could require more than one scope).
But by using `Security` instead of `Depends`, **FastAPI** will know that it can declare security scopes, use them internally, and document the API with OpenAPI.
But when you import `Query`, `Path`, `Depends`, `Security` and others from `fastapi`, <ahref="https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#recap"target="_blank">those are actually functions that return classes of the same name</a>.
But when you import `Query`, `Path`, `Depends`, `Security` and others from `fastapi`, those are actually functions that return special classes.
## Use `SecurityScopes`
@ -200,7 +217,7 @@ Here's how the hierarchy of dependencies and scopes looks like:
!!! tip
The important and "magic" thing here is that `get_current_user` will have a different list of `scopes` to check for each *path operation*.
All depending on the `scopes` declared in each *path operation* and each dependency in the dependency tree for that specific path operation.
All depending on the `scopes` declared in each *path operation* and each dependency in the dependency tree for that specific *path operation*.
## More details about `SecurityScopes`
@ -210,7 +227,7 @@ It will always have the security scopes declared in the current `Security` depen
Because the `SecurityScopes` will have all the scopes declared by dependants, you can use it to verify that a token has the required scopes in a central dependency function, and then declare different scope requirements in different *path operations*.
They will be checked independently for each path operation.
They will be checked independently for each *path operation*.
## Check it
@ -247,4 +264,4 @@ The most secure is the code flow, but is more complex to implement as it require
## `Security` in decorator `dependencies`
The same way you can define a `list` of <ahref="https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/"target="_blank">`Depends` in the decorator's `dependencies` parameter</a>, you could also use `Security` with `scopes` there.
The same way you can define a `list` of `Depends` in the decorator's `dependencies` parameter (as explained in [Dependencies in path operation decorators](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}), you could also use `Security` with `scopes` there.
If you are just starting, the <ahref="https://fastapi.tiangolo.com/tutorial/sql-databases/"target="_blank">SQLAlchemy tutorial</a> should be enough.
If you are just starting, the tutorial [SQL (Relational) Databases](../tutorial/sql-databases.md){.internal-link target=_blank} that uses SQLAlchemy should be enough.
Feel free to skip this.
If you are starting a project from scratch, you are probably better off with <ahref="https://fastapi.tiangolo.com/tutorial/sql-databases/"target="_blank">SQLAlchemy ORM</a>, or any other async ORM.
If you are starting a project from scratch, you are probably better off with SQLAlchemy ORM ([SQL (Relational) Databases](../tutorial/sql-databases.md){.internal-link target=_blank}), or any other async ORM.
If you already have a code base that uses <ahref="http://docs.peewee-orm.com/en/latest/"class="external-link"target="_blank">Peewee ORM</a>, you can check here how to use it with **FastAPI**.
@ -23,11 +23,11 @@ But if you need to change some of the defaults, support more than one predefined
Nevertheless, it's possible to do it, and here you'll see exactly what code you have to add to be able to use Peewee with FastAPI.
!!! note "Technical Details"
You can read more about Peewee's stand about async in Python <ahref="http://docs.peewee-orm.com/en/latest/peewee/database.html#async-with-gevent"target="_blank">in the docs</a>, <ahref="https://github.com/coleifer/peewee/issues/263#issuecomment-517347032"target="_blank">an issue</a>, <ahref="https://github.com/coleifer/peewee/pull/2072#issuecomment-563215132"class="external-link"target="_blank">a PR</a>.
You can read more about Peewee's stand about async in Python <ahref="http://docs.peewee-orm.com/en/latest/peewee/database.html#async-with-gevent"class="external-link"target="_blank">in the docs</a>, <ahref="https://github.com/coleifer/peewee/issues/263#issuecomment-517347032"class="external-link"target="_blank">an issue</a>, <ahref="https://github.com/coleifer/peewee/pull/2072#issuecomment-563215132"class="external-link"target="_blank">a PR</a>.
## The same app
We are going to create the same application as in the <ahref="https://fastapi.tiangolo.com/tutorial/sql-databases/"target="_blank">SQLAlchemy tutorial</a>.
We are going to create the same application as in the SQLAlchemy tutorial ([SQL (Relational) Databases](../tutorial/sql-databases.md){.internal-link target=_blank}).
Exactly the same technical details as in the <ahref="https://fastapi.tiangolo.com/tutorial/sql-databases/#note"target="_blank">SQLAlchemy tutorial</a> apply.
Exactly the same technical details as in [SQL (Relational) Databases](../tutorial/sql-databases.md#note){.internal-link target=_blank} apply.
### Make Peewee async-compatible `PeeweeConnectionState`
@ -247,7 +247,7 @@ Aso, when returning several objects, like in `get_users`, we directly call `list
list(models.User.select())
```
This is for the same reason that we had to create a custom `PeeweeGetterDict`. But by returning something that is already a `list` instead of the `peewee.ModelSelect` the `response_model` in the path operation with `List[models.User]` (that we'll see later) will work correctly.
This is for the same reason that we had to create a custom `PeeweeGetterDict`. But by returning something that is already a `list` instead of the `peewee.ModelSelect` the `response_model` in the *path operation* with `List[models.User]` (that we'll see later) will work correctly.
And these same full-stack generators were the base of the <ahref="/project-generation/"target="_blank">**FastAPI** project generator</a>.
And these same full-stack generators were the base of the [**FastAPI** Project Generators](project-generation.md){.internal-link target=_blank}.
!!! info
Flask-apispec was created by the same Marshmallow developers.
@ -408,8 +408,8 @@ It is the recommended server for Starlette and **FastAPI**.
You can combine it with Gunicorn, to have an asynchronous multi-process server.
Check more details in the <ahref="/deployment/"target="_blank">Deployment</a> section.
Check more details in the [Deployment](deployment.md){.internal-link target=_blank} section.
## Benchmarks and speed
To understand, compare, and see the difference between Uvicorn, Starlette and FastAPI, check the section about [Benchmarks](/benchmarks/).
To understand, compare, and see the difference between Uvicorn, Starlette and FastAPI, check the section about [Benchmarks](benchmarks.md){.internal-link target=_blank}.
Details about the `async def` syntax for path operation functions and some background about asynchronous code, concurrency, and parallelism.
Details about the `async def` syntax for *path operation functions* and some background about asynchronous code, concurrency, and parallelism.
## In a hurry?
@ -7,12 +6,11 @@ Details about the `async def` syntax for path operation functions and some backg
If you are using third party libraries that tell you to call them with `await`, like:
```Python
results = await some_library()
```
Then, declare your path operation functions with `async def` like:
Then, declare your *path operation functions* with `async def` like:
```Python hl_lines="2"
@app.get('/')
@ -26,7 +24,7 @@ async def read_results():
---
If you are using a third party library that communicates with something (a database, an API, the file system, etc) and doesn't have support for using `await`, (this is currently the case for most database libraries), then declare your path operation functions as normally, with just `def`, like:
If you are using a third party library that communicates with something (a database, an API, the file system, etc) and doesn't have support for using `await`, (this is currently the case for most database libraries), then declare your *path operation functions* as normally, with just `def`, like:
```Python hl_lines="2"
@app.get('/')
@ -45,13 +43,12 @@ If you just don't know, use normal `def`.
---
**Note**: you can mix `def` and `async def` in your path operation functions as much as you need and define each one using the best option for you. FastAPI will do the right thing with them.
**Note**: you can mix `def` and `async def` in your *path operation functions* as much as you need and define each one using the best option for you. FastAPI will do the right thing with them.
Anyway, in any of the cases above, FastAPI will still work asynchronously and be extremely fast.
But by following the steps above, it will be able to do some performance optimizations.
## Technical Details
Modern versions of Python have support for **"asynchronous code"** using something called **"coroutines"**, with **`async` and `await`** syntax.
@ -62,7 +59,6 @@ Let's see that phrase by parts in the sections below, below:
* **`async` and `await`**
* **Coroutines**
## Asynchronous Code
Asynchronous code just means that the language has a way to tell the computer / program that at some point in the code, he will have to wait for *something else* to finish somewhere else. Let's say that *something else* is called "slow-file".
@ -92,7 +88,6 @@ Instead of that, by being an "asynchronous" system, once finished, the task can
For "synchronous" (contrary to "asynchronous") they commonly also use the term "sequential", because the computer / program follows all the steps in sequence before switching to a different task, even if those steps involve waiting.
### Concurrency and Burgers
This idea of **asynchronous** code described above is also sometimes called **"concurrency"**. It is different from **"parallelism"**.
@ -103,7 +98,6 @@ But the details between *concurrency* and *parallelism* are quite different.
To see the difference, imagine the following story about burgers:
### Concurrent Burgers
You go with your crush to get fast food, you stand in line while the cashier takes the orders from the people in front of you.
@ -144,7 +138,6 @@ So you wait for your crush to finish the story (finish the current work / task b
Then you go to the counter, to the initial task that is now finished, pick the burgers, say thanks and take them to the table. That finishes that step / task of interaction with the counter. That in turn, creates a new task, of "eating burgers", but the previous one of "getting burgers" is finished.
### Parallel Burgers
You go with your crush to get parallel fast food.
@ -195,7 +188,6 @@ And you have to wait in the line for a long time or you lose your turn.
You probably wouldn't want to take your crush with you to do errands at the bank.
### Burger Conclusion
In this scenario of "fast food burgers with your crush", as there is a lot of waiting, it makes a lot more sense to have a concurrent system.
@ -220,7 +212,6 @@ And that's the same level of performance</a> you get with **FastAPI**.
And as you can have parallelism and asynchronicity at the same time, you get higher performance than most of the tested NodeJS frameworks and on par with Go, which is a compiled language closer to C <ahref="https://www.techempower.com/benchmarks/#section=data-r17&hw=ph&test=query&l=zijmkf-1"class="external-link"target="_blank">(all thanks to Starlette)</a>.
### Is concurrency better than parallelism?
Nope! That's not the moral of the story.
@ -258,7 +249,6 @@ For example:
* **Machine Learning**: it normally requires lots of "matrix" and "vector" multiplications. Think of a huge spreadsheet with numbers and multiplying all of them together at the same time.
* **Deep Learning**: this is a sub-field of Machine Learning, so, the same applies. It's just that there is not a single spreadsheet of numbers to multiply, but a huge set of them, and in many cases, you use a special processor to build and / or use those models.
### Concurrency + Parallelism: Web + Machine Learning
With **FastAPI** you can take the advantage of concurrency that is very common for web development (the same main attractive of NodeJS).
@ -267,8 +257,7 @@ But you can also exploit the benefits of parallelism and multiprocessing (having
That, plus the simple fact that Python is the main language for **Data Science**, Machine Learning and especially Deep Learning, make FastAPI a very good match for Data Science / Machine Learning web APIs and applications (among many others).
To see how to achieve this parallelism in production see the section about [Deployment](deployment.md).
To see how to achieve this parallelism in production see the section about [Deployment](deployment.md){.internal-link target=_blank}.
## `async` and `await`
@ -310,7 +299,7 @@ burgers = get_burgers(2)
---
So, if you are using a library that tells you that you can call it with `await`, you need to create the path operation functions that uses it with `async def`, like in:
So, if you are using a library that tells you that you can call it with `await`, you need to create the *path operation functions* that uses it with `async def`, like in:
```Python hl_lines="2 3"
@app.get('/burgers')
@ -327,11 +316,10 @@ But at the same time, functions defined with `async def` have to be "awaited". S
So, about the egg and the chicken, how do you call the first `async` function?
If you are working with **FastAPI** you don't have to worry about that, because that "first" function will be your path operation function, and FastAPI will know how to do the right thing.
If you are working with **FastAPI** you don't have to worry about that, because that "first" function will be your *path operation function*, and FastAPI will know how to do the right thing.
But if you want to use `async` / `await` without FastAPI, <ahref="https://docs.python.org/3/library/asyncio-task.html#coroutine"class="external-link"target="_blank">check the official Python docs</a>.
### Other forms of asynchronous code
This style of using `async` and `await` is relatively new in the language.
@ -346,7 +334,6 @@ In previous versions of Python, you could have used threads or <a href="http://w
In previous versions of NodeJS / Browser JavaScript, you would have used "callbacks". Which lead to <ahref="http://callbackhell.com/"class="external-link"target="_blank">callback hell</a>.
## Coroutines
**Coroutine** is just the very fancy term for the thing returned by an `async def` function. Python knows that it is something like a function that it can start and that it will end at some point, but that it might be paused internally too, whenever there is an `await` inside of it.
@ -363,7 +350,6 @@ That should make more sense now.
All that is what powers FastAPI (through Starlette) and what makes it have such an impressive performance.
## Very Technical Details
!!! warning
@ -379,7 +365,7 @@ When you declare a *path operation function* with normal `def` instead of `async
If you are coming from another async framework that does not work in the way described above and you are used to define trivial compute-only *path operation functions* with plain `def` for a tiny performance gain (about 100 nanoseconds), please note that in **FastAPI** the effect would be quite opposite. In these cases, it's better to use `async def` unless your *path operation functions* use code that performs blocking <abbrtitle="Input/Output: disk reading or writing, network communications.">IO</abbr>.
Still, in both situations, chances are that **FastAPI** will <ahref="https://fastapi.tiangolo.com/#performance"target="_blank">still be faster</a> than (or at least comparable to) your previous framework.
Still, in both situations, chances are that **FastAPI** will [still be faster](/#performance){.internal-link target=_blank} than (or at least comparable to) your previous framework.
If you followed the section about creating <ahref="https://fastapi.tiangolo.com/tutorial/bigger-applications/"target="_blank">Bigger Applications with Multiple Files
</a>, your `Dockerfile` might instead look like:
If you followed the section about creating [Bigger Applications with Multiple Files](tutorial/bigger-applications.md){.internal-link target=_blank}, your `Dockerfile` might instead look like:
```Dockerfile
FROM tiangolo/uvicorn-gunicorn-fastapi:python3.7
@ -214,7 +213,7 @@ To set up a Docker Swarm Mode cluster with Traefik and HTTPS handling, follow th
### Deploy a FastAPI application
The easiest way to set everything up, would be using the <ahref="/project-generation/"target="_blank">FastAPI project generator</a>.
The easiest way to set everything up, would be using the [**FastAPI** Project Generators](project-generation.md){.internal-link target=_blank}.
It is designed to be integrated with this Docker Swarm cluster with Traefik and HTTPS described above.
@ -26,7 +26,7 @@ Interactive API documentation and exploration web user interfaces. As the framew
It's all based on standard **Python 3.6 type** declarations (thanks to Pydantic). No new syntax to learn. Just standard modern Python.
If you need a 2 minute refresher of how to use Python types (even if you don't use FastAPI), check the tutorial section: [Python types](python-types.md).
If you need a 2 minute refresher of how to use Python types (even if you don't use FastAPI), check the short tutorial: [Python Types](python-types.md){.internal-link target=_blank}.
You write standard Python with types:
@ -121,7 +121,7 @@ Security and authentication integrated. Without any compromise with databases or
All the security schemes defined in OpenAPI, including:
* HTTP Basic.
* **OAuth2** (also with **JWT tokens**). Check the [tutorial on OAuth2 with JWT](tutorial/security/oauth2-jwt.md).
* **OAuth2** (also with **JWT tokens**). Check the tutorial on [OAuth2 with JWT](tutorial/security/oauth2-jwt.md){.internal-link target=_blank}.
* API keys in:
* Headers.
* Query parameters.
@ -136,9 +136,9 @@ All built as reusable tools and components that are easy to integrate with your
FastAPI includes an extremely easy to use, but extremely powerful <abbrtitle='also known as "components", "resources", "services", "providers"'><strong>Dependency Injection</strong></abbr> system.
* Even dependencies can have dependencies, creating a hierarchy or **"graph" of dependencies**.
* All **automatically handled** by the framework.
* All **automatically handled** by the framework.
* All the dependencies can require data from requests and **augment the path operation** constraints and automatic documentation.
* **Automatic validation** even for path operation parameters defined in dependencies.
* **Automatic validation** even for *path operation* parameters defined in dependencies.
* Support for complex user authentication systems, **database connections**, etc.
* **No compromise** with databases, frontends, etc. But easy integration with all of them.
@ -146,7 +146,7 @@ FastAPI includes an extremely easy to use, but extremely powerful <abbr title='a
Or in other way, no need for them, import and use the code you need.
Any integration is designed to be so simple to use (with dependencies) that you can create a "plug-in" for your application in 2 lines of code using the same structure and syntax used for your path operations.
Any integration is designed to be so simple to use (with dependencies) that you can create a "plug-in" for your application in 2 lines of code using the same structure and syntax used for your *path operations*.
@ -92,7 +92,7 @@ FastAPI stands on the shoulders of giants:
pip install fastapi
```
You will also need an ASGI server, for production such as <ahref="http://www.uvicorn.org"class="external-link"target="_blank">Uvicorn</a> or <ahref="https://gitlab.com/pgjones/hypercorn"target="_blank">Hypercorn</a>.
You will also need an ASGI server, for production such as <ahref="http://www.uvicorn.org"class="external-link"target="_blank">Uvicorn</a> or <ahref="https://gitlab.com/pgjones/hypercorn"class="external-link"target="_blank">Hypercorn</a>.
For a more complete example including more features, see the <ahref="https://fastapi.tiangolo.com/tutorial/intro/">Tutorial - User Guide</a>.
For a more complete example including more features, see the <ahref="https://fastapi.tiangolo.com/tutorial/">Tutorial - User Guide</a>.
**Spoiler alert**: the tutorial - user guide includes:
@ -375,7 +375,7 @@ For a more complete example including more features, see the <a href="https://fa
Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <ahref="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7"class="external-link"target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
To understand more about it, see the section <ahref="https://fastapi.tiangolo.com/benchmarks/"target="_blank">Benchmarks</a>.
To understand more about it, see the section <ahref="https://fastapi.tiangolo.com/benchmarks/"class="internal-link"target="_blank">Benchmarks</a>.
* **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic).
* **Intuitive**: Great editor support. <abbrtitle="also known as auto-complete, autocompletion, IntelliSense">Completion</abbr> everywhere. Less time debugging.
* **Easy**: Designed to be easy to use and learn. Less time reading docs.
* **Short**: Minimize code duplication. Multiple features from each parameter declaration.
* **Robust**: Get production-ready code. With automatic interactive documentation.
* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <ahref="https://github.com/OAI/OpenAPI-Specification"class="external-link"target="_blank">OpenAPI</a> and <ahref="http://json-schema.org/"class="external-link"target="_blank">JSON Schema</a>.
* [**Many other features**](https://github.com/tiangolo/fastapi) including automatic validation, serialization, interactive documentation, authentication with OAuth2 JWT tokens, etc.
* Many other features including automatic validation, serialization, interactive documentation, authentication with OAuth2 JWT tokens, etc.
* **Secure password** hashing by default.
* **JWT token** authentication.
* **SQLAlchemy** models (independent of Flask extensions, so they can be used with Celery workers directly).
@ -58,14 +58,14 @@ GitHub: <a href="https://github.com/tiangolo/full-stack-fastapi-couchbase" class
* Docker Swarm Mode deployment.
* **Docker Compose** integration and optimization for local development.
* **Production ready** Python web server using Uvicorn and Gunicorn.
* **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic).
* **Intuitive**: Great editor support. <abbrtitle="also known as auto-complete, autocompletion, IntelliSense">Completion</abbr> everywhere. Less time debugging.
* **Easy**: Designed to be easy to use and learn. Less time reading docs.
* **Short**: Minimize code duplication. Multiple features from each parameter declaration.
* **Robust**: Get production-ready code. With automatic interactive documentation.
* **Standards-based**: <ahref="https://github.com/OAI/OpenAPI-Specification"class="external-link"target="_blank">OpenAPI</a> and <ahref="http://json-schema.org/"class="external-link"target="_blank">JSON Schema</a>.
* [**Many other features**](https://github.com/tiangolo/fastapi) including automatic validation, serialization, interactive documentation, authentication with OAuth2 JWT tokens, etc.
* Many other features including automatic validation, serialization, interactive documentation, authentication with OAuth2 JWT tokens, etc.
@ -121,7 +121,6 @@ Now you know that you have to fix it, convert `age` to a string with `str(age)`:
{!./src/python_types/tutorial004.py!}
```
## Declaring types
You just saw the main place to declare type hints. As function parameters.
@ -214,7 +213,6 @@ This means:
* The keys of this `dict` are of type `str` (let's say, the name of each item).
* The values of this `dict` are of type `float` (let's say, the price of each item).
### Classes as types
You can also declare a class as the type of a variable.
@ -235,7 +233,6 @@ And then, again, you get all the editor support:
<imgsrc="/img/python-types/image06.png">
## Pydantic models
<ahref="https://pydantic-docs.helpmanual.io/"class="external-link"target="_blank">Pydantic</a> is a Python library to perform data validation.
@ -259,8 +256,7 @@ Taken from the official Pydantic docs:
**FastAPI** is all based on Pydantic.
You will see a lot more of all this in practice in the <ahref="/tutorial/intro/"target="_blank">Tutorial - User Guide</a> (the next section).
You will see a lot more of all this in practice in the [Tutorial - User Guide](tutorial/){.internal-link target=_blank}.
## Type hints in **FastAPI**
@ -280,7 +276,7 @@ With **FastAPI** you declare parameters with type hints and you get:
* **Document** the API using OpenAPI:
* which is then used by the automatic interactive documentation user interfaces.
This might all sound abstract. Don't worry. You'll see all this in action in the <ahref="/tutorial/intro/"target="_blank">Tutorial - User Guide</a> (the next section).
This might all sound abstract. Don't worry. You'll see all this in action in the [Tutorial - User Guide](tutorial/){.internal-link target=_blank}.
The important thing is that by using standard Python types, in a single place (instead of adding more classes, decorators, etc), **FastAPI** will do a lot of the work for you.
@ -19,9 +19,6 @@ First, import `BackgroundTasks` and define a parameter in your *path operation f
**FastAPI** will create the object of type `BackgroundTasks` for you and pass it as that parameter.
!!! tip
You declare a parameter of `BackgroundTasks` and use it in a very similar way as to when <ahref="/tutorial/using-request-directly/"target="_blank">using the `Request` directly</a>.
## Create a task function
Create a function to be run as the background task.
@ -86,7 +83,7 @@ If you need to perform heavy background computation and you don't necessarily ne
They tend to require more complex configurations, a message/job queue manager, like RabbitMQ or Redis, but they allow you to run background tasks in multiple processes, and especially, in multiple servers.
To see an example, check the <ahref="https://fastapi.tiangolo.com/project-generation/"target="_blank">Project Generators</a>, they all include Celery already configured.
To see an example, check the [Project Generators](../project-generation.md){.internal-link target=_blank}, they all include Celery already configured.
But if you need to access variables and objects from the same **FastAPI** app, or you need to perform small background tasks (like sending an email notification), you can simply just use `BackgroundTasks`.
And then you use it to declare your *path operations*.
@ -87,7 +87,7 @@ We are going to include this `APIrouter` in the main `FastAPI` app, but first, l
Let's say you also have the endpoints dedicated to handling "Items" from your application in the module at `app/routers/items.py`.
You have path operations for:
You have *path operations* for:
* `/items/`
* `/items/{item_id}`
@ -223,9 +223,9 @@ Now, let's include the router from the `items` submodule.
But, remember that we were lazy and didn't add `/items/` nor `tags` to all the *path operations*?
We can add a prefix to all the path operations using the parameter `prefix` of `app.include_router()`.
We can add a prefix to all the *path operations* using the parameter `prefix` of `app.include_router()`.
As the path of each path operation has to start with `/`, like in:
As the path of each *path operation* has to start with `/`, like in:
```Python hl_lines="1"
@router.get("/{item_id}")
@ -261,8 +261,8 @@ The end result is that the item paths are now:
* The *path operation* that declared a custom `403` response will have both the predefined responses (`404`) and the `403` declared in it directly.
* All these *path operations* will have the list of `dependencies` evaluated/executed before them.
* If you also declare dependencies in a specific *path operation*, **they will be executed too**.
* The router dependencies are executed first, then the <ahref="https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-decorator/"target="_blank">`dependencies` in the decorator</a>, and then the normal parameter dependencies.
* You can also add <ahref="https://fastapi.tiangolo.com/tutorial/security/oauth2-scopes/"target="_blank">`Security` dependencies with `scopes`</a>.
* The router dependencies are executed first, then the [`dependencies` in the decorator](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, and then the normal parameter dependencies.
* You can also add [`Security` dependencies with `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}.
!!! tip
Having `dependencies` in a decorator can be used, for example, to require authentication for a whole group of *path operations*. Even if the dependencies are not added individually to each one of them.
@ -271,7 +271,7 @@ The end result is that the item paths are now:
The `prefix`, `tags`, `responses` and `dependencies` parameters are (as in many other cases) just a feature from **FastAPI** to help you avoid code duplication.
!!! tip
You could also add path operations directly, for example with: `@app.get(...)`.
You could also add *path operations* directly, for example with: `@app.get(...)`.
Apart from `app.include_router()`, in the same **FastAPI** app.
@ -284,9 +284,9 @@ The end result is that the item paths are now:
The `APIRouter`s are not "mounted", they are not isolated from the rest of the application.
This is because we want to include their path operations in the OpenAPI schema and the user interfaces.
This is because we want to include their *path operations* in the OpenAPI schema and the user interfaces.
As we cannot just isolate them and "mount" them independently of the rest, the path operations are "cloned" (re-created), not included directly.
As we cannot just isolate them and "mount" them independently of the rest, the *path operations* are "cloned" (re-created), not included directly.
The same way you can declare additional validation and metadata in path operation function parameters with `Query`, `Path` and `Body`, you can declare validation and metadata inside of Pydantic models using Pydantic's `Field`.
The same way you can declare additional validation and metadata in *path operation function* parameters with `Query`, `Path` and `Body`, you can declare validation and metadata inside of Pydantic models using Pydantic's `Field`.
## Import `Field`
@ -28,10 +28,10 @@ You can then use `Field` with model attributes:
`Body` also returns objects of a subclass of `FieldInfo` directly. And there are others you will see later that are subclasses of the `Body` class.
Remember that when you import `Query`, `Path`, and others from `fastapi`, <ahref="https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#recap"target="_blank">those are actually functions that return classes of the same name</a>.
Remember that when you import `Query`, `Path`, and others from `fastapi`, those are actually functions that return special classes.
!!! tip
Notice how each model's attribute with a type, default value and `Field` has the same structure as a path operation function's parameter, with `Field` instead of `Path`, `Query` and `Body`.
Notice how each model's attribute with a type, default value and `Field` has the same structure as a *path operation function's* parameter, with `Field` instead of `Path`, `Query` and `Body`.
@ -116,7 +116,7 @@ Again, doing just that declaration, with **FastAPI** you get:
Apart from normal singular types like `str`, `int`, `float`, etc. You can use more complex singular types that inherit from `str`.
To see all the options you have, checkout the docs for <ahref="https://pydantic-docs.helpmanual.io/#exotic-types"class="external-link"target="_blank">Pydantic's exotic types</a>. You will see some examples in the next chapter.
To see all the options you have, checkout the docs for <ahref="https://pydantic-docs.helpmanual.io/usage/types/"class="external-link"target="_blank">Pydantic's exotic types</a>. You will see some examples in the next chapter.
For example, as in the `Image` model we have a `url` field, we can declare it to be instead of a `str`, a Pydantic's `HttpUrl`:
@ -94,4 +94,4 @@ In summary, to apply partial updates you would:
So, if you want to receive partial updates that can omit all the attributes, you need to have a model with all the attributes marked as optional (with default values or `None`).
To distinguish from the models with all optional values for **updates** and models with required values for **creation**, you can use the ideas described in <ahref="https://fastapi.tiangolo.com/tutorial/extra-models/"target="_blank">Extra Models</a>.
To distinguish from the models with all optional values for **updates** and models with required values for **creation**, you can use the ideas described in [Extra Models](extra-models.md){.internal-link target=_blank}.
@ -21,7 +21,7 @@ The first value is the default value, you can pass all the extra validation or a
!!! note "Technical Details"
`Cookie` is a "sister" class of `Path` and `Query`. It also inherits from the same common `Param` class.
But remember that when you import `Query`, `Path`, `Cookie` and others from `fastapi`, <ahref="https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#recap"target="_blank">those are actually functions that return classes of the same name</a>.
But remember that when you import `Query`, `Path`, `Cookie` and others from `fastapi`, those are actually functions that return special classes.
!!! info
To declare cookies, you need to use `Cookie`, because otherwise the parameters would be interpreted as query parameters.
@ -2,13 +2,13 @@ Before diving deeper into the **Dependency Injection** system, let's upgrade the
## A `dict` from the previous example
In the previous example, we are returning a `dict` from our dependency ("dependable"):
In the previous example, we were returning a `dict` from our dependency ("dependable"):
```Python hl_lines="7"
{!./src/dependencies/tutorial001.py!}
```
But then we get a `dict` in the parameter `commons` of the path operation function.
But then we get a `dict` in the parameter `commons` of the *path operation function*.
And we know that editors can't provide a lot of support (like completion) for `dict`s, because they can't know their keys and value types.
@ -63,9 +63,9 @@ Then, in **FastAPI**, you could use a Python class as a dependency.
What FastAPI actually checks is that it is a "callable" (function, class or anything else) and the parameters defined.
If you pass a "callable" as a dependency in **FastAPI**, it will analyze the parameters for that "callable", and process them in the same way as the parameters for a path operation function. Including sub-dependencies.
If you pass a "callable" as a dependency in **FastAPI**, it will analyze the parameters for that "callable", and process them in the same way as the parameters for a *path operation function*. Including sub-dependencies.
That also applies to callables with no parameters at all. The same as it would be for path operation functions with no parameters.
That also applies to callables with no parameters at all. The same as it would be for *path operation functions* with no parameters.
Then, we can change the dependency "dependable" `common_parameters` from above to the class `CommonQueryParameters`:
So, you can declare the dependency as the type of the variable, and use `Depends()` as the "default" value, without any parameter, instead of having to write the full class *again* inside of `Depends(CommonQueryParams)`.
So, you can declare the dependency as the type of the variable, and use `Depends()` as the "default" value (the value after the `=`) for that function's parameter, without any parameter, instead of having to write the full class *again* inside of `Depends(CommonQueryParams)`.
@ -57,4 +57,4 @@ So, you can re-use a normal dependency (that returns a value) you already use so
## Dependencies for a group of *path operations*
Later, when reading about how to <ahref="https://fastapi.tiangolo.com/tutorial/bigger-applications/"target="_blank">structure bigger applications</a>, possibly with multiple files, you will learn how to declare a single `dependencies` parameter for a group of *path operations*.
Later, when reading about how to structure bigger applications ([Bigger Applications - Multiple Files](../../tutorial/bigger-applications.md){.internal-link target=_blank}), possibly with multiple files, you will learn how to declare a single `dependencies` parameter for a group of *path operations*.
@ -10,11 +10,11 @@ To do this, use `yield` instead of `return`, and write the extra steps after.
!!! info
For this to work, you need to use **Python 3.7** or above, or in **Python 3.6**, install the "backports":
```bash
```
pip install async-exit-stack async-generator
```
This installs <ahref="https://github.com/sorcio/async_exit_stack"class="external-link"target="_blank">async-exit-stack</a> and <ahref="https://github.com/python-trio/async_generator"target="_blank">async-generator</a>.
This installs <ahref="https://github.com/sorcio/async_exit_stack"class="external-link"target="_blank">async-exit-stack</a> and <ahref="https://github.com/python-trio/async_generator"class="external-link"target="_blank">async-generator</a>.
!!! note "Technical Details"
Any function that is valid to use with:
@ -116,7 +116,7 @@ with open("./somefile.txt") as f:
print(contents)
```
Underneath, the `open("./somefile.txt")`returns an object that is a called a "Context Manager".
Underneath, the `open("./somefile.txt")`creates an object that is a called a "Context Manager".
When the `with` block finishes, it makes sure to close the file, even if there were exceptions.
@ -129,9 +129,9 @@ When you create a dependency with `yield`, **FastAPI** will internally convert i
If you are just starting with **FastAPI** you might want to skip it for now.
In Python, you can create context managers by <ahref="https://docs.python.org/3/reference/datamodel.html#context-managers"class="external-link"target="_blank">creating a class with two methods: `__enter__()` and `__exit__()`</a>.
In Python, you can create Context Managers by <ahref="https://docs.python.org/3/reference/datamodel.html#context-managers"class="external-link"target="_blank">creating a class with two methods: `__enter__()` and `__exit__()`</a>.
You can also use them with**FastAPI** dependencies with `yield` by using
You can also use them inside of**FastAPI** dependencies with `yield` by using
`with` or `async with` statements inside of the dependency function:
It is designed to be very simple to use, and to make it very easy for any developer to integrate other components with **FastAPI**.
## "Dependency Injection"?
## What is "Dependency Injection"
**"Dependency Injection"** means, in programming, that there is a way for your code (in this case, your path operation functions) to declare things that it requires to work and use: "dependencies".
**"Dependency Injection"** means, in programming, that there is a way for your code (in this case, your *path operation functions*) to declare things that it requires to work and use: "dependencies".
And then, that system (in this case **FastAPI**) will take care of doing whatever is needed to provide your code with those needed dependencies ("inject" the dependencies).
@ -13,7 +13,7 @@ This is very useful when you need to:
* Have shared logic (the same code logic again and again).
* Share database connections.
* Enforce security, authentication, role requirements, etc.
* etc.
* And many other things...
All these, while minimizing code repetition.
@ -27,7 +27,7 @@ But this way we can focus on how the **Dependency Injection** system works.
Let's first focus on the dependency.
It is just a function that can take all the same parameters that a path operation function can take:
It is just a function that can take all the same parameters that a *path operation function* can take:
```Python hl_lines="6 7"
{!./src/dependencies/tutorial001.py!}
@ -37,9 +37,9 @@ That's it.
**2 lines**.
And it has the same shape and structure that all your path operation functions.
And it has the same shape and structure that all your *path operation functions*.
You can think of it as a path operation function without the "decorator" (without the `@app.get("/some-path")`).
You can think of it as a *path operation function* without the "decorator" (without the `@app.get("/some-path")`).
And it can return anything you want.
@ -59,7 +59,7 @@ And then it just returns a `dict` containing those values.
### Declare the dependency, in the "dependant"
The same way you use `Body`, `Query`, etc. with your path operation function parameters, use `Depends` with a new parameter:
The same way you use `Body`, `Query`, etc. with your *path operation function* parameters, use `Depends` with a new parameter:
```Python hl_lines="11 16"
{!./src/dependencies/tutorial001.py!}
@ -71,7 +71,7 @@ You only give `Depends` a single parameter.
This parameter must be something like a function.
And that function takes parameters in the same way that path operation functions do.
And that function takes parameters in the same way that *path operation functions* do.
!!! tip
You'll see what other "things", apart from functions, can be used as dependencies in the next chapter.
@ -80,26 +80,25 @@ Whenever a new request arrives, **FastAPI** will take care of:
* Calling your dependency ("dependable") function with the correct parameters.
* Get the result from your function.
* Assign that result to the parameter in your path operation function.
* Assign that result to the parameter in your *path operation function*.
!!! note
!!! check
Notice that you don't have to create a special class and pass it somewhere to **FastAPI** to "register" it or anything similar.
You just pass it to `Depends` and **FastAPI** knows how to do the rest.
## To `async` or not to `async`
As dependencies will also be called by **FastAPI** (the same as your path operation functions), the same rules apply while defining your functions.
As dependencies will also be called by **FastAPI** (the same as your *path operation functions*), the same rules apply while defining your functions.
You can use `async def` or normal `def`.
And you can declare dependencies with `async def` inside of normal `def` path operation functions, or `def` dependencies inside of `async def` path operation functions, etc.
And you can declare dependencies with `async def` inside of normal `def`*path operation functions*, or `def` dependencies inside of `async def`*path operation functions*, etc.
It doesn't matter. **FastAPI** will know what to do.
!!! note
If you don't know, check the _"In a hurry?"_ section about <ahref="https://fastapi.tiangolo.com/async/#in-a-hurry"target="_blank">`async` and `await` in the docs</a>.
If you don't know, check the [Async: *"In a hurry?"*](../../async.md){.internal-link target=_blank} section about `async` and `await` in the docs.
## Integrated with OpenAPI
@ -118,7 +117,7 @@ Actually, all (or most) of the web frameworks work in this same way.
You never call those functions directly. They are called by your framework (in this case, **FastAPI**).
With the Dependency Injection system, you can also tell **FastAPI** that your path operation function also "depends" on something else that should be executed before your *path operation function*, and **FastAPI** will take care of executing it and "injecting" the results.
With the Dependency Injection system, you can also tell **FastAPI** that your *path operation function* also "depends" on something else that should be executed before your *path operation function*, and **FastAPI** will take care of executing it and "injecting" the results.
Other common terms for this same idea of "dependency injection" are:
@ -130,9 +129,9 @@ Other common terms for this same idea of "dependency injection" are:
## **FastAPI** plug-ins
Integrations and "plug-in"s can be built using the **Dependency Injection** system. But in fact, there is actually **no need to create "plug-ins"**, as by using dependencies it's possible to declare an infinite number of integrations and interactions that become available to your path operation functions.
Integrations and "plug-in"s can be built using the **Dependency Injection** system. But in fact, there is actually **no need to create "plug-ins"**, as by using dependencies it's possible to declare an infinite number of integrations and interactions that become available to your *path operation functions*.
And dependencies can be created in a very simple and intuitive way that allow you to just import the Python packages you need, and integrate them with your API functions in a couple of lines of code, _literally_.
And dependencies can be created in a very simple and intuitive way that allow you to just import the Python packages you need, and integrate them with your API functions in a couple of lines of code, *literally*.
You will see examples of this in the next chapters, about relational and NoSQL databases, security, etc.
@ -159,6 +158,6 @@ In the end, a hierarchical tree of dependencies is built, and the **Dependency I
## Integrated with **OpenAPI**
All these dependencies, while declaring their requirements, add parameters, validations, etc. to your path operations.
All these dependencies, while declaring their requirements, also add parameters, validations, etc. to your *path operations*.
**FastAPI** will take care of adding it all to the OpenAPI schema, so that it is shown in the interactive documentation systems.
@ -9,7 +9,7 @@ This is especially the case for user models, because:
!!! danger
Never store user's plaintext passwords. Always store a "secure hash" that you can then verify.
If you don't know, you will learn what a "password hash" is in the <ahref="/tutorial/security/simple-oauth2/#password-hashing"target="_blank">security chapters</a>.
If you don't know, you will learn what a "password hash" is in the [security chapters](security/simple-oauth2.md#password-hashing){.internal-link target=_blank}.
@ -160,7 +160,7 @@ And put it in a file `main.py`, then you would call `uvicorn` like:
uvicorn main:my_awesome_api --reload
```
### Step 3: create a path operation
### Step 3: create a *path operation*
#### Path
@ -218,7 +218,7 @@ So, in OpenAPI, each of the HTTP methods is called an "operation".
We are going to call them "**operations**" too.
#### Define a path operation function
#### Define a *path operation function*
```Python hl_lines="6"
{!./src/first_steps/tutorial001.py!}
@ -289,7 +289,7 @@ You could also define it as a normal function instead of `async def`:
```
!!! note
If you don't know the difference, check the _"In a hurry?"_ section about <ahref="https://fastapi.tiangolo.com/async/#in-a-hurry"target="_blank">`async` and `await` in the docs</a>.
If you don't know the difference, check the [Async: *"In a hurry?"*](../async.md#in-a-hurry){.internal-link target=_blank}.
@ -33,7 +33,7 @@ To return HTTP responses with errors to the client you use `HTTPException`.
Because it's a Python exception, you don't `return` it, you `raise` it.
This also means that if you are inside a utility function that you are calling inside of your path operation function, and you raise the `HTTPException` from inside of that utility function, it won't run the rest of the code in the path operation function, it will terminate that request right away and send the HTTP error from the `HTTPException` to the client.
This also means that if you are inside a utility function that you are calling inside of your *path operation function*, and you raise the `HTTPException` from inside of that utility function, it won't run the rest of the code in the *path operation function*, it will terminate that request right away and send the HTTP error from the `HTTPException` to the client.
The benefit of raising an exception over `return`ing a value will be more evident in the section about Dependencies and Security.
@ -231,7 +231,7 @@ So, you can keep raising **FastAPI**'s `HTTPException` as normally in your code.
But when you register an exception handler, you should register it for Starlette's `HTTPException`.
This way, if any part of Starlette's internal code, or a Starlette extension or plug-in, raises an `HTTPException`, your handler will be able to catch handle it.
This way, if any part of Starlette's internal code, or a Starlette extension or plug-in, raises an `HTTPException`, your handler will be able to catch and handle it.
In this example, to be able to have both `HTTPException`s in the same code, Starlette's exceptions is renamed to `StarletteHTTPException`:
@ -246,9 +246,9 @@ You could also just want to use the exception somehow, but then use the same def
You can import and re-use the default exception handlers from `fastapi.exception_handlers`:
```Python hl_lines="2 3 4 5 15 21"
{!./src/handling_errors/tutorial005.py!}
{!./src/handling_errors/tutorial006.py!}
```
In this example, you are just `print`ing the error with a very expressive notification.
In this example, you are just `print`ing the error with a very expressive message.
But you get the idea, you can use the exception and then just re-use the default exception handlers.
@ -21,7 +21,7 @@ The first value is the default value, you can pass all the extra validation or a
!!! note "Technical Details"
`Header` is a "sister" class of `Path`, `Query` and `Cookie`. It also inherits from the same common `Param` class.
But remember that when you import `Query`, `Path`, `Header`, and others from `fastapi`, <ahref="https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#recap"target="_blank">those are actually functions that return classes of the same name</a>.
But remember that when you import `Query`, `Path`, `Header`, and others from `fastapi`, those are actually functions that return special classes.
!!! info
To declare headers, you need to use `Header`, because otherwise the parameters would be interpreted as query parameters.
This tutorial shows you how to use **FastAPI** with all its features, step by step.
This tutorial shows you how to use **FastAPI** with most of its features, step by step.
Each section gradually builds on the previous ones, but it's structured to separate topics, so that you can go directly to any specific one to solve your specific API needs.
@ -36,7 +36,7 @@ pip install fastapi[all]
!!! note
You can also install it part by part.
This is what you would probably do once you want to deploy your application to production:
```
@ -50,3 +50,13 @@ pip install fastapi[all]
```
And the same for each of the optional dependencies that you want to use.
## Advanced User Guide
There is also an **Advanced User Guide** that you can read later after this **Tutorial - User guide**.
The **Advanced User Guide**, builds on this, uses the same concepts, and teaches you some extra features.
But you should first read the **Tutorial - User guide** (what you are reading right now).
It's designed so that you can build a complete application with just the **Tutorial - User guide**, and then extend it in different ways, depending on your needs, using some of the additional ideas from the **Advanced User Guide**.
@ -25,17 +25,15 @@ The middleware function receives:
{!./src/middleware/tutorial001.py!}
```
!!! tip
This technique is used in the tutorial about <ahref="https://fastapi.tiangolo.com/tutorial/sql-databases/"target="_blank">SQL (Relational) Databases</a>.
!!! tip
Have in mind that custom proprietary headers can be added <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers"class="external-link"target="_blank">using the 'X-' prefix</a>.
But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your <ahref="https://fastapi.tiangolo.com/tutorial/cors/"target="_blank">CORS configurations</a>, using the parameter `expose_headers` documented in <ahref="https://www.starlette.io/middleware/#corsmiddleware"class="external-link"target="_blank">Starlette's CORS docs</a>.
But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your CORS configurations ([CORS (Cross-Origin Resource Sharing)
](cors.md){.internal-link target=_blank}) using the parameter `expose_headers` documented in <ahref="https://www.starlette.io/middleware/#corsmiddleware"class="external-link"target="_blank">Starlette's CORS docs</a>.
### Before and after the `response`
You can add code to be run with the `request`, before any *path operation* receives it.
You can add code to be run with the `request`, before any *path operation* receives it.
And also after the `response` is generated, before returning it.
@ -39,9 +39,9 @@ You can add a `summary` and `description`:
## Description from docstring
As descriptions tend to be long and cover multiple lines, you can declare the path operation description in the function <abbrtitle="a multi-line string as the first expression inside a function (not assigned to any variable) used for documentation">docstring</abbr> and **FastAPI** will read it from there.
As descriptions tend to be long and cover multiple lines, you can declare the *path operation* description in the function <abbrtitle="a multi-line string as the first expression inside a function (not assigned to any variable) used for documentation">docstring</abbr> and **FastAPI** will read it from there.
You can write <ahref="https://en.wikipedia.org/wiki/Markdown"class="target-blank"target="_blank">Markdown</a> in the docstring, it will be interpreted and displayed correctly (taking into account docstring indentation).
You can write <ahref="https://en.wikipedia.org/wiki/Markdown"class="external-link"target="_blank">Markdown</a> in the docstring, it will be interpreted and displayed correctly (taking into account docstring indentation).
If you need to mark a path operation as <abbrtitle="obsolete, recommended not to use it">deprecated</abbr>, but without removing it, pass the parameter `deprecated`:
If you need to mark a *path operation* as <abbrtitle="obsolete, recommended not to use it">deprecated</abbr>, but without removing it, pass the parameter `deprecated`:
## Number validations: greater than and less than or equal
The same applies for:
@ -93,7 +94,7 @@ And the same for <abbr title="less than"><code>lt</code></abbr>.
## Recap
With `Query`, `Path` (and others you haven't seen yet) you can declare [metadata and string validations (the previous chapter)](/tutorial/query-params-str-validations).
With `Query`, `Path` (and others you haven't seen yet) you can declare metadata and string validations in the same ways as with [Query Parameters and String Validations](query-params-str-validations.md){.internal-link target=_blank}.
@ -105,7 +105,7 @@ Like `/users/me`, let's say that it's to get data about the current user.
And then you can also have a path `/users/{user_id}` to get data about a specific user by some user ID.
Because path operations are evaluated in order, you need to make sure that the path for `/users/me` is declared before the one for `/users/{user_id}`:
Because *path operations* are evaluated in order, you need to make sure that the path for `/users/me` is declared before the one for `/users/{user_id}`:
@ -188,7 +188,7 @@ In this case, there are 3 query parameters:
* `limit`, an optional `int`.
!!! tip
You could also use `Enum`s <ahref="https://fastapi.tiangolo.com/tutorial/path-params/#predefined-values"target="_blank">the same way as with *path parameters*</a>.
You could also use `Enum`s the same way as with [Path Parameters](path-params.md#predefined-values){.internal-link target=_blank}.
@ -26,9 +26,9 @@ Create file parameters the same way you would for `Body` or `Form`:
!!! info
`File` is a class that inherits directly from `Form`.
But remember that when you import `Query`, `Path`, `File` and others from `fastapi`, <ahref="https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#recap"target="_blank">those are actually functions that return classes of the same name</a>.
But remember that when you import `Query`, `Path`, `File` and others from `fastapi`, those are actually functions that return special classes.
!!! info
!!! tip
To declare File bodies, you need to use `File`, because otherwise the parameters would be interpreted as query parameters or body (JSON) parameters.
The files will be uploaded as "form data".
@ -62,7 +62,7 @@ Using `UploadFile` has several advantages over `bytes`:
* `filename`: A `str` with the original file name that was uploaded (e.g. `myimage.jpg`).
* `content_type`: A `str` with the content type (MIME type / media type) (e.g. `image/jpeg`).
* `file`: A <ahref="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile"target="_blank">`SpooledTemporaryFile`</a> (a <ahref="https://docs.python.org/3/glossary.html#term-file-like-object"target="_blank">file-like</a> object). This is the actual Python file that you can pass directly to other functions or libraries that expect a "file-like" object.
* `file`: A <ahref="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile"class="external-link"target="_blank">`SpooledTemporaryFile`</a> (a <ahref="https://docs.python.org/3/glossary.html#term-file-like-object"class="external-link"target="_blank">file-like</a> object). This is the actual Python file that you can pass directly to other functions or libraries that expect a "file-like" object.
`UploadFile` has the following `async` methods. They all call the corresponding file methods underneath (using the internal `SpooledTemporaryFile`).
@ -107,7 +107,7 @@ The way HTML forms (`<form></form>`) sends the data to the server normally uses
If you want to read more about these encodings and form fields, head to the <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST"class="external-link"target="_blank"><abbrtitle="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
!!! warning
You can declare multiple `File` and `Form` parameters in a path operation, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
You can declare multiple `File` and `Form` parameters in a *path operation*, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
@ -126,7 +126,7 @@ To use that, declare a `List` of `bytes` or `UploadFile`:
You will receive, as declared, a `list` of `bytes` or `UploadFile`s.
!!! note
Notice that, as of 2019-04-14, Swagger UI doesn't support multiple file uploads in the same form field. For more information, check <ahref="https://github.com/swagger-api/swagger-ui/issues/4276"target="_blank">#4276</a> and <ahref="https://github.com/swagger-api/swagger-ui/issues/3641"class="external-link"target="_blank">#3641</a>.
Notice that, as of 2019-04-14, Swagger UI doesn't support multiple file uploads in the same form field. For more information, check <ahref="https://github.com/swagger-api/swagger-ui/issues/4276"class="external-link"target="_blank">#4276</a> and <ahref="https://github.com/swagger-api/swagger-ui/issues/3641"class="external-link"target="_blank">#3641</a>.
Nevertheless, **FastAPI** is already compatible with it, using the standard OpenAPI.
@ -24,7 +24,7 @@ The files and form fields will be uploaded as form data and you will receive the
And you can declare some of the files as `bytes` and some as `UploadFile`.
!!! warning
You can declare multiple `File` and `Form` parameters in a path operation, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
You can declare multiple `File` and `Form` parameters in a *path operation*, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
@ -30,7 +30,7 @@ With `Form` you can declare the same metadata and validation as with `Body` (and
!!! info
`Form` is a class that inherits directly from `Body`.
!!! info
!!! tip
To declare form bodies, you need to use `Form` explicitly, because without it the parameters would be interpreted as query parameters or body (JSON) parameters.
## About "Form Fields"
@ -47,7 +47,7 @@ The way HTML forms (`<form></form>`) sends the data to the server normally uses
If you want to read more about these encodings and form fields, head to the <ahref="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST"class="external-link"target="_blank"><abbrtitle="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
!!! warning
You can declare multiple `Form` parameters in a path operation, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `application/x-www-form-urlencoded` instead of `application/json`.
You can declare multiple `Form` parameters in a *path operation*, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `application/x-www-form-urlencoded` instead of `application/json`.
This is not a limitation of **FastAPI**, it's part of the HTTP protocol.
You can declare the model used for the response with the parameter `response_model` in any of the path operations:
You can declare the model used for the response with the parameter `response_model` in any of the *path operations*:
* `@app.get()`
* `@app.post()`
@ -11,7 +11,7 @@ You can declare the model used for the response with the parameter `response_mod
```
!!! note
Notice that `response_model` is a parameter of the "decorator" method (`get`, `post`, etc). Not of your path operation function, like all the parameters and body.
Notice that `response_model` is a parameter of the "decorator" method (`get`, `post`, etc). Not of your *path operation function*, like all the parameters and body.
It receives the same type you would declare for a Pydantic model attribute, so, it can be a Pydantic model, but it can also be, e.g. a `list` of Pydantic models, like `List[Item]`.
@ -19,7 +19,7 @@ FastAPI will use this `response_model` to:
* Convert the output data to its type declaration.
* Validate the data.
* Add a JSON Schema for the response, in the OpenAPI path operation.
* Add a JSON Schema for the response, in the OpenAPI *path operation*.
* Will be used by the automatic documentation systems.
But most importantly:
@ -47,7 +47,7 @@ Now, whenever a browser is creating a user with a password, the API will return
In this case, it might not be a problem, because the user himself is sending the password.
But if we use the same model for another path operation, we could be sending our user's passwords to every client.
But if we use the same model for another *path operation*, we could be sending our user's passwords to every client.
!!! danger
Never send the plain password of a user in a response.
@ -60,7 +60,7 @@ We can instead create an input model with the plaintext password and an output m
{!./src/response_model/tutorial003.py!}
```
Here, even though our path operation function is returning the same input user that contains the password:
Here, even though our *path operation function* is returning the same input user that contains the password:
```Python hl_lines="22"
{!./src/response_model/tutorial003.py!}
@ -192,6 +192,6 @@ If you forget to use a `set` and use a `list` or `tuple` instead, FastAPI will s
## Recap
Use the path operation decorator's parameter `response_model` to define response models and especially to ensure private data is filtered out.
Use the *path operation decorator's* parameter `response_model` to define response models and especially to ensure private data is filtered out.
Use `response_model_exclude_unset` to return only the values explicitly set.
The same way you can specify a response model, you can also declare the HTTP status code used for the response with the parameter `status_code` in any of the path operations:
The same way you can specify a response model, you can also declare the HTTP status code used for the response with the parameter `status_code` in any of the *path operations*:
* `@app.get()`
* `@app.post()`
@ -11,7 +11,7 @@ The same way you can specify a response model, you can also declare the HTTP sta
```
!!! note
Notice that `status_code` is a parameter of the "decorator" method (`get`, `post`, etc). Not of your path operation function, like all the parameters and body.
Notice that `status_code` is a parameter of the "decorator" method (`get`, `post`, etc). Not of your *path operation function*, like all the parameters and body.
The `status_code` parameter receives a number with the HTTP status code.
@ -76,4 +76,4 @@ They are just a convenience, they hold the same number, but that way you can use
## Changing the default
Later, in a more advanced part of the tutorial/user guide, you will see how to <ahref="https://fastapi.tiangolo.com/tutorial/response-change-status-code/"target="_blank">return a different status code than the default</a> you are declaring here.
Later, in the **Advanced User Guide**, you will see how to return a different status code than the default you are declaring here.
@ -48,7 +48,7 @@ You will see something like this:
!!! check "Authorize button!"
You already have a shinny new "Authorize" button.
And your path operation has a little lock in the top-right corner that you can click.
And your *path operation* has a little lock in the top-right corner that you can click.
And if you click it, you have a little authorization form to type a `username` and `password` (and other optional fields):
@ -112,7 +112,7 @@ In this example we are going to use **OAuth2**, with the **Password** flow, usin
{!./src/security/tutorial001.py!}
```
It doesn't create that endpoint / path operation, but declares that that URL is the one that the client should use to get the token. That information is used in OpenAPI, and then in the interactive API documentation systems.
It doesn't create that endpoint / *path operation*, but declares that that URL is the one that the client should use to get the token. That information is used in OpenAPI, and then in the interactive API documentation systems.
!!! info
If you are a very strict "Pythonista" you might dislike the style of the parameter name `tokenUrl` instead of `token_url`.
In the previous chapter the security system (which is based on the dependency injection system) was giving the path operation function a `token` as a `str`:
In the previous chapter the security system (which is based on the dependency injection system) was giving the *path operation function* a `token` as a `str`:
```Python hl_lines="10"
{!./src/security/tutorial001.py!}
@ -26,7 +26,7 @@ Remember that dependencies can have sub-dependencies?
`get_current_user` will have a dependency with the same `oauth2_scheme` we created before.
The same as we were doing before in the path operation directly, our new dependency `get_current_user` will receive a `token` as a `str` from the sub-dependency `oauth2_scheme`:
The same as we were doing before in the *path operation* directly, our new dependency `get_current_user` will receive a `token` as a `str` from the sub-dependency `oauth2_scheme`:
```Python hl_lines="25"
{!./src/security/tutorial002.py!}
@ -42,7 +42,7 @@ The same as we were doing before in the path operation directly, our new depende
## Inject the current user
So now we can use the same `Depends` with our `get_current_user` in the path operation:
So now we can use the same `Depends` with our `get_current_user` in the *path operation*:
```Python hl_lines="31"
{!./src/security/tutorial002.py!}
@ -65,7 +65,7 @@ This will help us inside of the function with all the completion and type checks
## Other models
You can now get the current user directly in the path operation functions and deal with the security mechanisms at the **Dependency Injection** level, using `Depends`.
You can now get the current user directly in the *path operation functions* and deal with the security mechanisms at the **Dependency Injection** level, using `Depends`.
And you can use any model or data for the security requirements (in this case, a Pydantic model `User`).
@ -82,7 +82,7 @@ Just use any kind of model, any kind of class, any kind of database that you nee
## Code size
This example might seem verbose. Have in mind that we are mixing security, data models utility functions and path operations in the same file.
This example might seem verbose. Have in mind that we are mixing security, data models utility functions and *path operations* in the same file.
But here's the key point.
@ -90,11 +90,11 @@ The security and dependency injection stuff is written once.
And you can make it as complex as you want. And still, have it written only once, in a single place. With all the flexibility.
But you can have thousands of endpoints (path operations) using the same security system.
But you can have thousands of endpoints (*path operations*) using the same security system.
And all of them (or any portion of them that you want) can take the advantage of re-using these dependencies or any other dependencies you create.
And all these thousands of path operations can be as small as 3 lines:
And all these thousands of *path operations* can be as small as 3 lines:
```Python hl_lines="30 31 32"
{!./src/security/tutorial002.py!}
@ -102,10 +102,10 @@ And all these thousands of path operations can be as small as 3 lines:
## Recap
You can now get the current user directly in your path operation function.
You can now get the current user directly in your *path operation function*.
We are already halfway there.
We just need to add a path operation for the user/client to actually send the `username` and `password`.
We just need to add a *path operation* for the user/client to actually send the `username` and `password`.
@ -18,9 +18,9 @@ It is not encrypted, so, anyone could recover the information from the contents.
But it's signed. So, when you receive a token that you emitted, you can verify that you actually emitted it.
That way, you can create a token with an expiration of, let's say, 1 week, and then, after a week, when the user comes back with the token, you know he's still signed into your system.
That way, you can create a token with an expiration of, let's say, 1 week. And then when the user comes back the next day with the token, you know she/he is still signed into your system.
And after a week, the token will be expired. And if the user (or a third party) tried to modify the token to change the expiration, you would be able to discover it, because the signatures would not match.
And after a week, the token will be expired and the user will not be authorized and will have to sign in again to get a new token. And if the user (or a third party) tried to modify the token to change the expiration, you would be able to discover it, because the signatures would not match.
If you want to play with JWT tokens and see how they work, check <ahref="https://jwt.io/"class="external-link"target="_blank">https://jwt.io</a>.
@ -131,7 +131,7 @@ If the token is invalid, return an HTTP error right away.
{!./src/security/tutorial004.py!}
```
## Update the `/token` path operation
## Update the `/token`*path operation*
Create a `timedelta` with the expiration time of the token.
@ -211,7 +211,7 @@ You can use them to add a specific set of permissions to a JWT token.
Then you can give this token to a user directly or a third party, to interact with your API with a set of restrictions.
You can learn how to use them and how they are integrated into **FastAPI**in the next chapter.
You can learn how to use them and how they are integrated into **FastAPI**later in the **Advanced User Guide**.
## Recap
@ -229,10 +229,8 @@ It gives you all the flexibility to choose the ones that fit your project the be
And you can use directly many well maintained and widely used packages like `passlib` and `pyjwt`, because **FastAPI** doesn't require any complex mechanisms to integrate external packages.
But it provides you the tools to simplify the process as much as possible without compromising flexibility, robustness or security.
But it provides you the tools to simplify the process as much as possible without compromising flexibility, robustness, or security.
And you can use and implement secure, standard protocols, like OAuth2 in a relatively simple way.
In the next (optional) section you can see how to extend this even further, using OAuth2 "scopes", for a more fine-grained permission system, following these same standards.
OAuth2 with scopes (explained in the next section) is the mechanism used by many big authentication providers, like Facebook, Google, GitHub, Microsoft, Twitter, etc.
You can learn more in the **Advanced User Guide** about how to use OAuth2 "scopes", for a more fine-grained permission system, following these same standards. OAuth2 with scopes is the mechanism used by many big authentication providers, like Facebook, Google, GitHub, Microsoft, Twitter, etc. to authorize third party applications to interact with their APIs on behalf of their users.
@ -12,7 +12,7 @@ But don't worry, you can show it as you wish to your final users in the frontend
And your database models can use any other names you want.
But for the login path operation, we need to use these names to be compatible with the spec (and be able to, for example, use the integrated API documentation system).
But for the login *path operation*, we need to use these names to be compatible with the spec (and be able to, for example, use the integrated API documentation system).
The spec also states that the `username` and `password` must be sent as form data (so, no JSON here).
@ -26,14 +26,14 @@ Each "scope" is just a string (without spaces).
They are normally used to declare specific security permissions, for example:
* `"users:read"` or `"users:write"` are common examples.
* `users:read` or `users:write` are common examples.
* `instagram_basic` is used by Facebook / Instagram.
* `https://www.googleapis.com/auth/drive` is used by Google.
!!! info
In OAuth2 a "scope" is just a string that declares a specific permission required.
It doesn't matter if it has other characters like `:`, or if it is a URL.
It doesn't matter if it has other characters like `:` or if it is a URL.
Those details are implementation specific.
@ -114,7 +114,7 @@ But you cannot convert from the gibberish back to the password.
If your database is stolen, the thief won't have your users' plaintext passwords, only the hashes.
So, the thief won't be able to try to use that password in another system (as many users use the same password everywhere, this would be dangerous).
So, the thief won't be able to try to use those same passwords in another system (as many users use the same password everywhere, this would be dangerous).
```Python hl_lines="79 80 81 82"
{!./src/security/tutorial003.py!}
@ -137,7 +137,7 @@ UserInDB(
```
!!! info
For a more complete explanation of `**user_dict` check back in <ahref="/tutorial/extra-models/#about-user_indict"target="_blank">the documentation for **Extra Models**</a>.
For a more complete explanation of `**user_dict` check back in [the documentation for **Extra Models**](../extra-models.md#about-user_indict){.internal-link target=_blank}.
By creating functions that are only dedicated to interacting with the database (get a user or an item) independent of your path operation function, you can more easily reuse them in multiple parts and also add <abbrtitle="Automated tests, written in code, that check if another piece of code is working correctly.">unit tests</abbr> for them.
By creating functions that are only dedicated to interacting with the database (get a user or an item) independent of your *path operation function*, you can more easily reuse them in multiple parts and also add <abbrtitle="Automated tests, written in code, that check if another piece of code is working correctly.">unit tests</abbr> for them.
### Create data
@ -444,7 +444,7 @@ A "migration" is the set of steps needed whenever you change the structure of yo
pip install async-exit-stack async-generator
```
This installs <ahref="https://github.com/sorcio/async_exit_stack"target="_blank">async-exit-stack</a> and <ahref="https://github.com/python-trio/async_generator"class="external-link"target="_blank">async-generator</a>.
This installs <ahref="https://github.com/sorcio/async_exit_stack"class="external-link"target="_blank">async-exit-stack</a> and <ahref="https://github.com/python-trio/async_generator"class="external-link"target="_blank">async-generator</a>.
You can also use the alternative method with a "middleware" explained at the end.
@ -454,7 +454,7 @@ We need to have an independent database session/connection (`SessionLocal`) per
And then a new session will be created for the next request.
For that, we will create a new dependency with `yield`, as explained before in the section about <ahref="https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/"target="_blank">Dependencies with `yield`</a>.
For that, we will create a new dependency with `yield`, as explained before in the section about [Dependencies with `yield`](dependencies/dependencies-with-yield.md){.internal-link target=_blank}.
Our dependency will create a new SQLAlchemy `SessionLocal` that will be used in a single request, and then close it once the request is finished.
@ -492,9 +492,9 @@ Now, finally, here's the standard **FastAPI** *path operations* code.
We are creating the database session before each request in the dependency with `yield`, and then closing it afterwards.
And then we can create the required dependency in the path operation function, to get that session directly.
And then we can create the required dependency in the *path operation function*, to get that session directly.
With that, we can just call `crud.get_user` directly from inside of the path operation function and use that session.
With that, we can just call `crud.get_user` directly from inside of the *path operation function* and use that session.
!!! tip
Notice that the values you return are SQLAlchemy models, or lists of SQLAlchemy models.
@ -508,7 +508,7 @@ With that, we can just call `crud.get_user` directly from inside of the path ope
### About `def` vs `async def`
Here we are using SQLAlchemy code inside of the path operation function and in the dependency, and, in turn, it will go and communicate with an external database.
Here we are using SQLAlchemy code inside of the *path operation function* and in the dependency, and, in turn, it will go and communicate with an external database.
If you are curious and have a deep technical knowledge, you can check <ahref="https://fastapi.tiangolo.com/async/#very-technical-details"target="_blank">the very technical details of how this `async def` vs `def` is handled</a>.
If you are curious and have a deep technical knowledge, you can check the very technical details of how this `async def` vs `def` is handled in the [Async](../async.md#very-technical-details){.internal-link target=_blank} docs.
You can also use an online SQLite browser like <ahref="https://inloop.github.io/sqlite-viewer/"target="_blank">SQLite Viewer</a> or <ahref="https://extendsclass.com/sqlite-browser.html"class="external-link"target="_blank">ExtendsClass</a>.
You can also use an online SQLite browser like <ahref="https://inloop.github.io/sqlite-viewer/"class="external-link"target="_blank">SQLite Viewer</a> or <ahref="https://extendsclass.com/sqlite-browser.html"class="external-link"target="_blank">ExtendsClass</a>.
* "Mount" it the same way you would <ahref="https://fastapi.tiangolo.com/tutorial/sub-applications-proxy/"target="_blank">mount a Sub-Application</a>.
* "Mount" a `StaticFiles()` instance in a specific path.
```Python hl_lines="2 6"
{!./src/static_files/tutorial001.py!}
```
Then you could have a directory `./static/` with some files that will be served directly.
### What is "Mounting"
"Mounting" means adding a complete "independent" application in a specific path, that then takes care of handling all the sub-paths.
This is different from using an `APIRouter` as a mounted application is completely independent. The OpenAPI and docs from your main application won't include anything from the mounted application, etc.
You can read more about this in the **Advanced User Guide**.
@ -92,25 +92,7 @@ For more information about how to pass data to the backend (using `requests` or
!!! info
Note that the `TestClient` receives data that can be converted to JSON, not Pydantic models.
If you have a Pydantic model in your test and you want to send its data to the application during testing, you can use the <ahref="https://fastapi.tiangolo.com/tutorial/encoder/"target="_blank">JSON compatible encoder: `jsonable_encoder`</a>.
## Testing WebSockets
You can use the same `TestClient` to test WebSockets.
For this, you use the `TestClient` in a `with` statement, connecting to the WebSocket:
```Python hl_lines="27 28 29 30 31"
{!./src/app_testing/tutorial002.py!}
```
## Testing Events, `startup` and `shutdown`
When you need your event handlers (`startup` and `shutdown`) to run in your tests, you can use the `TestClient` with a `with` statement:
```Python hl_lines="9 10 11 12 20 21 22 23 24"
{!./src/app_testing/tutorial003.py!}
```
If you have a Pydantic model in your test and you want to send its data to the application during testing, you can use the `jsonable_encoder` descibed in [JSON Compatible Encoder](encoder.md){.internal-link target=_blank}.
Sebastián Ramírez
5 years ago
GitHub