🔖 Release 0.5.1: docs

📝 Update error handling docs, including Starlette's utils

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 applicactions 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/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/release-notes.md

@@ -1,5 +1,15 @@
 ## Next
 
+## 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>.

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/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/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 catched by your exception handler.

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:

fastapi/__init__.py

@@ -1,6 +1,6 @@
 """FastAPI framework, high performance, easy to learn, fast to code, ready for production"""
 
-__version__ = "0.5.0"
+__version__ = "0.5.1"
 
 from .applications import FastAPI
 from .routing import APIRouter

mkdocs.yml

@@ -66,6 +66,8 @@ nav:
     - Project Generation - Template: 'project-generation.md'
     - Alternatives, Inspiration and Comparisons: 'alternatives.md'
     - Benchmarks: 'benchmarks.md'
+    - Help FastAPI - Get Help: 'help-fastapi.md'
+    - Development - Contributing: 'contributing.md'
     - Release Notes: release-notes.md
 
 markdown_extensions: