: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
diff --git a/docs/en/docs/alternatives.md b/docs/en/docs/alternatives.md
index 2ad584c95..e98c0475a 100644
--- a/docs/en/docs/alternatives.md
+++ b/docs/en/docs/alternatives.md
@@ -474,7 +474,7 @@ It is the recommended server for Starlette and **FastAPI**.
The main web server to run **FastAPI** applications.
-You can combine it with Gunicorn, to have an asynchronous multi-process server.
+You can also use the `--workers` command line option to have an asynchronous multi-process server.
Check more details in the [Deployment](deployment/index.md){.internal-link target=_blank} section.
diff --git a/docs/en/docs/async.md b/docs/en/docs/async.md
index 7cf4af627..63bd8ca68 100644
--- a/docs/en/docs/async.md
+++ b/docs/en/docs/async.md
@@ -292,7 +292,7 @@ For example:
### Concurrency + Parallelism: Web + Machine Learning
-With **FastAPI** you can take the advantage of concurrency that is very common for web development (the same main attraction of NodeJS).
+With **FastAPI** you can take advantage of concurrency that is very common for web development (the same main attraction of NodeJS).
But you can also exploit the benefits of parallelism and multiprocessing (having multiple processes running in parallel) for **CPU bound** workloads like those in Machine Learning systems.
@@ -387,7 +387,7 @@ In previous versions of NodeJS / Browser JavaScript, you would have used "callba
## 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.
+**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.
But all this functionality of using asynchronous code with `async` and `await` is many times summarized as using "coroutines". It is comparable to the main key feature of Go, the "Goroutines".
diff --git a/docs/en/docs/contributing.md b/docs/en/docs/contributing.md
index 91d5724a8..0dc07b89b 100644
--- a/docs/en/docs/contributing.md
+++ b/docs/en/docs/contributing.md
@@ -170,7 +170,7 @@ If you run the examples with, e.g.:
```console
-$ uvicorn tutorial001:app --reload
+$ fastapi dev tutorial001.py
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
diff --git a/docs/en/docs/deployment/cloud.md b/docs/en/docs/deployment/cloud.md
index d34fbe2f7..3ea5087f8 100644
--- a/docs/en/docs/deployment/cloud.md
+++ b/docs/en/docs/deployment/cloud.md
@@ -14,4 +14,4 @@ You might want to try their services and follow their guides:
*
Platform.sh
*
Porter
-*
Coherence
+*
Coherence
diff --git a/docs/en/docs/deployment/concepts.md b/docs/en/docs/deployment/concepts.md
index f917d18b3..69ee71a73 100644
--- a/docs/en/docs/deployment/concepts.md
+++ b/docs/en/docs/deployment/concepts.md
@@ -94,7 +94,7 @@ In most cases, when you create a web API, you want it to be **always running**,
### In a Remote Server
-When you set up a remote server (a cloud server, a virtual machine, etc.) the simplest thing you can do is to use `fastapi run`, Uvicorn (or similar) manually, the same way you do when developing locally.
+When you set up a remote server (a cloud server, a virtual machine, etc.) the simplest thing you can do is use `fastapi run` (which uses Uvicorn) or something similar, manually, the same way you do when developing locally.
And it will work and will be useful **during development**.
@@ -178,7 +178,7 @@ For example, this could be handled by:
## Replication - Processes and Memory
-With a FastAPI application, using a server program like Uvicorn, running it once in **one process** can serve multiple clients concurrently.
+With a FastAPI application, using a server program like the `fastapi` command that runs Uvicorn, running it once in **one process** can serve multiple clients concurrently.
But in many cases, you will want to run several worker processes at the same time.
@@ -232,9 +232,7 @@ The main constraint to consider is that there has to be a **single** component h
Here are some possible combinations and strategies:
-* **Gunicorn** managing **Uvicorn workers**
- * Gunicorn would be the **process manager** listening on the **IP** and **port**, the replication would be by having **multiple Uvicorn worker processes**.
-* **Uvicorn** managing **Uvicorn workers**
+* **Uvicorn** with `--workers`
* One Uvicorn **process manager** would listen on the **IP** and **port**, and it would start **multiple Uvicorn worker processes**.
* **Kubernetes** and other distributed **container systems**
* Something in the **Kubernetes** layer would listen on the **IP** and **port**. The replication would be by having **multiple containers**, each with **one Uvicorn process** running.
diff --git a/docs/en/docs/deployment/docker.md b/docs/en/docs/deployment/docker.md
index 253e25fe5..2d832a238 100644
--- a/docs/en/docs/deployment/docker.md
+++ b/docs/en/docs/deployment/docker.md
@@ -167,22 +167,22 @@ def read_item(item_id: int, q: Union[str, None] = None):
Now in the same project directory create a file `Dockerfile` with:
```{ .dockerfile .annotate }
-# (1)
+# (1)!
FROM python:3.9
-# (2)
+# (2)!
WORKDIR /code
-# (3)
+# (3)!
COPY ./requirements.txt /code/requirements.txt
-# (4)
+# (4)!
RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
-# (5)
+# (5)!
COPY ./app /code/app
-# (6)
+# (6)!
CMD ["fastapi", "run", "app/main.py", "--port", "80"]
```
@@ -232,6 +232,38 @@ Review what each line does by clicking each number bubble in the code. ๐
///
+/// warning
+
+Make sure to **always** use the **exec form** of the `CMD` instruction, as explained below.
+
+///
+
+#### Use `CMD` - Exec Form
+
+The
`CMD` Docker instruction can be written using two forms:
+
+โ
**Exec** form:
+
+```Dockerfile
+# โ
Do this
+CMD ["fastapi", "run", "app/main.py", "--port", "80"]
+```
+
+โ๏ธ **Shell** form:
+
+```Dockerfile
+# โ๏ธ Don't do this
+CMD fastapi run app/main.py --port 80
+```
+
+Make sure to always use the **exec** form to ensure that FastAPI can shutdown gracefully and [lifespan events](../advanced/events.md){.internal-link target=_blank} are triggered.
+
+You can read more about it in the
Docker docs for shell and exec form.
+
+This can be quite noticeable when using `docker compose`. See this Docker Compose FAQ section for more technical details:
Why do my services take 10 seconds to recreate or stop?.
+
+#### Directory Structure
+
You should now have a directory structure like:
```
@@ -368,10 +400,10 @@ COPY ./requirements.txt /code/requirements.txt
RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
-# (1)
+# (1)!
COPY ./main.py /code/
-# (2)
+# (2)!
CMD ["fastapi", "run", "main.py", "--port", "80"]
```
@@ -424,11 +456,11 @@ Without using containers, making applications run on startup and with restarts c
## Replication - Number of Processes
-If you have a
cluster of machines with **Kubernetes**, Docker Swarm Mode, Nomad, or another similar complex system to manage distributed containers on multiple machines, then you will probably want to **handle replication** at the **cluster level** instead of using a **process manager** (like Gunicorn with workers) in each container.
+If you have a
cluster of machines with **Kubernetes**, Docker Swarm Mode, Nomad, or another similar complex system to manage distributed containers on multiple machines, then you will probably want to **handle replication** at the **cluster level** instead of using a **process manager** (like Uvicorn with workers) in each container.
One of those distributed container management systems like Kubernetes normally has some integrated way of handling **replication of containers** while still supporting **load balancing** for the incoming requests. All at the **cluster level**.
-In those cases, you would probably want to build a **Docker image from scratch** as [explained above](#dockerfile), installing your dependencies, and running **a single Uvicorn process** instead of running something like Gunicorn with Uvicorn workers.
+In those cases, you would probably want to build a **Docker image from scratch** as [explained above](#dockerfile), installing your dependencies, and running **a single Uvicorn process** instead of using multiple Uvicorn workers.
### Load Balancer
@@ -458,37 +490,44 @@ And normally this **load balancer** would be able to handle requests that go to
In this type of scenario, you probably would want to have **a single (Uvicorn) process per container**, as you would already be handling replication at the cluster level.
-So, in this case, you **would not** want to have a process manager like Gunicorn with Uvicorn workers, or Uvicorn using its own Uvicorn workers. You would want to have just a **single Uvicorn process** per container (but probably multiple containers).
+So, in this case, you **would not** want to have a multiple workers in the container, for example with the `--workers` command line option.You would want to have just a **single Uvicorn process** per container (but probably multiple containers).
-Having another process manager inside the container (as would be with Gunicorn or Uvicorn managing Uvicorn workers) would only add **unnecessary complexity** that you are most probably already taking care of with your cluster system.
+Having another process manager inside the container (as would be with multiple workers) would only add **unnecessary complexity** that you are most probably already taking care of with your cluster system.
### Containers with Multiple Processes and Special Cases
-Of course, there are **special cases** where you could want to have **a container** with a **Gunicorn process manager** starting several **Uvicorn worker processes** inside.
+Of course, there are **special cases** where you could want to have **a container** with several **Uvicorn worker processes** inside.
-In those cases, you can use the **official Docker image** that includes **Gunicorn** as a process manager running multiple **Uvicorn worker processes**, and some default settings to adjust the number of workers based on the current CPU cores automatically. I'll tell you more about it below in [Official Docker Image with Gunicorn - Uvicorn](#official-docker-image-with-gunicorn-uvicorn).
+In those cases, you can use the `--workers` command line option to set the number of workers that you want to run:
-Here are some examples of when that could make sense:
+```{ .dockerfile .annotate }
+FROM python:3.9
-#### A Simple App
+WORKDIR /code
-You could want a process manager in the container if your application is **simple enough** that you don't need (at least not yet) to fine-tune the number of processes too much, and you can just use an automated default (with the official Docker image), and you are running it on a **single server**, not a cluster.
+COPY ./requirements.txt /code/requirements.txt
-#### Docker Compose
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
-You could be deploying to a **single server** (not a cluster) with **Docker Compose**, so you wouldn't have an easy way to manage replication of containers (with Docker Compose) while preserving the shared network and **load balancing**.
+COPY ./app /code/app
-Then you could want to have **a single container** with a **process manager** starting **several worker processes** inside.
+# (1)!
+CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"]
+```
-#### Prometheus and Other Reasons
+1. Here we use the `--workers` command line option to set the number of workers to 4.
+
+Here are some examples of when that could make sense:
-You could also have **other reasons** that would make it easier to have a **single container** with **multiple processes** instead of having **multiple containers** with **a single process** in each of them.
+#### A Simple App
-For example (depending on your setup) you could have some tool like a Prometheus exporter in the same container that should have access to **each of the requests** that come.
+You could want a process manager in the container if your application is **simple enough** that can run it on a **single server**, not a cluster.
-In this case, if you had **multiple containers**, by default, when Prometheus came to **read the metrics**, it would get the ones for **a single container each time** (for the container that handled that particular request), instead of getting the **accumulated metrics** for all the replicated containers.
+#### Docker Compose
-Then, in that case, it could be simpler to have **one container** with **multiple processes**, and a local tool (e.g. a Prometheus exporter) on the same container collecting Prometheus metrics for all the internal processes and exposing those metrics on that single container.
+You could be deploying to a **single server** (not a cluster) with **Docker Compose**, so you wouldn't have an easy way to manage replication of containers (with Docker Compose) while preserving the shared network and **load balancing**.
+
+Then you could want to have **a single container** with a **process manager** starting **several worker processes** inside.
---
@@ -509,7 +548,7 @@ And then you can set those same memory limits and requirements in your configura
If your application is **simple**, this will probably **not be a problem**, and you might not need to specify hard memory limits. But if you are **using a lot of memory** (for example with **machine learning** models), you should check how much memory you are consuming and adjust the **number of containers** that runs in **each machine** (and maybe add more machines to your cluster).
-If you run **multiple processes per container** (for example with the official Docker image) you will have to make sure that the number of processes started doesn't **consume more memory** than what is available.
+If you run **multiple processes per container** you will have to make sure that the number of processes started doesn't **consume more memory** than what is available.
## Previous Steps Before Starting and Containers
@@ -529,80 +568,26 @@ If in your use case there's no problem in running those previous steps **multipl
### Single Container
-If you have a simple setup, with a **single container** that then starts multiple **worker processes** (or also just one process), then you could run those previous steps in the same container, right before starting the process with the app. The official Docker image supports this internally.
-
-## Official Docker Image with Gunicorn - Uvicorn
+If you have a simple setup, with a **single container** that then starts multiple **worker processes** (or also just one process), then you could run those previous steps in the same container, right before starting the process with the app.
-There is an official Docker image that includes Gunicorn running with Uvicorn workers, as detailed in a previous chapter: [Server Workers - Gunicorn with Uvicorn](server-workers.md){.internal-link target=_blank}.
+### Base Docker Image
-This image would be useful mainly in the situations described above in: [Containers with Multiple Processes and Special Cases](#containers-with-multiple-processes-and-special-cases).
+There used to be an official FastAPI Docker image:
tiangolo/uvicorn-gunicorn-fastapi. But it is now deprecated. โ๏ธ
-*
tiangolo/uvicorn-gunicorn-fastapi.
-
-/// warning
-
-There's a high chance that you **don't** need this base image or any other similar one, and would be better off by building the image from scratch as [described above in: Build a Docker Image for FastAPI](#build-a-docker-image-for-fastapi).
-
-///
+You should probably **not** use this base Docker image (or any other similar one).
-This image has an **auto-tuning** mechanism included to set the **number of worker processes** based on the CPU cores available.
+If you are using **Kubernetes** (or others) and you are already setting **replication** at the cluster level, with multiple **containers**. In those cases, you are better off **building an image from scratch** as described above: [Build a Docker Image for FastAPI](#build-a-docker-image-for-fastapi).
-It has **sensible defaults**, but you can still change and update all the configurations with **environment variables** or configuration files.
+And if you need to have multiple workers, you can simply use the `--workers` command line option.
-It also supports running
**previous steps before starting** with a script.
+/// note | Technical Details
-/// tip
+The Docker image was created when Uvicorn didn't support managing and restarting dead workers, so it was needed to use Gunicorn with Uvicorn, which added quite some complexity, just to have Gunicorn manage and restart the Uvicorn worker processes.
-To see all the configurations and options, go to the Docker image page:
tiangolo/uvicorn-gunicorn-fastapi.
+But now that Uvicorn (and the `fastapi` command) support using `--workers`, there's no reason to use a base Docker image instead of building your own (it's pretty much the same amount of code ๐
).
///
-### Number of Processes on the Official Docker Image
-
-The **number of processes** on this image is **computed automatically** from the CPU **cores** available.
-
-This means that it will try to **squeeze** as much **performance** from the CPU as possible.
-
-You can also adjust it with the configurations using **environment variables**, etc.
-
-But it also means that as the number of processes depends on the CPU the container is running, the **amount of memory consumed** will also depend on that.
-
-So, if your application consumes a lot of memory (for example with machine learning models), and your server has a lot of CPU cores **but little memory**, then your container could end up trying to use more memory than what is available, and degrading performance a lot (or even crashing). ๐จ
-
-### Create a `Dockerfile`
-
-Here's how you would create a `Dockerfile` based on this image:
-
-```Dockerfile
-FROM tiangolo/uvicorn-gunicorn-fastapi:python3.9
-
-COPY ./requirements.txt /app/requirements.txt
-
-RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt
-
-COPY ./app /app
-```
-
-### Bigger Applications
-
-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 hl_lines="7"
-FROM tiangolo/uvicorn-gunicorn-fastapi:python3.9
-
-COPY ./requirements.txt /app/requirements.txt
-
-RUN pip install --no-cache-dir --upgrade -r /app/requirements.txt
-
-COPY ./app /app/app
-```
-
-### When to Use
-
-You should probably **not** use this official base image (or any other similar one) if you are using **Kubernetes** (or others) and you are already setting **replication** at the cluster level, with multiple **containers**. In those cases, you are better off **building an image from scratch** as described above: [Build a Docker Image for FastAPI](#build-a-docker-image-for-fastapi).
-
-This image would be useful mainly in the special cases described above in [Containers with Multiple Processes and Special Cases](#containers-with-multiple-processes-and-special-cases). For example, if your application is **simple enough** that setting a default number of processes based on the CPU works well, you don't want to bother with manually configuring the replication at the cluster level, and you are not running more than one container with your app. Or if you are deploying with **Docker Compose**, running on a single server, etc.
-
## Deploy the Container Image
After having a Container (Docker) Image there are several ways to deploy it.
@@ -615,98 +600,9 @@ For example:
* With another tool like Nomad
* With a cloud service that takes your container image and deploys it
-## Docker Image with Poetry
-
-If you use
Poetry to manage your project's dependencies, you could use Docker multi-stage building:
-
-```{ .dockerfile .annotate }
-# (1)
-FROM python:3.9 as requirements-stage
-
-# (2)
-WORKDIR /tmp
-
-# (3)
-RUN pip install poetry
-
-# (4)
-COPY ./pyproject.toml ./poetry.lock* /tmp/
-
-# (5)
-RUN poetry export -f requirements.txt --output requirements.txt --without-hashes
-
-# (6)
-FROM python:3.9
-
-# (7)
-WORKDIR /code
-
-# (8)
-COPY --from=requirements-stage /tmp/requirements.txt /code/requirements.txt
-
-# (9)
-RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
-
-# (10)
-COPY ./app /code/app
-
-# (11)
-CMD ["fastapi", "run", "app/main.py", "--port", "80"]
-```
-
-1. This is the first stage, it is named `requirements-stage`.
+## Docker Image with `uv`
-2. Set `/tmp` as the current working directory.
-
- Here's where we will generate the file `requirements.txt`
-
-3. Install Poetry in this Docker stage.
-
-4. Copy the `pyproject.toml` and `poetry.lock` files to the `/tmp` directory.
-
- Because it uses `./poetry.lock*` (ending with a `*`), it won't crash if that file is not available yet.
-
-5. Generate the `requirements.txt` file.
-
-6. This is the final stage, anything here will be preserved in the final container image.
-
-7. Set the current working directory to `/code`.
-
-8. Copy the `requirements.txt` file to the `/code` directory.
-
- This file only lives in the previous Docker stage, that's why we use `--from-requirements-stage` to copy it.
-
-9. Install the package dependencies in the generated `requirements.txt` file.
-
-10. Copy the `app` directory to the `/code` directory.
-
-11. Use the `fastapi run` command to run your app.
-
-/// tip
-
-Click the bubble numbers to see what each line does.
-
-///
-
-A **Docker stage** is a part of a `Dockerfile` that works as a **temporary container image** that is only used to generate some files to be used later.
-
-The first stage will only be used to **install Poetry** and to **generate the `requirements.txt`** with your project dependencies from Poetry's `pyproject.toml` file.
-
-This `requirements.txt` file will be used with `pip` later in the **next stage**.
-
-In the final container image **only the final stage** is preserved. The previous stage(s) will be discarded.
-
-When using Poetry, it would make sense to use **Docker multi-stage builds** because you don't really need to have Poetry and its dependencies installed in the final container image, you **only need** to have the generated `requirements.txt` file to install your project dependencies.
-
-Then in the next (and final) stage you would build the image more or less in the same way as described before.
-
-### Behind a TLS Termination Proxy - Poetry
-
-Again, if you are running your container behind a TLS Termination Proxy (load balancer) like Nginx or Traefik, add the option `--proxy-headers` to the command:
-
-```Dockerfile
-CMD ["fastapi", "run", "app/main.py", "--proxy-headers", "--port", "80"]
-```
+If you are using
uv to install and manage your project, you can follow their
uv Docker guide.
## Recap
@@ -722,5 +618,3 @@ Using container systems (e.g. with **Docker** and **Kubernetes**) it becomes fai
In most cases, you probably won't want to use any base image, and instead **build a container image from scratch** one based on the official Python Docker image.
Taking care of the **order** of instructions in the `Dockerfile` and the **Docker cache** you can **minimize build times**, to maximize your productivity (and avoid boredom). ๐
-
-In certain special cases, you might want to use the official Docker image for FastAPI. ๐ค
diff --git a/docs/en/docs/deployment/manually.md b/docs/en/docs/deployment/manually.md
index 3324a7503..3f7c7a008 100644
--- a/docs/en/docs/deployment/manually.md
+++ b/docs/en/docs/deployment/manually.md
@@ -67,6 +67,8 @@ There are several alternatives, including:
*
Uvicorn: a high performance ASGI server.
*
Hypercorn: an ASGI server compatible with HTTP/2 and Trio among other features.
*
Daphne: the ASGI server built for Django Channels.
+*
Granian: A Rust HTTP server for Python applications.
+*
NGINX Unit: NGINX Unit is a lightweight and versatile web application runtime.
## Server Machine and Server Program
@@ -84,11 +86,9 @@ When you install FastAPI, it comes with a production server, Uvicorn, and you ca
But you can also install an ASGI server manually.
-Make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then you can install the server:
+Make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then you can install the server application.
-//// tab | Uvicorn
-
-*
Uvicorn, a lightning-fast ASGI server, built on uvloop and httptools.
+For example, to install Uvicorn:
@@ -100,6 +100,8 @@ $ pip install "uvicorn[standard]"
+A similar process would apply to any other ASGI server program.
+
/// tip
By adding the `standard`, Uvicorn will install and use some recommended extra dependencies.
@@ -110,32 +112,10 @@ When you install FastAPI with something like `pip install "fastapi[standard]"` y
///
-////
-
-//// tab | Hypercorn
-
-*
Hypercorn, an ASGI server also compatible with HTTP/2.
-
-
-
-```console
-$ pip install hypercorn
-
----> 100%
-```
-
-
-
-...or any other ASGI server.
-
-////
-
## Run the Server Program
If you installed an ASGI server manually, you would normally need to pass an import string in a special format for it to import your FastAPI application:
-//// tab | Uvicorn
-
```console
@@ -146,22 +126,6 @@ $ uvicorn main:app --host 0.0.0.0 --port 80
-////
-
-//// tab | Hypercorn
-
-
-
-```console
-$ hypercorn main:app --bind 0.0.0.0:80
-
-Running on 0.0.0.0:8080 over http (CTRL + C to quit)
-```
-
-
-
-////
-
/// note
The command `uvicorn main:app` refers to:
@@ -177,9 +141,11 @@ from main import app
///
+Each alternative ASGI server program would have a similar command, you can read more in their respective documentation.
+
/// warning
-Uvicorn and others support a `--reload` option that is useful during development.
+Uvicorn and other servers support a `--reload` option that is useful during development.
The `--reload` option consumes much more resources, is more unstable, etc.
@@ -187,43 +153,6 @@ It helps a lot during **development**, but you **shouldn't** use it in **product
///
-## Hypercorn with Trio
-
-Starlette and **FastAPI** are based on
AnyIO, which makes them compatible with both Python's standard library
asyncio and
Trio.
-
-Nevertheless, Uvicorn is currently only compatible with asyncio, and it normally uses
`uvloop`, the high-performance drop-in replacement for `asyncio`.
-
-But if you want to directly use **Trio**, then you can use **Hypercorn** as it supports it. โจ
-
-### Install Hypercorn with Trio
-
-First you need to install Hypercorn with Trio support:
-
-
-
-```console
-$ pip install "hypercorn[trio]"
----> 100%
-```
-
-
-
-### Run with Trio
-
-Then you can pass the command line option `--worker-class` with the value `trio`:
-
-
-
-```console
-$ hypercorn main:app --worker-class trio
-```
-
-
-
-And that will start Hypercorn with your app using Trio as the backend.
-
-Now you can use Trio internally in your app. Or even better, you can use AnyIO, to keep your code compatible with both Trio and asyncio. ๐
-
## Deployment Concepts
These examples run the server program (e.g Uvicorn), starting **a single process**, listening on all the IPs (`0.0.0.0`) on a predefined port (e.g. `80`).
diff --git a/docs/en/docs/deployment/server-workers.md b/docs/en/docs/deployment/server-workers.md
index efde5f3a1..5e369e071 100644
--- a/docs/en/docs/deployment/server-workers.md
+++ b/docs/en/docs/deployment/server-workers.md
@@ -1,4 +1,4 @@
-# Server Workers - Gunicorn with Uvicorn
+# Server Workers - Uvicorn with Workers
Let's check back those deployment concepts from before:
@@ -9,125 +9,92 @@ Let's check back those deployment concepts from before:
* Memory
* Previous steps before starting
-Up to this point, with all the tutorials in the docs, you have probably been running a **server program** like Uvicorn, running a **single process**.
+Up to this point, with all the tutorials in the docs, you have probably been running a **server program**, for example, using the `fastapi` command, that runs Uvicorn, running a **single process**.
When deploying applications you will probably want to have some **replication of processes** to take advantage of **multiple cores** and to be able to handle more requests.
As you saw in the previous chapter about [Deployment Concepts](concepts.md){.internal-link target=_blank}, there are multiple strategies you can use.
-Here I'll show you how to use
**Gunicorn** with **Uvicorn worker processes**.
+Here I'll show you how to use **Uvicorn** with **worker processes** using the `fastapi` command or the `uvicorn` command directly.
/// info
If you are using containers, for example with Docker or Kubernetes, I'll tell you more about that in the next chapter: [FastAPI in Containers - Docker](docker.md){.internal-link target=_blank}.
-In particular, when running on **Kubernetes** you will probably **not** want to use Gunicorn and instead run **a single Uvicorn process per container**, but I'll tell you about it later in that chapter.
+In particular, when running on **Kubernetes** you will probably **not** want to use workers and instead run **a single Uvicorn process per container**, but I'll tell you about it later in that chapter.
///
-## Gunicorn with Uvicorn Workers
+## Multiple Workers
-**Gunicorn** is mainly an application server using the **WSGI standard**. That means that Gunicorn can serve applications like Flask and Django. Gunicorn by itself is not compatible with **FastAPI**, as FastAPI uses the newest **
ASGI standard**.
+You can start multiple workers with the `--workers` command line option:
-But Gunicorn supports working as a **process manager** and allowing users to tell it which specific **worker process class** to use. Then Gunicorn would start one or more **worker processes** using that class.
+//// tab | `fastapi`
-And **Uvicorn** has a **Gunicorn-compatible worker class**.
-
-Using that combination, Gunicorn would act as a **process manager**, listening on the **port** and the **IP**. And it would **transmit** the communication to the worker processes running the **Uvicorn class**.
-
-And then the Gunicorn-compatible **Uvicorn worker** class would be in charge of converting the data sent by Gunicorn to the ASGI standard for FastAPI to use it.
-
-## Install Gunicorn and Uvicorn
-
-Make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install `gunicorn`:
+If you use the `fastapi` command:
```console
-$ pip install "uvicorn[standard]" gunicorn
-
----> 100%
+$
fastapi run --workers 4 main.py
+INFO Using path main.py
+INFO Resolved absolute path /home/user/code/awesomeapp/main.py
+INFO Searching for package file structure from directories with __init__.py files
+INFO Importing from /home/user/code/awesomeapp
+
+ โญโ Python module file โโฎ
+ โ โ
+ โ ๐ main.py โ
+ โ โ
+ โฐโโโโโโโโโโโโโโโโโโโโโโโฏ
+
+INFO Importing module main
+INFO Found importable FastAPI app
+
+ โญโ Importable FastAPI app โโฎ
+ โ โ
+ โ from main import app โ
+ โ โ
+ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
+
+INFO Using import string main:app
+
+ โญโโโโโโโโโโโ FastAPI CLI - Production mode โโโโโโโโโโโโฎ
+ โ โ
+ โ Serving at: http://0.0.0.0:8000 โ
+ โ โ
+ โ API docs: http://0.0.0.0:8000/docs โ
+ โ โ
+ โ Running in production mode, for development use: โ
+ โ โ
+ โ fastapi dev โ
+ โ โ
+ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
+
+INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
+INFO: Started parent process [27365]
+INFO: Started server process [27368]
+INFO: Waiting for application startup.
+INFO: Application startup complete.
+INFO: Started server process [27369]
+INFO: Waiting for application startup.
+INFO: Application startup complete.
+INFO: Started server process [27370]
+INFO: Waiting for application startup.
+INFO: Application startup complete.
+INFO: Started server process [27367]
+INFO: Waiting for application startup.
+INFO: Application startup complete.
+
```
-That will install both Uvicorn with the `standard` extra packages (to get high performance) and Gunicorn.
+////
-## Run Gunicorn with Uvicorn Workers
+//// tab | `uvicorn`
-Then you can run Gunicorn with:
-
-
-
-```console
-$ gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:80
-
-[19499] [INFO] Starting gunicorn 20.1.0
-[19499] [INFO] Listening at: http://0.0.0.0:80 (19499)
-[19499] [INFO] Using worker: uvicorn.workers.UvicornWorker
-[19511] [INFO] Booting worker with pid: 19511
-[19513] [INFO] Booting worker with pid: 19513
-[19514] [INFO] Booting worker with pid: 19514
-[19515] [INFO] Booting worker with pid: 19515
-[19511] [INFO] Started server process [19511]
-[19511] [INFO] Waiting for application startup.
-[19511] [INFO] Application startup complete.
-[19513] [INFO] Started server process [19513]
-[19513] [INFO] Waiting for application startup.
-[19513] [INFO] Application startup complete.
-[19514] [INFO] Started server process [19514]
-[19514] [INFO] Waiting for application startup.
-[19514] [INFO] Application startup complete.
-[19515] [INFO] Started server process [19515]
-[19515] [INFO] Waiting for application startup.
-[19515] [INFO] Application startup complete.
-```
-
-
-
-Let's see what each of those options mean:
-
-* `main:app`: This is the same syntax used by Uvicorn, `main` means the Python module named "`main`", so, a file `main.py`. And `app` is the name of the variable that is the **FastAPI** application.
- * You can imagine that `main:app` is equivalent to a Python `import` statement like:
-
- ```Python
- from main import app
- ```
-
- * So, the colon in `main:app` would be equivalent to the Python `import` part in `from main import app`.
-
-* `--workers`: The number of worker processes to use, each will run a Uvicorn worker, in this case, 4 workers.
-
-* `--worker-class`: The Gunicorn-compatible worker class to use in the worker processes.
- * Here we pass the class that Gunicorn can import and use with:
-
- ```Python
- import uvicorn.workers.UvicornWorker
- ```
-
-* `--bind`: This tells Gunicorn the IP and the port to listen to, using a colon (`:`) to separate the IP and the port.
- * If you were running Uvicorn directly, instead of `--bind 0.0.0.0:80` (the Gunicorn option) you would use `--host 0.0.0.0` and `--port 80`.
-
-In the output, you can see that it shows the **PID** (process ID) of each process (it's just a number).
-
-You can see that:
-
-* The Gunicorn **process manager** starts with PID `19499` (in your case it will be a different number).
-* Then it starts `Listening at: http://0.0.0.0:80`.
-* Then it detects that it has to use the worker class at `uvicorn.workers.UvicornWorker`.
-* And then it starts **4 workers**, each with its own PID: `19511`, `19513`, `19514`, and `19515`.
-
-Gunicorn would also take care of managing **dead processes** and **restarting** new ones if needed to keep the number of workers. So that helps in part with the **restart** concept from the list above.
-
-Nevertheless, you would probably also want to have something outside making sure to **restart Gunicorn** if necessary, and also to **run it on startup**, etc.
-
-## Uvicorn with Workers
-
-Uvicorn also has an option to start and run several **worker processes**.
-
-Nevertheless, as of now, Uvicorn's capabilities for handling worker processes are more limited than Gunicorn's. So, if you want to have a process manager at this level (at the Python level), then it might be better to try with Gunicorn as the process manager.
-
-In any case, you would run it like this:
+If you prefer to use the `uvicorn` command directly:
@@ -151,13 +118,15 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4
+////
+
The only new option here is `--workers` telling Uvicorn to start 4 worker processes.
You can also see that it shows the **PID** of each process, `27365` for the parent process (this is the **process manager**) and one for each worker process: `27368`, `27369`, `27370`, and `27367`.
## Deployment Concepts
-Here you saw how to use **Gunicorn** (or Uvicorn) managing **Uvicorn worker processes** to **parallelize** the execution of the application, take advantage of **multiple cores** in the CPU, and be able to serve **more requests**.
+Here you saw how to use multiple **workers** to **parallelize** the execution of the application, take advantage of **multiple cores** in the CPU, and be able to serve **more requests**.
From the list of deployment concepts from above, using workers would mainly help with the **replication** part, and a little bit with the **restarts**, but you still need to take care of the others:
@@ -172,13 +141,11 @@ From the list of deployment concepts from above, using workers would mainly help
In the next chapter about [FastAPI in Containers - Docker](docker.md){.internal-link target=_blank} I'll tell some strategies you could use to handle the other **deployment concepts**.
-I'll also show you the **official Docker image** that includes **Gunicorn with Uvicorn workers** and some default configurations that can be useful for simple cases.
-
-There I'll also show you how to **build your own image from scratch** to run a single Uvicorn process (without Gunicorn). It is a simple process and is probably what you would want to do when using a distributed container management system like **Kubernetes**.
+I'll show you how to **build your own image from scratch** to run a single Uvicorn process. It is a simple process and is probably what you would want to do when using a distributed container management system like **Kubernetes**.
## Recap
-You can use **Gunicorn** (or also Uvicorn) as a process manager with Uvicorn workers to take advantage of **multi-core CPUs**, to run **multiple processes in parallel**.
+You can use multiple worker processes with the `--workers` CLI option with the `fastapi` or `uvicorn` commands to take advantage of **multi-core CPUs**, to run **multiple processes in parallel**.
You could use these tools and ideas if you are setting up **your own deployment system** while taking care of the other deployment concepts yourself.
diff --git a/docs/en/docs/deployment/versions.md b/docs/en/docs/deployment/versions.md
index e387d5712..23f49cf99 100644
--- a/docs/en/docs/deployment/versions.md
+++ b/docs/en/docs/deployment/versions.md
@@ -30,7 +30,7 @@ fastapi[standard]>=0.112.0,<0.113.0
that would mean that you would use the versions `0.112.0` or above, but less than `0.113.0`, for example, a version `0.112.2` would still be accepted.
-If you use any other tool to manage your installations, like Poetry, Pipenv, or others, they all have a way that you can use to define specific versions for your packages.
+If you use any other tool to manage your installations, like `uv`, Poetry, Pipenv, or others, they all have a way that you can use to define specific versions for your packages.
## Available versions
diff --git a/docs/en/docs/index.md b/docs/en/docs/index.md
index ac4f4d00f..3ed3d7bf6 100644
--- a/docs/en/docs/index.md
+++ b/docs/en/docs/index.md
@@ -390,7 +390,7 @@ Coming back to the previous code example, **FastAPI** will:
* Check if there is an optional query parameter named `q` (as in `http://127.0.0.1:8000/items/foo?q=somequery`) for `GET` requests.
* As the `q` parameter is declared with `= None`, it is optional.
* Without the `None` it would be required (as is the body in the case with `PUT`).
-* For `PUT` requests to `/items/{item_id}`, Read the body as JSON:
+* For `PUT` requests to `/items/{item_id}`, read the body as JSON:
* Check that it has a required attribute `name` that should be a `str`.
* Check that it has a required attribute `price` that has to be a `float`.
* Check that it has an optional attribute `is_offer`, that should be a `bool`, if present.
diff --git a/docs/en/docs/python-types.md b/docs/en/docs/python-types.md
index 4ed1fc680..6994adb5f 100644
--- a/docs/en/docs/python-types.md
+++ b/docs/en/docs/python-types.md
@@ -324,7 +324,7 @@ In Python 3.6 and above (including Python 3.10) you can declare it by importing
{!../../../docs_src/python_types/tutorial009.py!}
```
-Using `Optional[str]` instead of just `str` will let the editor help you detecting errors where you could be assuming that a value is always a `str`, when it could actually be `None` too.
+Using `Optional[str]` instead of just `str` will let the editor help you detect errors where you could be assuming that a value is always a `str`, when it could actually be `None` too.
`Optional[Something]` is actually a shortcut for `Union[Something, None]`, they are equivalent.
diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md
index a8bbcc3b7..2f7fb0cbd 100644
--- a/docs/en/docs/release-notes.md
+++ b/docs/en/docs/release-notes.md
@@ -7,6 +7,35 @@ hide:
## Latest Changes
+### Docs
+
+* ๐ง Update sponsors: Coherence. PR [#12093](https://github.com/fastapi/fastapi/pull/12093) by [@tiangolo](https://github.com/tiangolo).
+* ๐ Fix async test example not to trigger DeprecationWarning. PR [#12084](https://github.com/fastapi/fastapi/pull/12084) by [@marcinsulikowski](https://github.com/marcinsulikowski).
+* ๐ Update `docs_src/path_params_numeric_validations/tutorial006.py`. PR [#11478](https://github.com/fastapi/fastapi/pull/11478) by [@MuhammadAshiqAmeer](https://github.com/MuhammadAshiqAmeer).
+* ๐ Update comma in `docs/en/docs/async.md`. PR [#12062](https://github.com/fastapi/fastapi/pull/12062) by [@Alec-Gillis](https://github.com/Alec-Gillis).
+* ๐ Update docs about serving FastAPI: ASGI servers, Docker containers, etc.. PR [#12069](https://github.com/fastapi/fastapi/pull/12069) by [@tiangolo](https://github.com/tiangolo).
+* ๐ Clarify `response_class` parameter, validations, and returning a response directly. PR [#12067](https://github.com/fastapi/fastapi/pull/12067) by [@tiangolo](https://github.com/tiangolo).
+* ๐ Fix minor typos and issues in the documentation. PR [#12063](https://github.com/fastapi/fastapi/pull/12063) by [@svlandeg](https://github.com/svlandeg).
+* ๐ Add note in Docker docs about ensuring graceful shutdowns and lifespan events with `CMD` exec form. PR [#11960](https://github.com/fastapi/fastapi/pull/11960) by [@GPla](https://github.com/GPla).
+
+### Translations
+
+* ๐ Add Dutch translation for `docs/nl/docs/index.md`. PR [#12042](https://github.com/fastapi/fastapi/pull/12042) by [@svlandeg](https://github.com/svlandeg).
+* ๐ Update Chinese translation for `docs/zh/docs/how-to/index.md`. PR [#12070](https://github.com/fastapi/fastapi/pull/12070) by [@synthpop123](https://github.com/synthpop123).
+
+### Internal
+
+* ๐ง Update sponsors, remove Kong. PR [#12085](https://github.com/fastapi/fastapi/pull/12085) by [@tiangolo](https://github.com/tiangolo).
+* โฌ [pre-commit.ci] pre-commit autoupdate. PR [#12076](https://github.com/fastapi/fastapi/pull/12076) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci).
+* ๐ท Update `latest-changes` GitHub Action. PR [#12073](https://github.com/fastapi/fastapi/pull/12073) by [@tiangolo](https://github.com/tiangolo).
+
+## 0.112.2
+
+### Fixes
+
+* ๐ Fix `allow_inf_nan` option for Param and Body classes. PR [#11867](https://github.com/fastapi/fastapi/pull/11867) by [@giunio-prc](https://github.com/giunio-prc).
+* ๐ Ensure that `app.include_router` merges nested lifespans. PR [#9630](https://github.com/fastapi/fastapi/pull/9630) by [@Lancetnik](https://github.com/Lancetnik).
+
### Refactors
* ๐จ Fix typing annotation for semi-internal `FastAPI.add_api_route()`. PR [#10240](https://github.com/fastapi/fastapi/pull/10240) by [@ordinary-jamie](https://github.com/ordinary-jamie).
@@ -14,6 +43,7 @@ hide:
### Docs
+* ๐ Fix a typo in `docs/en/docs/virtual-environments.md`. PR [#12064](https://github.com/fastapi/fastapi/pull/12064) by [@aymenkrifa](https://github.com/aymenkrifa).
* ๐ Add docs about Environment Variables and Virtual Environments. PR [#12054](https://github.com/fastapi/fastapi/pull/12054) by [@tiangolo](https://github.com/tiangolo).
* ๐ Add Asyncer mention in async docs. PR [#12037](https://github.com/fastapi/fastapi/pull/12037) by [@tiangolo](https://github.com/tiangolo).
* ๐ Move the Features docs to the top level to improve the main page menu. PR [#12036](https://github.com/fastapi/fastapi/pull/12036) by [@tiangolo](https://github.com/tiangolo).
@@ -35,7 +65,7 @@ hide:
* ๐ Add Portuguese translation for `docs/pt/docs/tutorial/request_file.md`. PR [#12018](https://github.com/fastapi/fastapi/pull/12018) by [@Joao-Pedro-P-Holanda](https://github.com/Joao-Pedro-P-Holanda).
* ๐ Add Japanese translation for `docs/ja/docs/learn/index.md`. PR [#11592](https://github.com/fastapi/fastapi/pull/11592) by [@ukwhatn](https://github.com/ukwhatn).
* ๐ Update Spanish translation docs for consistency. PR [#12044](https://github.com/fastapi/fastapi/pull/12044) by [@alejsdev](https://github.com/alejsdev).
-* ๐ Update docs about dependencies with yield. PR [#12028](https://github.com/fastapi/fastapi/pull/12028) by [@xuvjso](https://github.com/xuvjso).
+* ๐ Update Chinese translation for `docs/zh/docs/tutorial/dependencies/dependencies-with-yield.md`. PR [#12028](https://github.com/fastapi/fastapi/pull/12028) by [@xuvjso](https://github.com/xuvjso).
* ๐ Update FastAPI People, do not translate to have the most recent info. PR [#12034](https://github.com/fastapi/fastapi/pull/12034) by [@tiangolo](https://github.com/tiangolo).
* ๐ Update Urdu translation for `docs/ur/docs/benchmarks.md`. PR [#10046](https://github.com/fastapi/fastapi/pull/10046) by [@AhsanSheraz](https://github.com/AhsanSheraz).
diff --git a/docs/en/docs/tutorial/bigger-applications.md b/docs/en/docs/tutorial/bigger-applications.md
index 97f6b205b..1c33fd051 100644
--- a/docs/en/docs/tutorial/bigger-applications.md
+++ b/docs/en/docs/tutorial/bigger-applications.md
@@ -1,6 +1,6 @@
# Bigger Applications - Multiple Files
-If you are building an application or a web API, it's rarely the case that you can put everything on a single file.
+If you are building an application or a web API, it's rarely the case that you can put everything in a single file.
**FastAPI** provides a convenience tool to structure your application while keeping all the flexibility.
@@ -478,7 +478,7 @@ We can declare all that without having to modify the original `APIRouter` by pas
{!../../../docs_src/bigger_applications/app/main.py!}
```
-That way, the original `APIRouter` will keep unmodified, so we can still share that same `app/internal/admin.py` file with other projects in the organization.
+That way, the original `APIRouter` will stay unmodified, so we can still share that same `app/internal/admin.py` file with other projects in the organization.
The result is that in our app, each of the *path operations* from the `admin` module will have:
@@ -519,12 +519,12 @@ As we cannot just isolate them and "mount" them independently of the rest, the *
## Check the automatic API docs
-Now, run `uvicorn`, using the module `app.main` and the variable `app`:
+Now, run your app:
```console
-$ uvicorn app.main:app --reload
+$ fastapi dev app/main.py
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```
diff --git a/docs/en/docs/tutorial/body-multiple-params.md b/docs/en/docs/tutorial/body-multiple-params.md
index 511fb358e..d63cd2529 100644
--- a/docs/en/docs/tutorial/body-multiple-params.md
+++ b/docs/en/docs/tutorial/body-multiple-params.md
@@ -97,7 +97,7 @@ But you can also declare multiple body parameters, e.g. `item` and `user`:
////
-In this case, **FastAPI** will notice that there are more than one body parameters in the function (two parameters that are Pydantic models).
+In this case, **FastAPI** will notice that there is more than one body parameter in the function (there are two parameters that are Pydantic models).
So, it will then use the parameter names as keys (field names) in the body, and expect a body like:
diff --git a/docs/en/docs/tutorial/body-updates.md b/docs/en/docs/tutorial/body-updates.md
index 261f44d33..3257f9a08 100644
--- a/docs/en/docs/tutorial/body-updates.md
+++ b/docs/en/docs/tutorial/body-updates.md
@@ -155,7 +155,7 @@ In summary, to apply partial updates you would:
* Put that data in a Pydantic model.
* Generate a `dict` without default values from the input model (using `exclude_unset`).
* This way you can update only the values actually set by the user, instead of overriding values already stored with default values in your model.
-* Create a copy of the stored model, updating it's attributes with the received partial updates (using the `update` parameter).
+* Create a copy of the stored model, updating its attributes with the received partial updates (using the `update` parameter).
* Convert the copied model to something that can be stored in your DB (for example, using the `jsonable_encoder`).
* This is comparable to using the model's `.model_dump()` method again, but it makes sure (and converts) the values to data types that can be converted to JSON, for example, `datetime` to `str`.
* Save the data to your DB.
diff --git a/docs/en/docs/tutorial/body.md b/docs/en/docs/tutorial/body.md
index 608b50dbb..83f08ce84 100644
--- a/docs/en/docs/tutorial/body.md
+++ b/docs/en/docs/tutorial/body.md
@@ -123,7 +123,7 @@ The JSON Schemas of your models will be part of your OpenAPI generated schema, a
-And will be also used in the API docs inside each *path operation* that needs them:
+And will also be used in the API docs inside each *path operation* that needs them:
diff --git a/docs/en/docs/tutorial/cors.md b/docs/en/docs/tutorial/cors.md
index fd329e138..7dd0a5df5 100644
--- a/docs/en/docs/tutorial/cors.md
+++ b/docs/en/docs/tutorial/cors.md
@@ -40,7 +40,7 @@ You can configure it in your **FastAPI** application using the `CORSMiddleware`.
* Create a list of allowed origins (as strings).
* Add it as a "middleware" to your **FastAPI** application.
-You can also specify if your backend allows:
+You can also specify whether your backend allows:
* Credentials (Authorization headers, Cookies, etc).
* Specific HTTP methods (`POST`, `PUT`) or all of them with the wildcard `"*"`.
diff --git a/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md b/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md
index a392672bb..b3394f14e 100644
--- a/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md
+++ b/docs/en/docs/tutorial/dependencies/classes-as-dependencies.md
@@ -381,7 +381,7 @@ The last `CommonQueryParams`, in:
...is what **FastAPI** will actually use to know what is the dependency.
-From it is that FastAPI will extract the declared parameters and that is what FastAPI will actually call.
+It is from this one that FastAPI will extract the declared parameters and that is what FastAPI will actually call.
---
diff --git a/docs/en/docs/tutorial/extra-data-types.md b/docs/en/docs/tutorial/extra-data-types.md
index 849dee41f..3009acaf3 100644
--- a/docs/en/docs/tutorial/extra-data-types.md
+++ b/docs/en/docs/tutorial/extra-data-types.md
@@ -49,7 +49,7 @@ Here are some of the additional data types you can use:
* `Decimal`:
* Standard Python `Decimal`.
* In requests and responses, handled the same as a `float`.
-* You can check all the valid pydantic data types here:
Pydantic data types.
+* You can check all the valid Pydantic data types here:
Pydantic data types.
## Example
diff --git a/docs/en/docs/tutorial/handling-errors.md b/docs/en/docs/tutorial/handling-errors.md
index ca3cff661..14a3cf998 100644
--- a/docs/en/docs/tutorial/handling-errors.md
+++ b/docs/en/docs/tutorial/handling-errors.md
@@ -176,7 +176,7 @@ These are technical details that you might skip if it's not important for you no
**FastAPI** uses it so that, if you use a Pydantic model in `response_model`, and your data has an error, you will see the error in your log.
-But the client/user will not see it. Instead, the client will receive an "Internal Server Error" with a HTTP status code `500`.
+But the client/user will not see it. Instead, the client will receive an "Internal Server Error" with an HTTP status code `500`.
It should be this way because if you have a Pydantic `ValidationError` in your *response* or anywhere in your code (not in the client's *request*), it's actually a bug in your code.
@@ -262,7 +262,7 @@ from starlette.exceptions import HTTPException as StarletteHTTPException
### Reuse **FastAPI**'s exception handlers
-If you want to use the exception along with the same default exception handlers from **FastAPI**, You can import and reuse the default exception handlers from `fastapi.exception_handlers`:
+If you want to use the exception along with the same default exception handlers from **FastAPI**, you can import and reuse the default exception handlers from `fastapi.exception_handlers`:
```Python hl_lines="2-5 15 21"
{!../../../docs_src/handling_errors/tutorial006.py!}
diff --git a/docs/en/docs/tutorial/index.md b/docs/en/docs/tutorial/index.md
index 386fe5de9..bf613aace 100644
--- a/docs/en/docs/tutorial/index.md
+++ b/docs/en/docs/tutorial/index.md
@@ -95,7 +95,7 @@ If you don't want to have those optional dependencies, you can instead install `
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.
+The **Advanced User Guide** builds on this one, 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).
diff --git a/docs/en/docs/tutorial/middleware.md b/docs/en/docs/tutorial/middleware.md
index f0b3faf3b..06fb3f504 100644
--- a/docs/en/docs/tutorial/middleware.md
+++ b/docs/en/docs/tutorial/middleware.md
@@ -29,7 +29,7 @@ The middleware function receives:
* A function `call_next` that will receive the `request` as a parameter.
* This function will pass the `request` to the corresponding *path operation*.
* Then it returns the `response` generated by the corresponding *path operation*.
-* You can then modify further the `response` before returning it.
+* You can then further modify the `response` before returning it.
```Python hl_lines="8-9 11 14"
{!../../../docs_src/middleware/tutorial001.py!}
diff --git a/docs/en/docs/tutorial/query-params-str-validations.md b/docs/en/docs/tutorial/query-params-str-validations.md
index 859242d93..dd101a2a6 100644
--- a/docs/en/docs/tutorial/query-params-str-validations.md
+++ b/docs/en/docs/tutorial/query-params-str-validations.md
@@ -273,7 +273,7 @@ The **default** value of the **function parameter** is the **actual default** va
You could **call** that same function in **other places** without FastAPI, and it would **work as expected**. If there's a **required** parameter (without a default value), your **editor** will let you know with an error, **Python** will also complain if you run it without passing the required parameter.
-When you don't use `Annotated` and instead use the **(old) default value style**, if you call that function without FastAPI in **other place**, you have to **remember** to pass the arguments to the function for it to work correctly, otherwise the values will be different from what you expect (e.g. `QueryInfo` or something similar instead of `str`). And your editor won't complain, and Python won't complain running that function, only when the operations inside error out.
+When you don't use `Annotated` and instead use the **(old) default value style**, if you call that function without FastAPI in **other places**, you have to **remember** to pass the arguments to the function for it to work correctly, otherwise the values will be different from what you expect (e.g. `QueryInfo` or something similar instead of `str`). And your editor won't complain, and Python won't complain running that function, only when the operations inside error out.
Because `Annotated` can have more than one metadata annotation, you could now even use the same function with other tools, like
Typer. ๐
@@ -645,7 +645,7 @@ Remember that in most of the cases, when something is required, you can simply o
## Query parameter list / multiple values
-When you define a query parameter explicitly with `Query` you can also declare it to receive a list of values, or said in other way, to receive multiple values.
+When you define a query parameter explicitly with `Query` you can also declare it to receive a list of values, or said in another way, to receive multiple values.
For example, to declare a query parameter `q` that can appear multiple times in the URL, you can write:
@@ -1182,4 +1182,4 @@ Validations specific for strings:
In these examples you saw how to declare validations for `str` values.
-See the next chapters to see how to declare validations for other types, like numbers.
+See the next chapters to learn how to declare validations for other types, like numbers.
diff --git a/docs/en/docs/tutorial/schema-extra-example.md b/docs/en/docs/tutorial/schema-extra-example.md
index 70745b048..20dee3a4f 100644
--- a/docs/en/docs/tutorial/schema-extra-example.md
+++ b/docs/en/docs/tutorial/schema-extra-example.md
@@ -347,7 +347,7 @@ If the ideas above already work for you, that might be enough, and you probably
Before OpenAPI 3.1.0, OpenAPI used an older and modified version of **JSON Schema**.
-JSON Schema didn't have `examples`, so OpenAPI added it's own `example` field to its own modified version.
+JSON Schema didn't have `examples`, so OpenAPI added its own `example` field to its own modified version.
OpenAPI also added `example` and `examples` fields to other parts of the specification:
diff --git a/docs/en/docs/tutorial/security/first-steps.md b/docs/en/docs/tutorial/security/first-steps.md
index 4bd026caf..d1fe0163e 100644
--- a/docs/en/docs/tutorial/security/first-steps.md
+++ b/docs/en/docs/tutorial/security/first-steps.md
@@ -152,7 +152,7 @@ A "bearer" token is not the only option.
But it's the best one for our use case.
-And it might be the best for most use cases, unless you are an OAuth2 expert and know exactly why there's another option that suits better your needs.
+And it might be the best for most use cases, unless you are an OAuth2 expert and know exactly why there's another option that better suits your needs.
In that case, **FastAPI** also provides you with the tools to build it.
diff --git a/docs/en/docs/tutorial/security/get-current-user.md b/docs/en/docs/tutorial/security/get-current-user.md
index 6f3bf3944..7faaa3e13 100644
--- a/docs/en/docs/tutorial/security/get-current-user.md
+++ b/docs/en/docs/tutorial/security/get-current-user.md
@@ -316,7 +316,7 @@ And you can make it as complex as you want. And still, have it written only once
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 of them (or any portion of them that you want) can take 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:
diff --git a/docs/en/docs/virtual-environments.md b/docs/en/docs/virtual-environments.md
index 3c4aa49c1..fcc72fbe7 100644
--- a/docs/en/docs/virtual-environments.md
+++ b/docs/en/docs/virtual-environments.md
@@ -558,7 +558,7 @@ The solution to the problems of having all the packages in the global environmen
A virtual environment is a **directory**, very similar to the global one, where you can install the packages for a project.
-This way, each project will have it's own virtual environment (`.venv` directory) with its own packages.
+This way, each project will have its own virtual environment (`.venv` directory) with its own packages.
```mermaid
flowchart TB
diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml
index 6f1e12511..528c80b8e 100644
--- a/docs/en/mkdocs.yml
+++ b/docs/en/mkdocs.yml
@@ -363,6 +363,8 @@ extra:
name: ja - ๆฅๆฌ่ช
- link: /ko/
name: ko - ํ๊ตญ์ด
+ - link: /nl/
+ name: nl - Nederlands
- link: /pl/
name: pl - Polski
- link: /pt/
diff --git a/docs/en/overrides/main.html b/docs/en/overrides/main.html
index 229cbca71..851f8e895 100644
--- a/docs/en/overrides/main.html
+++ b/docs/en/overrides/main.html
@@ -70,12 +70,6 @@
-
diff --git a/docs/nl/docs/index.md b/docs/nl/docs/index.md
new file mode 100644
index 000000000..8edc3ba0c
--- /dev/null
+++ b/docs/nl/docs/index.md
@@ -0,0 +1,494 @@
+# FastAPI
+
+
+
+
+ 
+
+
+ FastAPI framework, zeer goede prestaties, eenvoudig te leren, snel te programmeren, klaar voor productie
+
+
+
+ 
+
+
+ 
+
+
+ 
+
+
+ 
+
+
+
+---
+
+**Documentatie**: https://fastapi.tiangolo.com
+
+**Broncode**:
https://github.com/tiangolo/fastapi
+
+---
+
+FastAPI is een modern, snel (zeer goede prestaties), web framework voor het bouwen van API's in Python, gebruikmakend van standaard Python type-hints.
+
+De belangrijkste kenmerken zijn:
+
+* **Snel**: Zeer goede prestaties, vergelijkbaar met **NodeJS** en **Go** (dankzij Starlette en Pydantic). [Een van de snelste beschikbare Python frameworks](#prestaties).
+* **Snel te programmeren**: Verhoog de snelheid om functionaliteit te ontwikkelen met ongeveer 200% tot 300%. *
+* **Minder bugs**: Verminder ongeveer 40% van de door mensen (ontwikkelaars) veroorzaakte fouten. *
+* **Intuรฏtief**: Buitengewoon goede ondersteuning voor editors.
Overal automische code aanvulling. Minder tijd kwijt aan debuggen.
+* **Eenvoudig**: Ontworpen om gemakkelijk te gebruiken en te leren. Minder tijd nodig om documentatie te lezen.
+* **Kort**: Minimaliseer codeduplicatie. Elke parameterdeclaratie ondersteunt meerdere functionaliteiten. Minder bugs.
+* **Robust**: Code gereed voor productie. Met automatische interactieve documentatie.
+* **Standards-based**: Gebaseerd op (en volledig verenigbaar met) open standaarden voor API's:
OpenAPI (voorheen bekend als Swagger) en
JSON Schema.
+
+
* schatting op basis van testen met een intern ontwikkelteam en bouwen van productieapplicaties.
+
+## Sponsors
+
+
+
+{% if sponsors %}
+{% for sponsor in sponsors.gold -%}
+
+{% endfor -%}
+{%- for sponsor in sponsors.silver -%}
+
+{% endfor %}
+{% endif %}
+
+
+
+
Overige sponsoren
+
+## Meningen
+
+"_[...] Ik gebruik **FastAPI** heel vaak tegenwoordig. [...] Ik ben van plan om het te gebruiken voor alle **ML-services van mijn team bij Microsoft**. Sommige van deze worden geรฏntegreerd in het kernproduct van **Windows** en sommige **Office**-producten._"
+
+
Kabir Khan -
Microsoft (ref)
+
+---
+
+"_We hebben de **FastAPI** library gebruikt om een **REST** server te maken die bevraagd kan worden om **voorspellingen** te maken. [voor Ludwig]_"
+
+
Piero Molino, Yaroslav Dudin en Sai Sumanth Miryala -
Uber (ref)
+
+---
+
+"_**Netflix** is verheugd om een open-source release aan te kondigen van ons **crisismanagement**-orkestratieframework: **Dispatch**! [gebouwd met **FastAPI**]_"
+
+
Kevin Glisson, Marc Vilanova, Forest Monsen -
Netflix (ref)
+
+---
+
+"_Ik ben super enthousiast over **FastAPI**. Het is zo leuk!_"
+
+
+
+---
+
+"_Wat je hebt gebouwd ziet er echt super solide en gepolijst uit. In veel opzichten is het wat ik wilde dat **Hug** kon zijn - het is echt inspirerend om iemand dit te zien bouwen._"
+
+
+
+---
+
+"Wie geรฏnteresseerd is in een **modern framework** voor het bouwen van REST API's, bekijkt best eens **FastAPI** [...] Het is snel, gebruiksvriendelijk en gemakkelijk te leren [...]_"
+
+"_We zijn overgestapt naar **FastAPI** voor onze **API's** [...] Het gaat jou vast ook bevallen [...]_"
+
+
+
+---
+
+"_Wie een Python API wil bouwen voor productie, kan ik ten stelligste **FastAPI** aanraden. Het is **prachtig ontworpen**, **eenvoudig te gebruiken** en **gemakkelijk schaalbaar**, het is een **cruciale component** geworden in onze strategie om API's centraal te zetten, en het vereenvoudigt automatisering en diensten zoals onze Virtual TAC Engineer._"
+
+
Deon Pillsbury -
Cisco (ref)
+
+---
+
+## **Typer**, de FastAPI van CLIs
+
+
+
+Als je een
CLI-app bouwt die in de terminal moet worden gebruikt in plaats van een web-API, gebruik dan
**Typer**.
+
+**Typer** is het kleine broertje van FastAPI. En het is bedoeld als de **FastAPI van CLI's**. ๏ธ
+
+## Vereisten
+
+FastAPI staat op de schouders van reuzen:
+
+*
Starlette voor de webonderdelen.
+*
Pydantic voor de datadelen.
+
+## Installatie
+
+
+
+```console
+$ pip install "fastapi[standard]"
+
+---> 100%
+```
+
+
+
+**Opmerking**: Zet `"fastapi[standard]"` tussen aanhalingstekens om ervoor te zorgen dat het werkt in alle terminals.
+
+## Voorbeeld
+
+### Creรซer het
+
+* Maak het bestand `main.py` aan met daarin:
+
+```Python
+from typing import Union
+
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+def read_root():
+ return {"Hello": "World"}
+
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int, q: Union[str, None] = None):
+ return {"item_id": item_id, "q": q}
+```
+
+
+Of maak gebruik van async def...
+
+Als je code gebruik maakt van `async` / `await`, gebruik dan `async def`:
+
+```Python hl_lines="9 14"
+from typing import Union
+
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+async def read_root():
+ return {"Hello": "World"}
+
+
+@app.get("/items/{item_id}")
+async def read_item(item_id: int, q: Union[str, None] = None):
+ return {"item_id": item_id, "q": q}
+```
+
+**Opmerking**:
+
+Als je het niet weet, kijk dan in het gedeelte _"Heb je haast?"_ over `async` en `await` in de documentatie.
+
+
+
+### Voer het uit
+
+Run de server met:
+
+
+
+```console
+$ fastapi dev main.py
+
+ โญโโโโโโโโโโ FastAPI CLI - Development mode โโโโโโโโโโโโฎ
+ โ โ
+ โ Serving at: http://127.0.0.1:8000 โ
+ โ โ
+ โ API docs: http://127.0.0.1:8000/docs โ
+ โ โ
+ โ Running in development mode, for production use: โ
+ โ โ
+ โ fastapi run โ
+ โ โ
+ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
+
+INFO: Will watch for changes in these directories: ['/home/user/code/awesomeapp']
+INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+INFO: Started reloader process [2248755] using WatchFiles
+INFO: Started server process [2248757]
+INFO: Waiting for application startup.
+INFO: Application startup complete.
+```
+
+
+
+
+Over het commando fastapi dev main.py...
+
+Het commando `fastapi dev` leest het `main.py` bestand, detecteert de **FastAPI** app, en start een server met Uvicorn.
+
+Standaard zal dit commando `fastapi dev` starten met "auto-reload" geactiveerd voor ontwikkeling op het lokale systeem.
+
+Je kan hier meer over lezen in de FastAPI CLI documentatie.
+
+
+
+### Controleer het
+
+Open je browser op
http://127.0.0.1:8000/items/5?q=somequery.
+
+Je zult een JSON response zien:
+
+```JSON
+{"item_id": 5, "q": "somequery"}
+```
+
+Je hebt een API gemaakt die:
+
+* HTTP verzoeken kan ontvangen op de _paden_ `/` en `/items/{item_id}`.
+* Beide _paden_ hebben `GET`
operaties (ook bekend als HTTP _methoden_).
+* Het _pad_ `/items/{item_id}` heeft een _pad parameter_ `item_id` dat een `int` moet zijn.
+* Het _pad_ `/items/{item_id}` heeft een optionele `str` _query parameter_ `q`.
+
+### Interactieve API documentatie
+
+Ga naar
http://127.0.0.1:8000/docs.
+
+Je ziet de automatische interactieve API documentatie (verstrekt door
Swagger UI):
+
+
+
+### Alternatieve API documentatie
+
+Ga vervolgens naar
http://127.0.0.1:8000/redoc.
+
+Je ziet de automatische interactieve API documentatie (verstrekt door
ReDoc):
+
+
+
+## Voorbeeld upgrade
+
+Pas nu het bestand `main.py` aan om de body van een `PUT` request te ontvangen.
+
+Dankzij Pydantic kunnen we de body declareren met standaard Python types.
+
+```Python hl_lines="4 9-12 25-27"
+from typing import Union
+
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+ name: str
+ price: float
+ is_offer: Union[bool, None] = None
+
+
+@app.get("/")
+def read_root():
+ return {"Hello": "World"}
+
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int, q: Union[str, None] = None):
+ return {"item_id": item_id, "q": q}
+
+
+@app.put("/items/{item_id}")
+def update_item(item_id: int, item: Item):
+ return {"item_name": item.name, "item_id": item_id}
+```
+
+De `fastapi dev` server zou automatisch moeten herladen.
+
+### Interactieve API documentatie upgrade
+
+Ga nu naar
http://127.0.0.1:8000/docs.
+
+* De interactieve API-documentatie wordt automatisch bijgewerkt, inclusief de nieuwe body:
+
+
+
+* Klik op de knop "Try it out", hiermee kan je de parameters invullen en direct met de API interacteren:
+
+
+
+* Klik vervolgens op de knop "Execute", de gebruikersinterface zal communiceren met jouw API, de parameters verzenden, de resultaten ophalen en deze op het scherm tonen:
+
+
+
+### Alternatieve API documentatie upgrade
+
+Ga vervolgens naar
http://127.0.0.1:8000/redoc.
+
+* De alternatieve documentatie zal ook de nieuwe queryparameter en body weergeven:
+
+
+
+### Samenvatting
+
+Samengevat declareer je **eenmalig** de types van parameters, body, etc. als functieparameters.
+
+Dat doe je met standaard moderne Python types.
+
+Je hoeft geen nieuwe syntax te leren, de methods of klassen van een specifieke bibliotheek, etc.
+
+Gewoon standaard **Python**.
+
+Bijvoorbeeld, voor een `int`:
+
+```Python
+item_id: int
+```
+
+of voor een complexer `Item` model:
+
+```Python
+item: Item
+```
+
+...en met die ene verklaring krijg je:
+
+* Editor ondersteuning, inclusief:
+ * Code aanvulling.
+ * Type validatie.
+* Validatie van data:
+ * Automatische en duidelijke foutboodschappen wanneer de data ongeldig is.
+ * Validatie zelfs voor diep geneste JSON objecten.
+*
Conversie van invoergegevens: afkomstig van het netwerk naar Python-data en -types. Zoals:
+ * JSON.
+ * Pad parameters.
+ * Query parameters.
+ * Cookies.
+ * Headers.
+ * Formulieren.
+ * Bestanden.
+*
Conversie van uitvoergegevens: converstie van Python-data en -types naar netwerkgegevens (zoals JSON):
+ * Converteer Python types (`str`, `int`, `float`, `bool`, `list`, etc).
+ * `datetime` objecten.
+ * `UUID` objecten.
+ * Database modellen.
+ * ...en nog veel meer.
+* Automatische interactieve API-documentatie, inclusief 2 alternatieve gebruikersinterfaces:
+ * Swagger UI.
+ * ReDoc.
+
+---
+
+Terugkomend op het vorige code voorbeeld, **FastAPI** zal:
+
+* Valideren dat er een `item_id` bestaat in het pad voor `GET` en `PUT` verzoeken.
+* Valideren dat het `item_id` van het type `int` is voor `GET` en `PUT` verzoeken.
+ * Wanneer dat niet het geval is, krijgt de cliรซnt een nuttige, duidelijke foutmelding.
+* Controleren of er een optionele query parameter is met de naam `q` (zoals in `http://127.0.0.1:8000/items/foo?q=somequery`) voor `GET` verzoeken.
+ * Aangezien de `q` parameter werd gedeclareerd met `= None`, is deze optioneel.
+ * Zonder de `None` declaratie zou deze verplicht zijn (net als bij de body in het geval met `PUT`).
+* Voor `PUT` verzoeken naar `/items/{item_id}`, lees de body als JSON:
+ * Controleer of het een verplicht attribuut `naam` heeft en dat dat een `str` is.
+ * Controleer of het een verplicht attribuut `price` heeft en dat dat een`float` is.
+ * Controleer of het een optioneel attribuut `is_offer` heeft, dat een `bool` is wanneer het aanwezig is.
+ * Dit alles werkt ook voor diep geneste JSON objecten.
+* Converteer automatisch van en naar JSON.
+* Documenteer alles met OpenAPI, dat gebruikt kan worden door:
+ * Interactieve documentatiesystemen.
+ * Automatische client code generatie systemen, voor vele talen.
+* Biedt 2 interactieve documentatie-webinterfaces aan.
+
+---
+
+Dit was nog maar een snel overzicht, maar je zou nu toch al een idee moeten hebben over hoe het allemaal werkt.
+
+Probeer deze regel te veranderen:
+
+```Python
+ return {"item_name": item.name, "item_id": item_id}
+```
+
+...van:
+
+```Python
+ ... "item_name": item.name ...
+```
+
+...naar:
+
+```Python
+ ... "item_price": item.price ...
+```
+
+...en zie hoe je editor de attributen automatisch invult en hun types herkent:
+
+
+
+Voor een vollediger voorbeeld met meer mogelijkheden, zie de
Tutorial - Gebruikershandleiding.
+
+**Spoiler alert**: de tutorial - gebruikershandleiding bevat:
+
+* Declaratie van **parameters** op andere plaatsen zoals: **headers**, **cookies**, **formuliervelden** en **bestanden**.
+* Hoe stel je **validatie restricties** in zoals `maximum_length` of een `regex`.
+* Een zeer krachtig en eenvoudig te gebruiken **
Dependency Injection** systeem.
+* Beveiliging en authenticatie, inclusief ondersteuning voor **OAuth2** met **JWT-tokens** en **HTTP Basic** auth.
+* Meer geavanceerde (maar even eenvoudige) technieken voor het declareren van **diep geneste JSON modellen** (dankzij Pydantic).
+* **GraphQL** integratie met
Strawberry en andere packages.
+* Veel extra functies (dankzij Starlette) zoals:
+ * **WebSockets**
+ * uiterst gemakkelijke tests gebaseerd op HTTPX en `pytest`
+ * **CORS**
+ * **Cookie Sessions**
+ * ...en meer.
+
+## Prestaties
+
+Onafhankelijke TechEmpower benchmarks tonen **FastAPI** applicaties draaiend onder Uvicorn aan als
een van de snelste Python frameworks beschikbaar, alleen onder Starlette en Uvicorn zelf (intern gebruikt door FastAPI). (*)
+
+Zie de sectie
Benchmarks om hier meer over te lezen.
+
+## Afhankelijkheden
+
+FastAPI maakt gebruik van Pydantic en Starlette.
+
+### `standard` Afhankelijkheden
+
+Wanneer je FastAPI installeert met `pip install "fastapi[standard]"`, worden de volgende `standard` optionele afhankelijkheden geรฏnstalleerd:
+
+Gebruikt door Pydantic:
+
+*
email_validator - voor email validatie.
+
+Gebruikt door Starlette:
+
+*
httpx - Vereist indien je de `TestClient` wil gebruiken.
+*
jinja2 - Vereist als je de standaard templateconfiguratie wil gebruiken.
+*
python-multipart - Vereist indien je
"parsen" van formulieren wil ondersteunen met `requests.form()`.
+
+Gebruikt door FastAPI / Starlette:
+
+*
uvicorn - voor de server die jouw applicatie laadt en bedient.
+* `fastapi-cli` - om het `fastapi` commando te voorzien.
+
+### Zonder `standard` Afhankelijkheden
+
+Indien je de optionele `standard` afhankelijkheden niet wenst te installeren, kan je installeren met `pip install fastapi` in plaats van `pip install "fastapi[standard]"`.
+
+### Bijkomende Optionele Afhankelijkheden
+
+Er zijn nog een aantal bijkomende afhankelijkheden die je eventueel kan installeren.
+
+Bijkomende optionele afhankelijkheden voor Pydantic:
+
+*
pydantic-settings - voor het beheren van settings.
+*
pydantic-extra-types - voor extra data types die gebruikt kunnen worden met Pydantic.
+
+Bijkomende optionele afhankelijkheden voor FastAPI:
+
+*
orjson - Vereist indien je `ORJSONResponse` wil gebruiken.
+*
ujson - Vereist indien je `UJSONResponse` wil gebruiken.
+
+## Licentie
+
+Dit project is gelicenseerd onder de voorwaarden van de MIT licentie.
diff --git a/docs/nl/mkdocs.yml b/docs/nl/mkdocs.yml
new file mode 100644
index 000000000..de18856f4
--- /dev/null
+++ b/docs/nl/mkdocs.yml
@@ -0,0 +1 @@
+INHERIT: ../en/mkdocs.yml
diff --git a/docs/pt/docs/advanced/async-tests.md b/docs/pt/docs/advanced/async-tests.md
index ab5bfa648..7cac26262 100644
--- a/docs/pt/docs/advanced/async-tests.md
+++ b/docs/pt/docs/advanced/async-tests.md
@@ -72,7 +72,7 @@ Note que a funรงรฃo de teste รฉ `async def` agora, no lugar de apenas `def` como
Entรฃo podemos criar um `AsyncClient` com a aplicaรงรฃo, e enviar requisiรงรตes assรญncronas para ela utilizando `await`.
-```Python hl_lines="9-10"
+```Python hl_lines="9-12"
{!../../../docs_src/async_tests/test_main.py!}
```
diff --git a/docs/zh/docs/how-to/index.md b/docs/zh/docs/how-to/index.md
index 262dcfaee..ac097618b 100644
--- a/docs/zh/docs/how-to/index.md
+++ b/docs/zh/docs/how-to/index.md
@@ -6,7 +6,7 @@
ๅฆๆๆไบๅ
ๅฎน็่ตทๆฅๅฏนไฝ ็้กน็ฎๆ็จ๏ผ่ฏท็ปง็ปญๆฅ้
๏ผๅฆๅ่ฏท็ดๆฅ่ทณ่ฟๅฎไปฌใ
-/// ๅฐๆๅทง
+/// tip | ๅฐๆๅทง
ๅฆๆไฝ ๆณไปฅ็ณป็ป็ๆนๅผ**ๅญฆไน FastAPI**๏ผๆจ่๏ผ๏ผ่ฏท้
่ฏป [ๆ็จ - ็จๆทๆๅ](../tutorial/index.md){.internal-link target=_blank} ็ๆฏไธ็ซ ่ใ
diff --git a/docs_src/async_tests/test_main.py b/docs_src/async_tests/test_main.py
index 9f1527d5f..a57a31f7d 100644
--- a/docs_src/async_tests/test_main.py
+++ b/docs_src/async_tests/test_main.py
@@ -1,12 +1,14 @@
import pytest
-from httpx import AsyncClient
+from httpx import ASGITransport, AsyncClient
from .main import app
@pytest.mark.anyio
async def test_root():
- async with AsyncClient(app=app, base_url="http://test") as ac:
+ async with AsyncClient(
+ transport=ASGITransport(app=app), base_url="http://test"
+ ) as ac:
response = await ac.get("/")
assert response.status_code == 200
assert response.json() == {"message": "Tomato"}
diff --git a/docs_src/path_params_numeric_validations/tutorial006.py b/docs_src/path_params_numeric_validations/tutorial006.py
index 0ea32694a..f07629aa0 100644
--- a/docs_src/path_params_numeric_validations/tutorial006.py
+++ b/docs_src/path_params_numeric_validations/tutorial006.py
@@ -13,4 +13,6 @@ async def read_items(
results = {"item_id": item_id}
if q:
results.update({"q": q})
+ if size:
+ results.update({"size": size})
return results
diff --git a/docs_src/path_params_numeric_validations/tutorial006_an.py b/docs_src/path_params_numeric_validations/tutorial006_an.py
index 22a143623..ac4732573 100644
--- a/docs_src/path_params_numeric_validations/tutorial006_an.py
+++ b/docs_src/path_params_numeric_validations/tutorial006_an.py
@@ -14,4 +14,6 @@ async def read_items(
results = {"item_id": item_id}
if q:
results.update({"q": q})
+ if size:
+ results.update({"size": size})
return results
diff --git a/docs_src/path_params_numeric_validations/tutorial006_an_py39.py b/docs_src/path_params_numeric_validations/tutorial006_an_py39.py
index 804751893..426ec3776 100644
--- a/docs_src/path_params_numeric_validations/tutorial006_an_py39.py
+++ b/docs_src/path_params_numeric_validations/tutorial006_an_py39.py
@@ -15,4 +15,6 @@ async def read_items(
results = {"item_id": item_id}
if q:
results.update({"q": q})
+ if size:
+ results.update({"size": size})
return results
diff --git a/fastapi/__init__.py b/fastapi/__init__.py
index 0b79d45ef..ac2508d89 100644
--- a/fastapi/__init__.py
+++ b/fastapi/__init__.py
@@ -1,6 +1,6 @@
"""FastAPI framework, high performance, easy to learn, fast to code, ready for production"""
-__version__ = "0.112.1"
+__version__ = "0.112.2"
from starlette import status as status
diff --git a/fastapi/params.py b/fastapi/params.py
index 860146531..cc2a5c13c 100644
--- a/fastapi/params.py
+++ b/fastapi/params.py
@@ -91,7 +91,7 @@ class Param(FieldInfo):
max_length=max_length,
discriminator=discriminator,
multiple_of=multiple_of,
- allow_nan=allow_inf_nan,
+ allow_inf_nan=allow_inf_nan,
max_digits=max_digits,
decimal_places=decimal_places,
**extra,
@@ -547,7 +547,7 @@ class Body(FieldInfo):
max_length=max_length,
discriminator=discriminator,
multiple_of=multiple_of,
- allow_nan=allow_inf_nan,
+ allow_inf_nan=allow_inf_nan,
max_digits=max_digits,
decimal_places=decimal_places,
**extra,
diff --git a/fastapi/routing.py b/fastapi/routing.py
index 2e7959f3d..49f1b6013 100644
--- a/fastapi/routing.py
+++ b/fastapi/routing.py
@@ -3,14 +3,16 @@ import dataclasses
import email.message
import inspect
import json
-from contextlib import AsyncExitStack
+from contextlib import AsyncExitStack, asynccontextmanager
from enum import Enum, IntEnum
from typing import (
Any,
+ AsyncIterator,
Callable,
Coroutine,
Dict,
List,
+ Mapping,
Optional,
Sequence,
Set,
@@ -67,7 +69,7 @@ from starlette.routing import (
websocket_session,
)
from starlette.routing import Mount as Mount # noqa
-from starlette.types import ASGIApp, Lifespan, Scope
+from starlette.types import AppType, ASGIApp, Lifespan, Scope
from starlette.websockets import WebSocket
from typing_extensions import Annotated, Doc, deprecated
@@ -119,6 +121,23 @@ def _prepare_response_content(
return res
+def _merge_lifespan_context(
+ original_context: Lifespan[Any], nested_context: Lifespan[Any]
+) -> Lifespan[Any]:
+ @asynccontextmanager
+ async def merged_lifespan(
+ app: AppType,
+ ) -> AsyncIterator[Optional[Mapping[str, Any]]]:
+ async with original_context(app) as maybe_original_state:
+ async with nested_context(app) as maybe_nested_state:
+ if maybe_nested_state is None and maybe_original_state is None:
+ yield None # old ASGI compatibility
+ else:
+ yield {**(maybe_nested_state or {}), **(maybe_original_state or {})}
+
+ return merged_lifespan # type: ignore[return-value]
+
+
async def serialize_response(
*,
field: Optional[ModelField] = None,
@@ -1308,6 +1327,10 @@ class APIRouter(routing.Router):
self.add_event_handler("startup", handler)
for handler in router.on_shutdown:
self.add_event_handler("shutdown", handler)
+ self.lifespan_context = _merge_lifespan_context(
+ self.lifespan_context,
+ router.lifespan_context,
+ )
def get(
self,
diff --git a/tests/test_allow_inf_nan_in_enforcing.py b/tests/test_allow_inf_nan_in_enforcing.py
new file mode 100644
index 000000000..9e855fdf8
--- /dev/null
+++ b/tests/test_allow_inf_nan_in_enforcing.py
@@ -0,0 +1,83 @@
+import pytest
+from fastapi import Body, FastAPI, Query
+from fastapi.testclient import TestClient
+from typing_extensions import Annotated
+
+app = FastAPI()
+
+
+@app.post("/")
+async def get(
+ x: Annotated[float, Query(allow_inf_nan=True)] = 0,
+ y: Annotated[float, Query(allow_inf_nan=False)] = 0,
+ z: Annotated[float, Query()] = 0,
+ b: Annotated[float, Body(allow_inf_nan=False)] = 0,
+) -> str:
+ return "OK"
+
+
+client = TestClient(app)
+
+
+@pytest.mark.parametrize(
+ "value,code",
+ [
+ ("-1", 200),
+ ("inf", 200),
+ ("-inf", 200),
+ ("nan", 200),
+ ("0", 200),
+ ("342", 200),
+ ],
+)
+def test_allow_inf_nan_param_true(value: str, code: int):
+ response = client.post(f"/?x={value}")
+ assert response.status_code == code, response.text
+
+
+@pytest.mark.parametrize(
+ "value,code",
+ [
+ ("-1", 200),
+ ("inf", 422),
+ ("-inf", 422),
+ ("nan", 422),
+ ("0", 200),
+ ("342", 200),
+ ],
+)
+def test_allow_inf_nan_param_false(value: str, code: int):
+ response = client.post(f"/?y={value}")
+ assert response.status_code == code, response.text
+
+
+@pytest.mark.parametrize(
+ "value,code",
+ [
+ ("-1", 200),
+ ("inf", 200),
+ ("-inf", 200),
+ ("nan", 200),
+ ("0", 200),
+ ("342", 200),
+ ],
+)
+def test_allow_inf_nan_param_default(value: str, code: int):
+ response = client.post(f"/?z={value}")
+ assert response.status_code == code, response.text
+
+
+@pytest.mark.parametrize(
+ "value,code",
+ [
+ ("-1", 200),
+ ("inf", 422),
+ ("-inf", 422),
+ ("nan", 422),
+ ("0", 200),
+ ("342", 200),
+ ],
+)
+def test_allow_inf_nan_body(value: str, code: int):
+ response = client.post("/", json=value)
+ assert response.status_code == code, response.text
diff --git a/tests/test_router_events.py b/tests/test_router_events.py
index 1b9de18ae..dd7ff3314 100644
--- a/tests/test_router_events.py
+++ b/tests/test_router_events.py
@@ -1,8 +1,8 @@
from contextlib import asynccontextmanager
-from typing import AsyncGenerator, Dict
+from typing import AsyncGenerator, Dict, Union
import pytest
-from fastapi import APIRouter, FastAPI
+from fastapi import APIRouter, FastAPI, Request
from fastapi.testclient import TestClient
from pydantic import BaseModel
@@ -109,3 +109,134 @@ def test_app_lifespan_state(state: State) -> None:
assert response.json() == {"message": "Hello World"}
assert state.app_startup is True
assert state.app_shutdown is True
+
+
+def test_router_nested_lifespan_state(state: State) -> None:
+ @asynccontextmanager
+ async def lifespan(app: FastAPI) -> AsyncGenerator[Dict[str, bool], None]:
+ state.app_startup = True
+ yield {"app": True}
+ state.app_shutdown = True
+
+ @asynccontextmanager
+ async def router_lifespan(app: FastAPI) -> AsyncGenerator[Dict[str, bool], None]:
+ state.router_startup = True
+ yield {"router": True}
+ state.router_shutdown = True
+
+ @asynccontextmanager
+ async def subrouter_lifespan(app: FastAPI) -> AsyncGenerator[Dict[str, bool], None]:
+ state.sub_router_startup = True
+ yield {"sub_router": True}
+ state.sub_router_shutdown = True
+
+ sub_router = APIRouter(lifespan=subrouter_lifespan)
+
+ router = APIRouter(lifespan=router_lifespan)
+ router.include_router(sub_router)
+
+ app = FastAPI(lifespan=lifespan)
+ app.include_router(router)
+
+ @app.get("/")
+ def main(request: Request) -> Dict[str, str]:
+ assert request.state.app
+ assert request.state.router
+ assert request.state.sub_router
+ return {"message": "Hello World"}
+
+ assert state.app_startup is False
+ assert state.router_startup is False
+ assert state.sub_router_startup is False
+ assert state.app_shutdown is False
+ assert state.router_shutdown is False
+ assert state.sub_router_shutdown is False
+
+ with TestClient(app) as client:
+ assert state.app_startup is True
+ assert state.router_startup is True
+ assert state.sub_router_startup is True
+ assert state.app_shutdown is False
+ assert state.router_shutdown is False
+ assert state.sub_router_shutdown is False
+ response = client.get("/")
+ assert response.status_code == 200, response.text
+ assert response.json() == {"message": "Hello World"}
+
+ assert state.app_startup is True
+ assert state.router_startup is True
+ assert state.sub_router_startup is True
+ assert state.app_shutdown is True
+ assert state.router_shutdown is True
+ assert state.sub_router_shutdown is True
+
+
+def test_router_nested_lifespan_state_overriding_by_parent() -> None:
+ @asynccontextmanager
+ async def lifespan(
+ app: FastAPI,
+ ) -> AsyncGenerator[Dict[str, Union[str, bool]], None]:
+ yield {
+ "app_specific": True,
+ "overridden": "app",
+ }
+
+ @asynccontextmanager
+ async def router_lifespan(
+ app: FastAPI,
+ ) -> AsyncGenerator[Dict[str, Union[str, bool]], None]:
+ yield {
+ "router_specific": True,
+ "overridden": "router", # should override parent
+ }
+
+ router = APIRouter(lifespan=router_lifespan)
+ app = FastAPI(lifespan=lifespan)
+ app.include_router(router)
+
+ with TestClient(app) as client:
+ assert client.app_state == {
+ "app_specific": True,
+ "router_specific": True,
+ "overridden": "app",
+ }
+
+
+def test_merged_no_return_lifespans_return_none() -> None:
+ @asynccontextmanager
+ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+ yield
+
+ @asynccontextmanager
+ async def router_lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+ yield
+
+ router = APIRouter(lifespan=router_lifespan)
+ app = FastAPI(lifespan=lifespan)
+ app.include_router(router)
+
+ with TestClient(app) as client:
+ assert not client.app_state
+
+
+def test_merged_mixed_state_lifespans() -> None:
+ @asynccontextmanager
+ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+ yield
+
+ @asynccontextmanager
+ async def router_lifespan(app: FastAPI) -> AsyncGenerator[Dict[str, bool], None]:
+ yield {"router": True}
+
+ @asynccontextmanager
+ async def sub_router_lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+ yield
+
+ sub_router = APIRouter(lifespan=sub_router_lifespan)
+ router = APIRouter(lifespan=router_lifespan)
+ app = FastAPI(lifespan=lifespan)
+ router.include_router(sub_router)
+ app.include_router(router)
+
+ with TestClient(app) as client:
+ assert client.app_state == {"router": True}
-
+
-
@@ -394,7 +393,7 @@ Coming back to the previous code example, **FastAPI** will:
* Check if there is an optional query parameter named `q` (as in `http://127.0.0.1:8000/items/foo?q=somequery`) for `GET` requests.
* As the `q` parameter is declared with `= None`, it is optional.
* Without the `None` it would be required (as is the body in the case with `PUT`).
-* For `PUT` requests to `/items/{item_id}`, Read the body as JSON:
+* For `PUT` requests to `/items/{item_id}`, read the body as JSON:
* Check that it has a required attribute `name` that should be a `str`.
* Check that it has a required attribute `price` that has to be a `float`.
* Check that it has an optional attribute `is_offer`, that should be a `bool`, if present.
diff --git a/docs/de/docs/advanced/async-tests.md b/docs/de/docs/advanced/async-tests.md
index 9f0bd4aa2..e56841faa 100644
--- a/docs/de/docs/advanced/async-tests.md
+++ b/docs/de/docs/advanced/async-tests.md
@@ -72,7 +72,7 @@ Beachten Sie, dass die Testfunktion jetzt `async def` ist und nicht nur `def` wi
Dann kรถnnen wir einen `AsyncClient` mit der App erstellen und mit `await` asynchrone Requests an ihn senden.
-```Python hl_lines="9-10"
+```Python hl_lines="9-12"
{!../../../docs_src/async_tests/test_main.py!}
```
diff --git a/docs/em/docs/advanced/async-tests.md b/docs/em/docs/advanced/async-tests.md
index 324b4f68a..11f885fe6 100644
--- a/docs/em/docs/advanced/async-tests.md
+++ b/docs/em/docs/advanced/async-tests.md
@@ -72,7 +72,7 @@ $ pytest
โคด๏ธ ๐ฅ ๐ช โ `AsyncClient` โฎ๏ธ ๐ฑ, & ๐จ ๐ ๐จ โซ๏ธ, โ๏ธ `await`.
-```Python hl_lines="9-10"
+```Python hl_lines="9-12"
{!../../../docs_src/async_tests/test_main.py!}
```
diff --git a/docs/en/data/sponsors.yml b/docs/en/data/sponsors.yml
index 8c0956ac5..3a767b6b1 100644
--- a/docs/en/data/sponsors.yml
+++ b/docs/en/data/sponsors.yml
@@ -17,15 +17,12 @@ gold:
- url: https://www.propelauth.com/?utm_source=fastapi&utm_campaign=1223&utm_medium=mainbadge
title: Auth, user management and more for your B2B product
img: https://fastapi.tiangolo.com/img/sponsors/propelauth.png
- - url: https://docs.withcoherence.com/configuration/frameworks/?utm_medium=advertising&utm_source=fastapi&utm_campaign=docs#fastapi-example
+ - url: https://docs.withcoherence.com/coherence-templates/full-stack-template/#fastapi?utm_medium=advertising&utm_source=fastapi&utm_campaign=docs
title: Coherence
img: https://fastapi.tiangolo.com/img/sponsors/coherence.png
- url: https://www.mongodb.com/developer/languages/python/python-quickstart-fastapi/?utm_campaign=fastapi_framework&utm_source=fastapi_sponsorship&utm_medium=web_referral
title: Simplify Full Stack Development with FastAPI & MongoDB
img: https://fastapi.tiangolo.com/img/sponsors/mongodb.png
- - url: https://konghq.com/products/kong-konnect?utm_medium=referral&utm_source=github&utm_campaign=platform&utm_content=fast-api
- title: Kong Konnect - API management platform
- img: https://fastapi.tiangolo.com/img/sponsors/kong.png
- url: https://zuplo.link/fastapi-gh
title: 'Zuplo: Scale, Protect, Document, and Monetize your FastAPI'
img: https://fastapi.tiangolo.com/img/sponsors/zuplo.png
diff --git a/docs/en/docs/advanced/async-tests.md b/docs/en/docs/advanced/async-tests.md
index ac459ff0c..580d9142c 100644
--- a/docs/en/docs/advanced/async-tests.md
+++ b/docs/en/docs/advanced/async-tests.md
@@ -72,7 +72,7 @@ Note that the test function is now `async def` instead of just `def` as before w
Then we can create an `AsyncClient` with the app, and send async requests to it, using `await`.
-```Python hl_lines="9-10"
+```Python hl_lines="9-12"
{!../../../docs_src/async_tests/test_main.py!}
```
diff --git a/docs/en/docs/advanced/custom-response.md b/docs/en/docs/advanced/custom-response.md
index 8a6555dba..79f755815 100644
--- a/docs/en/docs/advanced/custom-response.md
+++ b/docs/en/docs/advanced/custom-response.md
@@ -4,9 +4,9 @@ By default, **FastAPI** will return the responses using `JSONResponse`.
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` as part of the generated OpenAPI).
+But if you return a `Response` directly (or any subclass, like `JSONResponse`), the data won't be automatically converted (even if you declare a `response_model`), and the documentation won't be automatically generated (for example, including the specific "media type", in the HTTP header `Content-Type` as part of the generated OpenAPI).
-But you can also declare the `Response` that you want to be used, in the *path operation decorator*.
+But you can also declare the `Response` that you want to be used (e.g. any `Response` subclass), in the *path operation decorator* using the `response_class` parameter.
The contents that you return from your *path operation function* will be put inside of that `Response`.
diff --git a/docs/en/docs/advanced/response-directly.md b/docs/en/docs/advanced/response-directly.md
index 73071ed1b..2251659c5 100644
--- a/docs/en/docs/advanced/response-directly.md
+++ b/docs/en/docs/advanced/response-directly.md
@@ -28,7 +28,7 @@ This gives you a lot of flexibility. You can return any data type, override any
## Using the `jsonable_encoder` in a `Response`
-Because **FastAPI** doesn't do any change to a `Response` you return, you have to make sure it's contents are ready for it.
+Because **FastAPI** doesn't do any change to a `Response` you return, you have to make sure its contents are ready for it.
For example, you cannot put a Pydantic model in a `JSONResponse` without first converting it to a `dict` with all the data types (like `datetime`, `UUID`, etc) converted to JSON-compatible types.
diff --git a/docs/en/docs/advanced/sub-applications.md b/docs/en/docs/advanced/sub-applications.md
index 8c52e091f..568a9deca 100644
--- a/docs/en/docs/advanced/sub-applications.md
+++ b/docs/en/docs/advanced/sub-applications.md
@@ -36,12 +36,12 @@ In this case, it will be mounted at the path `/subapi`:
### Check the automatic API docs
-Now, run `uvicorn` with the main app, if your file is `main.py`, it would be:
+Now, run the `fastapi` command with your file:
-
-