FastAPI stands on the shoulders of giants:
-* [Starlette](https://www.starlette.dev/) for the web parts.
+* [Starlette](https://starlette.dev/) for the web parts.
* [Pydantic](https://docs.pydantic.dev/) for the data parts.
## Installation
<details markdown="1">
<summary>About the command <code>fastapi dev</code>...</summary>
-The command `fastapi dev` reads your `main.py` file automatically, detects the **FastAPI** app in it, and starts a server using [Uvicorn](https://www.uvicorn.dev).
+The command `fastapi dev` reads your `main.py` file automatically, detects the **FastAPI** app in it, and starts a server using [Uvicorn](https://uvicorn.dev).
By default, `fastapi dev` will start with auto-reload enabled for local development.
Used by FastAPI:
-* [`uvicorn`](https://www.uvicorn.dev) - for the server that loads and serves your application. This includes `uvicorn[standard]`, which includes some dependencies (e.g. `uvloop`) needed for high performance serving.
+* [`uvicorn`](https://uvicorn.dev) - for the server that loads and serves your application. This includes `uvicorn[standard]`, which includes some dependencies (e.g. `uvloop`) needed for high performance serving.
* `fastapi-cli[standard]` - to provide the `fastapi` command.
* This includes `fastapi-cloud-cli`, which allows you to deploy your FastAPI application to [FastAPI Cloud](https://fastapicloud.com).
/// note
-You can read more about the Starlette `lifespan` handlers in [Starlette's Lifespan' docs](https://www.starlette.dev/lifespan/).
+You can read more about the Starlette `lifespan` handlers in [Starlette's Lifespan' docs](https://starlette.dev/lifespan/).
Including how to handle lifespan state that can be used in other areas of your code.
* [Uvicorn's `ProxyHeadersMiddleware`](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py)
* [MessagePack](https://github.com/florimondmanca/msgpack-asgi)
-To see other available middlewares check [Starlette's Middleware docs](https://www.starlette.dev/middleware/) and the [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi).
+To see other available middlewares check [Starlette's Middleware docs](https://starlette.dev/middleware/) and the [ASGI Awesome List](https://github.com/florimondmanca/awesome-asgi).
///
-To see all the available parameters and options, check the [documentation in Starlette](https://www.starlette.dev/responses/#set-cookie).
+To see all the available parameters and options, check the [documentation in Starlette](https://starlette.dev/responses/#set-cookie).
Keep in mind that custom proprietary headers can be added [using the `X-` prefix](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).
-But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your CORS configurations (read more in [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), using the parameter `expose_headers` documented in [Starlette's CORS docs](https://www.starlette.dev/middleware/#corsmiddleware).
+But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your CORS configurations (read more in [CORS (Cross-Origin Resource Sharing)](../tutorial/cors.md)), using the parameter `expose_headers` documented in [Starlette's CORS docs](https://starlette.dev/middleware/#corsmiddleware).
## More details { #more-details }
-For more details, including how to test templates, check [Starlette's docs on templates](https://www.starlette.dev/templates/).
+For more details, including how to test templates, check [Starlette's docs on templates](https://starlette.dev/templates/).
{* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *}
-You can read more details about the ["Running lifespan in tests in the official Starlette documentation site."](https://www.starlette.dev/lifespan/#running-lifespan-in-tests)
+You can read more details about the ["Running lifespan in tests in the official Starlette documentation site."](https://starlette.dev/lifespan/#running-lifespan-in-tests)
For the deprecated `startup` and `shutdown` events, you can use the `TestClient` as follows:
/// note
-For more details, check Starlette's documentation for [testing WebSockets](https://www.starlette.dev/testclient/#testing-websocket-sessions).
+For more details, check Starlette's documentation for [testing WebSockets](https://starlette.dev/testclient/#testing-websocket-sessions).
///
## Details about the `Request` object { #details-about-the-request-object }
-As **FastAPI** is actually **Starlette** underneath, with a layer of several tools on top, you can use Starlette's [`Request`](https://www.starlette.dev/requests/) object directly when you need to.
+As **FastAPI** is actually **Starlette** underneath, with a layer of several tools on top, you can use Starlette's [`Request`](https://starlette.dev/requests/) object directly when you need to.
It would also mean that if you get data from the `Request` object directly (for example, read the body) it won't be validated, converted or documented (with OpenAPI, for the automatic API user interface) by FastAPI.
## `Request` documentation { #request-documentation }
-You can read more details about the [`Request` object in the official Starlette documentation site](https://www.starlette.dev/requests/).
+You can read more details about the [`Request` object in the official Starlette documentation site](https://starlette.dev/requests/).
/// note | Technical Details
To learn more about the options, check Starlette's documentation for:
-* [The `WebSocket` class](https://www.starlette.dev/websockets/).
-* [Class-based WebSocket handling](https://www.starlette.dev/endpoints/#websocketendpoint).
+* [The `WebSocket` class](https://starlette.dev/websockets/).
+* [Class-based WebSocket handling](https://starlette.dev/endpoints/#websocketendpoint).
///
-### [Starlette](https://www.starlette.dev/) { #starlette }
+### [Starlette](https://starlette.dev/) { #starlette }
Starlette is a lightweight <dfn title="The new standard for building asynchronous Python web applications">ASGI</dfn> framework/toolkit, which is ideal for building high-performance asyncio services.
///
-### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn }
+### [Uvicorn](https://uvicorn.dev) { #uvicorn }
Uvicorn is a lightning-fast ASGI server, built on uvloop and httptools.
There are several alternatives, including:
-* [Uvicorn](https://www.uvicorn.dev/): a high performance ASGI server.
+* [Uvicorn](https://uvicorn.dev): a high performance ASGI server.
* [Hypercorn](https://hypercorn.readthedocs.io/): an ASGI server compatible with HTTP/2 and Trio among other features.
* [Daphne](https://github.com/django/daphne): the ASGI server built for Django Channels.
* [Granian](https://github.com/emmett-framework/granian): A Rust HTTP server for Python applications.
///
-Internally, **FastAPI CLI** uses [Uvicorn](https://www.uvicorn.dev), a high-performance, production-ready, ASGI server. 😎
+Internally, **FastAPI CLI** uses [Uvicorn](https://uvicorn.dev), a high-performance, production-ready, ASGI server. 😎
The `fastapi` CLI will try to detect automatically the FastAPI app to run, assuming it's an object called `app` in a file `main.py` (or a couple other variants).
## Starlette features { #starlette-features }
-**FastAPI** is fully compatible with (and based on) [**Starlette**](https://www.starlette.dev/). So, any additional Starlette code you have, will also work.
+**FastAPI** is fully compatible with (and based on) [**Starlette**](https://starlette.dev/). So, any additional Starlette code you have, will also work.
`FastAPI` is actually a sub-class of `Starlette`. So, if you already know or use Starlette, most of the functionality will work the same way.
Then I contributed to it, to make it fully compliant with JSON Schema, to support different ways to define constraint declarations, and to improve editor support (type checks, autocompletion) based on the tests in several editors.
-During the development, I also contributed to [**Starlette**](https://www.starlette.dev/), the other key requirement.
+During the development, I also contributed to [**Starlette**](https://starlette.dev/), the other key requirement.
## Development { #development }
And those two things, `scope` and `receive`, are what is needed to create a new `Request` instance.
-To learn more about the `Request` check [Starlette's docs about Requests](https://www.starlette.dev/requests/).
+To learn more about the `Request` check [Starlette's docs about Requests](https://starlette.dev/requests/).
///
FastAPI stands on the shoulders of giants:
-* [Starlette](https://www.starlette.dev/) for the web parts.
+* [Starlette](https://starlette.dev/) for the web parts.
* [Pydantic](https://docs.pydantic.dev/) for the data parts.
## Installation { #installation }
<details markdown="1">
<summary>About the command <code>fastapi dev</code>...</summary>
-The command `fastapi dev` reads your `main.py` file automatically, detects the **FastAPI** app in it, and starts a server using [Uvicorn](https://www.uvicorn.dev).
+The command `fastapi dev` reads your `main.py` file automatically, detects the **FastAPI** app in it, and starts a server using [Uvicorn](https://uvicorn.dev).
By default, `fastapi dev` will start with auto-reload enabled for local development.
Used by FastAPI:
-* [`uvicorn`](https://www.uvicorn.dev) - for the server that loads and serves your application. This includes `uvicorn[standard]`, which includes some dependencies (e.g. `uvloop`) needed for high performance serving.
+* [`uvicorn`](https://uvicorn.dev) - for the server that loads and serves your application. This includes `uvicorn[standard]`, which includes some dependencies (e.g. `uvloop`) needed for high performance serving.
* `fastapi-cli[standard]` - to provide the `fastapi` command.
* This includes `fastapi-cloud-cli`, which allows you to deploy your FastAPI application to [FastAPI Cloud](https://fastapicloud.com).
* Upgrade the compatible version of Starlette to `0.12.0`.
* This includes support for ASGI 3 (the latest version of the standard).
- * It's now possible to use [Starlette's `StreamingResponse`](https://www.starlette.dev/responses/#streamingresponse) with iterators, like [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) objects (as those returned by `open()`).
+ * It's now possible to use [Starlette's `StreamingResponse`](https://starlette.dev/responses/#streamingresponse) with iterators, like [file-like](https://docs.python.org/3/glossary.html#term-file-like-object) objects (as those returned by `open()`).
* It's now possible to use the low level utility `iterate_in_threadpool` from `starlette.concurrency` (for advanced scenarios).
* PR [#243](https://github.com/tiangolo/fastapi/pull/243).
## Technical Details { #technical-details }
-The class `BackgroundTasks` comes directly from [`starlette.background`](https://www.starlette.dev/background/).
+The class `BackgroundTasks` comes directly from [`starlette.background`](https://starlette.dev/background/).
It is imported/included directly into FastAPI so that you can import it from `fastapi` and avoid accidentally importing the alternative `BackgroundTask` (without the `s` at the end) from `starlette.background`.
It's still possible to use `BackgroundTask` alone in FastAPI, but you have to create the object in your code and return a Starlette `Response` including it.
-You can see more details in [Starlette's official docs for Background Tasks](https://www.starlette.dev/background/).
+You can see more details in [Starlette's official docs for Background Tasks](https://starlette.dev/background/).
## Caveat { #caveat }
`FastAPI` is a class that inherits directly from `Starlette`.
-You can use all the [Starlette](https://www.starlette.dev/) functionality with `FastAPI` too.
+You can use all the [Starlette](https://starlette.dev/) functionality with `FastAPI` too.
///
## Install custom exception handlers { #install-custom-exception-handlers }
-You can add custom exception handlers with [the same exception utilities from Starlette](https://www.starlette.dev/exceptions/).
+You can add custom exception handlers with [the same exception utilities from Starlette](https://starlette.dev/exceptions/).
Let's say you have a custom exception `UnicornException` that you (or a library you use) might `raise`.
Keep in mind that custom proprietary headers can be added [using the `X-` prefix](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).
-But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your CORS configurations ([CORS (Cross-Origin Resource Sharing)](cors.md)) using the parameter `expose_headers` documented in [Starlette's CORS docs](https://www.starlette.dev/middleware/#corsmiddleware).
+But if you have custom headers that you want a client in a browser to be able to see, you need to add them to your CORS configurations ([CORS (Cross-Origin Resource Sharing)](cors.md)) using the parameter `expose_headers` documented in [Starlette's CORS docs](https://starlette.dev/middleware/#corsmiddleware).
///
## More info { #more-info }
-For more details and options check [Starlette's docs about Static Files](https://www.starlette.dev/staticfiles/).
+For more details and options check [Starlette's docs about Static Files](https://starlette.dev/staticfiles/).
# Testing { #testing }
-Thanks to [Starlette](https://www.starlette.dev/testclient/), testing **FastAPI** applications is easy and enjoyable.
+Thanks to [Starlette](https://starlette.dev/testclient/), testing **FastAPI** applications is easy and enjoyable.
It is based on [HTTPX](https://www.python-httpx.org), which in turn is designed based on Requests, so it's very familiar and intuitive.
errors.
Read more in the
- [Starlette docs for Applications](https://www.starlette.dev/applications/#starlette.applications.Starlette).
+ [Starlette docs for Applications](https://starlette.dev/applications/#starlette.applications.Starlette).
"""
),
] = False,
This is simply inherited from Starlette.
Read more about it in the
- [Starlette docs for Applications](https://www.starlette.dev/applications/#storing-state-on-the-app-instance).
+ [Starlette docs for Applications](https://starlette.dev/applications/#storing-state-on-the-app-instance).
"""
),
] = State()