🔖 Release 0.7.1, Raspberry Pi deployment and docs

* Furether technical details towards #33.

* 📝 Update note about previous async frameworks

.gitignore

@@ -10,3 +10,4 @@ site
 .coverage
 coverage.xml
 .netlify
+test.db

.travis.yml

@@ -15,3 +15,9 @@ script:
 
 after_script:
     - bash <(curl -s https://codecov.io/bash)
+
+deploy:
+  provider: script
+  script: bash scripts/trigger-docker.sh
+  on:
+    branch: master

Pipfile

@@ -24,7 +24,7 @@ python-multipart = "*"
 sqlalchemy = "*"
 
 [packages]
-starlette = "==0.10.1"
+starlette = "==0.11.1"
 pydantic = "==0.18.2"
 
 [requires]

Pipfile.lock

@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "37b34bb892b6b4dc0f7c941434d0e08199aa7a7ca83efb6294b89ace44168bba"
+            "sha256": "6b55a2dcce8b6bd5a1be8f170acb18478149218a01d1b026981a6297800cd3fa"
         },
         "pipfile-spec": 6,
         "requires": {
@@ -34,10 +34,10 @@
         },
         "starlette": {
             "hashes": [
-                "sha256:7cc05c33d00db3b2ddfd7516a737544ed0a34c9dd0ced94076f29b581ce4f532"
+                "sha256:9d48b35d1fc7521d59ae53c421297ab3878d3c7cd4b75266d77f6c73cccb78bb"
             ],
             "index": "pypi",
-            "version": "==0.10.1"
+            "version": "==0.11.1"
         }
     },
     "develop": {
@@ -199,11 +199,11 @@
         },
         "flake8": {
             "hashes": [
-                "sha256:c3ba1e130c813191db95c431a18cb4d20a468e98af7a77e2181b68574481ad36",
-                "sha256:fd9ddf503110bf3d8b1d270e8c673aab29ccb3dd6abf29bae1f54e5116ab4a91"
+                "sha256:6d8c66a65635d46d54de59b027a1dda40abbe2275b3164b634835ac9c13fd048",
+                "sha256:6eab21c6e34df2c05416faa40d0c59963008fff29b6f0ccfe8fa28152ab3e383"
             ],
             "index": "pypi",
-            "version": "==3.7.5"
+            "version": "==3.7.6"
         },
         "flit": {
             "hashes": [
@@ -229,11 +229,11 @@
         },
         "ipython": {
             "hashes": [
-                "sha256:6a9496209b76463f1dec126ab928919aaf1f55b38beb9219af3fe202f6bbdd12",
-                "sha256:f69932b1e806b38a7818d9a1e918e5821b685715040b48e59c657b3c7961b742"
+                "sha256:06de667a9e406924f97781bda22d5d76bfb39762b678762d86a466e63f65dc39",
+                "sha256:5d3e020a6b5f29df037555e5c45ab1088d6a7cf3bd84f47e0ba501eeb0c3ec82"
             ],
             "markers": "python_version >= '3.3'",
-            "version": "==7.2.0"
+            "version": "==7.3.0"
         },
         "ipython-genutils": {
             "hashes": [
@@ -387,17 +387,18 @@
         },
         "mkdocs-material": {
             "hashes": [
-                "sha256:4b4af83c704d2bab41be3a5228e800a5e1157003368fbf548d95073ce19e0f61",
-                "sha256:86c0042c803586985bf79c99962ebd4644c3f0ff095d5df541f09fa48f5b62cc"
+                "sha256:63c49a7020e5d187d5adcd441b259e0b81ad418599b22e2c2574b419ed833851",
+                "sha256:90a240f268f182a96098490d35bb75d5efc86b2f67d63a82b8750da20a72ef60"
             ],
             "index": "pypi",
-            "version": "==3.3.0"
+            "version": "==4.0.1"
         },
         "more-itertools": {
             "hashes": [
                 "sha256:0125e8f60e9e031347105eb1682cef932f5e97d7b9a1a28d9bf00c22a5daef40",
                 "sha256:590044e3942351a1bdb1de960b739ff4ce277960f2425ad4509446dbace8d9d1"
             ],
+            "markers": "python_version > '2.7'",
             "version": "==6.0.0"
         },
         "mypy": {
@@ -444,10 +445,10 @@
         },
         "parso": {
             "hashes": [
-                "sha256:6ecf7244be8e7283ec9009c72d074830e7e0e611c974f813d76db0390a4e0dd6",
-                "sha256:8162be7570ffb34ec0b8d215d7f3b6c5fab24f51eb3886d6dee362de96b6db94"
+                "sha256:4580328ae3f548b358f4901e38c0578229186835f0fa0846e47369796dd5bcc9",
+                "sha256:68406ebd7eafe17f8e40e15a84b56848eccbf27d7c1feb89e93d8fca395706db"
             ],
-            "version": "==0.3.3"
+            "version": "==0.3.4"
         },
         "pexpect": {
             "hashes": [
@@ -536,11 +537,11 @@
         },
         "pytest": {
             "hashes": [
-                "sha256:65aeaa77ae87c7fc95de56285282546cfa9c886dc8e5dc78313db1c25e21bc07",
-                "sha256:6ac6d467d9f053e95aaacd79f831dbecfe730f419c6c7022cb316b365cd9199d"
+                "sha256:067a1d4bf827ffdd56ad21bd46674703fce77c5957f6c1eef731f6146bfcef1c",
+                "sha256:9687049d53695ad45cf5fdc7bbd51f0c49f1ea3ecfc4b7f3fde7501b541f17f4"
             ],
             "index": "pypi",
-            "version": "==4.2.0"
+            "version": "==4.3.0"
         },
         "pytest-cov": {
             "hashes": [
@@ -582,33 +583,23 @@
         },
         "pyzmq": {
             "hashes": [
-                "sha256:25a0715c8f69cf72f67cfe5a68a3f3ed391c67c063d2257bec0fe7fc2c7f08f8",
-                "sha256:2bab63759632c6b9e0d5bf19cc63c3b01df267d660e0abcf230cf0afaa966349",
-                "sha256:30ab49d99b24bf0908ebe1cdfa421720bfab6f93174e4883075b7ff38cc555ba",
-                "sha256:32c7ca9fc547a91e3c26fc6080b6982e46e79819e706eb414dd78f635a65d946",
-                "sha256:41219ae72b3cc86d97557fe5b1ef5d1adc1057292ec597b50050874a970a39cf",
-                "sha256:4b8c48a9a13cea8f1f16622f9bd46127108af14cd26150461e3eab71e0de3e46",
-                "sha256:55724997b4a929c0d01b43c95051318e26ddbae23565018e138ae2dc60187e59",
-                "sha256:65f0a4afae59d4fc0aad54a917ab599162613a761b760ba167d66cc646ac3786",
-                "sha256:6f88591a8b246f5c285ee6ce5c1bf4f6bd8464b7f090b1333a446b6240a68d40",
-                "sha256:75022a4c60dcd8765bb9ca32f6de75a0ec83b0d96e0309dc479f4c7b21f26cb7",
-                "sha256:76ea493bfab18dcb090d825f3662b5612e2def73dffc196d51a5194b0294a81d",
-                "sha256:7b60c045b80709e4e3c085bab9b691e71761b44c2b42dbb047b8b498e7bc16b3",
-                "sha256:8e6af2f736734aef8ed6f278f9f552ec7f37b1a6b98e59b887484a840757f67d",
-                "sha256:9ac2298e486524331e26390eac14e4627effd3f8e001d4266ed9d8f1d2d31cce",
-                "sha256:9ba650f493a9bc1f24feca1d90fce0e5dd41088a252ac9840131dfbdbf3815ca",
-                "sha256:a02a4a385e394e46012dc83d2e8fd6523f039bb52997c1c34a2e0dd49ed839c1",
-                "sha256:a3ceee84114d9f5711fa0f4db9c652af0e4636c89eabc9b7f03a3882569dd1ed",
-                "sha256:a72b82ac1910f2cf61a49139f4974f994984475f771b0faa730839607eeedddf",
-                "sha256:ab136ac51027e7c484c53138a0fab4a8a51e80d05162eb7b1585583bcfdbad27",
-                "sha256:c095b224300bcac61e6c445e27f9046981b1ac20d891b2f1714da89d34c637c8",
-                "sha256:c5cc52d16c06dc2521340d69adda78a8e1031705924e103c0eb8fc8af861d810",
-                "sha256:d612e9833a89e8177f8c1dc68d7b4ff98d3186cd331acd616b01bbdab67d3a7b",
-                "sha256:e828376a23c66c6fe90dcea24b4b72cd774f555a6ee94081670872918df87a19",
-                "sha256:e9767c7ab2eb552796440168d5c6e23a99ecaade08dda16266d43ad461730192",
-                "sha256:ebf8b800d42d217e4710d1582b0c8bff20cdcb4faad7c7213e52644034300924"
+                "sha256:15f0bf7cd80020f165635595e197603aedb37fddf4164ad5ae226afc43242f7b",
+                "sha256:1756dc72e192c670490e38c788c3a35f901adc74ee436e5131d5a3e85fdd7dc6",
+                "sha256:1d1eb490da54679d724b08ef3ee04530849023670c4ba7e400ed2cdf906720c4",
+                "sha256:228402625796821f08706f58cc42a3c51c9897d723550babaefe4feec2b6dacc",
+                "sha256:3928534fa00a2aabfcfdb439c08ba37fbe99ab0cf57776c8db8d2b73a51693ba",
+                "sha256:3d2a295b1086d450981f73d3561ac204a0cc9c8ded386a4a34327d918f3b1d0a",
+                "sha256:4fd8621a309db6ec23ef1369f43cdf7a9b0dc217d8ff9ca4095a6e932b379bda",
+                "sha256:54fe55a1694ffe608c8e4c5183e83cab7a91f3e5c84bd6f188868d6676c12aba",
+                "sha256:618887be4ad754228c0cbba7631f6574608b4430fe93974e6322324f1304fdac",
+                "sha256:69130efb6efa936de601cb135a8a4eec1caccd4ea2b784237145ff4075c2d3ae",
+                "sha256:6e7f78eeac82140bde7e60e975c6e6b1b678a4dd377782ab63319c1c78bf3aa1",
+                "sha256:6ee760cdb84e43574da6b3f2f1fc1251e8acf87253900d28a06451c5f5de39e9",
+                "sha256:97cb1b7cd2c46e87b0a26651eccd2bbb8c758035efd1635ebb81ac36aa76a88c",
+                "sha256:abfa774dbadacc849121ed92eae05189d226daab583388b499472e1bbb17ef69",
+                "sha256:b30c339eb58355f51f4f54dd61d785f1ff58c86bca1c3a5916977631d121867b"
             ],
-            "version": "==17.1.2"
+            "version": "==18.0.0"
         },
         "qtconsole": {
             "hashes": [

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="https://fastapi.tiangolo.com"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal-vector.svg" alt='FastAPI'></a>
+  <a href="https://fastapi.tiangolo.com"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" alt="FastAPI"></a>
 </p>
 <p align="center">
     <em>FastAPI framework, high performance, easy to learn, fast to code, ready for production</em>
@@ -344,7 +344,7 @@ For a more complete example including more features, see the <a href="https://fa
 
 ## Performance
 
-Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <a href="https://www.techempower.com/benchmarks/#section=test&runid=a979de55-980d-4721-a46f-77298b3f3923&hw=ph&test=fortune&l=zijzen-7" target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
+Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
 
 To understand more about it, see the section <a href="https://fastapi.tiangolo.com/benchmarks/" target="_blank">Benchmarks</a>.
 

docs/alternatives.md

@@ -123,7 +123,7 @@ There are several Flask REST frameworks, but after investing the time and work i
 
 ### <a href="https://marshmallow.readthedocs.io/en/3.0/" target="_blank">Marshmallow</a>
 
-One of the main features needed by API systems is data "<abbr title="also called marshalling, convertion">serialization</abbr>" 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.
+One of the main features needed by API systems is data "<abbr title="also called marshalling, conversion">serialization</abbr>" 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.
 
 Another big feature needed by APIs is data validation, making sure that the data is valid, given certain parameters. For example, that some field is an `int`, and not some random string. This is especially useful for incoming data.
 
@@ -365,7 +365,7 @@ It is the recommended server for Starlette and **FastAPI**.
 !!! check "**FastAPI** recommends it as"
     The main web server to run **FastAPI** applications.
 
-    You can combine it with Gunicorn, to have an asynchronous multiprocess server.
+    You can combine it with Gunicorn, to have an asynchronous multi-process server.
 
     Check more details in the <a href="/deployment/" target="_blank">Deployment</a> section.
 

docs/async.md

@@ -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, <a href="https://docs.python.org/3/library/asyncio-task.html#coroutine" target="_blank">check the official Python docs</a>
+But if you want to use `async` / `await` without FastAPI, <a href="https://docs.python.org/3/library/asyncio-task.html#coroutine" target="_blank">check the official Python docs</a>.
 
 
 ### Other forms of asynchronous code
@@ -362,3 +362,43 @@ Let's see the same phrase from above:
 That should make more sense now.
 
 All that is what powers FastAPI (through Starlette) and what makes it have such an impressive performance.
+
+
+## Very Technical Details
+
+!!! warning
+    You can probably skip this.
+    
+    These are very technical details of how **FastAPI** works underneath.
+    
+    If you have quite some technical knowledge (co-routines, threads, blocking, etc) and are curious about how FastAPI handles `async def` vs normal `def`, go ahead.
+
+### Path operation functions
+
+When you declare a *path operation function* with normal `def` instead of `async def`, it is run in an external threadpool that is then awaited, instead of being called directly (as it would block the server).
+
+If you are coming from another async framework that does not work in the way described above and you are used to define trivial compute-only *path operation functions* with plain `def` for a tiny performance gain (about 100 nanoseconds), please note that in **FastAPI** the effect would be quite opposite. In these cases, it's better to use `async def` unless your *path operation functions* use code that performs blocking <abbr title="Input/Output: disk reading or writing, network communications.">IO</abbr>.
+
+Still, in both situations, chances are that **FastAPI** will <a href="https://fastapi.tiangolo.com/#performance" target="_blank">still be faster</a> than (or at least comparable to) your previous framework.
+
+### Dependencies
+
+The same applies for dependencies. If a dependency is a standard `def` function instead of `async def`, it is run in the external threadpool.
+
+### Sub-dependencies
+
+You can have multiple dependencies and sub-dependencies requiring each other (as parameters of the function definitions), some of them might be created with `async def` and some with normal `def`. It would still work, and the ones created with normal `def` would be called on an external thread instead of being "awaited".
+
+### Other utility functions
+
+Any other utility function that you call directly can be created with normal `def` or `async def` and FastAPI won't affect the way you call it.
+
+This is in contrast to the functions that FastAPI calls for you: *path operation functions* and dependencies.
+
+If your utility function is a normal function with `def`, it will be called directly (as you write it in your code), not in a threadpool, if the function is created with `async def` then you should await for that function when you call it in your code.
+
+---
+
+Again, these are very technical details that would probably be useful if you came searching for them.
+
+Otherwise, you should be good with the guidelines from the section above: <a href="#in-a-hurry">In a hurry?</a>.

docs/contributing.md

@@ -0,0 +1,123 @@
+First, you might want to see the basic ways to <a href="https://fastapi.tiangolo.com/help-fastapi/" target="_blank">help FastAPI and get help</a>.
+
+## Developing
+
+If you already cloned the repository and you know that you need to deep dive in the code, here are some guidelines to set up your environment.
+
+
+### Pipenv
+
+If you are using <a href="https://pipenv.readthedocs.io/en/latest/" target="_blank">Pipenv</a>, you can create a virtual environment and install the packages with:
+
+```bash
+pipenv install --dev
+```
+
+Then you can activate that virtual environment with:
+
+```bash
+pipenv shell
+```
+
+
+### No Pipenv
+
+If you are not using Pipenv, you can create a virtual environment with your preferred tool, and install the packages listed in the file `Pipfile`.
+
+
+### Flit
+
+**FastAPI** uses <a href="https://flit.readthedocs.io/en/latest/index.html" target="_blank">Flit</a> to build, package and publish the project.
+
+If you installed the development dependencies with one of the methods above, you already have the `flit` command.
+
+To install your local version of FastAPI as a package in your local environment, run:
+
+```bash
+flit install --symlink
+```
+
+It will install your local FastAPI in your local environment.
+
+
+#### Using your local FastAPI
+
+If you create a Python file that imports and uses FastAPI, and run it with the Python from your local environment, it will use your local FastAPI source code.
+
+And if you update that local FastAPI source code, as it is installed with `--symlink`, when you run that Python file again, it will use the fresh version of FastAPI you just edited.
+
+That way, you don't have to "install" your local version to be able to test every change.
+
+
+### Format
+
+There is a script that you can run that will format and clean all your code:
+
+```bash
+bash scripts/lint.sh
+```
+
+It will also auto-sort all your imports.
+
+For it to sort them correctly, you need to have FastAPI installed locally in your environment, with the command in the section above:
+
+```bash
+flit install --symlink
+```
+
+
+### Docs
+
+The documentation uses <a href="https://www.mkdocs.org/" target="_blank">MkDocs</a>.
+
+All the documentation is in Markdown format in the directory `./docs`.
+
+Many of the tutorials have blocks of code.
+
+In most of the cases, these blocks of code are actual complete applications that can be run as is.
+
+In fact, those blocks of code are not written inside the Markdown, they are Python files in the `./docs/src/` directory.
+
+And those Python files are included/injected in the documentation when generating the site.
+
+
+#### Docs for tests
+
+Most of the tests actually run against the example source files in the documentation.
+
+This helps making sure that:
+
+* The documentation is up to date.
+* The documentation examples can be run as is.
+* Most of the features are covered by the documentation, ensured by the coverage tests.
+
+During local development, there is a script that builds the site and checks for any changes, live-reloading:
+
+```bash
+bash scripts/docs-live.sh
+```
+
+It will serve the documentation on `http://0.0.0.0:8008`.
+
+That way, you can edit the documentation/source files and see the changes live.
+
+#### Apps and docs at the same time
+
+And if you run the examples with, e.g.:
+
+```bash
+uvicorn tutorial001:app --debug
+```
+
+as Uvicorn by default will use the port `8000`, the documentation on port `8008` won't clash.
+
+
+### Tests
+
+There is a script that you can run locally to test all the code and generate coverage reports in HTML:
+
+```bash
+bash scripts/test-cov-html.sh
+```
+
+This command generates a directory `./htmlcov/`, if you open the file `./htmlcov/index.html` in your browser, you can explore interactively the regions of code that are covered by the tests, and notice if there is any region missing.

docs/deployment.md

@@ -26,7 +26,7 @@ But you can still change and update all the configurations with environment vari
     To see all the configurations and options, go to the Docker image page: <a href="https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker" target="_blank">tiangolo/uvicorn-gunicorn-fastapi</a>.
 
 
-### Build your Image
+### Create a `Dockerfile`
 
 * Go to your project directory.
 * Create a `Dockerfile` with:
@@ -37,6 +37,37 @@ FROM tiangolo/uvicorn-gunicorn-fastapi:python3.7
 COPY ./app /app
 ```
 
+#### Bigger Applications
+
+If you followed the section about creating <a href="" target="_blank">Bigger Applications with Multiple Files
+</a>, your `Dockerfile` might instead look like:
+
+```Dockerfile
+FROM tiangolo/uvicorn-gunicorn-fastapi:python3.7
+
+COPY ./app /app/app
+```
+
+#### Raspberry Pi and other architectures
+
+If you are running Docker in a Raspberry Pi (that has an ARM processor) or any other architecture, you can create a `Dockerfile` from scratch, based on a Python base image (that is multi-architecture) and use Uvicorn alone.
+
+In this case, your `Dockerfile` could look like:
+
+```Dockerfile
+FROM python:3.7
+
+RUN pip install fastapi uvicorn
+
+EXPOSE 80
+
+COPY ./app /app
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]
+```
+
+### Create the **FastAPI** Code
+
 * Create an `app` directory and enter in it.
 * Create a `main.py` file with:
 
@@ -65,6 +96,8 @@ def read_item(item_id: int, q: str = None):
 └── Dockerfile
 ```
 
+### Build the Docker image
+
 * Go to the project directory (in where your `Dockerfile` is, containing your `app` directory).
 * Build your FastAPI image:
 
@@ -72,6 +105,8 @@ def read_item(item_id: int, q: str = None):
 docker build -t myimage .
 ```
 
+### Start the Docker container
+
 * Run a container based on your image:
 
 ```bash
@@ -145,7 +180,7 @@ Now, from a developer's perspective, here are several things to have in mind whi
     * It goes encrypted, but the encrypted contents are the same HTTP protocol.
 
 
-It is a common practice to have one program/HTTP server runing in 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 ofter called a <a href="https://en.wikipedia.org/wiki/TLS_termination_proxy" target="_blank">TLS Termination Proxy</a>.
+It is a common practice to have one program/HTTP server running in 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 ofter called a <a href="https://en.wikipedia.org/wiki/TLS_termination_proxy" target="_blank">TLS Termination Proxy</a>.
 
 
 ### Let's Encrypt

docs/features.md

@@ -71,7 +71,7 @@ my_second_user: User = User(**second_user_data)
 
 ### Editor support
 
-All the framework was designed to be easy and intuitive to use, all the decisons where tested on multiple editors even before starting development, to ensure the best development experience.
+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 <a href="https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features" target="_blank">that the most used feature is "autocompletion"</a>. 
 
@@ -89,7 +89,7 @@ Here's how your editor might help you:
 
 ![editor support](img/pycharm-completion.png)
 
-You will get completion in code you might even consider imposible before. As for example, the `price` key inside a JSON body (that could have been nested) that comes from a request.
+You will get completion in code you might even consider impossible before. As for example, the `price` key inside a JSON body (that could have been nested) that comes from a request.
 
 No more typing the wrong key names, coming back and forth between docs, or scrolling up and down to find if you finally used `username` or `user_name`.
 
@@ -201,4 +201,4 @@ With **FastAPI** you get all of **Pydantic**'s features (as FastAPI is based on
     * You can have deeply **nested JSON** objects and have them all validated and annotated.
 * **Extendible**:
     * Pydantic allows custom data types to be defined or you can extend validation with methods on a model decorated with the validator decorator.
-* 100% test coverage.
+* 100% test coverage.

docs/help-fastapi.md

@@ -0,0 +1,100 @@
+Are you liking **FastAPI**?
+
+Would you like to help FastAPI, other users, and the author?
+
+Or would you like to get help with **FastAPI**?
+
+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): <a href="https://github.com/tiangolo/fastapi" target="_blank">https://github.com/tiangolo/fastapi</a>.
+
+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): <a href="https://github.com/tiangolo/fastapi" target="_blank">https://github.com/tiangolo/fastapi</a>.
+
+There you can select "Releases only".
+
+Doing it, you will receive notifications (in your email) whenever there's a new release (a new version) of **FastAPI** with bug fixes and new features.
+
+
+## Connect with the author
+
+You can connect with me (Sebastián Ramírez / `tiangolo`), the author.
+
+You can:
+
+* <a href="https://github.com/tiangolo" target="_blank">Follow me on **GitHub**</a>.
+    * See other Open Source projects I have created that could help you.
+    * Follow me to see when I create a new Open Source project.
+* <a href="https://twitter.com/tiangolo" target="_blank">Follow me on **Twitter**</a>.
+    * Tell me how you use FastAPI (I love to hear that).
+    * Ask questions.
+* <a href="https://www.linkedin.com/in/tiangolo/" target="_blank">Connect with me on **Linkedin**</a>.
+    * Talk to me.
+    * Endorse me or recommend me :)
+* <a href="https://medium.com/@tiangolo" target="_blank">Read what I write (or follow me) on **Medium**</a>.
+    * Read other ideas, articles and tools I have created.
+    * Follow me to see when I publish something new.
+
+
+## Tweet about **FastAPI**
+
+<a href="http://twitter.com/home/?status=I'm loving FastAPI because... https://github.com/tiangolo/fastapi cc @tiangolo" target="_blank">Tweet about **FastAPI**</a> and let me and others why you like it.
+
+## Let me know how are you using **FastAPI**
+
+I love to hear about how **FastAPI** is being used, what have you liked in it, in which project/company are you using it, etc.
+
+You can let me know:
+
+* <a href="http://twitter.com/home/?status=Hey @tiangolo, I'm using FastAPI at..." target="_blank">On **Twitter**</a>.
+* <a href="https://www.linkedin.com/in/tiangolo/" target="_blank">On **Linkedin**</a>.
+* <a href="https://medium.com/@tiangolo" target="_blank">On **Medium**</a>.
+
+## Vote for FastAPI
+
+You can vote to include FastAPI in several "awesome lists":
+
+* <a href="https://github.com/vinta/awesome-python/pull/1209" target="_blank">Vote to include **FastAPI** in `awesome-python`</a>.
+* <a href="https://github.com/timofurrer/awesome-asyncio/pull/43" target="_blank">Vote to include **FastAPI** in `awesome-asyncio`</a>.
+
+## Help others with issues in GitHub
+
+You can see <a href="https://github.com/tiangolo/fastapi/issues" target="_blank">existing issues</a> and try and help others.
+
+## Watch the GitHub repository
+
+You can "watch" FastAPI in GitHub (clicking the "watch" button at the top right): <a href="https://github.com/tiangolo/fastapi" target="_blank">https://github.com/tiangolo/fastapi</a>.
+
+If you select "Watching" instead of "Releases only", you will receive notifications when someone creates a new issue.
+
+Then you can try and help them solving those issues.
+
+## Create issues
+
+You can <a href="https://github.com/tiangolo/fastapi/issues/new/choose" target="_blank">create a new issue</a> in the GitHub repository, for example to:
+
+* Report a bug/issue.
+* Suggest a new feature.
+* Ask a question.
+
+## Create a Pull Request
+
+You can <a href="https://github.com/tiangolo/fastapi" target="_blank">create a Pull Request</a>, for example:
+
+* To fix a typo you found on the documentation.
+* To propose new documentation sections.
+* To fix an existing issue/bug.
+* To add a new feature.
+
+---
+
+Thanks!

docs/history-design-future.md

@@ -0,0 +1,83 @@
+Some time ago, <a href="https://github.com/tiangolo/fastapi/issues/3#issuecomment-454956920" target="_blank">a **FastAPI** user asked</a>:
+
+> 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.
+
+As part of that, I needed to investigate, test and use many alternatives.
+
+The history of **FastAPI** is in great part the history of its predecessors.
+
+As said in the section <a href="https://fastapi.tiangolo.com/alternatives/" target="_blank">Alternatives</a>:
+
+<blockquote markdown="1">
+
+**FastAPI** wouldn't exist if not for the previous work of others.
+
+There have been many tools created before that have helped inspire its creation.
+
+I have been avoiding the creation of a new framework for several years. First I tried to solve all the features covered by **FastAPI** using many different frameworks, plug-ins, and tools.
+
+But at some point, there was no other option than creating something that provided all these features, taking the best ideas from previous tools, and combining them in the best way possible, using language features that weren't even available before (Python 3.6+ type hints).
+
+</blockquote>
+
+
+## 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.
+
+For example, it was clear that ideally it should be based on standard Python type hints.
+
+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 <a href="https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools" target="_blank">Python Developer Survey</a>, 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.
+
+That way I could find the best ways to reduce code duplication as much as possible, to have completion everywhere, type and error checks, etc.
+
+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 <a href="https://pydantic-docs.helpmanual.io/" target="_blank">**Pydantic**</a> 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 <a href="https://www.starlette.io/" target="_blank">**Starlette**</a>, 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.
+
+It is being chosen over previous alternatives for suiting many use cases better.
+
+Many developers and teams already depend on **FastAPI** for their projects (including me and my team).
+
+But still, there are many improvements and features to come.
+
+**FastAPI** has a great future ahead.
+
+And <a href="https://fastapi.tiangolo.com/help-fastapi/" target="_blank">your help</a> is greatly appreciated.

docs/index.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="https://fastapi.tiangolo.com"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal-vector.svg" alt='FastAPI'></a>
+  <a href="https://fastapi.tiangolo.com"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" alt="FastAPI"></a>
 </p>
 <p align="center">
     <em>FastAPI framework, high performance, easy to learn, fast to code, ready for production</em>
@@ -344,7 +344,7 @@ For a more complete example including more features, see the <a href="https://fa
 
 ## Performance
 
-Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <a href="https://www.techempower.com/benchmarks/#section=test&runid=a979de55-980d-4721-a46f-77298b3f3923&hw=ph&test=fortune&l=zijzen-7" target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
+Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
 
 To understand more about it, see the section <a href="https://fastapi.tiangolo.com/benchmarks/" target="_blank">Benchmarks</a>.
 

docs/project-generation.md

@@ -1,5 +1,56 @@
 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: <a href="https://github.com/tiangolo/full-stack-fastapi-postgresql" target="_blank">https://github.com/tiangolo/full-stack-fastapi-postgresql</a>
+
+### Features
+
+* Full **Docker** integration (Docker based).
+* Docker Swarm Mode deployment.
+* **Docker Compose** integration and optimization for local development
+* **Production ready** Python web server using Uvicorn and Gunicorn.
+* Python **[FastAPI](https://github.com/tiangolo/fastapi)** backend:
+    * **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic).
+    * **Intuitive**: Great editor support. <abbr title="also known as auto-complete, autocompletion, IntelliSense">Completion</abbr> everywhere. Less time debugging.
+    * **Easy**: Designed to be easy to use and learn. Less time reading docs.
+    * **Short**: Minimize code duplication. Multiple features from each parameter declaration.
+    * **Robust**: Get production-ready code. With automatic interactive documentation.
+    * **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <a href="https://github.com/OAI/OpenAPI-Specification" target="_blank">OpenAPI</a> and <a href="http://json-schema.org/" target="_blank">JSON Schema</a>.
+    * [**Many other features**](https://github.com/tiangolo/fastapi) including automatic validation, serialization, interactive documentation, authentication with OAuth2 JWT tokens, etc.
+* **Secure password** hashing by default.
+* **JWT token** authentication.
+* **SQLAlchemy** models (independent of Flask extensions, so they can be used with Celery workers directly).
+* Basic starting models for users (modify and remove as you need).
+* **Alembic** migrations.
+* **CORS** (Cross Origin Resource Sharing).
+* **Celery** worker that can import and use models and code from the rest of the backend selectively (you don't have to install the complete app in each worker).
+* REST backend tests based on **Pytest**, integrated with Docker, so you can test the full API interaction, independent on the database. As it runs in Docker, it can build a new data store from scratch each time (so you can use ElasticSearch, MongoDB, CouchDB, or whatever you want, and just test that the API works).
+* Easy Python integration with **Jupyter Kernels** for remote or in-Docker development with extensions like Atom Hydrogen or Visual Studio Code Jupyter.
+* **Vue** frontend:
+    * Generated with Vue CLI.
+    * **JWT Authentication** handling.
+    * Login view.
+    * After login, main dashboard view.
+    * Main dashboard with user creation and edition.
+    * Self user edition.
+    * **Vuex**.
+    * **Vue-router**.
+    * **Vuetify** for beautiful material design components.
+    * **TypeScript**.
+    * Docker server based on **Nginx** (configured to play nicely with Vue-router).
+    * Docker multi-stage building, so you don't need to save or commit compiled code.
+    * Frontend tests ran at build time (can be disabled too).
+    * Made as modular as possible, so it works out of the box, but you can re-generate with Vue CLI or create it as you need, and re-use what you want.
+* **PGAdmin** for PostgreSQL database, you can modify it to use PHPMyAdmin and MySQL easily.
+* **Flower** for Celery jobs monitoring.
+* Load balancing between frontend and backend with **Traefik**, so you can have both under the same domain, separated by path, but served by different containers.
+* Traefik integration, including Let's Encrypt **HTTPS** certificates automatic generation.
+* GitLab **CI** (continuous integration), including frontend and backend testing.
+
+
+
 ## Full-Stack-FastAPI-Couchbase
 
 GitHub: <a href="https://github.com/tiangolo/full-stack-fastapi-couchbase" target="_blank">https://github.com/tiangolo/full-stack-fastapi-couchbase</a>
@@ -10,7 +61,17 @@ GitHub: <a href="https://github.com/tiangolo/full-stack-fastapi-couchbase" targe
 * Docker Swarm Mode deployment.
 * **Docker Compose** integration and optimization for local development.
 * **Production ready** Python web server using Uvicorn and Gunicorn.
-* Python **FastAPI** backend with all its features.
+* Python **[FastAPI](https://github.com/tiangolo/fastapi)** backend:
+    * **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic).
+    * **Intuitive**: Great editor support. <abbr title="also known as auto-complete, autocompletion, IntelliSense">Completion</abbr> everywhere. Less time debugging.
+    * **Easy**: Designed to be easy to use and learn. Less time reading docs.
+    * **Short**: Minimize code duplication. Multiple features from each parameter declaration.
+    * **Robust**: Get production-ready code. With automatic interactive documentation.
+    * **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <a href="https://github.com/OAI/OpenAPI-Specification" target="_blank">OpenAPI</a> and <a href="http://json-schema.org/" target="_blank">JSON Schema</a>.
+    * [**Many other features**](https://github.com/tiangolo/fastapi) including automatic validation, serialization, interactive documentation, authentication with OAuth2 JWT tokens, etc.
+* **Secure password** hashing by default.
+* **JWT token** authentication.
+* **CORS** (Cross Origin Resource Sharing).
 * **Celery** worker that can import and use code from the rest of the backend selectively (you don't have to install the complete app in each worker).
 * **NoSQL Couchbase** database that supports direct synchronization via Couchbase Sync Gateway for offline-first applications.
 * **Full Text Search** integrated, using Couchbase.
@@ -36,7 +97,7 @@ GitHub: <a href="https://github.com/tiangolo/full-stack-fastapi-couchbase" targe
     * Docker multi-stage building, so you don't need to save or commit compiled code.
     * Frontend tests ran at build time (can be disabled too).
     * Made as modular as possible, so it works out of the box, but you can re-generate with Vue CLI or create it as you need, and re-use what you want.
-* Flower for Celery jobs monitoring.
+* **Flower** for Celery jobs monitoring.
 * Load balancing between frontend and backend with **Traefik**, so you can have both under the same domain, separated by path, but served by different containers.
 * Traefik integration, including Let's Encrypt **HTTPS** certificates automatic generation.
 * GitLab **CI** (continuous integration), including frontend and backend testing.

docs/python-types.md

@@ -49,7 +49,7 @@ But then you have to call "that method that converts the first letter to upper c
 
 Was it `upper`? Was it `uppercase`? `first_uppercase`? `capitalize`?
 
-Then, you try with the old programer's friend, editor autocompletion.
+Then, you try with the old programmer's friend, editor autocompletion.
 
 You type the first parameter of the function, `first_name`, then a dot (`.`) and then hit `Ctrl+Space` to trigger the completion.
 

docs/release-notes.md

@@ -1,5 +1,67 @@
 ## Next
 
+## 0.7.1
+
+* Update <a href="https://fastapi.tiangolo.com/async/#path-operation-functions" target="_blank">technical details about `async def` handling</a> with respect to previous frameworks. PR <a href="https://github.com/tiangolo/fastapi/pull/64" target="_blank">#64</a> by <a href="https://github.com/haizaar" target="_blank">@haizaar</a>.
+
+* Add <a href="https://fastapi.tiangolo.com/deployment/#raspberry-pi-and-other-architectures" target="_blank">deployment documentation for Docker in Raspberry Pi</a> and other architectures.
+
+* Trigger Docker images build on Travis CI automatically. PR <a href="https://github.com/tiangolo/fastapi/pull/65" target="_blank">#65</a>.
+
+## 0.7.0
+
+* Add support for `UploadFile` in `File` parameter annotations.
+    * This includes a file-like interface.
+    * Here's the updated documentation for declaring <a href="https://fastapi.tiangolo.com/tutorial/request-files/#file-parameters-with-uploadfile" target="_blank"> `File` parameters with `UploadFile`</a>.
+    * And here's the updated documentation for using <a href="https://fastapi.tiangolo.com/tutorial/request-forms-and-files/" target="_blank">`Form` parameters mixed with `File` parameters, supporting `bytes` and `UploadFile`</a> at the same time.
+    * PR <a href="https://github.com/tiangolo/fastapi/pull/63" target="_blank">#63</a>.
+
+## 0.6.4
+
+* Add <a href="https://fastapi.tiangolo.com/async/#very-technical-details" target="_blank">technical details about `async def` handling to docs</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/61" target="_blank">#61</a>.
+
+* Add docs for <a href="https://fastapi.tiangolo.com/tutorial/debugging/" target="_blank">Debugging FastAPI applications in editors</a>.
+
+* Clarify <a href="https://fastapi.tiangolo.com/deployment/#bigger-applications" target="_blank">Bigger Applications deployed with Docker</a>.
+
+* Fix typos in docs.
+
+* Add section about <a href="https://fastapi.tiangolo.com/history-design-future/" target="_blank">History, Design and Future</a>.
+
+* Add docs for using <a href="https://fastapi.tiangolo.com/tutorial/websockets/" target="_blank">WebSockets with **FastAPI**</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/62" target="_blank">#62</a>.
+
+## 0.6.3
+
+* Add Favicons to docs. PR <a href="https://github.com/tiangolo/fastapi/pull/53" target="_blank">#53</a>.
+
+## 0.6.2
+
+* Introduce new project generator based on FastAPI and PostgreSQL: <a href="https://github.com/tiangolo/full-stack-fastapi-postgresql" target="_blank">https://github.com/tiangolo/full-stack-fastapi-postgresql</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/52" target="_blank">#52</a>.
+
+* Update <a href="https://fastapi.tiangolo.com/tutorial/sql-databases/" target="_blank">SQL tutorial with SQLAlchemy, using `Depends` to improve editor support and reduce code repetition</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/52" target="_blank">#52</a>.
+
+* Improve middleware naming in tutorial for SQL with SQLAlchemy <a href="https://fastapi.tiangolo.com/tutorial/sql-databases/" target="_blank">https://fastapi.tiangolo.com/tutorial/sql-databases/</a>.
+
+## 0.6.1
+
+* Add docs for GraphQL: <a href="https://fastapi.tiangolo.com/tutorial/graphql/" target="_blank">https://fastapi.tiangolo.com/tutorial/graphql/</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/48" target="_blank">#48</a>.
+
+## 0.6.0
+
+* Update SQL with SQLAlchemy tutorial at <a href="https://fastapi.tiangolo.com/tutorial/sql-databases/" target="_blank">https://fastapi.tiangolo.com/tutorial/sql-databases/</a> using the new official `request.state`. PR <a href="https://github.com/tiangolo/fastapi/pull/45" target="_blank">#45</a>.
+
+* Upgrade Starlette to version `0.11.1` and add required compatibility changes. PR <a href="https://github.com/tiangolo/fastapi/pull/44" target="_blank">#44</a>.
+
+## 0.5.1
+
+* Add section about <a href="https://fastapi.tiangolo.com/help-fastapi/" target="_blank">helping and getting help with **FastAPI**</a>.
+
+* Add note about <a href="https://fastapi.tiangolo.com/tutorial/path-params/#order-matters" target="_blank">path operations order in docs</a>.
+
+* Update <a href="https://fastapi.tiangolo.com/tutorial/handling-errors/" target="_blank">section about error handling</a> with more information and make relation with Starlette error handling utilities more explicit. PR <a href="https://github.com/tiangolo/fastapi/pull/41" target="_blank">#41</a>.
+
+* Add <a href="" target="_blank">Development - Contributing section to the docs</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/42" target="_blank">#42</a>.
+
 ## 0.5.0
 
 * Add new `HTTPException` with support for custom headers. With new documentation for handling errors at: <a href="https://fastapi.tiangolo.com/tutorial/handling-errors/" target="_blank">https://fastapi.tiangolo.com/tutorial/handling-errors/</a>. PR <a href="https://github.com/tiangolo/fastapi/pull/35" target="_blank">#35</a>.
@@ -12,7 +74,7 @@
 
 ## 0.4.0
 
-* Add `openapi_prefix`, support for reverse proxy and mounting sub-applicaitons. See the docs at <a href="https://fastapi.tiangolo.com/tutorial/sub-applications-proxy/" target="_blank">https://fastapi.tiangolo.com/tutorial/sub-applications-proxy/</a>: <a href="https://github.com/tiangolo/fastapi/pull/26" target="_blank">#26</a> by <a href="https://github.com/kabirkhan" target="_blank">@kabirkhan</a>.
+* Add `openapi_prefix`, support for reverse proxy and mounting sub-applications. See the docs at <a href="https://fastapi.tiangolo.com/tutorial/sub-applications-proxy/" target="_blank">https://fastapi.tiangolo.com/tutorial/sub-applications-proxy/</a>: <a href="https://github.com/tiangolo/fastapi/pull/26" target="_blank">#26</a> by <a href="https://github.com/kabirkhan" target="_blank">@kabirkhan</a>.
 
 * Update <a href="https://fastapi.tiangolo.com/tutorial/sql-databases/" target="_blank">docs/tutorial for SQLAlchemy</a> including note about *DB Browser for SQLite*.
 

docs/src/debugging/tutorial001.py

@@ -0,0 +1,15 @@
+import uvicorn
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+def root():
+    a = "a"
+    b = "b" + a
+    return {"hello world": b}
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)

docs/src/graphql/tutorial001.py

@@ -0,0 +1,14 @@
+import graphene
+from fastapi import FastAPI
+from starlette.graphql import GraphQLApp
+
+
+class Query(graphene.ObjectType):
+    hello = graphene.String(name=graphene.String(default_value="stranger"))
+
+    def resolve_hello(self, info, name):
+        return "Hello " + name
+
+
+app = FastAPI()
+app.add_route("/", GraphQLApp(schema=graphene.Schema(query=Query)))

docs/src/handling_errors/tutorial003.py

@@ -0,0 +1,15 @@
+from fastapi import FastAPI
+from starlette.exceptions import HTTPException
+from starlette.responses import PlainTextResponse
+
+app = FastAPI()
+
+
+@app.exception_handler(HTTPException)
+async def http_exception(request, exc):
+    return PlainTextResponse(str(exc.detail), status_code=exc.status_code)
+
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World"}

docs/src/path_params/tutorial003.py

@@ -1,10 +1,13 @@
-from uuid import UUID
-
 from fastapi import FastAPI
 
 app = FastAPI()
 
 
-@app.get("/items/{item_id}")
-async def read_item(item_id: UUID):
-    return {"item_id": item_id}
+@app.get("/users/me")
+async def read_user_me():
+    return {"user_id": "the current user"}
+
+
+@app.get("/users/{user_id}")
+async def read_user(user_id: str):
+    return {"user_id": user_id}

docs/src/request_files/tutorial001.py

@@ -1,8 +1,13 @@
-from fastapi import FastAPI, File
+from fastapi import FastAPI, File, UploadFile
 
 app = FastAPI()
 
 
 @app.post("/files/")
-async def create_file(*, file: bytes = File(...)):
+async def create_file(file: bytes = File(...)):
     return {"file_size": len(file)}
+
+
+@app.post("/uploadfile/")
+async def create_upload_file(file: UploadFile = File(...)):
+    return {"filename": file.filename}

docs/src/request_forms_and_files/tutorial001.py

@@ -1,8 +1,14 @@
-from fastapi import FastAPI, File, Form
+from fastapi import FastAPI, File, Form, UploadFile
 
 app = FastAPI()
 
 
 @app.post("/files/")
-async def create_file(*, file: bytes = File(...), token: str = Form(...)):
-    return {"file_size": len(file), "token": token}
+async def create_file(
+    file: bytes = File(...), fileb: UploadFile = File(...), token: str = Form(...)
+):
+    return {
+        "file_size": len(file),
+        "token": token,
+        "fileb_content_type": fileb.content_type,
+    }

docs/src/security/tutorial004.py

@@ -1,7 +1,7 @@
 from datetime import datetime, timedelta
 
 import jwt
-from fastapi import Depends, FastAPI, Security, HTTPException
+from fastapi import Depends, FastAPI, HTTPException, Security
 from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
 from jwt import PyJWTError
 from passlib.context import CryptContext

docs/src/sql_databases/tutorial001.py

@@ -1,7 +1,7 @@
-from fastapi import FastAPI
+from fastapi import Depends, FastAPI
 from sqlalchemy import Boolean, Column, Integer, String, create_engine
 from sqlalchemy.ext.declarative import declarative_base, declared_attr
-from sqlalchemy.orm import sessionmaker
+from sqlalchemy.orm import Session, sessionmaker
 from starlette.requests import Request
 
 # SQLAlchemy specific code, as with any other app
@@ -11,7 +11,7 @@ SQLALCHEMY_DATABASE_URI = "sqlite:///./test.db"
 engine = create_engine(
     SQLALCHEMY_DATABASE_URI, connect_args={"check_same_thread": False}
 )
-Session = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
 
 
 class CustomBase:
@@ -33,7 +33,7 @@ class User(Base):
 
 Base.metadata.create_all(bind=engine)
 
-db_session = Session()
+db_session = SessionLocal()
 
 first_user = db_session.query(User).first()
 if not first_user:
@@ -45,23 +45,28 @@ db_session.close()
 
 
 # Utility
-def get_user(db_session, user_id: int):
+def get_user(db_session: Session, user_id: int):
     return db_session.query(User).filter(User.id == user_id).first()
 
 
+# Dependency
+def get_db(request: Request):
+    return request.state.db
+
+
 # FastAPI specific code
 app = FastAPI()
 
 
 @app.get("/users/{user_id}")
-def read_user(request: Request, user_id: int):
-    user = get_user(request._scope["db"], user_id=user_id)
+def read_user(user_id: int, db: Session = Depends(get_db)):
+    user = get_user(db, user_id=user_id)
     return user
 
 
 @app.middleware("http")
-async def close_db(request, call_next):
-    request._scope["db"] = Session()
+async def db_session_middleware(request: Request, call_next):
+    request.state.db = SessionLocal()
     response = await call_next(request)
-    request._scope["db"].close()
+    request.state.db.close()
     return response

docs/src/websockets/tutorial001.py

@@ -0,0 +1,53 @@
+from fastapi import FastAPI
+from starlette.responses import HTMLResponse
+from starlette.websockets import WebSocket
+
+app = FastAPI()
+
+html = """
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Chat</title>
+    </head>
+    <body>
+        <h1>WebSocket Chat</h1>
+        <form action="" onsubmit="sendMessage(event)">
+            <input type="text" id="messageText" autocomplete="off"/>
+            <button>Send</button>
+        </form>
+        <ul id='messages'>
+        </ul>
+        <script>
+            var ws = new WebSocket("ws://localhost:8000/ws");
+            ws.onmessage = function(event) {
+                var messages = document.getElementById('messages')
+                var message = document.createElement('li')
+                var content = document.createTextNode(event.data)
+                message.appendChild(content)
+                messages.appendChild(message)
+            };
+            function sendMessage(event) {
+                var input = document.getElementById("messageText")
+                ws.send(input.value)
+                input.value = ''
+                event.preventDefault()
+            }
+        </script>
+    </body>
+</html>
+"""
+
+
+@app.get("/")
+async def get():
+    return HTMLResponse(html)
+
+
+@app.websocket_route("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    await websocket.accept()
+    while True:
+        data = await websocket.receive_text()
+        await websocket.send_text(f"Message text was: {data}")
+    await websocket.close()

docs/tutorial/debugging.md

@@ -0,0 +1,87 @@
+You can connect the debugger in your editor, for example with Visual Studio Code or PyCharm.
+
+## Call `uvicorn`
+
+In your FastAPI application, import and run `uvicorn` directly:
+
+```Python hl_lines="1 15"
+{!./src/debugging/tutorial001.py!}
+```
+
+### About `__name__ == "__main__"`
+
+The main purpose of the `__name__ == "__main__"` is to have some code that is executed when your file is called with:
+
+```bash
+python myapp.py
+```
+
+but is not called when another file imports it, like in:
+
+```Python
+from myapp import app
+```
+
+#### More details
+
+Let's say your file is named `myapp.py`.
+
+If you run it with:
+
+```bash
+python myapp.py
+```
+
+then the internal variable `__name__` in your file, created automatically by Python, will have as value the string `"__main__"`.
+
+So, the section:
+
+```Python
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+will run.
+
+---
+
+This won't happen if you import that module (file).
+
+So, if you have another file `importer.py` with:
+
+```Python
+from myapp import app
+
+# Some more code
+```
+
+in that case, the automatic variable inside of `myapp.py` will not have the variable `__name__` with a value of `"__main__"`.
+
+So, the line:
+
+```Python
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
+will not be executed.
+
+!!! info
+    For more information, check <a href="https://docs.python.org/3/library/__main__.html" target="_blank">the official Python docs</a>.
+
+## Run your code with your debugger
+
+Because you are running the Uvicorn server directly from your code, you can call your Python program (your FastAPI application) directly form the debugger.
+
+---
+
+For example, in Visual Studio Code, you can:
+
+* Go to the "Debug" panel.
+* "Add configuration...".
+* Select "Python"
+* Run the debugger with the option "`Python: Current File (Integrated Terminal)`".
+
+It will then start the server with your **FastAPI** code, stop at your breakpoints, etc.
+
+Here's how it might look:
+
+<img src="/img/tutorial/debugging/image01.png">

docs/tutorial/extra-models.md

@@ -109,7 +109,7 @@ UserInDB(**user_in.dict())
 
 So, we get a Pydantic model from the data in another Pydantic model.
 
-#### Unrapping a `dict` and extra keywords
+#### Unwrapping a `dict` and extra keywords
 
 And then adding the extra keyword argument `hashed_password=hashed_password`, like in:
 

docs/tutorial/first-steps.md

@@ -69,7 +69,7 @@ A "schema" is a definition or description of something. Not the code that implem
 
 In this case, OpenAPI is a specification that dictates how to define a schema of your API.
 
-This OpenAPI schema would include your API paths, the posible parameters they take, etc.
+This OpenAPI schema would include your API paths, the possible parameters they take, etc.
 
 #### Data "schema"
 

docs/tutorial/graphql.md

@@ -0,0 +1,44 @@
+
+**FastAPI** has optional support for GraphQL (provided by Starlette directly), using the `graphene` library.
+
+You can combine normal FastAPI path operations with GraphQL on the same application.
+
+## Import and use `graphene`
+
+GraphQL is implemented with Graphene, you can check <a href="https://docs.graphene-python.org/en/latest/quickstart/" target="_blank">Graphene's docs</a> for more details.
+
+Import `graphene` and define your GraphQL data:
+
+```Python hl_lines="1 6 7 8 9 10"
+{!./src/graphql/tutorial001.py!}
+```
+
+## Add Starlette's `GraphQLApp`
+
+Then import and add Starlette's `GraphQLApp`:
+
+```Python hl_lines="3 14"
+{!./src/graphql/tutorial001.py!}
+```
+
+!!! info
+    Here we are using `.add_route`, that is the way to add a route in Starlette (inherited by FastAPI) without declaring the specific operation (as would be with `.get()`, `.post()`, etc).
+
+## Check it
+
+Run it with Uvicorn and open your browser at <a href="http://127.0.0.1:8000" target="_blank">http://127.0.0.1:8000</a>.
+
+You will see GraphiQL web user interface:
+
+<img src="/img/tutorial/graphql/image01.png">
+
+
+## More details
+
+For more details, including:
+
+* Accessing request information
+* Adding background tasks
+* Using normal or async functions
+
+check the official <a href="https://www.starlette.io/graphql/" target="_blank">Starlette GraphQL docs</a>.

docs/tutorial/handling-errors.md

@@ -43,6 +43,31 @@ In this example, when the client request an item by an ID that doesn't exist, ra
 {!./src/handling_errors/tutorial001.py!}
 ```
 
+### The resulting response
+
+If the client requests `http://example.com/items/foo` (an `item_id` `"foo"`), he will receive an HTTP status code of 200, and a JSON response of:
+
+```JSON
+{
+  "item": "The Foo Wrestlers"
+}
+```
+
+But if the client requests `http://example.com/items/bar` (a non-existent `item_id` `"bar"`), he will receive an HTTP status code of 404 (the "not found" error), and a JSON response of:
+
+```JSON
+{
+  "detail": "Item not found"
+}
+```
+
+!!! tip
+    When raising an `HTTPException`, you can pass any value that can be converted to JSON as the parameter `detail`, not only `str`.
+
+    You could pass a `dict`, a `list`, etc.
+
+    They are handled automatically by **FastAPI** and converted to JSON.
+
 ### Adding custom headers
 
 There are some situations in where it's useful to be able to add custom headers to the HTTP error. For example, for some types of security.
@@ -55,3 +80,20 @@ But in case you needed it for an advanced scenario, you can add custom headers:
 ```Python hl_lines="14"
 {!./src/handling_errors/tutorial002.py!}
 ```
+
+### Installing custom handlers
+
+If you need to add other custom exception handlers, or override the default one (that sends the errors as JSON), you can use <a href="https://www.starlette.io/exceptions/" target="_blank">the same exception utilities from Starlette</a>.
+
+For example, you could override the default exception handler with:
+
+```Python hl_lines="2 3 8 9 10"
+{!./src/handling_errors/tutorial003.py!}
+```
+
+...this would make it return "plain text" responses with the errors, instead of JSON responses.
+
+!!! info
+    Note that in this example we set the exception handler with Starlette's `HTTPException` instead of FastAPI's `HTTPException`.
+
+    This would ensure that if you use a plug-in or any other third-party tool that raises Starlette's `HTTPException` directly, it will be caught by your exception handler.

docs/tutorial/intro.md

@@ -1,6 +1,6 @@
 This tutorial shows you how to use **FastAPI** with all its features, step by step.
 
-Eeach section gradually builds on the previous ones, but it's structured to separate topics, so that you can go directly to any specific one to solve your specific API needs.
+Each section gradually builds on the previous ones, but it's structured to separate topics, so that you can go directly to any specific one to solve your specific API needs.
 
 It is also built to work as a future reference.
 

docs/tutorial/path-params.md

@@ -98,6 +98,24 @@ You can use the same type declarations with `str`, `float`, `bool` and many othe
 
 These are explored in the next chapters of the tutorial.
 
+
+## Order matters
+
+When creating *path operations*, you can find situations where you have a fixed path.
+
+Like `/users/me`, let's say that it's to get data about the current user.
+
+And then you can also have a path `/users/{user_id}` to get data about a specific user by some user ID.
+
+Because path operations are evaluated in order, you need to make sure that the path for `/users/me` is declared before the one for `/users/{user_id}`:
+
+```Python hl_lines="6 11"
+{!./src/path_params/tutorial003.py!}
+```
+
+Otherwise, the path for `/users/{user_id}` would match also for `/users/me`, "thinking" that it's receiving a parameter `user_id` with a value of `"me"`.
+
+
 ## Recap
 
 With **FastAPI**, by using short, intuitive and standard Python type declarations, you get:

docs/tutorial/query-params-str-validations.md

@@ -1,4 +1,4 @@
-**FastAPI** allows you to declare additonal information and validation for your parameters.
+**FastAPI** allows you to declare additional information and validation for your parameters.
 
 Let's take this application as example:
 

docs/tutorial/request-files.md

@@ -2,7 +2,7 @@ You can define files to be uploaded by the client using `File`.
 
 ## Import `File`
 
-Import `File` from `fastapi`:
+Import `File` and `UploadFile` from `fastapi`:
 
 ```Python hl_lines="1"
 {!./src/request_files/tutorial001.py!}
@@ -16,14 +16,78 @@ Create file parameters the same way you would for `Body` or `Form`:
 {!./src/request_files/tutorial001.py!}
 ```
 
-The files will be uploaded as form data and you will receive the contents as `bytes`.
-
 !!! info
     `File` is a class that inherits directly from `Form`.
 
 !!! info
     To declare File bodies, you need to use `File`, because otherwise the parameters would be interpreted as query parameters or body (JSON) parameters.
 
+The files will be uploaded as "form data".
+
+If you declare the type of your *path operation function* parameter as `bytes`, **FastAPI** will read the file for you and you will receive the contents as `bytes`.
+
+Have in mind that this means that the whole contents will be stored in memory. This will work well for small files.
+
+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`:
+
+```Python hl_lines="12"
+{!./src/request_files/tutorial001.py!}
+```
+
+Using `UploadFile` has several advantages over `bytes`:
+
+* It uses a "spooled" file:
+    * 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. All without consuming all the memory.
+* You can get metadata from the uploaded file.
+* It has a <a href="https://docs.python.org/3/glossary.html#term-file-like-object" target="_blank">file-like</a> `async` interface.
+* It exposes an actual Python <a href="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile" target="_blank">`SpooledTemporaryFile`</a> object that you can pass directly to other libraries that expect a file-like object.
+
+
+### `UploadFile`
+
+`UploadFile` has the following attributes:
+
+* `filename`: A `str` with the original file name that was uploaded (e.g. `myimage.jpg`).
+* `content_type`: A `str` with the content type (MIME type / media type) (e.g. `image/jpeg`).
+* `file`: A <a href="https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile" target="_blank">`SpooledTemporaryFile`</a> (a <a href="https://docs.python.org/3/glossary.html#term-file-like-object" target="_blank">file-like</a> object). This is the actual Python file that you can pass directly to other functions or libraries that expect a "file-like" object.
+
+
+`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.
+* `read(size)`: Reads `size` (`int`) bytes/characters of the file.
+* `seek(offset)`: Goes to the byte position `offset` (`int`) in the file.
+    * E.g., `await myfile.seek(0)` would go to the start of the file.
+    * This is especially useful if you run `await myfile.read()` once and then need to read the contents again.
+* `close()`: Closes the file.
+
+As all these methods are `async` methods, you need to "await" them.
+
+For example, inside of an `async` *path operation function* you can get the contents with:
+
+```Python
+contents = await myfile.read()
+```
+
+If you are inside of a normal `def` *path operation function*, you can access the `UploadFile.file` directly, for example:
+
+```Python
+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"? 
 
 The way HTML forms (`<form></form>`) sends the data to the server normally uses a "special" encoding for that data, it's different from JSON.
@@ -35,7 +99,7 @@ The way HTML forms (`<form></form>`) 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 encondings and form fields, head to the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
+    If you want to read more about these encodings and form fields, head to the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
 
 
 !!! warning

docs/tutorial/request-forms-and-files.md

@@ -10,12 +10,14 @@ You can define files and form fields at the same time using `File` and `Form`.
 
 Create file and form parameters the same way you would for `Body` or `Query`:
 
-```Python hl_lines="7"
+```Python hl_lines="8"
 {!./src/request_forms_and_files/tutorial001.py!}
 ```
 
 The files and form fields will be uploaded as form data and you will receive the files and form fields.
 
+And you can declare some of the files as `bytes` and some as `UploadFile`.
+
 !!! warning
     You can declare multiple `File` and `Form` parameters in a path operation, but you can't also declare `Body` fields that you expect to receive as JSON, as the request will have the body encoded using `multipart/form-data` instead of `application/json`.
 

docs/tutorial/request-forms.md

@@ -39,7 +39,7 @@ The way HTML forms (`<form></form>`) 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 encondings and form fields, head to the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
+    If you want to read more about these encodings and form fields, head to the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> web docs for <code>POST</code></a>.
 
 
 !!! warning

docs/tutorial/response-model.md

@@ -40,7 +40,7 @@ And we are using this model to declare our input and the same model to declare o
 
 Now, whenever a browser is creating a user with a password, the API will return the same password in the response.
 
-In this case, it might not be a problem, becase the user himself is sending the password.
+In this case, it might not be a problem, because the user himself is sending the password.
 
 But if we use the same model for another path operation, we could be sending the passwords of our users to every client.
 

docs/tutorial/security/get-current-user.md

@@ -30,7 +30,7 @@ So, we can have sub-dependencies using `Security` too.
 
 `get_current_user` will have a `Security` dependency with the same `oauth2_scheme` we created before.
 
-The same as we were doing before in the path operation direclty, our new dependency will receive a `token` as a `str` from the `Security` dependency:
+The same as we were doing before in the path operation directly, our new dependency will receive a `token` as a `str` from the `Security` dependency:
 
 ```Python hl_lines="25"
 {!./src/security/tutorial002.py!}

docs/tutorial/security/simple-oauth2.md

@@ -24,14 +24,14 @@ The form field name is `scope` (in singular), but it is actually a long string w
 
 Each "scope" is just a string (without spaces).
 
-They are normally used to declare specific security permissions, for exampe:
+They are normally used to declare specific security permissions, for example:
 
 * `"users:read"` or `"users:write"` are common examples.
 * `instagram_basic` is used by Facebook / Instagram.
 * `https://www.googleapis.com/auth/drive` is used by Google.
 
 !!! info
-    In OAuth2 a "scope" is just a string that declares a specific permision required.
+    In OAuth2 a "scope" is just a string that declares a specific permission required.
 
     It doesn't matter if it has other characters like `:`, or if it is a URL.
     

docs/tutorial/sql-databases.md

@@ -16,6 +16,10 @@ 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: <a href="https://github.com/tiangolo/full-stack-fastapi-postgresql" target="_blank">https://github.com/tiangolo/full-stack-fastapi-postgresql</a>
+
+
 !!! note
     Notice that most of the code is the standard `SQLAlchemy` code you would use with any framework.
 
@@ -74,11 +78,17 @@ connect_args={"check_same_thread": False}
     That argument `check_same_thread` is there mainly to be able to run the tests that cover this example.
     
 
-## Create a `Session` class
+## Create a `SessionLocal` class
 
-Each instance of the `Session` class will have a connection to the database.
+Each instance of the `SessionLocal` class will have a connection to the database.
 
-This is not a connection to the database yet, but once we create an instance of this class, that instance will have the actual connection to the database.
+This object (class) is not a connection to the database yet, but once we create an instance of this class, that instance will have the actual connection to the database.
+
+We name it `SessionLocal` to distinguish it form the `Session` we are importing from SQLAlchemy.
+
+We will use `Session` to declare types later and getter better editor support and completion.
+
+For now, create the `SessionLocal`:
 
 ```Python hl_lines="14"
 {!./src/sql_databases/tutorial001.py!}
@@ -86,9 +96,9 @@ This is not a connection to the database yet, but once we create an instance of
 
 ## Create a middleware to handle sessions
 
-Now let's temporarily jump to the end of the file, to use the `Session` class we created above.
+Now let's temporarily jump to the end of the file, to use the `SessionLocal` class we created above.
 
-We need to have an independent `Session` per request, use the same session through all the request and then close it after the request is finished.
+We need to have an independent database session/connection (`SessionLocal`) per request, use the same session through all the request and then close it after the request is finished.
 
 And then a new session will be created for the next request.
 
@@ -96,21 +106,34 @@ For that, we will create a new middleware.
 
 A "middleware" is a function that is always executed for each request, and have code before and after the request.
 
-The middleware we will create (just a function) will create a new SQLAlchemy `Session` for each request, add it to the request and then close it once the request is finished.
+This middleware (just a function) will create a new SQLAlchemy `SessionLocal` for each request, add it to the request and then close it once the request is finished.
 
-```Python hl_lines="62 63 64 65 66 67"
+```Python hl_lines="67 68 69 70 71 72"
 {!./src/sql_databases/tutorial001.py!}
 ```
 
-### About `request._scope`
+### About `request.state`
 
-`request._scope` is a "private property" of each request. We normally shouldn't need to use a "private property" from a Python object.
+<a href="https://www.starlette.io/requests/#other-state" target="_blank">`request.state` is a property of each Starlette `Request` object</a>, it is there to store arbitrary objects attached to the request itself, like the database session in this case.
 
-But we need to attach the session to the request to be able to ensure a single session/database-connection is used through all the request, and then closed afterwards.
+For us in this case, it helps us ensuring a single session/database-connection is used through all the request, and then closed afterwards (in the middleware).
 
-In the near future, Starlette <a href="https://github.com/encode/starlette/issues/379" target="_blank">will have a way to attach custom objects to each request</a>.
+## Create a dependency
 
-When that happens, this tutorial will be updated to use the new official way of doing it.
+To simplify the code, reduce repetition and get better editor support, we will create a dependency that returns this same database session from the request.
+
+And when using the dependency in a path operation function, we declare it with the type `Session` we imported directly from SQLAlchemy.
+
+This will then give us better editor support inside the path operation function, because the editor will know that the `db` parameter is of type `Session`.
+
+```Python hl_lines="53 54 68"
+{!./src/sql_databases/tutorial001.py!}
+```
+
+!!! info "Technical Details"
+    The parameter `db` is actually of type `SessionLocal`, but this class (created with `sessionmaker()`) is a "proxy" of a SQLAlchemy `Session`, so, the editor doesn't really know what methods are provided.
+    
+    But by declaring the type as `Session`, the editor now can know the available methods (`.add()`, `.query()`, `.commit()`, etc) and can provide better support (like completion). The type declaration doesn't affect the actual object.
 
 ## Create a `CustomBase` model
 
@@ -184,7 +207,7 @@ Now, finally, here's the standard **FastAPI** code.
 
 Create your app and path operation function:
 
-```Python hl_lines="53 56 57 58 59"
+```Python hl_lines="58 61 62 63 64"
 {!./src/sql_databases/tutorial001.py!}
 ```
 
@@ -192,9 +215,13 @@ We are creating the database session before each request, attaching it to the re
 
 All of this is done in the middleware explained above.
 
-Because of that, we can use the `Request` to access the database session with `request._scope["db"]`.
+Then, in the dependency `get_db()` we are extracting the database session from the request.
 
-Then we can just call `get_user` directly from inside of the path operation function and use that session.
+And then we can create the dependency in the path operation function, to get that session directly.
+
+With that, we can just call `get_user` directly from inside of the path operation function and use that session.
+
+Having this 3-step process (middleware, dependency, path operation) in this simple example might seem like an overkill. But imagine if you had 20 or 100 path operations, doing this, you would be reducing a lot of code repetition, and getting better support/checks/completion in all those path operation functions.
 
 ## Create the path operation function
 
@@ -216,10 +243,13 @@ user = get_user(db_session, user_id=user_id)
 
 Then we should declare the path operation without `async def`, just with a normal `def`:
 
-```Python hl_lines="57"
+```Python hl_lines="62"
 {!./src/sql_databases/tutorial001.py!}
 ```
 
+!!! note "Very Technical Details"
+    If you are curious and have a deep technical knowledge, you can check <a href="https://fastapi.tiangolo.com/async/#very-technical-details" target="_blank">the very technical details of how this `async def` vs `def` is handled</a>.
+
 ## 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 <abbr title="Automatically updating the database to have any new column we define in our models.">migrations</abbr> with <a href="https://alembic.sqlalchemy.org" target="_blank">Alembic</a> directly.
@@ -270,7 +300,7 @@ That's something that you can improve in this example application, here's the cu
 }
 ```
 
-## Interact with the database direclty
+## 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 <a href="https://sqlitebrowser.org/" target="_blank">DB Browser for SQLite</a>.
 

docs/tutorial/using-request-directly.md

@@ -21,7 +21,7 @@ Although any other parameter declared normally (for example, the body with a Pyd
 
 But there are specific cases where it's useful to get the `Request` object.
 
-## Use the `Request` object direclty
+## Use the `Request` object directly
 
 Let's imagine you want to get the client's IP address/host inside of your *path operation function*.
 

docs/tutorial/websockets.md

@@ -0,0 +1,93 @@
+
+You can use <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API" target="_blank">WebSockets</a> with **FastAPI**.
+
+## WebSockets client
+
+### In production
+
+In your production system, you probably have a frontend created with a modern framework like React, Vue.js or Angular.
+
+And to communicate using WebSockets with your backend you would probably use your frontend's utilities.
+
+Or you might have a native mobile application that communicates with your WebSocket backend directly, in native code.
+
+Or you might have any other way to communicate with the WebSocket endpoint.
+
+---
+
+But for this example, we'll use a very simple HTML document with some JavaScript, all inside a long string.
+
+This, of course, is not optimal and you wouldn't use it for production.
+
+In production you would have one of the options above.
+
+But it's the simplest way to focus on the server-side of WebSockets and have a working example:
+
+```Python hl_lines="2 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 42 43 44"
+{!./src/websockets/tutorial001.py!}
+```
+
+## Create a `websocket_route`
+
+In your **FastAPI** application, create a `websocket_route`:
+
+```Python hl_lines="3 47 48"
+{!./src/websockets/tutorial001.py!}
+```
+
+!!! tip
+    In this example we are importing `WebSocket` from `starlette.websockets` to use it in the type declaration in the WebSocket route function.
+
+    That is not required, but it's recommended as it will provide you completion and checks inside the function.
+
+
+!!! info
+    This `websocket_route` we are using comes directly from <a href="https://www.starlette.io/applications/" target="_blank">Starlette</a>. 
+    
+    That's why the naming convention is not the same as with other API path operations (`get`, `post`, etc).
+
+
+## Await for messages and send messages
+
+In your WebSocket route you can `await` for messages and send messages.
+
+```Python hl_lines="49 50 51 52 53"
+{!./src/websockets/tutorial001.py!}
+```
+
+You can receive and send binary, text, and JSON data.
+
+To learn more about the options, check Starlette's documentation for:
+
+* <a href="https://www.starlette.io/applications/" target="_blank">Applications (`websocket_route`)</a>.
+* <a href="https://www.starlette.io/websockets/" target="_blank">The `WebSocket` class</a>.
+* <a href="https://www.starlette.io/endpoints/#websocketendpoint" target="_blank">Class-based WebSocket handling</a>.
+
+
+## Test it
+
+If your file is named `main.py`, run your application with:
+
+```bash
+uvicorn main:app --debug
+```
+
+Open your browser at <a href="http://127.0.0.1:8000" target="_blank">http://127.0.0.1:8000</a>.
+
+You will see a simple page like:
+
+<img src="/img/tutorial/websockets/image01.png">
+
+You can type messages in the input box, and send them:
+
+<img src="/img/tutorial/websockets/image02.png">
+
+And your **FastAPI** application with WebSockets will respond back:
+
+<img src="/img/tutorial/websockets/image03.png">
+
+You can send (and receive) many messages:
+
+<img src="/img/tutorial/websockets/image04.png">
+
+And all of them will use the same WebSocket connection.

fastapi/__init__.py

@@ -1,8 +1,9 @@
 """FastAPI framework, high performance, easy to learn, fast to code, ready for production"""
 
-__version__ = "0.5.0"
+__version__ = "0.7.1"
 
 from .applications import FastAPI
 from .routing import APIRouter
 from .params import Body, Path, Query, Header, Cookie, Form, File, Security, Depends
 from .exceptions import HTTPException
+from .datastructures import UploadFile

fastapi/applications.py

@@ -7,9 +7,9 @@ from pydantic import BaseModel
 from starlette.applications import Starlette
 from starlette.exceptions import ExceptionMiddleware, HTTPException
 from starlette.middleware.errors import ServerErrorMiddleware
-from starlette.middleware.lifespan import LifespanMiddleware
 from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
+from starlette.routing import BaseRoute
 
 
 async def http_exception(request: Request, exc: HTTPException) -> JSONResponse:
@@ -26,6 +26,7 @@ class FastAPI(Starlette):
     def __init__(
         self,
         debug: bool = False,
+        routes: List[BaseRoute] = None,
         template_directory: str = None,
         title: str = "Fast API",
         description: str = "",
@@ -37,14 +38,11 @@ class FastAPI(Starlette):
         **extra: Dict[str, Any],
     ) -> None:
         self._debug = debug
-        self.router: routing.APIRouter = routing.APIRouter()
+        self.router: routing.APIRouter = routing.APIRouter(routes)
         self.exception_middleware = ExceptionMiddleware(self.router, debug=debug)
         self.error_middleware = ServerErrorMiddleware(
             self.exception_middleware, debug=debug
         )
-        self.lifespan_middleware = LifespanMiddleware(self.error_middleware)
-        self.schema_generator = None
-        self.template_env = self.load_template_env(template_directory)
 
         self.title = title
         self.description = description

fastapi/datastructures.py

@@ -0,0 +1,15 @@
+from typing import Any, Callable, Iterable, Type
+
+from starlette.datastructures import UploadFile as StarletteUploadFile
+
+
+class UploadFile(StarletteUploadFile):
+    @classmethod
+    def __get_validators__(cls: Type["UploadFile"]) -> Iterable[Callable]:
+        yield cls.validate
+
+    @classmethod
+    def validate(cls: Type["UploadFile"], v: Any) -> Any:
+        if not isinstance(v, StarletteUploadFile):
+            raise ValueError(f"Expected UploadFile, received: {type(v)}")
+        return v

fastapi/dependencies/utils.py

@@ -17,6 +17,7 @@ from pydantic.fields import Field, Required, Shape
 from pydantic.schema import get_annotation_from_schema
 from pydantic.utils import lenient_issubclass
 from starlette.concurrency import run_in_threadpool
+from starlette.datastructures import UploadFile
 from starlette.requests import Headers, QueryParams, Request
 
 param_supported_types = (
@@ -323,6 +324,12 @@ async def request_body_to_args(
                 else:
                     values[field.name] = deepcopy(field.default)
                 continue
+            if (
+                isinstance(field.schema, params.File)
+                and lenient_issubclass(field.type_, bytes)
+                and isinstance(value, UploadFile)
+            ):
+                value = await value.read()
             v_, errors_ = field.validate(value, values, loc=("body", field.alias))
             if isinstance(errors_, ErrorWrapper):
                 errors.append(errors_)
@@ -333,6 +340,21 @@ async def request_body_to_args(
     return values, errors
 
 
+def get_schema_compatible_field(*, field: Field) -> Field:
+    if lenient_issubclass(field.type_, UploadFile):
+        return Field(
+            name=field.name,
+            type_=bytes,
+            class_validators=field.class_validators,
+            model_config=field.model_config,
+            default=field.default,
+            required=field.required,
+            alias=field.alias,
+            schema=field.schema,
+        )
+    return field
+
+
 def get_body_field(*, dependant: Dependant, name: str) -> Field:
     flat_dependant = get_flat_dependant(dependant)
     if not flat_dependant.body_params:
@@ -340,11 +362,11 @@ def get_body_field(*, dependant: Dependant, name: str) -> Field:
     first_param = flat_dependant.body_params[0]
     embed = getattr(first_param.schema, "embed", None)
     if len(flat_dependant.body_params) == 1 and not embed:
-        return first_param
+        return get_schema_compatible_field(field=first_param)
     model_name = "Body_" + name
     BodyModel = create_model(model_name)
     for f in flat_dependant.body_params:
-        BodyModel.__fields__[f.name] = f
+        BodyModel.__fields__[f.name] = get_schema_compatible_field(field=f)
     required = any(True for f in flat_dependant.body_params if f.required)
     if any(isinstance(f.schema, params.File) for f in flat_dependant.body_params):
         BodySchema: Type[params.Body] = params.File

fastapi/openapi/docs.py

@@ -8,6 +8,7 @@ def get_swagger_ui_html(*, openapi_url: str, title: str) -> HTMLResponse:
     <html>
     <head>
     <link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui.css">
+    <link rel="shortcut icon" href="https://fastapi.tiangolo.com/img/favicon.png">
     <title>
     """
         + title
@@ -55,6 +56,7 @@ def get_redoc_html(*, openapi_url: str, title: str) -> HTMLResponse:
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+    <link rel="shortcut icon" href="https://fastapi.tiangolo.com/img/favicon.png">
 
     <!--
     ReDoc doesn't change outer page styles

fastapi/routing.py

@@ -15,7 +15,6 @@ from pydantic.utils import lenient_issubclass
 from starlette import routing
 from starlette.concurrency import run_in_threadpool
 from starlette.exceptions import HTTPException
-from starlette.formparsers import UploadFile
 from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
 from starlette.routing import compile_path, get_name, request_response
@@ -57,10 +56,7 @@ def get_app(
                     raw_body = await request.form()
                     form_fields = {}
                     for field, value in raw_body.items():
-                        if isinstance(value, UploadFile):
-                            form_fields[field] = await value.read()
-                        else:
-                            form_fields[field] = value
+                        form_fields[field] = value
                     if form_fields:
                         body = form_fields
                 else:

mkdocs.yml

@@ -61,11 +61,17 @@ nav:
         - Bigger Applications - Multiple Files: 'tutorial/bigger-applications.md'
         - Sub Applications - Behind a Proxy: 'tutorial/sub-applications-proxy.md'
         - Application Configuration: 'tutorial/application-configuration.md'
+        - GraphQL: 'tutorial/graphql.md'
+        - WebSockets: 'tutorial/websockets.md'
+        - Debugging: 'tutorial/debugging.md'
     - Concurrency and async / await: 'async.md'
     - Deployment: 'deployment.md'
     - Project Generation - Template: 'project-generation.md'
     - Alternatives, Inspiration and Comparisons: 'alternatives.md'
+    - History, Design and Future: 'history-design-future.md'
     - Benchmarks: 'benchmarks.md'
+    - Help FastAPI - Get Help: 'help-fastapi.md'
+    - Development - Contributing: 'contributing.md'
     - Release Notes: release-notes.md
 
 markdown_extensions:

pyproject.toml

@@ -19,7 +19,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
 ]
 requires = [
-    "starlette >=0.9.11,<=0.10.1",
+    "starlette ==0.11.1",
     "pydantic >=0.17,<=0.18.2"
 ]
 description-file = "README.md"

scripts/trigger-docker.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+set -e
+set -x
+
+body='{
+"request": {
+"branch":"master"
+}}'
+
+curl -s -X POST \
+   -H "Content-Type: application/json" \
+   -H "Accept: application/json" \
+   -H "Travis-API-Version: 3" \
+   -H "Authorization: token $TRAVIS_TOKEN" \
+   -d "$body" \
+   https://api.travis-ci.org/repo/tiangolo%2Fuvicorn-gunicorn-fastapi-docker/requests

tests/test_datastructures.py

@@ -0,0 +1,7 @@
+import pytest
+from fastapi import UploadFile
+
+
+def test_upload_file_invalid():
+    with pytest.raises(ValueError):
+        UploadFile.validate("not a Starlette UploadFile")

tests/test_tutorial/test_request_files/test_tutorial001.py

@@ -39,7 +39,39 @@ openapi_schema = {
                     "required": True,
                 },
             }
-        }
+        },
+        "/uploadfile/": {
+            "post": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Create Upload File Post",
+                "operationId": "create_upload_file_uploadfile__post",
+                "requestBody": {
+                    "content": {
+                        "multipart/form-data": {
+                            "schema": {
+                                "$ref": "#/components/schemas/Body_create_upload_file"
+                            }
+                        }
+                    },
+                    "required": True,
+                },
+            }
+        },
     },
     "components": {
         "schemas": {
@@ -51,6 +83,14 @@ openapi_schema = {
                     "file": {"title": "File", "type": "string", "format": "binary"}
                 },
             },
+            "Body_create_upload_file": {
+                "title": "Body_create_upload_file",
+                "required": ["file"],
+                "type": "object",
+                "properties": {
+                    "file": {"title": "File", "type": "string", "format": "binary"}
+                },
+            },
             "ValidationError": {
                 "title": "ValidationError",
                 "required": ["loc", "msg", "type"],
@@ -131,3 +171,14 @@ def test_post_large_file(tmpdir):
     response = client.post("/files/", files={"file": open(path, "rb")})
     assert response.status_code == 200
     assert response.json() == {"file_size": default_pydantic_max_size + 1}
+
+
+def test_post_upload_file(tmpdir):
+    path = os.path.join(tmpdir, "test.txt")
+    with open(path, "wb") as file:
+        file.write(b"<file content>")
+
+    client = TestClient(app)
+    response = client.post("/uploadfile/", files={"file": open(path, "rb")})
+    assert response.status_code == 200
+    assert response.json() == {"filename": "test.txt"}

tests/test_tutorial/test_request_forms_and_files/test_tutorial001.py

@@ -1,4 +1,5 @@
 import os
+from pathlib import Path
 
 from starlette.testclient import TestClient
 
@@ -45,10 +46,11 @@ openapi_schema = {
         "schemas": {
             "Body_create_file": {
                 "title": "Body_create_file",
-                "required": ["file", "token"],
+                "required": ["file", "fileb", "token"],
                 "type": "object",
                 "properties": {
                     "file": {"title": "File", "type": "string", "format": "binary"},
+                    "fileb": {"title": "Fileb", "type": "string", "format": "binary"},
                     "token": {"title": "Token", "type": "string"},
                 },
             },
@@ -94,20 +96,32 @@ file_required = {
             "loc": ["body", "file"],
             "msg": "field required",
             "type": "value_error.missing",
-        }
+        },
+        {
+            "loc": ["body", "fileb"],
+            "msg": "field required",
+            "type": "value_error.missing",
+        },
     ]
 }
 
 token_required = {
     "detail": [
+        {
+            "loc": ["body", "fileb"],
+            "msg": "field required",
+            "type": "value_error.missing",
+        },
         {
             "loc": ["body", "token"],
             "msg": "field required",
             "type": "value_error.missing",
-        }
+        },
     ]
 }
 
+# {'detail': [, {'loc': ['body', 'token'], 'msg': 'field required', 'type': 'value_error.missing'}]}
+
 file_and_token_required = {
     "detail": [
         {
@@ -115,6 +129,11 @@ file_and_token_required = {
             "msg": "field required",
             "type": "value_error.missing",
         },
+        {
+            "loc": ["body", "fileb"],
+            "msg": "field required",
+            "type": "value_error.missing",
+        },
         {
             "loc": ["body", "token"],
             "msg": "field required",
@@ -153,14 +172,24 @@ def test_post_file_no_token(tmpdir):
     assert response.json() == token_required
 
 
-def test_post_file_and_token(tmpdir):
-    path = os.path.join(tmpdir, "test.txt")
-    with open(path, "wb") as file:
-        file.write(b"<file content>")
+def test_post_files_and_token(tmpdir):
+    patha = Path(tmpdir) / "test.txt"
+    pathb = Path(tmpdir) / "testb.txt"
+    patha.write_text("<file content>")
+    pathb.write_text("<file b content>")
 
     client = TestClient(app)
     response = client.post(
-        "/files/", data={"token": "foo"}, files={"file": open(path, "rb")}
+        "/files/",
+        data={"token": "foo"},
+        files={
+            "file": patha.open("rb"),
+            "fileb": ("testb.txt", pathb.open("rb"), "text/plain"),
+        },
     )
     assert response.status_code == 200
-    assert response.json() == {"file_size": 14, "token": "foo"}
+    assert response.json() == {
+        "file_size": 14,
+        "token": "foo",
+        "fileb_content_type": "text/plain",
+    }