diff --git a/README.md b/README.md index cf94ea3ba..80b9a1938 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ The key features are: * **Easy**: Designed to be easy to use and learn. Less time reading docs. * **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs. * **Robust**: Get production-ready code. With automatic interactive documentation. -* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema. +* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema. * estimation based on tests on an internal development team, building production applications. @@ -83,9 +83,8 @@ Python 3.6+ FastAPI stands on the shoulders of giants: -* Starlette for the web parts. -* Pydantic for the data parts. - +* Starlette for the web parts. +* Pydantic for the data parts. ## Installation @@ -93,7 +92,7 @@ FastAPI stands on the shoulders of giants: pip install fastapi ``` -You will also need an ASGI server, for production such as Uvicorn or Hypercorn. +You will also need an ASGI server, for production such as Uvicorn or Hypercorn. ```bash pip install uvicorn @@ -120,6 +119,7 @@ def read_root(): def read_item(item_id: int, q: str = None): return {"item_id": item_id, "q": q} ``` +
Or use async def... @@ -142,7 +142,7 @@ async def read_item(item_id: int, q: str = None): ``` **Note**: - + If you don't know, check the _"In a hurry?"_ section about `async` and `await` in the docs.
@@ -168,7 +168,7 @@ The command `uvicorn main:app` refers to: ### Check it -Open your browser at http://127.0.0.1:8000/items/5?q=somequery. +Open your browser at http://127.0.0.1:8000/items/5?q=somequery. You will see the JSON response as: @@ -185,18 +185,17 @@ You already created an API that: ### Interactive API docs -Now go to http://127.0.0.1:8000/docs. +Now go to http://127.0.0.1:8000/docs. -You will see the automatic interactive API documentation (provided by Swagger UI): +You will see the automatic interactive API documentation (provided by Swagger UI): ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) - ### Alternative API docs -And now, go to http://127.0.0.1:8000/redoc. +And now, go to http://127.0.0.1:8000/redoc. -You will see the alternative automatic documentation (provided by ReDoc): +You will see the alternative automatic documentation (provided by ReDoc): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -238,7 +237,7 @@ The server should reload automatically (because you added `--reload` to the `uvi ### Interactive API docs upgrade -Now go to http://127.0.0.1:8000/docs. +Now go to http://127.0.0.1:8000/docs. * The interactive API documentation will be automatically updated, including the new body: @@ -252,16 +251,14 @@ Now go to http://127.0.0.1: ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) - ### Alternative API docs upgrade -And now, go to http://127.0.0.1:8000/redoc. +And now, go to http://127.0.0.1:8000/redoc. * The alternative documentation will also reflect the new query parameter and body: ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) - ### Recap In summary, you declare **once** the types of parameters, body, etc. as function parameters. @@ -331,7 +328,6 @@ Coming back to the previous code example, **FastAPI** will: * Automatic client code generation systems, for many languages. * Provide 2 interactive documentation web interfaces directly. - --- We just scratched the surface, but you already get the idea of how it all works. @@ -358,7 +354,6 @@ Try changing the line with: ![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) - For a more complete example including more features, see the Tutorial - User Guide. **Spoiler alert**: the tutorial - user guide includes: @@ -376,10 +371,9 @@ For a more complete example including more features, see the one of the fastest Python frameworks available, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*) +Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as one of the fastest Python frameworks available, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*) To understand more about it, see the section Benchmarks. @@ -390,7 +384,6 @@ Used by Pydantic: * ujson - for faster JSON "parsing". * email_validator - for email validation. - Used by Starlette: * requests - Required if you want to use the `TestClient`. @@ -398,7 +391,7 @@ Used by Starlette: * jinja2 - Required if you want to use the default template configuration. * python-multipart - Required if you want to support form "parsing", with `request.form()`. * itsdangerous - Required for `SessionMiddleware` support. -* pyyaml - Required for `SchemaGenerator` support. +* pyyaml - Required for Starlette's `SchemaGenerator` support (you probably don't need it with FastAPI). * graphene - Required for `GraphQLApp` support. * ujson - Required if you want to use `UJSONResponse`. diff --git a/docs/alternatives.md b/docs/alternatives.md index 1e974c020..630388877 100644 --- a/docs/alternatives.md +++ b/docs/alternatives.md @@ -12,7 +12,7 @@ But at some point, there was no other option than creating something that provid ## Previous tools -### Django +### Django It's the most popular Python framework and is widely trusted. It is used to build systems like Instagram. @@ -20,7 +20,7 @@ It's relatively tightly coupled with relational databases (like MySQL or Postgre It was created to generate the HTML in the backend, not to create APIs used by a modern frontend (like React, Vue.js and Angular) or by other systems (like IoT devices) communicating with it. -### Django REST Framework +### Django REST Framework Django REST framework was created to be a flexible toolkit for building Web APIs using Django underneath, to improve its API capabilities. @@ -35,7 +35,7 @@ It was one of the first examples of **automatic API documentation**, and this wa !!! check "Inspired **FastAPI** to" Have an automatic API documentation web user interface. -### Flask +### Flask Flask is a "microframework", it doesn't include database integrations nor many of the things that come by default in Django. @@ -55,7 +55,7 @@ Given the simplicity of Flask, it seemed like a good match for building APIs. Th Have a simple and easy to use routing system. -### Requests +### Requests **FastAPI** is not actually an alternative to **Requests**. Their scope is very different. @@ -95,7 +95,7 @@ See the similarities in `requests.get(...)` and `@app.get(...)`. * Have sensible defaults, but powerful customizations. -### Swagger / OpenAPI +### Swagger / OpenAPI The main feature I wanted from Django REST Framework was the automatic API documentation. @@ -112,8 +112,8 @@ That's why when talking about version 2.0 it's common to say "Swagger", and for And integrate standards-based user interface tools: - * Swagger UI - * ReDoc + * Swagger UI + * ReDoc These two were chosen for being fairly popular and stable, but doing a quick search, you could find dozens of additional alternative user interfaces for OpenAPI (that you can use with **FastAPI**). @@ -121,7 +121,7 @@ That's why when talking about version 2.0 it's common to say "Swagger", and for There are several Flask REST frameworks, but after investing the time and work into investigating them, I found that many are discontinued or abandoned, with several standing issues that made them unfit. -### Marshmallow +### Marshmallow One of the main features needed by API systems is data "serialization" which is taking data from the code (Python) and converting it into something that can be sent through the network. For example, converting an object containing data from a database into a JSON object. Converting `datetime` objects into strings, etc. @@ -136,7 +136,7 @@ But it was created before there existed Python type hints. So, to define every < !!! check "Inspired **FastAPI** to" Use code to define "schemas" that provide data types and validation, automatically. -### Webargs +### Webargs Another big feature required by APIs is parsing data from incoming requests. @@ -152,7 +152,7 @@ It's a great tool and I have used it a lot too, before having **FastAPI**. !!! check "Inspired **FastAPI** to" Have automatic validation of incoming request data. -### APISpec +### APISpec Marshmallow and Webargs provide validation, parsing and serialization as plug-ins. @@ -177,7 +177,7 @@ The editor can't help much with that. And if we modify parameters or Marshmallow !!! check "Inspired **FastAPI** to" Support the open standard for APIs, OpenAPI. -### Flask-apispec +### Flask-apispec It's a Flask plug-in, that ties together Webargs, Marshmallow and APISpec. @@ -191,9 +191,9 @@ This combination of Flask, Flask-apispec with Marshmallow and Webargs was my fav Using it led to the creation of several Flask full-stack generators. These are the main stack I (and several external teams) have been using up to now: -* https://github.com/tiangolo/full-stack -* https://github.com/tiangolo/full-stack-flask-couchbase -* https://github.com/tiangolo/full-stack-flask-couchdb +* https://github.com/tiangolo/full-stack +* https://github.com/tiangolo/full-stack-flask-couchbase +* https://github.com/tiangolo/full-stack-flask-couchdb And these same full-stack generators were the base of the **FastAPI** project generator. @@ -203,7 +203,7 @@ And these same full-stack generators were the base of the NestJS (and Angular) +### NestJS (and Angular) This isn't even Python, NestJS is a JavaScript (TypeScript) NodeJS framework inspired by Angular. @@ -222,21 +222,21 @@ It can't handle nested models very well. So, if the JSON body in the request is Have a powerful dependency injection system. Find a way to minimize code repetition. -### Sanic +### Sanic It was one of the first extremely fast Python frameworks based on `asyncio`. It was made to be very similar to Flask. !!! note "Technical Details" - It used `uvloop` instead of the default Python `asyncio` loop. That's what made it so fast. + It used `uvloop` instead of the default Python `asyncio` loop. That's what made it so fast. - It still doesn't implement the ASGI spec for Python asynchronous web development, but it clearly inspired Uvicorn and Starlette, that are currently faster than Sanic in open benchmarks. + It still doesn't implement the ASGI spec for Python asynchronous web development, but it clearly inspired Uvicorn and Starlette, that are currently faster than Sanic in open benchmarks. !!! check "Inspired **FastAPI** to" Find a way to have a crazy performance. That's why **FastAPI** is based on Starlette, as it is the fastest framework available (tested by third-party benchmarks). -### Falcon +### Falcon Falcon is another high performance Python framework, it is designed to be minimal, and work as the foundation of other frameworks like Hug. @@ -253,7 +253,7 @@ So, data validation, serialization, and documentation, have to be done in code, Although in FastAPI it's optional, and is used mainly to set headers, cookies, and alternative status codes. -### Molten +### Molten I discovered Molten in the first stages of building **FastAPI**. And it has quite similar ideas: @@ -274,7 +274,7 @@ Routes are declared in a single place, using functions declared in other places This actually inspired updating parts of Pydantic, to support the same validation declaration style (all this functionality is now already available in Pydantic). -### Hug +### Hug Hug was one of the first frameworks to implement the declaration of API parameter types using Python type hints. This was a great idea that inspired other tools to do the same. @@ -289,7 +289,7 @@ It has an interesting, uncommon feature: using the same framework, it's possible As it is based on the previous standard for synchronous Python web frameworks (WSGI), it can't handle Websockets and other things, although it still has high performance too. !!! info - Hug was created by Timothy Crosley, the same creator of `isort`, a great tool to automatically sort imports in Python files. + Hug was created by Timothy Crosley, the same creator of `isort`, a great tool to automatically sort imports in Python files. !!! check "Ideas inspired in **FastAPI**" Hug inspired parts of APIStar, and was one of the tools I found most promising, alongside APIStar. @@ -298,7 +298,7 @@ As it is based on the previous standard for synchronous Python web frameworks (W Hug inspired **FastAPI** to declare a `response` parameter in functions to set headers and cookies. -### APIStar (<= 0.5) +### APIStar (<= 0.5) Right before deciding to build **FastAPI** I found **APIStar** server. It had almost everything I was looking for and had a great design. @@ -342,7 +342,7 @@ Now APIStar is a set of tools to validate OpenAPI specifications, not a web fram ## Used by **FastAPI** -### Pydantic +### Pydantic Pydantic is a library to define data validation, serialization and documentation (using JSON Schema) based on Python type hints. @@ -355,7 +355,7 @@ It is comparable to Marshmallow. Although it's faster than Marshmallow in benchm **FastAPI** then takes that JSON Schema data and puts it in OpenAPI, apart from all the other things it does. -### Starlette +### Starlette Starlette is a lightweight ASGI framework/toolkit, which is ideal for building high-performance asyncio services. @@ -395,7 +395,7 @@ That's one of the main things that **FastAPI** adds on top, all based on Python So, anything that you can do with Starlette, you can do it directly with **FastAPI**, as it is basically Starlette on steroids. -### Uvicorn +### Uvicorn Uvicorn is a lightning-fast ASGI server, built on uvloop and httptools. diff --git a/docs/async.md b/docs/async.md index e55fe5fae..ff0d8c7fb 100644 --- a/docs/async.md +++ b/docs/async.md @@ -218,7 +218,7 @@ That kind of asynchronicity is what made NodeJS popular (even though NodeJS is n And that's the same level of performance you get with **FastAPI**. -And as you can have parallelism and asynchronicity at the same time, you get higher performance than most of the tested NodeJS frameworks and on par with Go, which is a compiled language closer to C (all thanks to Starlette). +And as you can have parallelism and asynchronicity at the same time, you get higher performance than most of the tested NodeJS frameworks and on par with Go, which is a compiled language closer to C (all thanks to Starlette). ### Is concurrency better than parallelism? @@ -329,7 +329,7 @@ So, about the egg and the chicken, how do you call the first `async` function? If you are working with **FastAPI** you don't have to worry about that, because that "first" function will be your path operation function, and FastAPI will know how to do the right thing. -But if you want to use `async` / `await` without FastAPI, check the official Python docs. +But if you want to use `async` / `await` without FastAPI, check the official Python docs. ### Other forms of asynchronous code @@ -342,9 +342,9 @@ This same syntax (or almost identical) was also included recently in modern vers But before that, handling asynchronous code was quite more complex and difficult. -In previous versions of Python, you could have used threads or Gevent. But the code is way more complex to understand, debug, and think about. +In previous versions of Python, you could have used threads or Gevent. But the code is way more complex to understand, debug, and think about. -In previous versions of NodeJS / Browser JavaScript, you would have used "callbacks". Which lead to callback hell. +In previous versions of NodeJS / Browser JavaScript, you would have used "callbacks". Which lead to callback hell. ## Coroutines diff --git a/docs/benchmarks.md b/docs/benchmarks.md index 78d1fc2b7..95efcab53 100644 --- a/docs/benchmarks.md +++ b/docs/benchmarks.md @@ -1,4 +1,4 @@ -Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as one of the fastest Python frameworks available, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*) +Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as one of the fastest Python frameworks available, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*) But when checking benchmarks and comparisons you should have the following in mind. diff --git a/docs/contributing.md b/docs/contributing.md index efdc9f0ab..cffa47320 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -28,7 +28,7 @@ Or in Windows' PowerShell: $ .\env\Scripts\Activate.ps1 ``` -Or if you use Bash for Windows (e.g. [Git Bash](https://gitforwindows.org/){.external-link target=_blank}): +Or if you use Bash for Windows (e.g. Git Bash): ```console $ source ./env/Scripts/activate @@ -58,7 +58,7 @@ some/directory/fastapi/env/bin/pip ### Flit -**FastAPI** uses Flit to build, package and publish the project. +**FastAPI** uses Flit to build, package and publish the project. After activating the environment as described above, install `flit`: @@ -112,7 +112,7 @@ As it runs one command after the other and modifies and reverts many files, it t ## Docs -The documentation uses MkDocs. +The documentation uses MkDocs. All the documentation is in Markdown format in the directory `./docs`. diff --git a/docs/css/custom.css b/docs/css/custom.css index 033385e18..674cfdb20 100644 --- a/docs/css/custom.css +++ b/docs/css/custom.css @@ -1,3 +1,3 @@ a.external-link::after { - content: " [↪]" + content: " [↪]"; } diff --git a/docs/deployment.md b/docs/deployment.md index 91e0b88a9..eaa593d35 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,4 +1,4 @@ -You can use **Docker** for deployment. It has several advantages like security, replicability, development simplicity, etc. +You can use **Docker** for deployment. It has several advantages like security, replicability, development simplicity, etc. In this section you'll see instructions and links to guides to know how to: @@ -11,20 +11,18 @@ In this section you'll see instructions and links to guides to know how to: You can also easily use **FastAPI** in a standard server directly too (without Docker). - ## Docker If you are using Docker, you can use the official Docker image: -### tiangolo/uvicorn-gunicorn-fastapi +### tiangolo/uvicorn-gunicorn-fastapi This image has an "auto-tuning" mechanism included, so that you can just add your code and get very high performance automatically. And without making sacrifices. But you can still change and update all the configurations with environment variables or configuration files. !!! tip - To see all the configurations and options, go to the Docker image page: tiangolo/uvicorn-gunicorn-fastapi. - + To see all the configurations and options, go to the Docker image page: tiangolo/uvicorn-gunicorn-fastapi. ### Create a `Dockerfile` @@ -115,10 +113,9 @@ docker run -d --name mycontainer -p 80:80 myimage Now you have an optimized FastAPI server in a Docker container. Auto-tuned for your current server (and number of CPU cores). - ### Check it -You should be able to check it in your Docker container's URL, for example: http://192.168.99.100/items/5?q=somequery or http://127.0.0.1/items/5?q=somequery (or equivalent, using your Docker host). +You should be able to check it in your Docker container's URL, for example: http://192.168.99.100/items/5?q=somequery or http://127.0.0.1/items/5?q=somequery (or equivalent, using your Docker host). You will see something like: @@ -126,25 +123,22 @@ You will see something like: {"item_id": 5, "q": "somequery"} ``` - ### Interactive API docs -Now you can go to http://192.168.99.100/docs or http://127.0.0.1/docs (or equivalent, using your Docker host). +Now you can go to http://192.168.99.100/docs or http://127.0.0.1/docs (or equivalent, using your Docker host). -You will see the automatic interactive API documentation (provided by Swagger UI): +You will see the automatic interactive API documentation (provided by Swagger UI): ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) - ### Alternative API docs -And you can also go to http://192.168.99.100/redoc or http://127.0.0.1/redoc (or equivalent, using your Docker host). +And you can also go to http://192.168.99.100/redoc or http://127.0.0.1/redoc (or equivalent, using your Docker host). -You will see the alternative automatic documentation (provided by ReDoc): +You will see the alternative automatic documentation (provided by ReDoc): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) - ## HTTPS ### About HTTPS @@ -156,7 +150,7 @@ But it is way more complex than that. !!! tip If you are in a hurry or don't care, continue with the next section for step by step instructions to set everything up. -To learn the basics of HTTPS, from a consumer perspective, check https://howhttps.works/. +To learn the basics of HTTPS, from a consumer perspective, check https://howhttps.works/. Now, from a developer's perspective, here are several things to have in mind while thinking about HTTPS: @@ -174,15 +168,13 @@ Now, from a developer's perspective, here are several things to have in mind whi * By default, that would mean that you can only have one HTTPS certificate per IP address. * No matter how big your server is or how small each application you have on it might be. * There is a solution to this, however. -* There's an extension to the TLS protocol (the one handling the encryption at the TCP level, before HTTP) called SNI. +* There's an extension to the TLS protocol (the one handling the encryption at the TCP level, before HTTP) called SNI. * This SNI extension allows one single server (with a single IP address) to have several HTTPS certificates and serve multiple HTTPS domains/applications. * For this to work, a single component (program) running on the server, listening on the public IP address, must have all the HTTPS certificates in the server. * After obtaining a secure connection, the communication protocol is still HTTP. * The contents are encrypted, even though they are being sent with the HTTP protocol. - -It is a common practice to have one program/HTTP server running on the server (the machine, host, etc.) and managing all the HTTPS parts : sending the decrypted HTTP requests to the actual HTTP application running in the same server (the **FastAPI** application, in this case), take the HTTP response from the application, encrypt it using the appropriate certificate and sending it back to the client using HTTPS. This server is often called a TLS Termination Proxy. - +It is a common practice to have one program/HTTP server running on the server (the machine, host, etc.) and managing all the HTTPS parts : sending the decrypted HTTP requests to the actual HTTP application running in the same server (the **FastAPI** application, in this case), take the HTTP response from the application, encrypt it using the appropriate certificate and sending it back to the client using HTTPS. This server is often called a TLS Termination Proxy. ### Let's Encrypt @@ -190,7 +182,7 @@ Before Let's Encrypt, these HTTPS certificates were sold by trusted third-partie The process to acquire one of these certificates used to be cumbersome, require quite some paperwork and the certificates were quite expensive. -But then Let's Encrypt was created. +But then Let's Encrypt was created. It is a project from the Linux Foundation. It provides HTTPS certificates for free. In an automated way. These certificates use all the standard cryptographic security, and are short lived (about 3 months), so the security is actually better because of their reduced lifespan. @@ -198,10 +190,9 @@ The domains are securely verified and the certificates are generated automatical The idea is to automate the acquisition and renewal of these certificates, so that you can have secure HTTPS, for free, forever. - ### Traefik -Traefik is a high performance reverse proxy / load balancer. It can do the "TLS Termination Proxy" job (apart from other features). +Traefik is a high performance reverse proxy / load balancer. It can do the "TLS Termination Proxy" job (apart from other features). It has integration with Let's Encrypt. So, it can handle all the HTTPS parts, including certificate acquisition and renewal. @@ -211,7 +202,6 @@ It also has integrations with Docker. So, you can declare your domains in each a With this information and tools, continue with the next section to combine everything. - ## Docker Swarm mode cluster with Traefik and HTTPS You can have a Docker Swarm mode cluster set up in minutes (about 20 min) with a main Traefik handling HTTPS (including certificate acquisition and renewal). @@ -220,8 +210,7 @@ By using Docker Swarm mode, you can start with a "cluster" of a single machine ( To set up a Docker Swarm Mode cluster with Traefik and HTTPS handling, follow this guide: -### Docker Swarm Mode and Traefik for an HTTPS cluster. - +### Docker Swarm Mode and Traefik for an HTTPS cluster ### Deploy a FastAPI application @@ -233,20 +222,19 @@ You can generate a project in about 2 min. The generated project has instructions to deploy it, doing it takes another 2 min. - ## Alternatively, deploy **FastAPI** without Docker You can deploy **FastAPI** directly without Docker too. You just need to install an ASGI compatible server like: -* Uvicorn, a lightning-fast ASGI server, built on uvloop and httptools. +* Uvicorn, a lightning-fast ASGI server, built on uvloop and httptools. ```bash pip install uvicorn ``` -* Hypercorn, an ASGI server also compatible with HTTP/2. +* Hypercorn, an ASGI server also compatible with HTTP/2. ```bash pip install hypercorn @@ -268,7 +256,7 @@ hypercorn main:app --bind 0.0.0.0:80 You might want to set up some tooling to make sure it is restarted automatically if it stops. -You might also want to install Gunicorn and use it as a manager for Uvicorn, or use Hypercorn with multiple workers. +You might also want to install Gunicorn and use it as a manager for Uvicorn, or use Hypercorn with multiple workers. Making sure to fine-tune the number of workers, etc. diff --git a/docs/external-links.md b/docs/external-links.md index 9b8476425..73648c88f 100644 --- a/docs/external-links.md +++ b/docs/external-links.md @@ -5,103 +5,103 @@ There are many posts, articles, tools, and projects, related to **FastAPI**. Here's an incomplete list of some of them. !!! tip - If you have an article, project, tool, or anything related to **FastAPI** that is not yet listed here, create a [Pull Request adding it](https://github.com/tiangolo/fastapi/edit/master/docs/external-links.md){.external-link target=_blank}. + If you have an article, project, tool, or anything related to **FastAPI** that is not yet listed here, create a Pull Request adding it. ## Articles ### English -* [FastAPI/Starlette debug vs prod](https://medium.com/@williamhayes/fastapi-starlette-debug-vs-prod-5f7561db3a59){.external-link target=_blank} by [William Hayes](https://medium.com/@williamhayes){.external-link target=_blank}. +* FastAPI/Starlette debug vs prod by William Hayes. -* [FastAPI — Google as an external authentication provider](https://medium.com/data-rebels/fastapi-google-as-an-external-authentication-provider-3a527672cf33){.external-link target=_blank} by [Nils de Bruin](https://medium.com/@nils_29588){.external-link target=_blank}. +* FastAPI — Google as an external authentication provider by Nils de Bruin. -* [FastAPI — How to add basic and cookie authentication](https://medium.com/data-rebels/fastapi-how-to-add-basic-and-cookie-authentication-a45c85ef47d3){.external-link target=_blank} by [Nils de Bruin](https://medium.com/@nils_29588){.external-link target=_blank}. +* FastAPI — How to add basic and cookie authentication by Nils de Bruin. -* [Introduction to the fastapi python framework](https://dev.to/errietta/introduction-to-the-fastapi-python-framework-2n10){.external-link target=_blank} by [Errieta Kostala](https://dev.to/errietta){.external-link target=_blank}. +* Introduction to the fastapi python framework by Errieta Kostala. -* [FastAPI and Scikit-Learn: Easily Deploy Models](http://nickc1.github.io/api,/scikit-learn/2019/01/10/scikit-fastapi.html){.external-link target=_blank} by [Nick Cortale](http://nickc1.github.io/){.external-link target=_blank}. +* FastAPI and Scikit-Learn: Easily Deploy Models by Nick Cortale. -* [FastAPI authentication revisited: Enabling API key authentication](https://medium.com/data-rebels/fastapi-authentication-revisited-enabling-api-key-authentication-122dc5975680){.external-link target=_blank} by [Nils de Bruin](https://medium.com/@nils_29588){.external-link target=_blank}. +* FastAPI authentication revisited: Enabling API key authentication by Nils de Bruin. -* [FastAPI, a simple use case on logging](https://blog.bartab.fr/fastapi-logging-on-the-fly/){.external-link target=_blank} by [@euri10](https://blog.bartab.fr/){.external-link target=_blank}. +* FastAPI, a simple use case on logging by @euri10. -* [Deploying a scikit-learn model with ONNX and FastAPI](https://medium.com/@nico.axtmann95/deploying-a-scikit-learn-model-with-onnx-und-fastapi-1af398268915){.external-link target=_blank} by [Nico Axtmann](https://www.linkedin.com/in/nico-axtmann){.external-link target=_blank}. +* Deploying a scikit-learn model with ONNX and FastAPI by Nico Axtmann. -* [Top 5 Asynchronous Web Frameworks for Python](https://geekflare.com/python-asynchronous-web-frameworks/){.external-link target=_blank} by [Ankush Thakur](https://geekflare.com/author/ankush/){.external-link target=_blank} on [GeekFlare](https://geekflare.com){.external-link target=_blank}. +* Top 5 Asynchronous Web Frameworks for Python by Ankush Thakur on GeekFlare. -* [JWT Authentication with FastAPI and AWS Cognito](https://medium.com/@gntrm/jwt-authentication-with-fastapi-and-aws-cognito-1333f7f2729e){.external-link target=_blank} by [Johannes Gontrum](https://twitter.com/gntrm){.external-link target=_blank}. +* JWT Authentication with FastAPI and AWS Cognito by Johannes Gontrum. -* [How to Deploy a Machine Learning Model](https://towardsdatascience.com/how-to-deploy-a-machine-learning-model-dc51200fe8cf){.external-link target=_blank} by [Maarten Grootendorst](https://www.linkedin.com/in/mgrootendorst/){.external-link target=_blank} on [Towards Data Science](https://towardsdatascience.com/){.external-link target=_blank}. +* How to Deploy a Machine Learning Model by Maarten Grootendorst on Towards Data Science. -* [Uber: Ludwig v0.2 Adds New Features and Other Improvements to its Deep Learning Toolbox [including a FastAPI server]](https://eng.uber.com/ludwig-v0-2/){.external-link target=_blank} on [Uber Engineering](https://eng.uber.com){.external-link target=_blank}. +* [Uber: Ludwig v0.2 Adds New Features and Other Improvements to its Deep Learning Toolbox [including a FastAPI server]](https://eng.uber.com/ludwig-v0-2/){.external-link target=_blank} on Uber Engineering. -* [A FastAPI and Swagger UI visual cheatsheet](https://gitlab.com/euri10/fastapi_cheatsheet){.external-link target=_blank} by [@euri10](https://gitlab.com/euri10){.external-link target=_blank} +* A FastAPI and Swagger UI visual cheatsheet by @euri10 -* [Using Docker Compose to deploy a lightweight Python REST API with a job queue](https://medium.com/@mike.p.moritz/using-docker-compose-to-deploy-a-lightweight-python-rest-api-with-a-job-queue-37e6072a209b){.external-link target=_blank} by [Mike Moritz](https://medium.com/@mike.p.moritz){.external-link target=_blank}. +* Using Docker Compose to deploy a lightweight Python REST API with a job queue by Mike Moritz. -* [Setting up Tortoise ORM with FastAPI](https://robwagner.dev/tortoise-fastapi-setup/){.external-link target=_blank} by [Rob Wagner](https://robwagner.dev/){.external-link target=_blank}. +* Setting up Tortoise ORM with FastAPI by Rob Wagner. -* [Why I'm Leaving Flask](https://dev.to/dbanty/why-i-m-leaving-flask-3ki6){.external-link target=_blank} by [Dylan Anthony](https://dev.to/dbanty){.external-link target=_blank}. +* Why I'm Leaving Flask by Dylan Anthony. -* [How To Deploy Tensorflow 2.0 Models As An API Service With FastAPI & Docker](https://medium.com/python-data/how-to-deploy-tensorflow-2-0-models-as-an-api-service-with-fastapi-docker-128b177e81f3){.external-link target=_blank} by [Bernard Brenyah](https://medium.com/@bbrenyah){.external-link target=_blank}. +* How To Deploy Tensorflow 2.0 Models As An API Service With FastAPI & Docker by Bernard Brenyah. -* [TestDriven.io: Developing and Testing an Asynchronous API with FastAPI and Pytest](https://testdriven.io/blog/fastapi-crud/){.external-link target=_blank} by [Michael Herman](https://testdriven.io/authors/herman/){.external-link target=_blank}. +* TestDriven.io: Developing and Testing an Asynchronous API with FastAPI and Pytest by Michael Herman. -* [Towards Data Science: Deploying Iris Classifications with FastAPI and Docker](https://towardsdatascience.com/deploying-iris-classifications-with-fastapi-and-docker-7c9b83fdec3a){.external-link target=_blank} by [Mandy Gu](https://towardsdatascience.com/@mandygu){.external-link target=_blank}. +* Towards Data Science: Deploying Iris Classifications with FastAPI and Docker by Mandy Gu. -* [Deploy Machine Learning Models with Keras, FastAPI, Redis and Docker](https://medium.com/analytics-vidhya/deploy-machine-learning-models-with-keras-fastapi-redis-and-docker-4940df614ece){.external-link target=_blank} by [Shane Soh](https://medium.com/@shane.soh){.external-link target=_blank}. +* Deploy Machine Learning Models with Keras, FastAPI, Redis and Docker by Shane Soh. -* [Another Boilerplate to FastAPI: Azure Pipeline CI + Pytest](https://medium.com/@arthur393/another-boilerplate-to-fastapi-azure-pipeline-ci-pytest-3c8d9a4be0bb){target=_blank} by [Arthur Henrique](https://twitter.com/arthurheinrique){target=_blank}. +* Another Boilerplate to FastAPI: Azure Pipeline CI + Pytest by Arthur Henrique. ### Japanese -* [FastAPI｜DB接続してCRUDするPython製APIサーバーを構築](https://qiita.com/mtitg/items/47770e9a562dd150631d){.external-link target=_blank} by [@mtitg](https://qiita.com/mtitg){.external-link target=_blank}. +* FastAPI｜DB接続してCRUDするPython製APIサーバーを構築 by @mtitg. -* [python製の最新APIフレームワーク FastAPI を触ってみた](https://qiita.com/ryoryomaru/items/59958ed385b3571d50de){.external-link target=_blank} by [@ryoryomaru](https://qiita.com/ryoryomaru){.external-link target=_blank}. +* python製の最新APIフレームワーク FastAPI を触ってみた by @ryoryomaru. -* [FastAPIでCORSを回避](https://qiita.com/angel_katayoku/items/0e1f5dbbe62efc612a78){.external-link target=_blank} by [@angel_katayoku](https://qiita.com/angel_katayoku){.external-link target=_blank}. +* FastAPIでCORSを回避 by @angel_katayoku. -* [FastAPIをMySQLと接続してDockerで管理してみる](https://qiita.com/angel_katayoku/items/4fbc1a4e2b33fa2237d2){.external-link target=_blank} by [@angel_katayoku](https://qiita.com/angel_katayoku){.external-link target=_blank}. +* FastAPIをMySQLと接続してDockerで管理してみる by @angel_katayoku. -* [FastAPIでPOSTされたJSONのレスポンスbodyを受け取る](https://qiita.com/angel_katayoku/items/8a458a8952f50b73f420){.external-link target=_blank} by [@angel_katayoku](https://qiita.com/angel_katayoku){.external-link target=_blank}. +* FastAPIでPOSTされたJSONのレスポンスbodyを受け取る by @angel_katayoku. -* [フロントエンド開発者向けのDockerによるPython開発環境構築](https://qiita.com/hikarut/items/b178af2e2440c67c6ac4){.external-link target=_blank} by [Hikaru Takahashi](https://qiita.com/hikarut){.external-link target=_blank}. +* フロントエンド開発者向けのDockerによるPython開発環境構築 by Hikaru Takahashi. -* [【第1回】FastAPIチュートリアル: ToDoアプリを作ってみよう【環境構築編】](https://rightcode.co.jp/blog/information-technology/fastapi-tutorial-todo-apps-environment){.external-link target=_blank} by [ライトコードメディア編集部](https://rightcode.co.jp/author/jun){.external-link target=_blank} +* 【第1回】FastAPIチュートリアル: ToDoアプリを作ってみよう【環境構築編】 by ライトコードメディア編集部 -* [【第2回】FastAPIチュートリアル: ToDoアプリを作ってみよう【モデル構築編】](https://rightcode.co.jp/blog/information-technology/fastapi-tutorial-todo-apps-model-building){.external-link target=_blank} by [ライトコードメディア編集部](https://rightcode.co.jp/author/jun){.external-link target=_blank} +* 【第2回】FastAPIチュートリアル: ToDoアプリを作ってみよう【モデル構築編】 by ライトコードメディア編集部 -* [【第3回】FastAPIチュートリアル: toDoアプリを作ってみよう【認証・ユーザ登録編】](https://rightcode.co.jp/blog/information-technology/fastapi-tutorial-todo-apps-authentication-user-registration){.external-link target=_blank} by [ライトコードメディア編集部](https://rightcode.co.jp/author/jun){.external-link target=_blank} +* 【第3回】FastAPIチュートリアル: toDoアプリを作ってみよう【認証・ユーザ登録編】 by ライトコードメディア編集部 -* [【第4回】FastAPIチュートリアル: toDoアプリを作ってみよう【管理者ページ改良編】](https://rightcode.co.jp/blog/information-technology/fastapi-tutorial-todo-apps-admin-page-improvement){.external-link target=_blank} by [ライトコードメディア編集部](https://rightcode.co.jp/author/jun){.external-link target=_blank} +* 【第4回】FastAPIチュートリアル: toDoアプリを作ってみよう【管理者ページ改良編】 by ライトコードメディア編集部 ### Chinese -* [使用FastAPI框架快速构建高性能的api服务](https://cloud.tencent.com/developer/article/1431448){.external-link target=_blank} by [逍遥散人](https://cloud.tencent.com/developer/user/5471722){.external-link target=_blank}. +* 使用FastAPI框架快速构建高性能的api服务 by 逍遥散人. -* [FastAPI框架中文文档](https://wxq0309.github.io/){.external-link target=_blank} by [何大仙](https://wxq0309.github.io/){.external-link target=_blank}. +* FastAPI框架中文文档 by 何大仙. ### Vietnamese -* [FASTAPI: TRIỂN KHAI BẰNG DOCKER](https://fullstackstation.com/fastapi-trien-khai-bang-docker/){.external-link target=_blank} by [Nguyễn Nhân](https://fullstackstation.com/author/figonking/){.external-link target=_blank}. +* FASTAPI: TRIỂN KHAI BẰNG DOCKER by Nguyễn Nhân. ### Russian -* [Мелкая питонячая радость #2: Starlette - Солидная примочка – FastAPI](https://habr.com/ru/post/454440/){.external-link target=_blank} by [Andrey Korchak](https://habr.com/ru/users/57uff3r/){.external-link target=_blank}. +* Мелкая питонячая радость #2: Starlette - Солидная примочка – FastAPI by Andrey Korchak. -* [Почему Вы должны попробовать FastAPI?](https://habr.com/ru/post/478620/){.external-link target=_blank} by [prostomarkeloff](https://github.com/prostomarkeloff){.external-link target=_blank}. +* Почему Вы должны попробовать FastAPI? by prostomarkeloff. ### German -* [Inbetriebnahme eines scikit-learn-Modells mit ONNX und FastAPI](https://blog.codecentric.de/2019/08/inbetriebnahme-eines-scikit-learn-modells-mit-onnx-und-fastapi/){.external-link target=_blank} by [Nico Axtmann](https://twitter.com/_nicoax){.external-link target=_blank}. +* Inbetriebnahme eines scikit-learn-Modells mit ONNX und FastAPI by Nico Axtmann. ## Podcasts -* [FastAPI on PythonBytes](https://pythonbytes.fm/episodes/show/123/time-to-right-the-py-wrongs?time_in_sec=855){.external-link target=_blank} by [Python Bytes FM](https://pythonbytes.fm/){.external-link target=_blank}. +* FastAPI on PythonBytes by Python Bytes FM. ## Talks -* [PyCon UK 2019: FastAPI from the ground up](https://www.youtube.com/watch?v=3DLwPcrE5mA){.external-link target=_blank} by [Chris Withers](https://twitter.com/chriswithers13){.external-link target=_blank}. +* PyCon UK 2019: FastAPI from the ground up by Chris Withers. ## Projects diff --git a/docs/features.md b/docs/features.md index 6ced5fe38..cddff7b70 100644 --- a/docs/features.md +++ b/docs/features.md @@ -5,8 +5,8 @@ ### Based on open standards -* OpenAPI for API creation, including declarations of path operations, parameters, body requests, security, etc. -* Automatic data model documentation with JSON Schema (as OpenAPI itself is based on JSON Schema). +* OpenAPI for API creation, including declarations of path operations, parameters, body requests, security, etc. +* Automatic data model documentation with JSON Schema (as OpenAPI itself is based on JSON Schema). * Designed around these standards, after a meticulous study. Instead of an afterthought layer on top. * This also allows using automatic **client code generation** in many languages. @@ -14,15 +14,14 @@ Interactive API documentation and exploration web user interfaces. As the framework is based on OpenAPI, there are multiple options, 2 included by default. -* Swagger UI, with interactive exploration, call and test your API directly from the browser. +* Swagger UI, with interactive exploration, call and test your API directly from the browser. ![Swagger UI interaction](img/index/index-03-swagger-02.png) -* Alternative API documentation with ReDoc. +* Alternative API documentation with ReDoc. ![ReDoc](img/index/index-06-redoc-02.png) - ### Just Modern Python It's all based on standard **Python 3.6 type** declarations (thanks to Pydantic). No new syntax to learn. Just standard modern Python. @@ -66,14 +65,14 @@ my_second_user: User = User(**second_user_data) !!! info `**second_user_data` means: - + Pass the keys and values of the `second_user_data` dict directly as key-value arguments, equivalent to: `User(id=4, name="Mary", joined="2018-11-30")` ### Editor support All the framework was designed to be easy and intuitive to use, all the decisions where tested on multiple editors even before starting development, to ensure the best development experience. -In the last Python developer survey it was clear that the most used feature is "autocompletion". +In the last Python developer survey it was clear that the most used feature is "autocompletion". The whole **FastAPI** framework is based to satisfy that. Autocompletion works everywhere. @@ -81,11 +80,11 @@ You will rarely need to come back to the docs. Here's how your editor might help you: -* in Visual Studio Code: +* in Visual Studio Code: ![editor support](img/vscode-completion.png) -* in PyCharm: +* in PyCharm: ![editor support](img/pycharm-completion.png) @@ -128,7 +127,7 @@ All the security schemes defined in OpenAPI, including: * Query parameters. * Cookies, etc. -Plus all the security features from Starlette (including **session cookies**). +Plus all the security features from Starlette (including **session cookies**). All built as reusable tools and components that are easy to integrate with your systems, data stores, relational and NoSQL databases, etc. @@ -143,14 +142,12 @@ FastAPI includes an extremely easy to use, but extremely powerful one of the fastest Python frameworks available, on par with **NodeJS** and **Go**. +* Seriously impressive performance. It is one of the fastest Python frameworks available, on par with **NodeJS** and **Go**. * **WebSocket** support. * **GraphQL** support. * In-process background tasks. @@ -178,7 +175,7 @@ With **FastAPI** you get all of **Starlette**'s features (as FastAPI is just Sta ## Pydantic features -**FastAPI** is fully compatible with (and based on) Pydantic. So, any additional Pydantic code you have, will also work. +**FastAPI** is fully compatible with (and based on) Pydantic. So, any additional Pydantic code you have, will also work. Including external libraries also based on Pydantic, as ORMs, ODMs for databases. @@ -188,13 +185,13 @@ The same applies the other way around, in many cases you can just pass the objec With **FastAPI** you get all of **Pydantic**'s features (as FastAPI is based on Pydantic for all the data handling): -* **No brainfuck**: +* **No brainfuck**: * No new schema definition micro-language to learn. * If you know Python types you know how to use Pydantic. * Plays nicely with your **IDE/linter/brain**: * Because pydantic data structures are just instances of classes you define; auto-completion, linting, mypy and your intuition should all work properly with your validated data. * **Fast**: - * in benchmarks Pydantic is faster than all other tested libraries. + * in benchmarks Pydantic is faster than all other tested libraries. * Validate **complex structures**: * Use of hierarchical Pydantic models, Python `typing`’s `List` and `Dict`, etc. * And validators allow complex data schemas to be clearly and easily defined, checked and documented as JSON Schema. diff --git a/docs/help-fastapi.md b/docs/help-fastapi.md index f029d0aa3..bb13d94a3 100644 --- a/docs/help-fastapi.md +++ b/docs/help-fastapi.md @@ -8,17 +8,15 @@ There are very simple ways to help (several involve just one or two clicks). And there are several ways to get help too. - ## Star **FastAPI** in GitHub -You can "star" FastAPI in GitHub (clicking the star button at the top right): https://github.com/tiangolo/fastapi. +You can "star" FastAPI in GitHub (clicking the star button at the top right): https://github.com/tiangolo/fastapi. By adding a star, other users will be able to find it more easily and see that it has been already useful for others. - ## Watch the GitHub repository for releases -You can "watch" FastAPI in GitHub (clicking the "watch" button at the top right): https://github.com/tiangolo/fastapi. +You can "watch" FastAPI in GitHub (clicking the "watch" button at the top right): https://github.com/tiangolo/fastapi. There you can select "Releases only". @@ -30,33 +28,32 @@ Doing it, you will receive notifications (in your email) whenever there's a new Join the chat at https://gitter.im/tiangolo/fastapi -Join the chat on Gitter: https://gitter.im/tiangolo/fastapi. +Join the chat on Gitter: https://gitter.im/tiangolo/fastapi. There you can ask quick questions, help others, share ideas, etc. ## Connect with the author -You can connect with me (Sebastián Ramírez / `tiangolo`), the author. +You can connect with me (Sebastián Ramírez / `tiangolo`), the author. You can: -* Follow me on **GitHub**. +* Follow me on **GitHub**. * See other Open Source projects I have created that could help you. * Follow me to see when I create a new Open Source project. -* Follow me on **Twitter**. +* Follow me on **Twitter**. * Tell me how you use FastAPI (I love to hear that). * Ask questions. -* Connect with me on **Linkedin**. +* Connect with me on **Linkedin**. * Talk to me. * Endorse me or recommend me :) -* Read what I write (or follow me) on **Medium**. +* Read what I write (or follow me) on **Medium**. * Read other ideas, articles and tools I have created. * Follow me to see when I publish something new. - ## Tweet about **FastAPI** -Tweet about **FastAPI** and let me and others know why you like it. +Tweet about **FastAPI** and let me and others know why you like it. ## Let me know how are you using **FastAPI** @@ -64,22 +61,22 @@ I love to hear about how **FastAPI** is being used, what have you liked in it, i You can let me know: -* On **Twitter**. -* On **Linkedin**. -* On **Medium**. +* On **Twitter**. +* On **Linkedin**. +* On **Medium**. ## Vote for FastAPI -* Vote to include **FastAPI** in `awesome-python`. -* Vote for **FastAPI** in Slant. +* Vote to include **FastAPI** in `awesome-python`. +* Vote for **FastAPI** in Slant. ## Help others with issues in GitHub -You can see existing issues and try and help others. +You can see existing issues and try and help others. ## Watch the GitHub repository -You can "watch" FastAPI in GitHub (clicking the "watch" button at the top right): https://github.com/tiangolo/fastapi. +You can "watch" FastAPI in GitHub (clicking the "watch" button at the top right): https://github.com/tiangolo/fastapi. If you select "Watching" instead of "Releases only", you will receive notifications when someone creates a new issue. @@ -87,7 +84,7 @@ Then you can try and help them solving those issues. ## Create issues -You can create a new issue in the GitHub repository, for example to: +You can create a new issue in the GitHub repository, for example to: * Report a bug/issue. * Suggest a new feature. @@ -95,7 +92,7 @@ You can create a Pull Request, for example: +You can create a Pull Request, for example: * To fix a typo you found on the documentation. * To propose new documentation sections. diff --git a/docs/history-design-future.md b/docs/history-design-future.md index 88d081870..7f3ec8cf9 100644 --- a/docs/history-design-future.md +++ b/docs/history-design-future.md @@ -1,10 +1,9 @@ -Some time ago, a **FastAPI** user asked: +Some time ago, a **FastAPI** user asked: > What’s the history of this project? It seems to have come from nowhere to awesome in a few weeks [...] Here's a little bit of that history. - ## Alternatives I have been creating APIs with complex requirements for several years (Machine Learning, distributed systems, asynchronous jobs, NoSQL databases, etc), leading several teams of developers. @@ -27,7 +26,6 @@ But at some point, there was no other option than creating something that provid - ## Investigation By using all the previous alternatives I had the chance to learn from all of them, take ideas, and combine them in the best way I could find for myself and the teams of developers I have worked with. @@ -38,14 +36,13 @@ Also, the best approach was to use already existing standards. So, before even starting to code **FastAPI**, I spent several months studying the specs for OpenAPI, JSON Schema, OAuth2, etc. Understanding their relationship, overlap, and differences. - ## Design Then I spent some time designing the developer "API" I wanted to have as a user (as a developer using FastAPI). I tested several ideas in the most popular Python editors: PyCharm, VS Code, Jedi based editors. -By the last Python Developer Survey, that covers about 80% of the users. +By the last Python Developer Survey, that covers about 80% of the users. It means that **FastAPI** was specifically tested with the editors used by 80% of the Python developers. And as most of the other editors tend to work similarly, all its benefits should work for virtually all editors. @@ -53,21 +50,18 @@ That way I could find the best ways to reduce code duplication as much as possib All in a way that provided the best development experience for all the developers. - ## Requirements -After testing several alternatives, I decided that I was going to use **Pydantic** for its advantages. +After testing several alternatives, I decided that I was going to use **Pydantic** for its advantages. 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**, the other key requirement. - +During the development, I also contributed to **Starlette**, the other key requirement. ## Development By the time I started creating **FastAPI** itself, most of the pieces were already in place, the design was defined, the requirements and tools were ready, and the knowledge about the standards and specifications was clear and fresh. - ## Future By this point, it's already clear that **FastAPI** with its ideas is being useful for many people. diff --git a/docs/index.md b/docs/index.md index cf94ea3ba..80b9a1938 100644 --- a/docs/index.md +++ b/docs/index.md @@ -39,7 +39,7 @@ The key features are: * **Easy**: Designed to be easy to use and learn. Less time reading docs. * **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs. * **Robust**: Get production-ready code. With automatic interactive documentation. -* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema. +* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema. * estimation based on tests on an internal development team, building production applications. @@ -83,9 +83,8 @@ Python 3.6+ FastAPI stands on the shoulders of giants: -* Starlette for the web parts. -* Pydantic for the data parts. - +* Starlette for the web parts. +* Pydantic for the data parts. ## Installation @@ -93,7 +92,7 @@ FastAPI stands on the shoulders of giants: pip install fastapi ``` -You will also need an ASGI server, for production such as Uvicorn or Hypercorn. +You will also need an ASGI server, for production such as Uvicorn or Hypercorn. ```bash pip install uvicorn @@ -120,6 +119,7 @@ def read_root(): def read_item(item_id: int, q: str = None): return {"item_id": item_id, "q": q} ``` +
Or use async def... @@ -142,7 +142,7 @@ async def read_item(item_id: int, q: str = None): ``` **Note**: - + If you don't know, check the _"In a hurry?"_ section about `async` and `await` in the docs.
@@ -168,7 +168,7 @@ The command `uvicorn main:app` refers to: ### Check it -Open your browser at http://127.0.0.1:8000/items/5?q=somequery. +Open your browser at http://127.0.0.1:8000/items/5?q=somequery. You will see the JSON response as: @@ -185,18 +185,17 @@ You already created an API that: ### Interactive API docs -Now go to http://127.0.0.1:8000/docs. +Now go to http://127.0.0.1:8000/docs. -You will see the automatic interactive API documentation (provided by Swagger UI): +You will see the automatic interactive API documentation (provided by Swagger UI): ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) - ### Alternative API docs -And now, go to http://127.0.0.1:8000/redoc. +And now, go to http://127.0.0.1:8000/redoc. -You will see the alternative automatic documentation (provided by ReDoc): +You will see the alternative automatic documentation (provided by ReDoc): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -238,7 +237,7 @@ The server should reload automatically (because you added `--reload` to the `uvi ### Interactive API docs upgrade -Now go to http://127.0.0.1:8000/docs. +Now go to http://127.0.0.1:8000/docs. * The interactive API documentation will be automatically updated, including the new body: @@ -252,16 +251,14 @@ Now go to http://127.0.0.1: ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-05-swagger-04.png) - ### Alternative API docs upgrade -And now, go to http://127.0.0.1:8000/redoc. +And now, go to http://127.0.0.1:8000/redoc. * The alternative documentation will also reflect the new query parameter and body: ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) - ### Recap In summary, you declare **once** the types of parameters, body, etc. as function parameters. @@ -331,7 +328,6 @@ Coming back to the previous code example, **FastAPI** will: * Automatic client code generation systems, for many languages. * Provide 2 interactive documentation web interfaces directly. - --- We just scratched the surface, but you already get the idea of how it all works. @@ -358,7 +354,6 @@ Try changing the line with: ![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) - For a more complete example including more features, see the Tutorial - User Guide. **Spoiler alert**: the tutorial - user guide includes: @@ -376,10 +371,9 @@ For a more complete example including more features, see the one of the fastest Python frameworks available, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*) +Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as one of the fastest Python frameworks available, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*) To understand more about it, see the section Benchmarks. @@ -390,7 +384,6 @@ Used by Pydantic: * ujson - for faster JSON "parsing". * email_validator - for email validation. - Used by Starlette: * requests - Required if you want to use the `TestClient`. @@ -398,7 +391,7 @@ Used by Starlette: * jinja2 - Required if you want to use the default template configuration. * python-multipart - Required if you want to support form "parsing", with `request.form()`. * itsdangerous - Required for `SessionMiddleware` support. -* pyyaml - Required for `SchemaGenerator` support. +* pyyaml - Required for Starlette's `SchemaGenerator` support (you probably don't need it with FastAPI). * graphene - Required for `GraphQLApp` support. * ujson - Required if you want to use `UJSONResponse`. diff --git a/docs/project-generation.md b/docs/project-generation.md index 569d17300..9dc0aa0f6 100644 --- a/docs/project-generation.md +++ b/docs/project-generation.md @@ -1,11 +1,10 @@ There is a project generator that you can use to get started, with a lot of the initial set up, security, database and first API endpoints already done for you. - ## Full-Stack-FastAPI-PostgreSQL -GitHub: https://github.com/tiangolo/full-stack-fastapi-postgresql +GitHub: https://github.com/tiangolo/full-stack-fastapi-postgresql -### Features +### Full-Stack-FastAPI-PostgreSQL Features * Full **Docker** integration (Docker based). * Docker Swarm Mode deployment. @@ -17,7 +16,7 @@ GitHub: OpenAPI and JSON Schema. + * **Standards-based**: Based on (and fully compatible with) the open standards for APIs: OpenAPI and JSON Schema. * [**Many other features**](https://github.com/tiangolo/fastapi) including automatic validation, serialization, interactive documentation, authentication with OAuth2 JWT tokens, etc. * **Secure password** hashing by default. * **JWT token** authentication. @@ -49,13 +48,11 @@ GitHub: https://github.com/tiangolo/full-stack-fastapi-couchbase +GitHub: https://github.com/tiangolo/full-stack-fastapi-couchbase -### Features +### Full-Stack-FastAPI-Couchbase Features * Full **Docker** integration (Docker based). * Docker Swarm Mode deployment. @@ -67,7 +64,7 @@ GitHub: OpenAPI and JSON Schema. + * **Standards-based**: OpenAPI and JSON Schema. * [**Many other features**](https://github.com/tiangolo/fastapi) including automatic validation, serialization, interactive documentation, authentication with OAuth2 JWT tokens, etc. * **Secure password** hashing by default. * **JWT token** authentication. diff --git a/docs/python-types.md b/docs/python-types.md index acaf1303e..175e0e3aa 100644 --- a/docs/python-types.md +++ b/docs/python-types.md @@ -238,7 +238,7 @@ And then, again, you get all the editor support: ## Pydantic models -Pydantic is a Python library to perform data validation. +Pydantic is a Python library to perform data validation. You declare the "shape" of the data as classes with attributes. @@ -255,7 +255,7 @@ Taken from the official Pydantic docs: ``` !!! info - To learn more about Pydantic, check its docs. + To learn more about Pydantic, check its docs. **FastAPI** is all based on Pydantic. @@ -285,4 +285,4 @@ This might all sound abstract. Don't worry. You'll see all this in action in the The important thing is that by using standard Python types, in a single place (instead of adding more classes, decorators, etc), **FastAPI** will do a lot of the work for you. !!! info - If you already went through all the tutorial and came back to see more about types, a good resource is the "cheat sheet" from `mypy`. \ No newline at end of file + If you already went through all the tutorial and came back to see more about types, a good resource is the "cheat sheet" from `mypy`. diff --git a/docs/tutorial/additional-responses.md b/docs/tutorial/additional-responses.md index 15ff23d6d..71c4cf61d 100644 --- a/docs/tutorial/additional-responses.md +++ b/docs/tutorial/additional-responses.md @@ -1,6 +1,6 @@ !!! warning This is a rather advanced topic. - + If you are starting with **FastAPI**, you might not need this. You can declare additional responses, with additional status codes, media types, descriptions, etc. @@ -21,7 +21,6 @@ Each of those response `dict`s can have a key `model`, containing a Pydantic mod For example, to declare another response with a status code `404` and a Pydantic model `Message`, you can write: - ```Python hl_lines="18 23" {!./src/additional_responses/tutorial001.py!} ``` @@ -199,7 +198,6 @@ It will all be combined and included in your OpenAPI, and shown in the API docs: - ## Combine predefined responses and custom ones You might want to have some predefined responses that apply to many *path operations*, but you want to combine them with custom responses needed by each *path operation*. @@ -236,5 +234,5 @@ For example: To see what exactly you can include in the responses, you can check these sections in the OpenAPI specification: -* OpenAPI Responses Object, it includes the `Response Object`. -* OpenAPI Response Object, you can include anything from this directly in each response inside your `responses` parameter. Including `description`, `headers`, `content` (inside of this is that you declare different media types and JSON Schemas), and `links`. +* OpenAPI Responses Object, it includes the `Response Object`. +* OpenAPI Response Object, you can include anything from this directly in each response inside your `responses` parameter. Including `description`, `headers`, `content` (inside of this is that you declare different media types and JSON Schemas), and `links`. diff --git a/docs/tutorial/async-sql-databases.md b/docs/tutorial/async-sql-databases.md index 5f75bce7d..e8cd3724f 100644 --- a/docs/tutorial/async-sql-databases.md +++ b/docs/tutorial/async-sql-databases.md @@ -1,4 +1,4 @@ -You can also use `encode/databases` with **FastAPI** to connect to databases using `async` and `await`. +You can also use `encode/databases` with **FastAPI** to connect to databases using `async` and `await`. It is compatible with: @@ -13,7 +13,7 @@ Later, for your production application, you might want to use a database server !!! tip You could adopt ideas from the previous section about SQLAlchemy ORM, like using utility functions to perform operations in the database, independent of your **FastAPI** code. - This section doesn't apply those ideas, to be equivalent to the counterpart in Starlette. + This section doesn't apply those ideas, to be equivalent to the counterpart in Starlette. ## Import and set up `SQLAlchemy` @@ -149,7 +149,7 @@ So, the final result returned would be something like: ## Check it -You can copy this code as is, and see the docs at http://127.0.0.1:8000/docs. +You can copy this code as is, and see the docs at http://127.0.0.1:8000/docs. There you can see all your API documented and interact with it: @@ -157,4 +157,4 @@ There you can see all your API documented and interact with it: ## More info -You can read more about `encode/databases` at its GitHub page. +You can read more about `encode/databases` at its GitHub page. diff --git a/docs/tutorial/background-tasks.md b/docs/tutorial/background-tasks.md index 2181497e3..1b50dd423 100644 --- a/docs/tutorial/background-tasks.md +++ b/docs/tutorial/background-tasks.md @@ -22,7 +22,6 @@ First, import `BackgroundTasks` and define a parameter in your *path operation f !!! tip You declare a parameter of `BackgroundTasks` and use it in a very similar way as to when using the `Request` directly. - ## Create a task function Create a function to be run as the background task. @@ -31,7 +30,7 @@ It is just a standard function that can receive parameters. It can be an `async def` or normal `def` function, **FastAPI** will know how to handle it correctly. -In this case, the task function will write to a file (simulating sending an email). +In this case, the task function will write to a file (simulating sending an email). And as the write operation doesn't use `async` and `await`, we define the function with normal `def`: @@ -71,7 +70,7 @@ And then another background task generated at the *path operation function* will ## Technical Details -The class `BackgroundTasks` comes directly from `starlette.background`. +The class `BackgroundTasks` comes directly from `starlette.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`. @@ -79,11 +78,11 @@ By only using `BackgroundTasks` (and not `BackgroundTask`), it's then possible t 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. +You can see more details in Starlette's official docs for Background Tasks. ## Caveat -If you need to perform heavy background computation and you don't necessarily need it to be run by the same process (for example, you don't need to share memory, variables, etc), you might benefit from using other bigger tools like Celery. +If you need to perform heavy background computation and you don't necessarily need it to be run by the same process (for example, you don't need to share memory, variables, etc), you might benefit from using other bigger tools like Celery. They tend to require more complex configurations, a message/job queue manager, like RabbitMQ or Redis, but they allow you to run background tasks in multiple processes, and especially, in multiple servers. diff --git a/docs/tutorial/bigger-applications.md b/docs/tutorial/bigger-applications.md index 54efb2b09..79156e5c9 100644 --- a/docs/tutorial/bigger-applications.md +++ b/docs/tutorial/bigger-applications.md @@ -44,7 +44,6 @@ Let's say you have a file structure like this: * The file `app/routers/users.py` is beside the `app/routers/__init__.py`. * So, it's a submodule: `app.routers.users`. - ## `APIRouter` Let's say the file dedicated to handling just users is the submodule at `/app/routers/users.py`. @@ -55,7 +54,6 @@ But it's still part of the same **FastAPI** application/web API (it's part of th You can create the *path operations* for that module using `APIRouter`. - ### Import `APIRouter` You import it and create an "instance" the same way you would with the class `FastAPI`: @@ -64,7 +62,6 @@ You import it and create an "instance" the same way you would with the class `Fa {!./src/bigger_applications/app/routers/users.py!} ``` - ### Path operations with `APIRouter` And then you use it to declare your *path operations*. @@ -86,7 +83,6 @@ All the same parameters, responses, dependencies, tags, etc. We are going to include this `APIrouter` in the main `FastAPI` app, but first, let's add another `APIRouter`. - ## Another module with `APIRouter` Let's say you also have the endpoints dedicated to handling "Items" from your application in the module at `app/routers/items.py`. @@ -144,7 +140,6 @@ We import the other submodules that have `APIRouter`s: As the file `app/routers/items.py` is part of the same Python package, we can import it using "dot notation". - ### How the importing works The section: @@ -172,7 +167,7 @@ from app.routers import items, users The second version is an "absolute import". - To learn more about Python Packages and Modules, read the official Python documentation about Modules. + To learn more about Python Packages and Modules, read the official Python documentation about Modules. ### Avoid name collisions @@ -301,7 +296,7 @@ Now, run `uvicorn`, using the module `app.main` and the variable `app`: uvicorn app.main:app --reload ``` -And open the docs at http://127.0.0.1:8000/docs. +And open the docs at http://127.0.0.1:8000/docs. You will see the automatic API docs, including the paths from all the submodules, using the correct paths (and prefixes) and the correct tags: diff --git a/docs/tutorial/body-fields.md b/docs/tutorial/body-fields.md index 08b854e55..fdb4ee533 100644 --- a/docs/tutorial/body-fields.md +++ b/docs/tutorial/body-fields.md @@ -11,7 +11,6 @@ First, you have to import it: !!! warning Notice that `Field` is imported directly from `pydantic`, not from `fastapi` as are all the rest (`Query`, `Path`, `Body`, etc). - ## Declare model attributes You can then use `Field` with model attributes: @@ -45,7 +44,7 @@ If you know JSON Schema and want to add extra information apart from what we hav !!! warning Have in mind that extra parameters passed won't add any validation, only annotation, for documentation purposes. -For example, you can use that functionality to pass a JSON Schema example field to a body request JSON Schema: +For example, you can use that functionality to pass a JSON Schema example field to a body request JSON Schema: ```Python hl_lines="20 21 22 23 24 25" {!./src/body_fields/tutorial002.py!} diff --git a/docs/tutorial/body-nested-models.md b/docs/tutorial/body-nested-models.md index 0ae699921..c70e5f3ff 100644 --- a/docs/tutorial/body-nested-models.md +++ b/docs/tutorial/body-nested-models.md @@ -116,7 +116,7 @@ Again, doing just that declaration, with **FastAPI** you get: Apart from normal singular types like `str`, `int`, `float`, etc. You can use more complex singular types that inherit from `str`. -To see all the options you have, checkout the docs for Pydantic's exotic types. You will see some examples in the next chapter. +To see all the options you have, checkout the docs for Pydantic's exotic types. You will see some examples in the next chapter. For example, as in the `Image` model we have a `url` field, we can declare it to be instead of a `str`, a Pydantic's `HttpUrl`: @@ -231,7 +231,7 @@ In this case, you would accept any `dict` as long as it has `int` keys with `flo ## Recap -With **FastAPI** you have the maximum flexibility provided by Pydantic models, while keeping your code simple, short and elegant. +With **FastAPI** you have the maximum flexibility provided by Pydantic models, while keeping your code simple, short and elegant. But with all the benefits: diff --git a/docs/tutorial/body-updates.md b/docs/tutorial/body-updates.md index 33880aad6..2d4961dd4 100644 --- a/docs/tutorial/body-updates.md +++ b/docs/tutorial/body-updates.md @@ -1,6 +1,6 @@ ## Update replacing with `PUT` -To update an item you can use the [HTTP `PUT`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) operation. +To update an item you can use the HTTP `PUT` operation. You can use the `jsonable_encoder` to convert the input data to data that can be stored as JSON (e.g. with a NoSQL database). For example, converting `datetime` to `str`. @@ -28,7 +28,7 @@ And the data would be saved with that "new" `tax` of `10.5`. ## Partial updates with `PATCH` -You can also use the [HTTP `PATCH`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) operation to *partially* update data. +You can also use the HTTP `PATCH` operation to *partially* update data. This means that you can send only the data that you want to update, leaving the rest intact. diff --git a/docs/tutorial/body.md b/docs/tutorial/body.md index d59700748..6cb95d0dc 100644 --- a/docs/tutorial/body.md +++ b/docs/tutorial/body.md @@ -4,7 +4,7 @@ A **request** body is data sent by the client to your API. A **response** body i Your API almost always has to send a **response** body. But clients don't necessarily need to send **request** bodies all the time. -To declare a **request** body, you use Pydantic models with all their power and benefits. +To declare a **request** body, you use Pydantic models with all their power and benefits. !!! info You cannot send a request body using a `GET` operation (HTTP method). @@ -71,7 +71,7 @@ With just that Python type declaration, **FastAPI** will: * If the data is invalid, it will return a nice and clear error, indicating exactly where and what was the incorrect data. * Give you the received data in the parameter `item`. * As you declared it in the function to be of type `Item`, you will also have all the editor support (completion, etc) for all of the attributes and their types. -* Generate JSON Schema definitions for your model, you can also use them anywhere else you like if it makes sense for your project. +* Generate JSON Schema definitions for your model, you can also use them anywhere else you like if it makes sense for your project. * Those schemas will be part of the generated OpenAPI schema, and used by the automatic documentation UIs. ## Automatic docs @@ -100,13 +100,12 @@ And it was thoroughly tested at the design phase, before any implementation, to There were even some changes to Pydantic itself to support this. -The previous screenshots were taken with Visual Studio Code. +The previous screenshots were taken with Visual Studio Code. -But you would get the same editor support with PyCharm and most of the other Python editors: +But you would get the same editor support with PyCharm and most of the other Python editors: - ## Use the model Inside of the function, you can access all the attributes of the model object directly: @@ -139,4 +138,4 @@ The function parameters will be recognized as follows: * If the parameter is also declared in the **path**, it will be used as a path parameter. * If the parameter is of a **singular type** (like `int`, `float`, `str`, `bool`, etc) it will be interpreted as a **query** parameter. -* If the parameter is declared to be of the type of a **Pydantic model**, it will be interpreted as a request **body**. \ No newline at end of file +* If the parameter is declared to be of the type of a **Pydantic model**, it will be interpreted as a request **body**. diff --git a/docs/tutorial/cors.md b/docs/tutorial/cors.md index d37822b4f..6e93354a2 100644 --- a/docs/tutorial/cors.md +++ b/docs/tutorial/cors.md @@ -1,4 +1,4 @@ -CORS or "Cross-Origin Resource Sharing" refers to the situations when a frontend running in a browser has JavaScript code that communicates with a backend, and the backend is in a different "origin" than the frontend. +CORS or "Cross-Origin Resource Sharing" refers to the situations when a frontend running in a browser has JavaScript code that communicates with a backend, and the backend is in a different "origin" than the frontend. ## Origin @@ -32,7 +32,7 @@ So, for everything to work correctly, it's better to specify explicitly the allo ## Use `CORSMiddleware` -You can configure it in your **FastAPI** application using Starlette's `CORSMiddleware`. +You can configure it in your **FastAPI** application using Starlette's `CORSMiddleware`. * Import it from Starlette. * Create a list of allowed origins (as strings). @@ -50,6 +50,6 @@ You can also specify if your backend allows: ## More info -For more details of what you can specify in `CORSMiddleware`, check Starlette's `CORSMiddleware` docs. +For more details of what you can specify in `CORSMiddleware`, check Starlette's `CORSMiddleware` docs. -For more info about CORS, check the Mozilla CORS documentation. \ No newline at end of file +For more info about CORS, check the Mozilla CORS documentation. diff --git a/docs/tutorial/custom-request-and-route.md b/docs/tutorial/custom-request-and-route.md index 300bbb054..9385b0249 100644 --- a/docs/tutorial/custom-request-and-route.md +++ b/docs/tutorial/custom-request-and-route.md @@ -13,7 +13,7 @@ For example, if you want to read or manipulate the request body before it is pro Some use cases include: -* Converting non-JSON request bodies to JSON (e.g. [`msgpack`](https://msgpack.org/index.html)). +* Converting non-JSON request bodies to JSON (e.g. `msgpack`). * Decompressing gzip-compressed request bodies. * Automatically logging all request bodies. @@ -58,7 +58,7 @@ Here we use it to create a `GzipRequest` from the original request. 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. + To learn more about the `Request` check Starlette's docs about Requests. The only thing the function returned by `GzipRequest.get_route_handler` does differently is convert the `Request` to a `GzipRequest`. diff --git a/docs/tutorial/debugging.md b/docs/tutorial/debugging.md index 67d23c6e1..3800abd1b 100644 --- a/docs/tutorial/debugging.md +++ b/docs/tutorial/debugging.md @@ -65,7 +65,7 @@ So, the line: will not be executed. !!! info - For more information, check the official Python docs. + For more information, check the official Python docs. ## Run your code with your debugger diff --git a/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/tutorial/dependencies/dependencies-with-yield.md index 687ecd39d..73a8c8081 100644 --- a/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/tutorial/dependencies/dependencies-with-yield.md @@ -14,13 +14,13 @@ To do this, use `yield` instead of `return`, and write the extra steps after. pip install async-exit-stack async-generator ``` - This installs async-exit-stack and async-generator. + This installs async-exit-stack and async-generator. !!! note "Technical Details" Any function that is valid to use with: - * `@contextlib.contextmanager` or - * `@contextlib.asynccontextmanager` + * `@contextlib.contextmanager` or + * `@contextlib.asynccontextmanager` would be valid to use as a **FastAPI** dependency. @@ -98,7 +98,7 @@ You can have any combinations of dependencies that you want. **FastAPI** will make sure everything is run in the correct order. !!! note "Technical Details" - This works thanks to Python's Context Managers. + This works thanks to Python's Context Managers. **FastAPI** uses them internally to achieve this. @@ -108,7 +108,7 @@ You can have any combinations of dependencies that you want. "Context Managers" are any of those Python objects that you can use in a `with` statement. -For example, you can use `with` to read a file: +For example, you can use `with` to read a file: ```Python with open("./somefile.txt") as f: @@ -129,7 +129,7 @@ When you create a dependency with `yield`, **FastAPI** will internally convert i If you are just starting with **FastAPI** you might want to skip it for now. -In Python, you can create context managers by creating a class with two methods: `__enter__()` and `__exit__()`. +In Python, you can create context managers by creating a class with two methods: `__enter__()` and `__exit__()`. You can also use them with **FastAPI** dependencies with `yield` by using `with` or `async with` statements inside of the dependency function: @@ -141,8 +141,8 @@ You can also use them with **FastAPI** dependencies with `yield` by using !!! tip Another way to create a context manager is with: - * `@contextlib.contextmanager` or - * `@contextlib.asynccontextmanager` + * `@contextlib.contextmanager` or + * `@contextlib.asynccontextmanager` using them to decorate a function with a single `yield`. diff --git a/docs/tutorial/encoder.md b/docs/tutorial/encoder.md index 41893194e..4ce940eca 100644 --- a/docs/tutorial/encoder.md +++ b/docs/tutorial/encoder.md @@ -10,7 +10,7 @@ Let's imagine that you have a database `fake_db` that only receives JSON compati For example, it doesn't receive `datetime` objects, as those are not compatible with JSON. -So, a `datetime` object would have to be converted to a `str` containing the data in ISO format. +So, a `datetime` object would have to be converted to a `str` containing the data in ISO format. The same way, this database wouldn't receive a Pydantic model (an object with attributes), only a `dict`. @@ -24,7 +24,7 @@ It receives an object, like a Pydantic model, and returns a JSON compatible vers In this example, it would convert the Pydantic model to a `dict`, and the `datetime` to a `str`. -The result of calling it is something that can be encoded with the Python standard `json.dumps()`. +The result of calling it is something that can be encoded with the Python standard `json.dumps()`. It doesn't return a large `str` containing the data in JSON format (as a string). It returns a Python standard data structure (e.g. a `dict`) with values and sub-values that are all compatible with JSON. diff --git a/docs/tutorial/events.md b/docs/tutorial/events.md index 4998e50f9..d95a60a4c 100644 --- a/docs/tutorial/events.md +++ b/docs/tutorial/events.md @@ -32,12 +32,12 @@ Here, the `shutdown` event handler function will write a text line `"Application !!! tip Notice that in this case we are using a standard Python `open()` function that interacts with a file. - + So, it involves I/O (input/output), that requires "waiting" for things to be written to disk. - + But `open()` doesn't use `async` and `await`. - + So, we declare the event handler function with standard `def` instead of `async def`. !!! info - You can read more about these event handlers in Starlette's Events' docs. \ No newline at end of file + You can read more about these event handlers in Starlette's Events' docs. \ No newline at end of file diff --git a/docs/tutorial/extending-openapi.md b/docs/tutorial/extending-openapi.md index ce0d78c1f..c074ff712 100644 --- a/docs/tutorial/extending-openapi.md +++ b/docs/tutorial/extending-openapi.md @@ -5,7 +5,6 @@ If you already know that you need to modify the generated OpenAPI schema, continue reading. - There are some cases where you might need to modify the generated OpenAPI schema. In this section you will see how. @@ -37,7 +36,7 @@ And that function `get_openapi()` receives as parameters: Using the information above, you can use the same utility function to generate the OpenAPI schema and override each part that you need. -For example, let's add ReDoc's OpenAPI extension to include a custom logo. +For example, let's add ReDoc's OpenAPI extension to include a custom logo. ### Normal **FastAPI** @@ -85,7 +84,7 @@ Now you can replace the `.openapi()` method with your new function. ### Check it -Once you go to http://127.0.0.1:8000/redoc you will see that you are using your custom logo (in this example, **FastAPI**'s logo): +Once you go to http://127.0.0.1:8000/redoc you will see that you are using your custom logo (in this example, **FastAPI**'s logo): @@ -132,12 +131,12 @@ You can probably right-click each link and select an option similar to `Save lin **Swagger UI** uses the files: -* `swagger-ui-bundle.js` -* `swagger-ui.css` +* `swagger-ui-bundle.js` +* `swagger-ui.css` And **ReDoc** uses the file: -* `redoc.standalone.js` +* `redoc.standalone.js` After that, your file structure could look like: @@ -171,7 +170,7 @@ pip install aiofiles ### Test the static files -Start your application and go to http://127.0.0.1:8000/static/redoc.standalone.js. +Start your application and go to http://127.0.0.1:8000/static/redoc.standalone.js. You should see a very long JavaScript file for **ReDoc**. @@ -238,6 +237,6 @@ Now, to be able to test that everything works, create a path operation: ### Test it -Now, you should be able to disconnect your WiFi, go to your docs at http://127.0.0.1:8000/docs, and reload the page. +Now, you should be able to disconnect your WiFi, go to your docs at http://127.0.0.1:8000/docs, and reload the page. And even without Internet, you would be able to see the docs for your API and interact with it. diff --git a/docs/tutorial/extra-data-types.md b/docs/tutorial/extra-data-types.md index d2194eac9..241c3c2cc 100644 --- a/docs/tutorial/extra-data-types.md +++ b/docs/tutorial/extra-data-types.md @@ -19,10 +19,10 @@ And you will still have the same features as seen up to now: Here are some of the additional data types you can use: -* `UUID`: +* `UUID`: * A standard "Universally Unique Identifier", common as an ID in many databases and systems. * In requests and responses will be represented as a `str`. -* `datetime.datetime`: +* `datetime.datetime`: * A Python `datetime.datetime`. * In requests and responses will be represented as a `str` in ISO 8601 format, like: `2008-09-15T15:53:00+05:00`. * `datetime.date`: @@ -34,7 +34,7 @@ Here are some of the additional data types you can use: * `datetime.timedelta`: * A Python `datetime.timedelta`. * In requests and responses will be represented as a `float` of total seconds. - * Pydantic also allows representing it as a "ISO 8601 time diff encoding", see the docs for more info. + * Pydantic also allows representing it as a "ISO 8601 time diff encoding", see the docs for more info. * `frozenset`: * In requests and responses, treated the same as a `set`: * In requests, a list will be read, eliminating duplicates and converting it to a `set`. @@ -48,7 +48,6 @@ Here are some of the additional data types you can use: * Standard Python `Decimal`. * In requests and responses, handled the same as a `float`. - ## Example Here's an example path operation with parameters using some of the above types. diff --git a/docs/tutorial/extra-models.md b/docs/tutorial/extra-models.md index 875ce8aec..7accf0234 100644 --- a/docs/tutorial/extra-models.md +++ b/docs/tutorial/extra-models.md @@ -158,7 +158,7 @@ You can declare a response to be the `Union` of two types, that means, that the It will be defined in OpenAPI with `anyOf`. -To do that, use the standard Python type hint `typing.Union`: +To do that, use the standard Python type hint `typing.Union`: ```Python hl_lines="1 14 15 18 19 20 33" {!./src/extra_models/tutorial003.py!} diff --git a/docs/tutorial/first-steps.md b/docs/tutorial/first-steps.md index c1c556778..e1f3a5ce8 100644 --- a/docs/tutorial/first-steps.md +++ b/docs/tutorial/first-steps.md @@ -32,7 +32,7 @@ That last line shows the URL where your app is being served, in your local machi ### Check it -Open your browser at http://127.0.0.1:8000. +Open your browser at http://127.0.0.1:8000. You will see the JSON response as: @@ -42,18 +42,17 @@ You will see the JSON response as: ### Interactive API docs -Now go to http://127.0.0.1:8000/docs. +Now go to http://127.0.0.1:8000/docs. -You will see the automatic interactive API documentation (provided by Swagger UI): +You will see the automatic interactive API documentation (provided by Swagger UI): ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) - ### Alternative API docs -And now, go to http://127.0.0.1:8000/redoc. +And now, go to http://127.0.0.1:8000/redoc. -You will see the alternative automatic documentation (provided by ReDoc): +You will see the alternative automatic documentation (provided by ReDoc): ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -81,11 +80,11 @@ In that case, it would mean the JSON attributes, and data types they have, etc. OpenAPI defines an API schema for your API. And that schema includes definitions (or "schemas") of the data sent and received by your API using **JSON Schema**, the standard for JSON data schemas. -#### Check it +#### Check the `openapi.json` If you are curious about how the raw OpenAPI schema looks like, it is just an automatically generated JSON with the descriptions of all your API. -You can see it directly at: http://127.0.0.1:8000/openapi.json. +You can see it directly at: http://127.0.0.1:8000/openapi.json. It will show a JSON starting with something like: @@ -110,7 +109,7 @@ It will show a JSON starting with something like: ... ``` -#### What for? +#### What is OpenAPI for This OpenAPI schema is what powers the 2 interactive documentation systems included. @@ -256,7 +255,7 @@ And the more exotic ones: !!! tip You are free to use each operation (HTTP method) as you wish. - + **FastAPI** doesn't enforce any specific meaning. The information here is presented as a guideline, not a requirement. @@ -275,7 +274,7 @@ This is our "**path operation function**": {!./src/first_steps/tutorial001.py!} ``` -This is a Python function. +This is a Python function. It will be called by **FastAPI** whenever it receives a request to the URL "`/`" using `GET`. @@ -304,11 +303,10 @@ You can also return Pydantic models (you'll see more about that later). There are many other objects and models that will be automatically converted to JSON (including ORMs, etc). Try using your favorite ones, it's highly probable that they are already supported. - ## Recap * Import `FastAPI`. * Create an `app` instance. * Write a **path operation decorator** (like `@app.get("/")`). * Write a **path operation function** (like `def root(): ...` above). -* Run the development server (like `uvicorn main:app --reload`). \ No newline at end of file +* Run the development server (like `uvicorn main:app --reload`). diff --git a/docs/tutorial/graphql.md b/docs/tutorial/graphql.md index 45a85d4ad..9746bda06 100644 --- a/docs/tutorial/graphql.md +++ b/docs/tutorial/graphql.md @@ -5,7 +5,7 @@ You can combine normal FastAPI path operations with GraphQL on the same applicat ## Import and use `graphene` -GraphQL is implemented with Graphene, you can check Graphene's docs for more details. +GraphQL is implemented with Graphene, you can check Graphene's docs for more details. Import `graphene` and define your GraphQL data: @@ -26,13 +26,12 @@ Then import and add Starlette's `GraphQLApp`: ## Check it -Run it with Uvicorn and open your browser at http://127.0.0.1:8000. +Run it with Uvicorn and open your browser at http://127.0.0.1:8000. You will see GraphiQL web user interface: - ## More details For more details, including: @@ -41,4 +40,4 @@ For more details, including: * Adding background tasks * Using normal or async functions -check the official Starlette GraphQL docs. +check the official Starlette GraphQL docs. diff --git a/docs/tutorial/handling-errors.md b/docs/tutorial/handling-errors.md index d4f1d5486..973e91b98 100644 --- a/docs/tutorial/handling-errors.md +++ b/docs/tutorial/handling-errors.md @@ -82,7 +82,7 @@ But in case you needed it for an advanced scenario, you can add custom headers: ## Install custom exception handlers -You can add custom exception handlers with the same exception utilities from Starlette. +You can add custom exception handlers with the same exception utilities from Starlette. Let's say you have a custom exception `UnicornException` that you (or a library you use) might `raise`. @@ -156,7 +156,7 @@ path -> item_id !!! warning These are technical details that you might skip if it's not important for you now. -`RequestValidationError` is a sub-class of Pydantic's `ValidationError`. +`RequestValidationError` is a sub-class of Pydantic's `ValidationError`. **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. diff --git a/docs/tutorial/middleware.md b/docs/tutorial/middleware.md index f3a904d61..7b18adc22 100644 --- a/docs/tutorial/middleware.md +++ b/docs/tutorial/middleware.md @@ -28,11 +28,10 @@ The middleware function receives: !!! tip This technique is used in the tutorial about SQL (Relational) Databases. - !!! tip - Have in mind that custom proprietary headers can be added using the 'X-' prefix. + Have in mind that custom proprietary headers can be added using the 'X-' prefix. - 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, using the parameter `expose_headers` documented in Starlette's CORS docs. + 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, using the parameter `expose_headers` documented in Starlette's CORS docs. ### Before and after the `response` @@ -48,7 +47,7 @@ For example, you could add a custom header `X-Process-Time` containing the time ## Starlette's Middleware -You can also add any other Starlette Middleware. +You can also add any other Starlette Middleware. These are classes instead of plain functions. diff --git a/docs/tutorial/nosql-databases.md b/docs/tutorial/nosql-databases.md index 29387f8c1..0c695d042 100644 --- a/docs/tutorial/nosql-databases.md +++ b/docs/tutorial/nosql-databases.md @@ -1,6 +1,6 @@ **FastAPI** can also be integrated with any NoSQL. -Here we'll see an example using **Couchbase**, a document based NoSQL database. +Here we'll see an example using **Couchbase**, a document based NoSQL database. You can adapt it to any other NoSQL database like: @@ -11,7 +11,7 @@ You can adapt it to any other NoSQL database like: * **ElasticSearch**, etc. !!! tip - There is an official project generator with **FastAPI** and **Couchbase**, all based on **Docker**, including a frontend and more tools: https://github.com/tiangolo/full-stack-fastapi-couchbase + There is an official project generator with **FastAPI** and **Couchbase**, all based on **Docker**, including a frontend and more tools: https://github.com/tiangolo/full-stack-fastapi-couchbase ## Import Couchbase components @@ -84,9 +84,8 @@ We don't create it as a subclass of Pydantic's `BaseModel` but as a subclass of !!! note Notice that we have a `hashed_password` and a `type` field that will be stored in the database. - - But it is not part of the general `User` model (the one we will return in the path operation). + But it is not part of the general `User` model (the one we will return in the path operation). ## Get the user @@ -104,14 +103,14 @@ By creating a function that is only dedicated to getting your user from a `usern ``` ### f-strings - -If you are not familiar with the `f"userprofile::{username}"`, it is a Python "f-string". + +If you are not familiar with the `f"userprofile::{username}"`, it is a Python "f-string". Any variable that is put inside of `{}` in an f-string will be expanded / injected in the string. ### `dict` unpacking -If you are not familiar with the `UserInDB(**result.value)`, it is using `dict` "unpacking". +If you are not familiar with the `UserInDB(**result.value)`, it is using `dict` "unpacking". It will take the `dict` at `result.value`, and take each of its keys and values and pass them as key-values to `UserInDB` as keyword arguments. @@ -140,7 +139,7 @@ UserInDB(username="johndoe", hashed_password="some_hash") ### Create the path operation function -As our code is calling Couchbase and we are not using the experimental Python await support, we should declare our function with normal `def` instead of `async def`. +As our code is calling Couchbase and we are not using the experimental Python await support, we should declare our function with normal `def` instead of `async def`. Also, Couchbase recommends not using a single `Bucket` object in multiple "threads", so, we can get just get the bucket directly and pass it to our utility functions: diff --git a/docs/tutorial/openapi-callbacks.md b/docs/tutorial/openapi-callbacks.md index 311767a6b..b7e48c5e3 100644 --- a/docs/tutorial/openapi-callbacks.md +++ b/docs/tutorial/openapi-callbacks.md @@ -34,7 +34,7 @@ This part is pretty normal, most of the code is probably already familiar to you ``` !!! tip - The `callback_url` query parameter uses a Pydantic URL type. + The `callback_url` query parameter uses a Pydantic URL type. The only new thing is the `callbacks=messages_callback_router.routes` as an argument to the *path operation decorator*. We'll see what that is next. @@ -62,7 +62,7 @@ This example doesn't implement the callback itself (that could be just a line of !!! tip The actual callback is just an HTTP request. - When implementing the callback yourself, you could use something like HTTPX or Requests. + When implementing the callback yourself, you could use something like HTTPX or Requests. ## Write the callback documentation code @@ -110,11 +110,11 @@ It should look just like a normal FastAPI *path operation*: There are 2 main differences from a normal *path operation*: * It doesn't need to have any actual code, because your app will never call this code. It's only used to document the *external API*. So, the function could just have `pass`. -* The *path* can contain an OpenAPI 3 expression (see more below) where it can use variables with parameters and parts of the original request sent to *your API*. +* The *path* can contain an OpenAPI 3 expression (see more below) where it can use variables with parameters and parts of the original request sent to *your API*. ### The callback path expression -The callback *path* can have an OpenAPI 3 expression that can contain parts of the original request sent to *your API*. +The callback *path* can have an OpenAPI 3 expression that can contain parts of the original request sent to *your API*. In this case, it's the `str`: @@ -179,7 +179,7 @@ Now use the parameter `callbacks` in *your API's path operation decorator* to pa ### Check the docs -Now you can start your app with Uvicorn and go to http://127.0.0.1:8000/docs. +Now you can start your app with Uvicorn and go to http://127.0.0.1:8000/docs. You will see your docs including a "Callback" section for your *path operation* that shows how the *external API* should look like: diff --git a/docs/tutorial/path-operation-configuration.md b/docs/tutorial/path-operation-configuration.md index 0808adec9..a60d8e07f 100644 --- a/docs/tutorial/path-operation-configuration.md +++ b/docs/tutorial/path-operation-configuration.md @@ -17,7 +17,6 @@ But if you don't remember what each number code is for, you can use the shortcut That status code will be used in the response and will be added to the OpenAPI schema. - ## Tags You can add tags to your path operation, pass the parameter `tags` with a `list` of `str` (commonly just one `str`): @@ -42,7 +41,7 @@ You can add a `summary` and `description`: As descriptions tend to be long and cover multiple lines, you can declare the path operation description in the function docstring and **FastAPI** will read it from there. -You can write Markdown in the docstring, it will be interpreted and displayed correctly (taking into account docstring indentation). +You can write Markdown in the docstring, it will be interpreted and displayed correctly (taking into account docstring indentation). ```Python hl_lines="19 20 21 22 23 24 25 26 27" {!./src/path_operation_configuration/tutorial004.py!} @@ -65,7 +64,7 @@ You can specify the response description with the parameter `response_descriptio !!! info OpenAPI specifies that each path operation requires a response description. - + So, if you don't provide one, **FastAPI** will automatically generate one of "Successful response". @@ -74,7 +73,6 @@ You can specify the response description with the parameter `response_descriptio If you need to mark a path operation as deprecated, but without removing it, pass the parameter `deprecated`: - ```Python hl_lines="16" {!./src/path_operation_configuration/tutorial006.py!} ``` @@ -89,4 +87,4 @@ Check how deprecated and non-deprecated path operations look like: ## Recap -You can configure and add metadata for your path operations easily by passing parameters to the path operation decorators. \ No newline at end of file +You can configure and add metadata for your path operations easily by passing parameters to the path operation decorators. diff --git a/docs/tutorial/path-params.md b/docs/tutorial/path-params.md index d0c592d68..36ccaddea 100644 --- a/docs/tutorial/path-params.md +++ b/docs/tutorial/path-params.md @@ -6,7 +6,7 @@ You can declare path "parameters" or "variables" with the same syntax used by Py The value of the path parameter `item_id` will be passed to your function as the argument `item_id`. -So, if you run this example and go to http://127.0.0.1:8000/items/foo, you will see a response of: +So, if you run this example and go to http://127.0.0.1:8000/items/foo, you will see a response of: ```JSON {"item_id":"foo"} @@ -27,7 +27,7 @@ In this case, `item_id` is declared to be an `int`. ## Data conversion -If you run this example and open your browser at http://127.0.0.1:8000/items/3, you will see a response of: +If you run this example and open your browser at http://127.0.0.1:8000/items/3, you will see a response of: ```JSON {"item_id":3} @@ -40,7 +40,7 @@ If you run this example and open your browser at http://127.0.0.1:8000/items/foo, you will see a nice HTTP error of: +But if you go to the browser at http://127.0.0.1:8000/items/foo, you will see a nice HTTP error of: ```JSON { @@ -59,7 +59,7 @@ But if you go to the browser at http://127.0.0.1:8000/items/4.2 +The same error would appear if you provided a `float` instead of an int, as in: http://127.0.0.1:8000/items/4.2 !!! check So, with the same Python type declaration, **FastAPI** gives you data validation. @@ -70,7 +70,7 @@ The same error would appear if you provided a `float` instead of an int, as in: ## Documentation -And when you open your browser at http://127.0.0.1:8000/docs, you will see an automatic, interactive, API documentation like: +And when you open your browser at http://127.0.0.1:8000/docs, you will see an automatic, interactive, API documentation like: @@ -81,7 +81,7 @@ And when you open your browser at OpenAPI standard, there are many compatible tools. +And because the generated schema is from the OpenAPI standard, there are many compatible tools. Because of this, **FastAPI** itself provides an alternative API documentation (using ReDoc): @@ -91,7 +91,7 @@ The same way, there are many compatible tools. Including code generation tools f ## Pydantic -All the data validation is performed under the hood by Pydantic, so you get all the benefits from it. And you know you are in good hands. +All the data validation is performed under the hood by Pydantic, so you get all the benefits from it. And you know you are in good hands. You can use the same type declarations with `str`, `float`, `bool` and many other complex data types. @@ -130,7 +130,7 @@ And create class attributes with fixed values, those fixed values will be the av ``` !!! info - Enumerations (or enums) are available in Python since version 3.4. + Enumerations (or enums) are available in Python since version 3.4. !!! tip If you are wondering, "AlexNet", "ResNet", and "LeNet" are just names of Machine Learning models. diff --git a/docs/tutorial/query-params-str-validations.md b/docs/tutorial/query-params-str-validations.md index 4d3315375..2340ee71e 100644 --- a/docs/tutorial/query-params-str-validations.md +++ b/docs/tutorial/query-params-str-validations.md @@ -118,7 +118,7 @@ So, when you need to declare a value as required while using `Query`, you can us ``` !!! info - If you hadn't seen that `...` before: it is a a special single value, it is part of Python and is called "Ellipsis". + If you hadn't seen that `...` before: it is a a special single value, it is part of Python and is called "Ellipsis". This will let **FastAPI** know that this parameter is required. @@ -276,4 +276,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. \ No newline at end of file +See the next chapters to see how to declare validations for other types, like numbers. diff --git a/docs/tutorial/request-files.md b/docs/tutorial/request-files.md index 3207dc076..c1a2bf1d2 100644 --- a/docs/tutorial/request-files.md +++ b/docs/tutorial/request-files.md @@ -1,7 +1,7 @@ You can define files to be uploaded by the client using `File`. !!! info - To receive uploaded files, first install [`python-multipart`](https://andrew-d.github.io/python-multipart/). + To receive uploaded files, first install `python-multipart`. E.g. `pip install python-multipart`. @@ -39,7 +39,6 @@ Have in mind that this means that the whole contents will be stored in memory. T But there are several cases in where you might benefit from using `UploadFile`. - ## `File` parameters with `UploadFile` Define a `File` parameter with a type of `UploadFile`: @@ -54,9 +53,8 @@ Using `UploadFile` has several advantages over `bytes`: * A file stored in memory up to a maximum size limit, and after passing this limit it will be stored in disk. * This means that it will work well for large files like images, videos, large binaries, etc. without consuming all the memory. * You can get metadata from the uploaded file. -* It has a file-like `async` interface. -* It exposes an actual Python `SpooledTemporaryFile` object that you can pass directly to other libraries that expect a file-like object. - +* It has a file-like `async` interface. +* It exposes an actual Python `SpooledTemporaryFile` object that you can pass directly to other libraries that expect a file-like object. ### `UploadFile` @@ -66,7 +64,6 @@ Using `UploadFile` has several advantages over `bytes`: * `content_type`: A `str` with the content type (MIME type / media type) (e.g. `image/jpeg`). * `file`: A `SpooledTemporaryFile` (a file-like object). This is the actual Python file that you can pass directly to other functions or libraries that expect a "file-like" object. - `UploadFile` has the following `async` methods. They all call the corresponding file methods underneath (using the internal `SpooledTemporaryFile`). * `write(data)`: Writes `data` (`str` or `bytes`) to the file. @@ -93,11 +90,10 @@ contents = myfile.file.read() !!! note "`async` Technical Details" When you use the `async` methods, **FastAPI** runs the file methods in a threadpool and awaits for them. - !!! note "Starlette Technical Details" **FastAPI**'s `UploadFile` inherits directly from **Starlette**'s `UploadFile`, but adds some necessary parts to make it compatible with **Pydantic** and the other parts of FastAPI. -## "Form Data"? +## What is "Form Data" The way HTML forms (`
`) sends the data to the server normally uses a "special" encoding for that data, it's different from JSON. @@ -108,8 +104,7 @@ The way HTML forms (`
`) sends the data to the server normally uses But when the form includes files, it is encoded as `multipart/form-data`. If you use `File`, **FastAPI** will know it has to get the files from the correct part of the body. - If you want to read more about these encodings and form fields, head to the MDN web docs for POST. - + If you want to read more about these encodings and form fields, head to the MDN web docs for POST. !!! warning You can declare multiple `File` and `Form` parameters in a path operation, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`. @@ -131,7 +126,7 @@ To use that, declare a `List` of `bytes` or `UploadFile`: You will receive, as declared, a `list` of `bytes` or `UploadFile`s. !!! note - Notice that, as of 2019-04-14, Swagger UI doesn't support multiple file uploads in the same form field. For more information, check #4276 and #3641. + Notice that, as of 2019-04-14, Swagger UI doesn't support multiple file uploads in the same form field. For more information, check #4276 and #3641. Nevertheless, **FastAPI** is already compatible with it, using the standard OpenAPI. diff --git a/docs/tutorial/request-forms-and-files.md b/docs/tutorial/request-forms-and-files.md index 5c71635e5..ce057eab3 100644 --- a/docs/tutorial/request-forms-and-files.md +++ b/docs/tutorial/request-forms-and-files.md @@ -1,7 +1,7 @@ You can define files and form fields at the same time using `File` and `Form`. !!! info - To receive uploaded files and/or form data, first install [`python-multipart`](https://andrew-d.github.io/python-multipart/). + To receive uploaded files and/or form data, first install `python-multipart`. E.g. `pip install python-multipart`. diff --git a/docs/tutorial/request-forms.md b/docs/tutorial/request-forms.md index 8c64b3af8..95b356e75 100644 --- a/docs/tutorial/request-forms.md +++ b/docs/tutorial/request-forms.md @@ -1,7 +1,7 @@ When you need to receive form fields instead of JSON, you can use `Form`. !!! info - To use forms, first install [`python-multipart`](https://andrew-d.github.io/python-multipart/). + To use forms, first install `python-multipart`. E.g. `pip install python-multipart`. @@ -33,7 +33,7 @@ With `Form` you can declare the same metadata and validation as with `Body` (and !!! info To declare form bodies, you need to use `Form` explicitly, because without it the parameters would be interpreted as query parameters or body (JSON) parameters. -## "Form Fields"? +## About "Form Fields" The way HTML forms (`
`) sends the data to the server normally uses a "special" encoding for that data, it's different from JSON. @@ -44,8 +44,7 @@ The way HTML forms (`
`) sends the data to the server normally uses But when the form includes files, it is encoded as `multipart/form-data`. You'll read about handling files in the next chapter. - If you want to read more about these encodings and form fields, head to the MDN web docs for POST. - + If you want to read more about these encodings and form fields, head to the MDN web docs for POST. !!! warning You can declare multiple `Form` parameters in a path operation, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `application/x-www-form-urlencoded` instead of `application/json`. diff --git a/docs/tutorial/response-cookies.md b/docs/tutorial/response-cookies.md index 62c633752..7d4c15be7 100644 --- a/docs/tutorial/response-cookies.md +++ b/docs/tutorial/response-cookies.md @@ -29,7 +29,7 @@ Then set Cookies in it, and then return it: ``` !!! tip - Have in mind that if you return a response directly instead of using the `Response` parameter, FastAPI will return it directly. + Have in mind that if you return a response directly instead of using the `Response` parameter, FastAPI will return it directly. So, you will have to make sure your data is of the correct type. E.g. it is compatible with JSON, if you are returning a `JSONResponse`. @@ -37,4 +37,4 @@ Then set Cookies in it, and then return it: ### More info -To see all the available parameters and options, check the documentation in Starlette. +To see all the available parameters and options, check the documentation in Starlette. diff --git a/docs/tutorial/response-directly.md b/docs/tutorial/response-directly.md index 0feb93793..348a6f978 100644 --- a/docs/tutorial/response-directly.md +++ b/docs/tutorial/response-directly.md @@ -10,7 +10,7 @@ It might be useful, for example, to return custom headers or cookies. ## Starlette `Response` -In fact, you can return any Starlette `Response` or any sub-class of it. +In fact, you can return any Starlette `Response` or any sub-class of it. !!! tip `JSONResponse` itself is a sub-class of `Response`. @@ -42,9 +42,9 @@ The example above shows all the parts you need, but it's not very useful yet, as Now, let's see how you could use that to return a custom response. -Let's say you want to return a response that is not available in the default Starlette `Response`s. +Let's say you want to return a response that is not available in the default Starlette `Response`s. -Let's say that you want to return XML. +Let's say that you want to return XML. You could put your XML content in a string, put it in a Starlette Response, and return it: diff --git a/docs/tutorial/response-headers.md b/docs/tutorial/response-headers.md index f9608956e..7926e4e2f 100644 --- a/docs/tutorial/response-headers.md +++ b/docs/tutorial/response-headers.md @@ -28,6 +28,6 @@ Create a response as described in using the 'X-' prefix. +Have in mind that custom proprietary headers can be added using the 'X-' prefix. -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, using the parameter `expose_headers` documented in Starlette's CORS docs. +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, using the parameter `expose_headers` documented in Starlette's CORS docs. diff --git a/docs/tutorial/response-model.md b/docs/tutorial/response-model.md index 8057bd23b..178ca3783 100644 --- a/docs/tutorial/response-model.md +++ b/docs/tutorial/response-model.md @@ -120,7 +120,7 @@ So, if you send a request to that *path operation* for the item with ID `foo`, t ``` !!! info - FastAPI uses Pydantic model's `.dict()` with its `exclude_unset` parameter to achieve this. + FastAPI uses Pydantic model's `.dict()` with its `exclude_unset` parameter to achieve this. #### Data with values for fields with defaults diff --git a/docs/tutorial/response-status-code.md b/docs/tutorial/response-status-code.md index 45b82a254..bd86b5a89 100644 --- a/docs/tutorial/response-status-code.md +++ b/docs/tutorial/response-status-code.md @@ -50,7 +50,7 @@ In short: * `500` and above are for server errors. You almost never use them directly. When something goes wrong at some part in your application code, or server, it will automatically return one of these status codes. !!! tip - To know more about each status code and which code is for what, check the MDN documentation about HTTP status codes. + To know more about each status code and which code is for what, check the MDN documentation about HTTP status codes. ## Shortcut to remember the names diff --git a/docs/tutorial/security/first-steps.md b/docs/tutorial/security/first-steps.md index 1ed9e8c62..26dbed0d7 100644 --- a/docs/tutorial/security/first-steps.md +++ b/docs/tutorial/security/first-steps.md @@ -25,7 +25,7 @@ Copy the example in a file `main.py`: ## Run it !!! info - First install [`python-multipart`](https://andrew-d.github.io/python-multipart/). + First install `python-multipart`. E.g. `pip install python-multipart`. @@ -39,7 +39,7 @@ uvicorn main:app --reload ## Check it -Go to the interactive docs at: http://127.0.0.1:8000/docs. +Go to the interactive docs at: http://127.0.0.1:8000/docs. You will see something like this: @@ -50,7 +50,6 @@ You will see something like this: And your path operation has a little lock in the top-right corner that you can click. - And if you click it, you have a little authorization form to type a `username` and `password` (and other optional fields): @@ -66,7 +65,6 @@ It can be used by third party applications and systems. And it can also be used by yourself, to debug, check and test the same application. - ## The `password` flow Now let's go back a bit and understand what is all that. @@ -99,10 +97,9 @@ So, let's review it from that simplified point of view: In this example we are going to use **OAuth2**, with the **Password** flow, using a **Bearer** token. - !!! info 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. diff --git a/docs/tutorial/security/http-basic-auth.md b/docs/tutorial/security/http-basic-auth.md index a3fad2346..cbdad8279 100644 --- a/docs/tutorial/security/http-basic-auth.md +++ b/docs/tutorial/security/http-basic-auth.md @@ -18,7 +18,6 @@ Then, when you type that username and password, the browser sends them in the he * It returns an object of type `HTTPBasicCredentials`: * It contains the `username` and `password` sent. - ```Python hl_lines="2 6 10" {!./src/security/tutorial006.py!} ``` @@ -33,7 +32,7 @@ Here's a more complete example. Use a dependency to check if the username and password are correct. -For this, use the Python standard module `secrets` to check the username and password: +For this, use the Python standard module `secrets` to check the username and password: ```Python hl_lines="1 13 14 15" {!./src/security/tutorial007.py!} diff --git a/docs/tutorial/security/oauth2-jwt.md b/docs/tutorial/security/oauth2-jwt.md index a4be54e20..10c777bc8 100644 --- a/docs/tutorial/security/oauth2-jwt.md +++ b/docs/tutorial/security/oauth2-jwt.md @@ -22,7 +22,7 @@ That way, you can create a token with an expiration of, let's say, 1 week, and t And after a week, the token will be expired. And if the user (or a third party) tried to modify the token to change the expiration, you would be able to discover it, because the signatures would not match. -If you want to play with JWT tokens and see how they work, check https://jwt.io. +If you want to play with JWT tokens and see how they work, check https://jwt.io. ## Install `PyJWT` @@ -40,7 +40,7 @@ Whenever you pass exactly the same content (exactly the same password) you get e But you cannot convert from the gibberish back to the password. -### What for? +### Why use password hashing If your database is stolen, the thief won't have your users' plaintext passwords, only the hashes. @@ -141,7 +141,6 @@ Create a real JWT access token and return it. {!./src/security/tutorial004.py!} ``` - ### Technical details about the JWT "subject" `sub` The JWT specification says that there's a key `sub`, with the subject of the token. @@ -166,7 +165,7 @@ The important thing to have in mind is that the `sub` key should have a unique i ## Check it -Run the server and go to the docs: http://127.0.0.1:8000/docs. +Run the server and go to the docs: http://127.0.0.1:8000/docs. You'll see the user interface like: diff --git a/docs/tutorial/security/simple-oauth2.md b/docs/tutorial/security/simple-oauth2.md index 4937d7bd2..cd0341b20 100644 --- a/docs/tutorial/security/simple-oauth2.md +++ b/docs/tutorial/security/simple-oauth2.md @@ -39,7 +39,6 @@ They are normally used to declare specific security permissions, for example: For OAuth2 they are just strings. - ## Code to get the `username` and `password` Now let's use the utilities provided by **FastAPI** to handle this. @@ -69,11 +68,11 @@ First, import `OAuth2PasswordRequestForm`, and use it as a dependency with `Depe !!! info The `OAuth2PasswordRequestForm` is not a special class for **FastAPI** as is `OAuth2PasswordBearer`. - + `OAuth2PasswordBearer` makes **FastAPI** know that it is a security scheme. So it is added that way to OpenAPI. - + But `OAuth2PasswordRequestForm` is just a class dependency that you could have written yourself, or you could have declared `Form` parameters directly. - + But as it's a common use case, it is provided by **FastAPI** directly, just to make it easier. ### Use the form data @@ -111,7 +110,7 @@ Whenever you pass exactly the same content (exactly the same password) you get e But you cannot convert from the gibberish back to the password. -##### What for? +##### Why use password hashing If your database is stolen, the thief won't have your users' plaintext passwords, only the hashes. @@ -124,7 +123,7 @@ So, the thief won't be able to try to use that password in another system (as ma #### About `**user_dict` `UserInDB(**user_dict)` means: - + *Pass the keys and values of the `user_dict` directly as key-value arguments, equivalent to:* ```Python @@ -201,7 +200,7 @@ So, in our endpoint, we will only get a user if the user exists, was correctly a ## See it in action -Open the interactive docs: http://127.0.0.1:8000/docs. +Open the interactive docs: http://127.0.0.1:8000/docs. ### Authenticate diff --git a/docs/tutorial/sql-databases-peewee.md b/docs/tutorial/sql-databases-peewee.md index 99f983e41..63df28672 100644 --- a/docs/tutorial/sql-databases-peewee.md +++ b/docs/tutorial/sql-databases-peewee.md @@ -5,7 +5,7 @@ If you are starting a project from scratch, you are probably better off with SQLAlchemy ORM, or any other async ORM. -If you already have a code base that uses Peewee ORM, you can check here how to use it with **FastAPI**. +If you already have a code base that uses Peewee ORM, you can check here how to use it with **FastAPI**. !!! warning "Python 3.7+ required" You will need Python 3.7 or above to safely use Peewee with FastAPI. @@ -23,7 +23,7 @@ But if you need to change some of the defaults, support more than one predefined Nevertheless, it's possible to do it, and here you'll see exactly what code you have to add to be able to use Peewee with FastAPI. !!! note "Technical Details" - You can read more about Peewee's stand about async in Python in the docs, an issue, a PR. + You can read more about Peewee's stand about async in Python in the docs, an issue, a PR. ## The same app @@ -88,7 +88,7 @@ connect_args={"check_same_thread": False} ### Make Peewee async-compatible `PeeweeConnectionState` -The main issue with Peewee and FastAPI is that Peewee relies heavily on Python's `threading.local`, and it doesn't have a direct way to override it or let you handle connections/sessions directly (as is done in the SQLAlchemy tutorial). +The main issue with Peewee and FastAPI is that Peewee relies heavily on Python's `threading.local`, and it doesn't have a direct way to override it or let you handle connections/sessions directly (as is done in the SQLAlchemy tutorial). And `threading.local` is not compatible with the new async features of modern Python. @@ -103,7 +103,7 @@ And `threading.local` is not compatible with the new async features of modern Py But Python 3.7 and above provide a more advanced alternative to `threading.local`, that can also be used in the places where `threading.local` would be used, but is compatible with the new async features. -We are going to use that. It's called `contextvars`. +We are going to use that. It's called `contextvars`. We are going to override the internal parts of Peewee that use `threading.local` and replace them with `contextvars`, with the corresponding updates. @@ -206,7 +206,7 @@ It provides a special custom object of class `ModelSelect`. It's possible to create a `list` of its items with `list(some_user.items)`. -But the object itself is not a `list`. And it's also not an actual Python generator. Because of this, Pydantic doesn't know by default how to convert it to a `list` of Pydantic *models* / schemas. +But the object itself is not a `list`. And it's also not an actual Python generator. Because of this, Pydantic doesn't know by default how to convert it to a `list` of Pydantic *models* / schemas. But recent versions of Pydantic allow providing a custom class that inherits from `pydantic.utils.GetterDict`, to provide the functionality used when using the `orm_mode = True` to retrieve the values for ORM model attributes. @@ -307,7 +307,7 @@ For the **next request**, as we will reset that context variable again in the mi #### Peewee Proxy -If you are using a [Peewee Proxy](http://docs.peewee-orm.com/en/latest/peewee/database.html#dynamically-defining-a-database){.external-link target=_blank}, the actual database is at `db.obj`. +If you are using a Peewee Proxy, the actual database is at `db.obj`. So, you would reset it with: @@ -381,9 +381,9 @@ Then run your app with Uvicorn: uvicorn sql_app.main:app --reload ``` -Open your browser at http://127.0.0.1:8000/docs and create a couple of users. +Open your browser at http://127.0.0.1:8000/docs and create a couple of users. -Then open 10 tabs at http://127.0.0.1:8000/docs#/default/read_slow_users_slowusers__get at the same time. +Then open 10 tabs at http://127.0.0.1:8000/docs#/default/read_slow_users_slowusers__get at the same time. Go to the *path operation* "Get `/slowusers/`" in all of the tabs. Use the "Try it out" button and execute the request in each tab, one right after the other. @@ -475,7 +475,7 @@ Repeat the same process with the 10 tabs. This time all of them will wait and yo ### The problem -Peewee uses [`threading.local`](https://docs.python.org/3/library/threading.html#thread-local-data){.external-link target=_blank} by default to store it's database "state" data (connection, transactions, etc). +Peewee uses `threading.local` by default to store it's database "state" data (connection, transactions, etc). `threading.local` creates a value exclusive to the current thread, but an async framework would run all the "tasks" (e.g. requests) in the same thread, and possibly not in order. @@ -485,7 +485,7 @@ This means that, with Peewee's current implementation, multiple tasks could be u ### Context variables -Python 3.7 has [`contextvars`](https://docs.python.org/3/library/contextvars.html){.external-link target=_blank} that can create a local variable very similar to `threading.local`, but also supporting these async features. +Python 3.7 has `contextvars` that can create a local variable very similar to `threading.local`, but also supporting these async features. There are several things to have in mind. diff --git a/docs/tutorial/sql-databases.md b/docs/tutorial/sql-databases.md index 4bf621a5c..ec00f041b 100644 --- a/docs/tutorial/sql-databases.md +++ b/docs/tutorial/sql-databases.md @@ -2,7 +2,7 @@ But you can use any relational database that you want. -Here we'll see an example using SQLAlchemy. +Here we'll see an example using SQLAlchemy. You can easily adapt it to any database supported by SQLAlchemy, like: @@ -17,8 +17,7 @@ In this example, we'll use **SQLite**, because it uses a single file and Python Later, for your production application, you might want to use a database server like **PostgreSQL**. !!! tip - There is an official project generator with **FastAPI** and **PostgreSQL**, all based on **Docker**, including a frontend and more tools: https://github.com/tiangolo/full-stack-fastapi-postgresql - + There is an official project generator with **FastAPI** and **PostgreSQL**, all based on **Docker**, including a frontend and more tools: https://github.com/tiangolo/full-stack-fastapi-postgresql !!! note Notice that most of the code is the standard `SQLAlchemy` code you would use with any framework. @@ -288,7 +287,7 @@ Not only the IDs of those items, but all the data that we defined in the Pydanti Now, in the Pydantic *models* for reading, `Item` and `User`, add an internal `Config` class. -This `Config` class is used to provide configurations to Pydantic. +This `Config` class is used to provide configurations to Pydantic. In the `Config` class, set the attribute `orm_mode = True`. @@ -324,7 +323,7 @@ And with this, the Pydantic *model* is compatible with ORMs, and you can just de You will be able to return a database model and it will read the data from it. #### Technical Details about ORM mode - + SQLAlchemy and many others are by default "lazy loading". That means, for example, that they don't fetch the data for relationships from the database unless you try to access the attribute that would contain that data. @@ -430,7 +429,7 @@ In a very simplistic way create the database tables: #### Alembic Note -Normally you would probably initialize your database (create tables, etc) with Alembic. +Normally you would probably initialize your database (create tables, etc) with Alembic. And you would also use Alembic for "migrations" (that's its main job). @@ -445,7 +444,7 @@ A "migration" is the set of steps needed whenever you change the structure of yo pip install async-exit-stack async-generator ``` - This installs async-exit-stack and async-generator. + This installs async-exit-stack and async-generator. You can also use the alternative method with a "middleware" explained at the end. @@ -539,13 +538,13 @@ def read_user(user_id: int, db: Session = Depends(get_db)): ## Migrations -Because we are using SQLAlchemy directly and we don't require any kind of plug-in for it to work with **FastAPI**, we could integrate database migrations with Alembic directly. +Because we are using SQLAlchemy directly and we don't require any kind of plug-in for it to work with **FastAPI**, we could integrate database migrations with Alembic directly. And as the code related to SQLAlchemy and the SQLAlchemy models lives in separate independent files, you would even be able to perform the migrations with Alembic without having to install FastAPI, Pydantic, or anything else. The same way, you would be able to use the same SQLAlchemy models and utilities in other parts of your code that are not related to **FastAPI**. -For example, in a background task worker with Celery, RQ, or ARQ. +For example, in a background task worker with Celery, RQ, or ARQ. ## Review all the files @@ -599,7 +598,7 @@ Then you can run it with Uvicorn: uvicorn sql_app.main:app --reload ``` -And then, you can open your browser at http://127.0.0.1:8000/docs. +And then, you can open your browser at http://127.0.0.1:8000/docs. And you will be able to interact with your **FastAPI** application, reading data from a real database: @@ -607,13 +606,13 @@ And you will be able to interact with your **FastAPI** application, reading data ## Interact with the database directly -If you want to explore the SQLite database (file) directly, independently of FastAPI, to debug its contents, add tables, columns, records, modify data, etc. you can use DB Browser for SQLite. +If you want to explore the SQLite database (file) directly, independently of FastAPI, to debug its contents, add tables, columns, records, modify data, etc. you can use DB Browser for SQLite. It will look like this: -You can also use an online SQLite browser like SQLite Viewer or ExtendsClass. +You can also use an online SQLite browser like SQLite Viewer or ExtendsClass. ## Alternative DB session with middleware @@ -638,7 +637,7 @@ The middleware we'll add (just a function) will create a new SQLAlchemy `Session ### About `request.state` -`request.state` is a property of each Starlette `Request` object. It is there to store arbitrary objects attached to the request itself, like the database session in this case. +`request.state` is a property of each Starlette `Request` object. It is there to store arbitrary objects attached to the request itself, like the database session in this case. For us in this case, it helps us ensure a single database session is used through all the request, and then closed afterwards (in the middleware). diff --git a/docs/tutorial/static-files.md b/docs/tutorial/static-files.md index 31955fcb7..0b1cfb8d4 100644 --- a/docs/tutorial/static-files.md +++ b/docs/tutorial/static-files.md @@ -1,4 +1,4 @@ -You can serve static files automatically from a directory using Starlette's Static Files. +You can serve static files automatically from a directory using Starlette's Static Files. ## Install `aiofiles` @@ -31,4 +31,4 @@ All these parameters can be different than "`static`", adjust them with the need ## More info -For more details and options check Starlette's docs about Static Files. +For more details and options check Starlette's docs about Static Files. diff --git a/docs/tutorial/sub-applications-proxy.md b/docs/tutorial/sub-applications-proxy.md index 84c76b4c5..c8d5df4aa 100644 --- a/docs/tutorial/sub-applications-proxy.md +++ b/docs/tutorial/sub-applications-proxy.md @@ -33,7 +33,6 @@ For these cases, you can declare an `openapi_prefix` parameter in your `FastAPI` See the section below, about "mounting", for an example. - ## Mounting a **FastAPI** application "Mounting" means adding a complete "independent" application in a specific path, that then takes care of handling all the sub-paths. @@ -78,18 +77,16 @@ Now, run `uvicorn`, if your file is at `main.py`, it would be: uvicorn main:app --reload ``` -And open the docs at http://127.0.0.1:8000/docs. +And open the docs at http://127.0.0.1:8000/docs. You will see the automatic API docs for the main app, including only its own paths: - -And then, open the docs for the sub-application, at http://127.0.0.1:8000/subapi/docs. +And then, open the docs for the sub-application, at http://127.0.0.1:8000/subapi/docs. You will see the automatic API docs for the sub-application, including only its own sub-paths, with their correct prefix: - -If you try interacting with any of the two user interfaces, they will work, because the browser will be able to talk to the correct path (or sub-path). \ No newline at end of file +If you try interacting with any of the two user interfaces, they will work, because the browser will be able to talk to the correct path (or sub-path). diff --git a/docs/tutorial/templates.md b/docs/tutorial/templates.md index a909ece48..2a43903b8 100644 --- a/docs/tutorial/templates.md +++ b/docs/tutorial/templates.md @@ -64,4 +64,4 @@ And because you are using `StaticFiles`, that CSS file would be served automatic ## More details -For more details, including how to test templates, check Starlette's docs on templates. \ No newline at end of file +For more details, including how to test templates, check Starlette's docs on templates. diff --git a/docs/tutorial/testing.md b/docs/tutorial/testing.md index d1be2f09f..2819b4f60 100644 --- a/docs/tutorial/testing.md +++ b/docs/tutorial/testing.md @@ -1,8 +1,8 @@ -Thanks to Starlette's TestClient, testing **FastAPI** applications is easy and enjoyable. +Thanks to Starlette's TestClient, testing **FastAPI** applications is easy and enjoyable. -It is based on Requests, so it's very familiar and intuitive. +It is based on Requests, so it's very familiar and intuitive. -With it, you can use pytest directly with **FastAPI**. +With it, you can use pytest directly with **FastAPI**. ## Using `TestClient` @@ -21,7 +21,7 @@ Write simple `assert` statements with the standard Python expressions that you n ``` !!! tip - Notice that the testing functions are normal `def`, not `async def`. + Notice that the testing functions are normal `def`, not `async def`. And the calls to the client are also normal calls, not using `await`. @@ -87,7 +87,7 @@ E.g.: * To pass *headers*, use a `dict` in the `headers` parameter. * For *cookies*, a `dict` in the `cookies` parameter. -For more information about how to pass data to the backend (using `requests` or the `TestClient`) check the Requests documentation. +For more information about how to pass data to the backend (using `requests` or the `TestClient`) check the Requests documentation. !!! info Note that the `TestClient` receives data that can be converted to JSON, not Pydantic models. diff --git a/docs/tutorial/using-request-directly.md b/docs/tutorial/using-request-directly.md index 1c00731eb..9a7b9d66d 100644 --- a/docs/tutorial/using-request-directly.md +++ b/docs/tutorial/using-request-directly.md @@ -13,7 +13,7 @@ But there are situations where you might need to access the `Request` object dir ## 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` 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` 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 annotated (with OpenAPI, for the automatic documentation) by FastAPI. @@ -52,4 +52,4 @@ Then declare a *path operation function* parameter with the type being the `Requ ## `Request` documentation -You can read more details about the `Request` object in the official Starlette documentation site. +You can read more details about the `Request` object in the official Starlette documentation site. diff --git a/docs/tutorial/websockets.md b/docs/tutorial/websockets.md index 16bba8ee3..aae5f2be2 100644 --- a/docs/tutorial/websockets.md +++ b/docs/tutorial/websockets.md @@ -1,5 +1,5 @@ -You can use WebSockets with **FastAPI**. +You can use WebSockets with **FastAPI**. ## WebSockets client @@ -68,18 +68,17 @@ They work the same way as for other FastAPI endpoints/*path operations*: !!! info In a WebSocket it doesn't really make sense to raise an `HTTPException`. So it's better to close the WebSocket connection directly. - You can use a closing code from the valid codes defined in the specification. + You can use a closing code from the valid codes defined in the specification. - In the future, there will be a `WebSocketException` that you will be able to `raise` from anywhere, and add exception handlers for it. It depends on the PR #527 in Starlette. + In the future, there will be a `WebSocketException` that you will be able to `raise` from anywhere, and add exception handlers for it. It depends on the PR #527 in Starlette. ## More info To learn more about the options, check Starlette's documentation for: -* Applications (`websocket_route`). -* The `WebSocket` class. -* Class-based WebSocket handling. - +* Applications (`websocket_route`). +* The `WebSocket` class. +* Class-based WebSocket handling. ## Test it @@ -89,7 +88,7 @@ If your file is named `main.py`, run your application with: uvicorn main:app --reload ``` -Open your browser at http://127.0.0.1:8000. +Open your browser at http://127.0.0.1:8000. You will see a simple page like: