🔖 Release version 0.27.0

#274

docs/release-notes.md

@@ -1,5 +1,37 @@
 ## Next release
 
+## 0.27.0
+
+* Fix broken link in docs about OAuth 2.0 with scopes. PR [#275](https://github.com/tiangolo/fastapi/pull/275) by [@dmontagu](https://github.com/dmontagu).
+
+* Refactor param extraction using Pydantic `Field`:
+    * Large refactor, improvement, and simplification of param extraction from *path operations*.
+    * Fix/add support for list *query parameters* with list defaults. New documentation: [Query parameter list / multiple values with defaults](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#query-parameter-list-multiple-values-with-defaults).
+    * Add support for enumerations in *path operation* parameters. New documentation: [Path Parameters: Predefined values](https://fastapi.tiangolo.com/tutorial/path-params/#predefined-values).
+    * Add support for type annotations using `Optional` as in `param: Optional[str] = None`. New documentation: [Optional type declarations](https://fastapi.tiangolo.com/tutorial/query-params/#optional-type-declarations).
+    * PR [#278](https://github.com/tiangolo/fastapi/pull/278).
+
+## 0.26.0
+
+* Separate error handling for validation errors.
+    * This will allow developers to customize the exception handlers.
+    * Document better how to handle exceptions and use error handlers.
+    * Include `RequestValidationError` and `WebSocketRequestValidationError` (this last one will be useful once [encode/starlette#527](https://github.com/encode/starlette/pull/527) or equivalent is merged).
+    * New documentation about exceptions handlers:
+        * [Install custom exception handlers](https://fastapi.tiangolo.com/tutorial/handling-errors/#install-custom-exception-handlers).
+        * [Override the default exception handlers](https://fastapi.tiangolo.com/tutorial/handling-errors/#override-the-default-exception-handlers).
+        * [Re-use **FastAPI's** exception handlers](https://fastapi.tiangolo.com/tutorial/handling-errors/#re-use-fastapis-exception-handlers).
+    * PR [#273](https://github.com/tiangolo/fastapi/pull/273).
+
+* Fix support for *paths* in *path parameters* without needing explicit `Path(...)`.
+    * PR [#256](https://github.com/tiangolo/fastapi/pull/256).
+    * Documented in PR [#272](https://github.com/tiangolo/fastapi/pull/272) by [@wshayes](https://github.com/wshayes).
+    * New documentation at: [Path Parameters containing paths](https://fastapi.tiangolo.com/tutorial/path-params/#path-parameters-containing-paths).
+
+* Update docs for testing FastAPI. Include using `POST`, sending JSON, testing headers, etc. New documentation: [Testing](https://fastapi.tiangolo.com/tutorial/testing/#testing-extended-example). PR [#271](https://github.com/tiangolo/fastapi/pull/271).
+
+* Fix type declaration of `response_model` to allow generic Python types as `List[Model]`. Mainly to fix `mypy` for users. PR [#266](https://github.com/tiangolo/fastapi/pull/266).
+
 ## 0.25.0
 
 * Add support for Pydantic's `include`, `exclude`, `by_alias`.

docs/src/app_testing/main_b.py

@@ -0,0 +1,36 @@
+from fastapi import FastAPI, Header, HTTPException
+from pydantic import BaseModel
+
+fake_secret_token = "coneofsilence"
+
+fake_db = {
+    "foo": {"id": "foo", "title": "Foo", "description": "There goes my hero"},
+    "bar": {"id": "bar", "title": "Bar", "description": "The bartenders"},
+}
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+    id: str
+    title: str
+    description: str = None
+
+
+@app.get("/items/{item_id}", response_model=Item)
+async def read_main(item_id: str, x_token: str = Header(...)):
+    if x_token != fake_secret_token:
+        raise HTTPException(status_code=400, detail="Invalid X-Token header")
+    if item_id not in fake_db:
+        raise HTTPException(status_code=404, detail="Item not found")
+    return fake_db[item_id]
+
+
+@app.post("/items/", response_model=Item)
+async def create_item(item: Item, x_token: str = Header(...)):
+    if x_token != fake_secret_token:
+        raise HTTPException(status_code=400, detail="Invalid X-Token header")
+    if item.id in fake_db:
+        raise HTTPException(status_code=400, detail="Item already exists")
+    fake_db[item.id] = item
+    return item

docs/src/app_testing/test_main_b.py

@@ -0,0 +1,65 @@
+from starlette.testclient import TestClient
+
+from .main_b import app
+
+client = TestClient(app)
+
+
+def test_read_item():
+    response = client.get("/items/foo", headers={"X-Token": "coneofsilence"})
+    assert response.status_code == 200
+    assert response.json() == {
+        "id": "foo",
+        "title": "Foo",
+        "description": "There goes my hero",
+    }
+
+
+def test_read_item_bad_token():
+    response = client.get("/items/foo", headers={"X-Token": "hailhydra"})
+    assert response.status_code == 400
+    assert response.json() == {"detail": "Invalid X-Token header"}
+
+
+def test_read_inexistent_item():
+    response = client.get("/items/baz", headers={"X-Token": "coneofsilence"})
+    assert response.status_code == 404
+    assert response.json() == {"detail": "Item not found"}
+
+
+def test_create_item():
+    response = client.post(
+        "/items/",
+        headers={"X-Token": "coneofsilence"},
+        json={"id": "foobar", "title": "Foo Bar", "description": "The Foo Barters"},
+    )
+    assert response.status_code == 200
+    assert response.json() == {
+        "id": "foobar",
+        "title": "Foo Bar",
+        "description": "The Foo Barters",
+    }
+
+
+def test_create_item_bad_token():
+    response = client.post(
+        "/items/",
+        headers={"X-Token": "hailhydra"},
+        json={"id": "bazz", "title": "Bazz", "description": "Drop the bazz"},
+    )
+    assert response.status_code == 400
+    assert response.json() == {"detail": "Invalid X-Token header"}
+
+
+def test_create_existing_token():
+    response = client.post(
+        "/items/",
+        headers={"X-Token": "coneofsilence"},
+        json={
+            "id": "foo",
+            "title": "The Foo ID Stealers",
+            "description": "There goes my stealer",
+        },
+    )
+    assert response.status_code == 400
+    assert response.json() == {"detail": "Item already exists"}

docs/src/handling_errors/tutorial003.py

@@ -1,15 +1,26 @@
 from fastapi import FastAPI
-from starlette.exceptions import HTTPException
-from starlette.responses import PlainTextResponse
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+
+class UnicornException(Exception):
+    def __init__(self, name: str):
+        self.name = name
+
 
 app = FastAPI()
 
 
-@app.exception_handler(HTTPException)
-async def http_exception(request, exc):
-    return PlainTextResponse(str(exc.detail), status_code=exc.status_code)
+@app.exception_handler(UnicornException)
+async def unicorn_exception_handler(request: Request, exc: UnicornException):
+    return JSONResponse(
+        status_code=418,
+        content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."},
+    )
 
 
-@app.get("/")
-async def root():
-    return {"message": "Hello World"}
+@app.get("/unicorns/{name}")
+async def read_unicorn(name: str):
+    if name == "yolo":
+        raise UnicornException(name=name)
+    return {"unicorn_name": name}

docs/src/handling_errors/tutorial004.py

@@ -0,0 +1,23 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.exceptions import RequestValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.responses import PlainTextResponse
+
+app = FastAPI()
+
+
+@app.exception_handler(StarletteHTTPException)
+async def http_exception_handler(request, exc):
+    return PlainTextResponse(str(exc.detail), status_code=exc.status_code)
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request, exc):
+    return PlainTextResponse(str(exc), status_code=400)
+
+
+@app.get("/items/{item_id}")
+async def read_item(item_id: int):
+    if item_id == 3:
+        raise HTTPException(status_code=418, detail="Nope! I don't like 3.")
+    return {"item_id": item_id}

docs/src/handling_errors/tutorial005.py

@@ -0,0 +1,28 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.exception_handlers import (
+    http_exception_handler,
+    request_validation_exception_handler,
+)
+from fastapi.exceptions import RequestValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+app = FastAPI()
+
+
+@app.exception_handler(StarletteHTTPException)
+async def custom_http_exception_handler(request, exc):
+    print(f"OMG! An HTTP error!: {exc}")
+    return await http_exception_handler(request, exc)
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request, exc):
+    print(f"OMG! The client sent invalid data!: {exc}")
+    return await request_validation_exception_handler(request, exc)
+
+
+@app.get("/items/{item_id}")
+async def read_item(item_id: int):
+    if item_id == 3:
+        raise HTTPException(status_code=418, detail="Nope! I don't like 3.")
+    return {"item_id": item_id}

docs/src/path_params/tutorial004.py

@@ -0,0 +1,8 @@
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/files/{file_path:path}")
+async def read_user_me(file_path: str):
+    return {"file_path": file_path}

docs/src/path_params/tutorial005.py

@@ -0,0 +1,21 @@
+from enum import Enum
+
+from fastapi import FastAPI
+
+
+class ModelName(Enum):
+    alexnet = "alexnet"
+    resnet = "resnet"
+    lenet = "lenet"
+
+
+app = FastAPI()
+
+
+@app.get("/model/{model_name}")
+async def get_model(model_name: ModelName):
+    if model_name == ModelName.alexnet:
+        return {"model_name": model_name, "message": "Deep Learning FTW!"}
+    if model_name.value == "lenet":
+        return {"model_name": model_name, "message": "LeCNN all the images"}
+    return {"model_name": model_name, "message": "Have some residuals"}

docs/src/query_params/tutorial007.py

@@ -0,0 +1,11 @@
+from typing import Optional
+
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/items/{item_id}")
+async def read_user_item(item_id: str, limit: Optional[int] = None):
+    item = {"item_id": item_id, "limit": limit}
+    return item

docs/src/query_params_str_validations/tutorial012.py

@@ -0,0 +1,11 @@
+from typing import List
+
+from fastapi import FastAPI, Query
+
+app = FastAPI()
+
+
+@app.get("/items/")
+async def read_items(q: List[str] = Query(["foo", "bar"])):
+    query_items = {"q": q}
+    return query_items

docs/tutorial/handling-errors.md

@@ -68,7 +68,7 @@ But if the client requests `http://example.com/items/bar` (a non-existent `item_
 
     They are handled automatically by **FastAPI** and converted to JSON.
 
-### Adding custom headers
+## Add 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.
 
@@ -76,24 +76,138 @@ You probably won't need to use it directly in your code.
 
 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
+## Install custom exception 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>.
+You can add custom exception handlers with <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:
+Let's say you have a custom exception `UnicornException` that you (or a library you use) might `raise`.
 
-```Python hl_lines="2 3 8 9 10"
+And you want to handle this exception globally with FastAPI.
+
+You could add a custom exception handler with `@app.exception_handler()`:
+
+```Python hl_lines="6 7 8 14 15 16 17 18 24"
 {!./src/handling_errors/tutorial003.py!}
 ```
 
-...this would make it return "plain text" responses with the errors, instead of JSON responses.
+Here, if you request `/unicorns/yolo`, the *path operation* will `raise` a `UnicornException`.
 
-!!! info
-    Note that in this example we set the exception handler with Starlette's `HTTPException` instead of FastAPI's `HTTPException`.
+But it will be handled by the `unicorn_exception_handler`.
 
-    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.
+So, you will receive a clean error, with an HTTP status code of `418` and a JSON content of:
+
+```JSON
+{"message": "Oops! yolo did something. There goes a rainbow..."}
+```
+
+## Override the default exception handlers
+
+**FastAPI** has some default exception handlers.
+
+These handlers are in charge or returning the default JSON responses when you `raise` an `HTTPException` and when the request has invalid data.
+
+You can override these exception handlers with your own.
+
+### Override request validation exceptions
+
+When a request contains invalid data, **FastAPI** internally raises a `RequestValidationError`.
+
+And it also includes a default exception handler for it.
+
+To override it, import the `RequestValidationError` and use it with `@app.exception_handler(RequestValidationError)` to decorate the exception handler.
+
+The exception handler will receive a `Request` and the exception.
+
+```Python hl_lines="2 14 15 16"
+{!./src/handling_errors/tutorial004.py!}
+```
+
+Now, if you go to `/items/foo`, instead of getting the default JSON error with:
+
+```JSON
+{
+    "detail": [
+        {
+            "loc": [
+                "path",
+                "item_id"
+            ],
+            "msg": "value is not a valid integer",
+            "type": "type_error.integer"
+        }
+    ]
+}
+```
+
+you will get a text version, with:
+
+```
+1 validation error
+path -> item_id
+  value is not a valid integer (type=type_error.integer)
+```
+
+#### `RequestValidationError` vs `ValidationError`
+
+!!! warning
+    These are technical details that you might skip if it's not important for you now.
+
+`RequestValidationError` is a sub-class of Pydantic's <a href="https://pydantic-docs.helpmanual.io/#error-handling" target="_blank">`ValidationError`</a>.
+
+**FastAPI** uses it so that, if you use a Pydantic model in `response_model`, and your data has an error, you will see the error in your log.
+
+But the client/user will not see it. Instead, the client will receive an "Internal Server Error" with a HTTP status code `500`.
+
+It should be this way because if you have a Pydantic `ValidationError` in your *response* or anywhere in your code (not in the client's *request*), it's actually a bug in your code.
+
+And while you fix it, your clients/users shouldn't have access to internal information about the error, as that could expose a security vulnerability.
+
+### Override the `HTTPException` error handler
+
+The same way, you can override the `HTTPException` handler.
+
+For example, you could want to return a plain text response instead of JSON for these errors:
+
+```Python hl_lines="1 3 9 10 11 22"
+{!./src/handling_errors/tutorial004.py!}
+```
+
+#### FastAPI's `HTTPException` vs Starlette's `HTTPException`
+
+**FastAPI** has its own `HTTPException`.
+
+And **FastAPI**'s `HTTPException` error class inherits from Starlette's `HTTPException` error class.
+
+The only difference, is that **FastAPI**'s `HTTPException` allows you to add headers to be included in the response.
+
+This is needed/used internally for OAuth 2.0 and some security utilities.
+
+So, you can keep raising **FastAPI**'s `HTTPException` as normally in your code.
+
+But when you register an exception handler, you should register it for Starlette's `HTTPException`.
+
+This way, if any part of Starlette's internal code, or a Starlette extension or plug-in, raises an `HTTPException`, your handler will be able to catch handle it.
+
+In this example, to be able to have both `HTTPException`s in the same code, Starlette's exceptions is renamed to `StarletteHTTPException`:
+
+```Python
+from starlette.exceptions import HTTPException as StarletteHTTPException
+```
+
+### Re-use **FastAPI**'s exception handlers
+
+You could also just want to use the exception somehow, but then use the same default exception handlers from **FastAPI**.
+
+You can import and re-use the default exception handlers from `fastapi.exception_handlers`:
+
+```Python hl_lines="2 3 4 5 15 21"
+{!./src/handling_errors/tutorial005.py!}
+```
+
+In this example, you are just `print`ing the error with a very expressive notification.
+
+But you get the idea, you can use the exception and then just re-use the default exception handlers.

docs/tutorial/path-params.md

@@ -35,7 +35,7 @@ If you run this example and open your browser at <a href="http://127.0.0.1:8000/
 
 !!! check
     Notice that the value your function received (and returned) is `3`, as a Python `int`, not a string `"3"`.
-    
+
     So, with that type declaration, **FastAPI** gives you automatic request <abbr title="converting the string that comes from an HTTP request into Python data">"parsing"</abbr>.
 
 ## Data validation
@@ -61,12 +61,11 @@ because the path parameter `item_id` had a value of `"foo"`, which is not an `in
 
 The same error would appear if you provided a `float` instead of an int, as in: <a href="http://127.0.0.1:8000/items/4.2" target="_blank">http://127.0.0.1:8000/items/4.2</a>
 
-
 !!! check
     So, with the same Python type declaration, **FastAPI** gives you data validation.
 
-    Notice that the error also clearly states exactly the point where the validation didn't pass. 
-    
+    Notice that the error also clearly states exactly the point where the validation didn't pass.
+
     This is incredibly helpful while developing and debugging code that interacts with your API.
 
 ## Documentation
@@ -96,8 +95,7 @@ All the data validation is performed under the hood by <a href="https://pydantic
 
 You can use the same type declarations with `str`, `float`, `bool` and many other complex data types.
 
-These are explored in the next chapters of the tutorial.
-
+Several of these are explored in the next chapters of the tutorial.
 
 ## Order matters
 
@@ -115,6 +113,109 @@ Because path operations are evaluated in order, you need to make sure that the p
 
 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"`.
 
+## Predefined values
+
+If you have a *path operation* that receives a *path parameter*, but you want the possible valid *path parameter* values to be predefined, you can use a standard Python <abbr title="Enumeration">`Enum`</abbr>.
+
+### Create an `Enum` class
+
+Import `Enum` and create a sub-class that inherits from it.
+
+And create class attributes with fixed values, those fixed values will be the available valid values:
+
+```Python hl_lines="1 6 7 8 9"
+{!./src/path_params/tutorial005.py!}
+```
+
+!!! info
+    <a href="https://docs.python.org/3/library/enum.html" target="_blank">Enumerations (or enums) are available in Python</a> since version 3.4.
+
+!!! tip
+    If you are wondering, "AlexNet", "ResNet", and "LeNet" are just names of Machine Learning <abbr title="Technically, Deep Learning model architectures">models</abbr>.
+
+### Declare a *path parameter*
+
+Then create a *path parameter* with a type annotation using the enum class you created (`ModelName`):
+
+```Python hl_lines="16"
+{!./src/path_params/tutorial005.py!}
+```
+
+### Check the docs
+
+Because the available values for the *path parameter* are specified, the interactive docs can show them nicely:
+
+<img src="/img/tutorial/path-params/image03.png">
+
+### Working with Python *enumerations*
+
+The value of the *path parameter* will be an *enumeration member*.
+
+#### Compare *enumeration members*
+
+You can compare it with the *enumeration member* in your created enum `ModelName`:
+
+```Python hl_lines="17"
+{!./src/path_params/tutorial005.py!}
+```
+
+#### Get the *enumeration value*
+
+You can get the actual value (a `str` in this case) using `model_name.value`, or in general, `your_enum_member.value`:
+
+```Python hl_lines="19"
+{!./src/path_params/tutorial005.py!}
+```
+
+!!! tip
+    You could also access the value `"lenet"` with `ModelName.lenet.value`.
+
+#### Return *enumeration members*
+
+You can return *enum members* from your *path operation*, even nested in a JSON body (e.g. a `dict`).
+
+They will be converted to their corresponding values before returning them to the client:
+
+```Python hl_lines="18 20 21"
+{!./src/path_params/tutorial005.py!}
+```
+
+## Path parameters containing paths
+
+Let's say you have a *path operation* with a path `/files/{file_path}`.
+
+But you need `file_path` itself to contain a *path*, like `home/johndoe/myfile.txt`.
+
+So, the URL for that file would be something like: `/files/home/johndoe/myfile.txt`.
+
+### OpenAPI support
+
+OpenAPI doesn't support a way to declare a *path parameter* to contain a *path* inside, as that could lead to scenarios that are difficult to test and define.
+
+Nevertheless, you can still do it in **FastAPI**, using one of the internal tools from Starlette.
+
+And the docs would still work, although not adding any documentation telling that the parameter should contain a path.
+
+### Path convertor
+
+Using an option directly from Starlette you can declare a *path parameter* containing a *path* using a URL like:
+
+```
+/files/{file_path:path}
+```
+
+In this case, the name of the parameter is `file_path`, and the last part, `:path`, tells it that the parameter should match any *path*.
+
+So, you can use it with:
+
+```Python hl_lines="6"
+{!./src/path_params/tutorial004.py!}
+```
+
+!!! tip
+    You could need the parameter to contain `/home/johndoe/myfile.txt`, with a leading slash (`/`).
+
+    In that case, the URL would be: `/files//home/johndoe/myfile.txt`, with a double slash (`//`) between `files` and `home`.
 
 ## Recap
 
@@ -127,4 +228,4 @@ With **FastAPI**, by using short, intuitive and standard Python type declaration
 
 And you only have to declare them once.
 
-That's probably the main visible advantage of **FastAPI** compared to alternative frameworks (apart from the raw performance).
+That's probably the main visible advantage of **FastAPI** compared to alternative frameworks (apart from the raw performance).

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

@@ -12,7 +12,6 @@ The query parameter `q` is of type `str`, and by default is `None`, so it is opt
 
 We are going to enforce that even though `q` is optional, whenever it is provided, it **doesn't exceed a length of 50 characters**.
 
-
 ### Import `Query`
 
 To achieve that, first import `Query` from `fastapi`:
@@ -29,7 +28,7 @@ And now use it as the default value of your parameter, setting the parameter `ma
 {!./src/query_params_str_validations/tutorial002.py!}
 ```
 
-As we have to replace the default value `None` with `Query(None)`, the first parameter to `Query` serves the same purpose of defining that default value. 
+As we have to replace the default value `None` with `Query(None)`, the first parameter to `Query` serves the same purpose of defining that default value.
 
 So:
 
@@ -41,7 +40,7 @@ q: str = Query(None)
 
 ```Python
 q: str = None
-``` 
+```
 
 But it declares it explicitly as being a query parameter.
 
@@ -53,7 +52,6 @@ q: str = Query(None, max_length=50)
 
 This will validate the data, show a clear error when the data is not valid, and document the parameter in the OpenAPI schema path operation.
 
-
 ## Add more validations
 
 You can also add a parameter `min_length`:
@@ -119,7 +117,7 @@ So, when you need to declare a value as required while using `Query`, you can us
 {!./src/query_params_str_validations/tutorial006.py!}
 ```
 
-!!! info 
+!!! info
     If you hadn't seen that `...` before: it is a a special single value, it is <a href="https://docs.python.org/3/library/constants.html#Ellipsis" target="_blank">part of Python and is called "Ellipsis"</a>.
 
 This will let **FastAPI** know that this parameter is required.
@@ -156,11 +154,35 @@ So, the response to that URL would be:
 !!! tip
     To declare a query parameter with a type of `list`, like in the example above, you need to explicitly use `Query`, otherwise it would be interpreted as a request body.
 
-
 The interactive API docs will update accordingly, to allow multiple values:
 
 <img src="/img/tutorial/query-params-str-validations/image02.png">
 
+### Query parameter list / multiple values with defaults
+
+And you can also define a default `list` of values if none are provided:
+
+```Python hl_lines="9"
+{!./src/query_params_str_validations/tutorial012.py!}
+```
+
+If you go to:
+
+```
+http://localhost:8000/items/
+```
+
+the default of `q` will be: `["foo", "bar"]` and your response will be:
+
+```JSON
+{
+  "q": [
+    "foo",
+    "bar"
+  ]
+}
+```
+
 ## Declare more metadata
 
 You can add more information about the parameter.

docs/tutorial/query-params.md

@@ -186,3 +186,39 @@ In this case, there are 3 query parameters:
 * `needy`, a required `str`.
 * `skip`, an `int` with a default value of `0`.
 * `limit`, an optional `int`.
+
+!!! tip
+    You could also use `Enum`s <a href="https://fastapi.tiangolo.com/tutorial/path-params/#predefined-values" target="_blank">the same way as with *path parameters*</a>.
+
+## Optional type declarations
+
+!!! warning
+    This might be an advanced use case.
+
+    You might want to skip it.
+
+If you are using `mypy` it could complain with type declarations like:
+
+```Python
+limit: int = None
+```
+
+With an error like:
+
+```
+Incompatible types in assignment (expression has type "None", variable has type "int")
+```
+
+In those cases you can use `Optional` to tell `mypy` that the value could be `None`, like:
+
+```Python
+from typing import Optional
+
+limit: Optional[int] = None
+```
+
+In a *path operation* that could look like:
+
+```Python hl_lines="9"
+{!./src/query_params/tutorial007.py!}
+```

docs/tutorial/security/oauth2-scopes.md

@@ -247,4 +247,4 @@ The most secure is the code flow, but is more complex to implement as it require
 
 ## `Security` in decorator `dependencies`
 
-The same way you can define a `list` of <a href="https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-decorator/" target="_blank">`Depends` in the decorator's `dependencies` parameter</a>, you could also use `Security` with `scopes` there.
+The same way you can define a `list` of <a href="https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/" target="_blank">`Depends` in the decorator's `dependencies` parameter</a>, you could also use `Security` with `scopes` there.

docs/tutorial/testing.md

@@ -22,12 +22,11 @@ Write simple `assert` statements with the standard Python expressions that you n
 
 !!! tip
     Notice that the testing functions are normal `def`, not `async def`. 
-    
+
     And the calls to the client are also normal calls, not using `await`.
 
     This allows you to use `pytest` directly without complications.
 
-
 ## Separating tests
 
 In a real application, you probably would have your tests in a different file.
@@ -50,6 +49,51 @@ Then you could have a file `test_main.py` with your tests, and import your `app`
 {!./src/app_testing/test_main.py!}
 ```
 
+## Testing: extended example
+
+Now let's extend this example and add more details to see how to test different parts.
+
+### Extended **FastAPI** app file
+
+Let's say you have a file `main_b.py` with your **FastAPI** app.
+
+It has a `GET` operation that could return an error.
+
+It has a `POST` operation that could return several errors.
+
+Both *path operations* require an `X-Token` header.
+
+```Python
+{!./src/app_testing/main_b.py!}
+```
+
+### Extended testing file
+
+You could then have a `test_main_b.py`, the same as before, with the extended tests:
+
+```Python
+{!./src/app_testing/test_main_b.py!}
+```
+
+Whenever you need the client to pass information in the request and you don't know how to, you can search (Google) how to do it in `requests`.
+
+Then you just do the same in your tests.
+
+E.g.:
+
+* To pass a *path* or *query* parameter, add it to the URL itself.
+* To pass a JSON body, pass a Python object (e.g. a `dict`) to the parameter `json`.
+* If you need to send *Form Data* instead of JSON, use the `data` parameter instead.
+* To pass *headers*, use a `dict` in the `headers` parameter.
+* For *cookies*, a `dict` in the `cookies` parameter.
+
+For more information about how to pass data to the backend (using `requests` or the `TestClient`) check the <a href="http://docs.python-requests.org" target="_blank">Requests documentation</a>.
+
+!!! info
+    Note that the `TestClient` receives data that can be converted to JSON, not Pydantic models.
+
+    If you have a Pydantic model in your test and you want to send its data to the application during testing, you can use the <a href="https://fastapi.tiangolo.com/tutorial/encoder/" target="_blank">JSON compatible encoder: `jsonable_encoder`</a>.
+
 ## Testing WebSockets
 
 You can use the same `TestClient` to test WebSockets.

fastapi/__init__.py

@@ -1,6 +1,6 @@
 """FastAPI framework, high performance, easy to learn, fast to code, ready for production"""
 
-__version__ = "0.25.0"
+__version__ = "0.27.0"
 
 from starlette.background import BackgroundTasks
 

fastapi/applications.py

@@ -1,6 +1,11 @@
 from typing import Any, Callable, Dict, List, Optional, Set, Type, Union
 
 from fastapi import routing
+from fastapi.exception_handlers import (
+    http_exception_handler,
+    request_validation_exception_handler,
+)
+from fastapi.exceptions import RequestValidationError
 from fastapi.openapi.docs import (
     get_redoc_html,
     get_swagger_ui_html,
@@ -8,7 +13,6 @@ from fastapi.openapi.docs import (
 )
 from fastapi.openapi.utils import get_openapi
 from fastapi.params import Depends
-from pydantic import BaseModel
 from starlette.applications import Starlette
 from starlette.exceptions import ExceptionMiddleware, HTTPException
 from starlette.middleware.errors import ServerErrorMiddleware
@@ -17,16 +21,6 @@ from starlette.responses import HTMLResponse, JSONResponse, Response
 from starlette.routing import BaseRoute
 
 
-async def http_exception(request: Request, exc: HTTPException) -> JSONResponse:
-    headers = getattr(exc, "headers", None)
-    if headers:
-        return JSONResponse(
-            {"detail": exc.detail}, status_code=exc.status_code, headers=headers
-        )
-    else:
-        return JSONResponse({"detail": exc.detail}, status_code=exc.status_code)
-
-
 class FastAPI(Starlette):
     def __init__(
         self,
@@ -120,14 +114,17 @@ class FastAPI(Starlette):
                 )
 
             self.add_route(self.redoc_url, redoc_html, include_in_schema=False)
-        self.add_exception_handler(HTTPException, http_exception)
+        self.add_exception_handler(HTTPException, http_exception_handler)
+        self.add_exception_handler(
+            RequestValidationError, request_validation_exception_handler
+        )
 
     def add_api_route(
         self,
         path: str,
         endpoint: Callable,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[Depends] = None,
@@ -173,7 +170,7 @@ class FastAPI(Starlette):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[Depends] = None,
@@ -252,7 +249,7 @@ class FastAPI(Starlette):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[Depends] = None,
@@ -295,7 +292,7 @@ class FastAPI(Starlette):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[Depends] = None,
@@ -338,7 +335,7 @@ class FastAPI(Starlette):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[Depends] = None,
@@ -381,7 +378,7 @@ class FastAPI(Starlette):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[Depends] = None,
@@ -424,7 +421,7 @@ class FastAPI(Starlette):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[Depends] = None,
@@ -467,7 +464,7 @@ class FastAPI(Starlette):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[Depends] = None,
@@ -510,7 +507,7 @@ class FastAPI(Starlette):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[Depends] = None,
@@ -553,7 +550,7 @@ class FastAPI(Starlette):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[Depends] = None,

fastapi/dependencies/utils.py

@@ -1,8 +1,6 @@
 import asyncio
 import inspect
 from copy import deepcopy
-from datetime import date, datetime, time, timedelta
-from decimal import Decimal
 from typing import (
     Any,
     Callable,
@@ -14,8 +12,8 @@ from typing import (
     Tuple,
     Type,
     Union,
+    cast,
 )
-from uuid import UUID
 
 from fastapi import params
 from fastapi.dependencies.models import Dependant, SecurityRequirement
@@ -23,7 +21,7 @@ from fastapi.security.base import SecurityBase
 from fastapi.security.oauth2 import OAuth2, SecurityScopes
 from fastapi.security.open_id_connect_url import OpenIdConnect
 from fastapi.utils import get_path_param_names
-from pydantic import BaseConfig, Schema, create_model
+from pydantic import BaseConfig, BaseModel, Schema, create_model
 from pydantic.error_wrappers import ErrorWrapper
 from pydantic.errors import MissingError
 from pydantic.fields import Field, Required, Shape
@@ -35,22 +33,21 @@ from starlette.datastructures import FormData, Headers, QueryParams, UploadFile
 from starlette.requests import Request
 from starlette.websockets import WebSocket
 
-param_supported_types = (
-    str,
-    int,
-    float,
-    bool,
-    UUID,
-    date,
-    datetime,
-    time,
-    timedelta,
-    Decimal,
-)
-
-sequence_shapes = {Shape.LIST, Shape.SET, Shape.TUPLE}
+sequence_shapes = {
+    Shape.LIST,
+    Shape.SET,
+    Shape.TUPLE,
+    Shape.SEQUENCE,
+    Shape.TUPLE_ELLIPS,
+}
 sequence_types = (list, set, tuple)
-sequence_shape_to_type = {Shape.LIST: list, Shape.SET: set, Shape.TUPLE: tuple}
+sequence_shape_to_type = {
+    Shape.LIST: list,
+    Shape.SET: set,
+    Shape.TUPLE: tuple,
+    Shape.SEQUENCE: list,
+    Shape.TUPLE_ELLIPS: list,
+}
 
 
 def get_param_sub_dependant(
@@ -126,6 +123,26 @@ def get_flat_dependant(dependant: Dependant) -> Dependant:
     return flat_dependant
 
 
+def is_scalar_field(field: Field) -> bool:
+    return (
+        field.shape == Shape.SINGLETON
+        and not lenient_issubclass(field.type_, BaseModel)
+        and not isinstance(field.schema, params.Body)
+    )
+
+
+def is_scalar_sequence_field(field: Field) -> bool:
+    if field.shape in sequence_shapes and not lenient_issubclass(
+        field.type_, BaseModel
+    ):
+        if field.sub_fields is not None:
+            for sub_field in field.sub_fields:
+                if not is_scalar_field(sub_field):
+                    return False
+        return True
+    return False
+
+
 def get_dependant(
     *, path: str, call: Callable, name: str = None, security_scopes: List[str] = None
 ) -> Dependant:
@@ -133,83 +150,78 @@ def get_dependant(
     endpoint_signature = inspect.signature(call)
     signature_params = endpoint_signature.parameters
     dependant = Dependant(call=call, name=name)
-    for param_name in signature_params:
-        param = signature_params[param_name]
+    for param_name, param in signature_params.items():
         if isinstance(param.default, params.Depends):
             sub_dependant = get_param_sub_dependant(
                 param=param, path=path, security_scopes=security_scopes
             )
             dependant.dependencies.append(sub_dependant)
-    for param_name in signature_params:
-        param = signature_params[param_name]
-        if (
-            (param.default == param.empty) or isinstance(param.default, params.Path)
-        ) and (param_name in path_param_names):
-            assert (
-                lenient_issubclass(param.annotation, param_supported_types)
-                or param.annotation == param.empty
+    for param_name, param in signature_params.items():
+        if isinstance(param.default, params.Depends):
+            continue
+        if add_non_field_param_to_dependency(param=param, dependant=dependant):
+            continue
+        param_field = get_param_field(param=param, default_schema=params.Query)
+        if param_name in path_param_names:
+            assert param.default == param.empty or isinstance(
+                param.default, params.Path
+            ), "Path params must have no defaults or use Path(...)"
+            assert is_scalar_field(
+                field=param_field
             ), f"Path params must be of one of the supported types"
-            add_param_to_fields(
+            param_field = get_param_field(
                 param=param,
-                dependant=dependant,
                 default_schema=params.Path,
                 force_type=params.ParamTypes.path,
             )
-        elif (
-            param.default == param.empty
-            or param.default is None
-            or isinstance(param.default, param_supported_types)
-        ) and (
-            param.annotation == param.empty
-            or lenient_issubclass(param.annotation, param_supported_types)
-        ):
-            add_param_to_fields(
-                param=param, dependant=dependant, default_schema=params.Query
-            )
-        elif isinstance(param.default, params.Param):
-            if param.annotation != param.empty:
-                origin = getattr(param.annotation, "__origin__", None)
-                param_all_types = param_supported_types + (list, tuple, set)
-                if isinstance(param.default, (params.Query, params.Header)):
-                    assert lenient_issubclass(
-                        param.annotation, param_all_types
-                    ) or lenient_issubclass(
-                        origin, param_all_types
-                    ), f"Parameters for Query and Header must be of type str, int, float, bool, list, tuple or set: {param}"
-                else:
-                    assert lenient_issubclass(
-                        param.annotation, param_supported_types
-                    ), f"Parameters for Path and Cookies must be of type str, int, float, bool: {param}"
-            add_param_to_fields(
-                param=param, dependant=dependant, default_schema=params.Query
-            )
-        elif lenient_issubclass(param.annotation, Request):
-            dependant.request_param_name = param_name
-        elif lenient_issubclass(param.annotation, WebSocket):
-            dependant.websocket_param_name = param_name
-        elif lenient_issubclass(param.annotation, BackgroundTasks):
-            dependant.background_tasks_param_name = param_name
-        elif lenient_issubclass(param.annotation, SecurityScopes):
-            dependant.security_scopes_param_name = param_name
-        elif not isinstance(param.default, params.Depends):
-            add_param_to_body_fields(param=param, dependant=dependant)
+            add_param_to_fields(field=param_field, dependant=dependant)
+        elif is_scalar_field(field=param_field):
+            add_param_to_fields(field=param_field, dependant=dependant)
+        elif isinstance(
+            param.default, (params.Query, params.Header)
+        ) and is_scalar_sequence_field(param_field):
+            add_param_to_fields(field=param_field, dependant=dependant)
+        else:
+            assert isinstance(
+                param_field.schema, params.Body
+            ), f"Param: {param_field.name} can only be a request body, using Body(...)"
+            dependant.body_params.append(param_field)
     return dependant
 
 
-def add_param_to_fields(
+def add_non_field_param_to_dependency(
+    *, param: inspect.Parameter, dependant: Dependant
+) -> Optional[bool]:
+    if lenient_issubclass(param.annotation, Request):
+        dependant.request_param_name = param.name
+        return True
+    elif lenient_issubclass(param.annotation, WebSocket):
+        dependant.websocket_param_name = param.name
+        return True
+    elif lenient_issubclass(param.annotation, BackgroundTasks):
+        dependant.background_tasks_param_name = param.name
+        return True
+    elif lenient_issubclass(param.annotation, SecurityScopes):
+        dependant.security_scopes_param_name = param.name
+        return True
+    return None
+
+
+def get_param_field(
     *,
     param: inspect.Parameter,
-    dependant: Dependant,
-    default_schema: Type[Schema] = params.Param,
+    default_schema: Type[params.Param] = params.Param,
     force_type: params.ParamTypes = None,
-) -> None:
+) -> Field:
     default_value = Required
+    had_schema = False
     if not param.default == param.empty:
         default_value = param.default
-    if isinstance(default_value, params.Param):
+    if isinstance(default_value, Schema):
+        had_schema = True
         schema = default_value
         default_value = schema.default
-        if getattr(schema, "in_", None) is None:
+        if isinstance(schema, params.Param) and getattr(schema, "in_", None) is None:
             schema.in_ = default_schema.in_
         if force_type:
             schema.in_ = force_type
@@ -234,43 +246,26 @@ def add_param_to_fields(
         class_validators={},
         schema=schema,
     )
-    if schema.in_ == params.ParamTypes.path:
+    if not had_schema and not is_scalar_field(field=field):
+        field.schema = params.Body(schema.default)
+    return field
+
+
+def add_param_to_fields(*, field: Field, dependant: Dependant) -> None:
+    field.schema = cast(params.Param, field.schema)
+    if field.schema.in_ == params.ParamTypes.path:
         dependant.path_params.append(field)
-    elif schema.in_ == params.ParamTypes.query:
+    elif field.schema.in_ == params.ParamTypes.query:
         dependant.query_params.append(field)
-    elif schema.in_ == params.ParamTypes.header:
+    elif field.schema.in_ == params.ParamTypes.header:
         dependant.header_params.append(field)
     else:
         assert (
-            schema.in_ == params.ParamTypes.cookie
-        ), f"non-body parameters must be in path, query, header or cookie: {param.name}"
+            field.schema.in_ == params.ParamTypes.cookie
+        ), f"non-body parameters must be in path, query, header or cookie: {field.name}"
         dependant.cookie_params.append(field)
 
 
-def add_param_to_body_fields(*, param: inspect.Parameter, dependant: Dependant) -> None:
-    default_value = Required
-    if not param.default == param.empty:
-        default_value = param.default
-    if isinstance(default_value, Schema):
-        schema = default_value
-        default_value = schema.default
-    else:
-        schema = Schema(default_value)
-    required = default_value == Required
-    annotation = get_annotation_from_schema(param.annotation, schema)
-    field = Field(
-        name=param.name,
-        type_=annotation,
-        default=None if required else default_value,
-        alias=schema.alias or param.name,
-        required=required,
-        model_config=BaseConfig,
-        class_validators={},
-        schema=schema,
-    )
-    dependant.body_params.append(field)
-
-
 def is_coroutine_callable(call: Callable) -> bool:
     if inspect.isfunction(call):
         return asyncio.iscoroutinefunction(call)
@@ -354,7 +349,7 @@ def request_params_to_args(
         if field.shape in sequence_shapes and isinstance(
             received_params, (QueryParams, Headers)
         ):
-            value = received_params.getlist(field.alias)
+            value = received_params.getlist(field.alias) or field.default
         else:
             value = received_params.get(field.alias)
         schema: params.Param = field.schema

fastapi/exception_handlers.py

@@ -0,0 +1,23 @@
+from fastapi.exceptions import RequestValidationError
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.status import HTTP_422_UNPROCESSABLE_ENTITY
+
+
+async def http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse:
+    headers = getattr(exc, "headers", None)
+    if headers:
+        return JSONResponse(
+            {"detail": exc.detail}, status_code=exc.status_code, headers=headers
+        )
+    else:
+        return JSONResponse({"detail": exc.detail}, status_code=exc.status_code)
+
+
+async def request_validation_exception_handler(
+    request: Request, exc: RequestValidationError
+) -> JSONResponse:
+    return JSONResponse(
+        status_code=HTTP_422_UNPROCESSABLE_ENTITY, content={"detail": exc.errors()}
+    )

fastapi/exceptions.py

@@ -1,3 +1,4 @@
+from pydantic import ValidationError
 from starlette.exceptions import HTTPException as StarletteHTTPException
 
 
@@ -7,3 +8,11 @@ class HTTPException(StarletteHTTPException):
     ) -> None:
         super().__init__(status_code=status_code, detail=detail)
         self.headers = headers
+
+
+class RequestValidationError(ValidationError):
+    pass
+
+
+class WebSocketRequestValidationError(ValidationError):
+    pass

fastapi/openapi/utils.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, List, Optional, Sequence, Tuple, Type
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Type, cast
 
 from fastapi import routing
 from fastapi.dependencies.models import Dependant
@@ -9,7 +9,7 @@ from fastapi.openapi.models import OpenAPI
 from fastapi.params import Body, Param
 from fastapi.utils import get_flat_models_from_routes, get_model_definitions
 from pydantic.fields import Field
-from pydantic.schema import Schema, field_schema, get_model_name_map
+from pydantic.schema import field_schema, get_model_name_map
 from pydantic.utils import lenient_issubclass
 from starlette.responses import JSONResponse
 from starlette.routing import BaseRoute
@@ -97,12 +97,8 @@ def get_openapi_operation_request_body(
     body_schema, _ = field_schema(
         body_field, model_name_map=model_name_map, ref_prefix=REF_PREFIX
     )
-    schema: Schema = body_field.schema
-    if isinstance(schema, Body):
-        request_media_type = schema.media_type
-    else:
-        # Includes not declared media types (Schema)
-        request_media_type = "application/json"
+    body_field.schema = cast(Body, body_field.schema)
+    request_media_type = body_field.schema.media_type
     required = body_field.required
     request_body_oai: Dict[str, Any] = {}
     if required:

fastapi/routing.py

@@ -13,6 +13,7 @@ from fastapi.dependencies.utils import (
     solve_dependencies,
 )
 from fastapi.encoders import jsonable_encoder
+from fastapi.exceptions import RequestValidationError, WebSocketRequestValidationError
 from pydantic import BaseConfig, BaseModel, Schema
 from pydantic.error_wrappers import ErrorWrapper, ValidationError
 from pydantic.fields import Field
@@ -28,7 +29,7 @@ from starlette.routing import (
     request_response,
     websocket_session,
 )
-from starlette.status import HTTP_422_UNPROCESSABLE_ENTITY, WS_1008_POLICY_VIOLATION
+from starlette.status import WS_1008_POLICY_VIOLATION
 from starlette.websockets import WebSocket
 
 
@@ -103,10 +104,7 @@ def get_app(
             request=request, dependant=dependant, body=body
         )
         if errors:
-            errors_out = ValidationError(errors)
-            raise HTTPException(
-                status_code=HTTP_422_UNPROCESSABLE_ENTITY, detail=errors_out.errors()
-            )
+            raise RequestValidationError(errors)
         else:
             assert dependant.call is not None, "dependant.call must be a function"
             if is_coroutine:
@@ -141,10 +139,7 @@ def get_websocket_app(dependant: Dependant) -> Callable:
         )
         if errors:
             await websocket.close(code=WS_1008_POLICY_VIOLATION)
-            errors_out = ValidationError(errors)
-            raise HTTPException(
-                status_code=HTTP_422_UNPROCESSABLE_ENTITY, detail=errors_out.errors()
-            )
+            raise WebSocketRequestValidationError(errors)
         assert dependant.call is not None, "dependant.call must me a function"
         await dependant.call(**values)
 
@@ -169,7 +164,7 @@ class APIRoute(routing.Route):
         path: str,
         endpoint: Callable,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[params.Depends] = None,
@@ -255,10 +250,11 @@ class APIRoute(routing.Route):
         assert inspect.isfunction(endpoint) or inspect.ismethod(
             endpoint
         ), f"An endpoint must be a function or method"
-        self.dependant = get_dependant(path=path, call=self.endpoint)
+        self.dependant = get_dependant(path=self.path_format, call=self.endpoint)
         for depends in self.dependencies[::-1]:
             self.dependant.dependencies.insert(
-                0, get_parameterless_sub_dependant(depends=depends, path=path)
+                0,
+                get_parameterless_sub_dependant(depends=depends, path=self.path_format),
             )
         self.body_field = get_body_field(dependant=self.dependant, name=self.name)
         self.app = request_response(
@@ -282,7 +278,7 @@ class APIRouter(routing.Router):
         path: str,
         endpoint: Callable,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[params.Depends] = None,
@@ -329,7 +325,7 @@ class APIRouter(routing.Router):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[params.Depends] = None,
@@ -450,7 +446,7 @@ class APIRouter(routing.Router):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[params.Depends] = None,
@@ -495,7 +491,7 @@ class APIRouter(routing.Router):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[params.Depends] = None,
@@ -539,7 +535,7 @@ class APIRouter(routing.Router):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[params.Depends] = None,
@@ -583,7 +579,7 @@ class APIRouter(routing.Router):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[params.Depends] = None,
@@ -627,7 +623,7 @@ class APIRouter(routing.Router):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[params.Depends] = None,
@@ -671,7 +667,7 @@ class APIRouter(routing.Router):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[params.Depends] = None,
@@ -715,7 +711,7 @@ class APIRouter(routing.Router):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[params.Depends] = None,
@@ -759,7 +755,7 @@ class APIRouter(routing.Router):
         self,
         path: str,
         *,
-        response_model: Type[BaseModel] = None,
+        response_model: Type[Any] = None,
         status_code: int = 200,
         tags: List[str] = None,
         dependencies: List[params.Depends] = None,

pyproject.toml

@@ -20,7 +20,7 @@ classifiers = [
 ]
 requires = [
     "starlette >=0.11.1,<=0.12.0",
-    "pydantic >=0.17,<=0.26.0"
+    "pydantic >=0.26,<=0.26.0"
 ]
 description-file = "README.md"
 requires-python = ">=3.6"

tests/test_invalid_sequence_param.py

@@ -0,0 +1,29 @@
+from typing import List, Tuple
+
+import pytest
+from fastapi import FastAPI, Query
+from pydantic import BaseModel
+
+
+def test_invalid_sequence():
+    with pytest.raises(AssertionError):
+        app = FastAPI()
+
+        class Item(BaseModel):
+            title: str
+
+        @app.get("/items/")
+        def read_items(q: List[Item] = Query(None)):
+            pass  # pragma: no cover
+
+
+def test_invalid_tuple():
+    with pytest.raises(AssertionError):
+        app = FastAPI()
+
+        class Item(BaseModel):
+            title: str
+
+        @app.get("/items/")
+        def read_items(q: Tuple[Item, Item] = Query(None)):
+            pass  # pragma: no cover

tests/test_tutorial/test_handling_errors/test_tutorial003.py

@@ -0,0 +1,91 @@
+from starlette.testclient import TestClient
+
+from handling_errors.tutorial003 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/unicorns/{name}": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Read Unicorn",
+                "operationId": "read_unicorn_unicorns__name__get",
+                "parameters": [
+                    {
+                        "required": True,
+                        "schema": {"title": "Name", "type": "string"},
+                        "name": "name",
+                        "in": "path",
+                    }
+                ],
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": ["loc", "msg", "type"],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "msg": {"title": "Message", "type": "string"},
+                    "type": {"title": "Error Type", "type": "string"},
+                },
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/ValidationError"},
+                    }
+                },
+            },
+        }
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_get():
+    response = client.get("/unicorns/shinny")
+    assert response.status_code == 200
+    assert response.json() == {"unicorn_name": "shinny"}
+
+
+def test_get_exception():
+    response = client.get("/unicorns/yolo")
+    assert response.status_code == 418
+    assert response.json() == {
+        "message": "Oops! yolo did something. There goes a rainbow..."
+    }

tests/test_tutorial/test_handling_errors/test_tutorial004.py

@@ -0,0 +1,100 @@
+from starlette.testclient import TestClient
+
+from handling_errors.tutorial004 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/items/{item_id}": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Read Item",
+                "operationId": "read_item_items__item_id__get",
+                "parameters": [
+                    {
+                        "required": True,
+                        "schema": {"title": "Item_Id", "type": "integer"},
+                        "name": "item_id",
+                        "in": "path",
+                    }
+                ],
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": ["loc", "msg", "type"],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "msg": {"title": "Message", "type": "string"},
+                    "type": {"title": "Error Type", "type": "string"},
+                },
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/ValidationError"},
+                    }
+                },
+            },
+        }
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_get_validation_error():
+    response = client.get("/items/foo")
+    assert response.status_code == 400
+    validation_error_str_lines = [
+        b"1 validation error",
+        b"path -> item_id",
+        b"  value is not a valid integer (type=type_error.integer)",
+    ]
+    assert response.content == b"\n".join(validation_error_str_lines)
+
+
+def test_get_http_error():
+    response = client.get("/items/3")
+    assert response.status_code == 418
+    assert response.content == b"Nope! I don't like 3."
+
+
+def test_get():
+    response = client.get("/items/2")
+    assert response.status_code == 200
+    assert response.json() == {"item_id": 2}

tests/test_tutorial/test_handling_errors/test_tutorial005.py

@@ -0,0 +1,103 @@
+from starlette.testclient import TestClient
+
+from handling_errors.tutorial005 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/items/{item_id}": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Read Item",
+                "operationId": "read_item_items__item_id__get",
+                "parameters": [
+                    {
+                        "required": True,
+                        "schema": {"title": "Item_Id", "type": "integer"},
+                        "name": "item_id",
+                        "in": "path",
+                    }
+                ],
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": ["loc", "msg", "type"],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "msg": {"title": "Message", "type": "string"},
+                    "type": {"title": "Error Type", "type": "string"},
+                },
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/ValidationError"},
+                    }
+                },
+            },
+        }
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_get_validation_error():
+    response = client.get("/items/foo")
+    assert response.status_code == 422
+    assert response.json() == {
+        "detail": [
+            {
+                "loc": ["path", "item_id"],
+                "msg": "value is not a valid integer",
+                "type": "type_error.integer",
+            }
+        ]
+    }
+
+
+def test_get_http_error():
+    response = client.get("/items/3")
+    assert response.status_code == 418
+    assert response.json() == {"detail": "Nope! I don't like 3."}
+
+
+def test_get():
+    response = client.get("/items/2")
+    assert response.status_code == 200
+    assert response.json() == {"item_id": 2}

tests/test_tutorial/test_path_params/test_tutorial004.py

@@ -0,0 +1,91 @@
+from starlette.testclient import TestClient
+
+from path_params.tutorial004 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/files/{file_path}": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Read User Me",
+                "operationId": "read_user_me_files__file_path__get",
+                "parameters": [
+                    {
+                        "required": True,
+                        "schema": {"title": "File_Path", "type": "string"},
+                        "name": "file_path",
+                        "in": "path",
+                    }
+                ],
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": ["loc", "msg", "type"],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "msg": {"title": "Message", "type": "string"},
+                    "type": {"title": "Error Type", "type": "string"},
+                },
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/ValidationError"},
+                    }
+                },
+            },
+        }
+    },
+}
+
+
+def test_openapi():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_file_path():
+    response = client.get("/files/home/johndoe/myfile.txt")
+    print(response.content)
+    assert response.status_code == 200
+    assert response.json() == {"file_path": "home/johndoe/myfile.txt"}
+
+
+def test_root_file_path():
+    response = client.get("/files//home/johndoe/myfile.txt")
+    print(response.content)
+    assert response.status_code == 200
+    assert response.json() == {"file_path": "/home/johndoe/myfile.txt"}

tests/test_tutorial/test_path_params/test_tutorial005.py

@@ -0,0 +1,120 @@
+import pytest
+from starlette.testclient import TestClient
+
+from path_params.tutorial005 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/model/{model_name}": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Get Model",
+                "operationId": "get_model_model__model_name__get",
+                "parameters": [
+                    {
+                        "required": True,
+                        "schema": {
+                            "title": "Model_Name",
+                            "enum": ["alexnet", "resnet", "lenet"],
+                        },
+                        "name": "model_name",
+                        "in": "path",
+                    }
+                ],
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": ["loc", "msg", "type"],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "msg": {"title": "Message", "type": "string"},
+                    "type": {"title": "Error Type", "type": "string"},
+                },
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/ValidationError"},
+                    }
+                },
+            },
+        }
+    },
+}
+
+
+def test_openapi():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+@pytest.mark.parametrize(
+    "url,status_code,expected",
+    [
+        (
+            "/model/alexnet",
+            200,
+            {"model_name": "alexnet", "message": "Deep Learning FTW!"},
+        ),
+        (
+            "/model/lenet",
+            200,
+            {"model_name": "lenet", "message": "LeCNN all the images"},
+        ),
+        (
+            "/model/resnet",
+            200,
+            {"model_name": "resnet", "message": "Have some residuals"},
+        ),
+        (
+            "/model/foo",
+            422,
+            {
+                "detail": [
+                    {
+                        "loc": ["path", "model_name"],
+                        "msg": "value is not a valid enumeration member",
+                        "type": "type_error.enum",
+                    }
+                ]
+            },
+        ),
+    ],
+)
+def test_get_enums(url, status_code, expected):
+    response = client.get(url)
+    assert response.status_code == status_code
+    assert response.json() == expected

tests/test_tutorial/test_query_params/test_tutorial007.py

@@ -0,0 +1,95 @@
+from starlette.testclient import TestClient
+
+from query_params.tutorial007 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/items/{item_id}": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Read User Item",
+                "operationId": "read_user_item_items__item_id__get",
+                "parameters": [
+                    {
+                        "required": True,
+                        "schema": {"title": "Item_Id", "type": "string"},
+                        "name": "item_id",
+                        "in": "path",
+                    },
+                    {
+                        "required": False,
+                        "schema": {"title": "Limit", "type": "integer"},
+                        "name": "limit",
+                        "in": "query",
+                    },
+                ],
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": ["loc", "msg", "type"],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "msg": {"title": "Message", "type": "string"},
+                    "type": {"title": "Error Type", "type": "string"},
+                },
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/ValidationError"},
+                    }
+                },
+            },
+        }
+    },
+}
+
+
+def test_openapi():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_read_item():
+    response = client.get("/items/foo")
+    assert response.status_code == 200
+    assert response.json() == {"item_id": "foo", "limit": None}
+
+
+def test_read_item_query():
+    response = client.get("/items/foo?limit=5")
+    assert response.status_code == 200
+    assert response.json() == {"item_id": "foo", "limit": 5}

tests/test_tutorial/test_query_params_str_validations/test_tutorial012.py

@@ -0,0 +1,96 @@
+from starlette.testclient import TestClient
+
+from query_params_str_validations.tutorial012 import app
+
+client = TestClient(app)
+
+openapi_schema = {
+    "openapi": "3.0.2",
+    "info": {"title": "Fast API", "version": "0.1.0"},
+    "paths": {
+        "/items/": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    },
+                    "422": {
+                        "description": "Validation Error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/HTTPValidationError"
+                                }
+                            }
+                        },
+                    },
+                },
+                "summary": "Read Items",
+                "operationId": "read_items_items__get",
+                "parameters": [
+                    {
+                        "required": False,
+                        "schema": {
+                            "title": "Q",
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "default": ["foo", "bar"],
+                        },
+                        "name": "q",
+                        "in": "query",
+                    }
+                ],
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "ValidationError": {
+                "title": "ValidationError",
+                "required": ["loc", "msg", "type"],
+                "type": "object",
+                "properties": {
+                    "loc": {
+                        "title": "Location",
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "msg": {"title": "Message", "type": "string"},
+                    "type": {"title": "Error Type", "type": "string"},
+                },
+            },
+            "HTTPValidationError": {
+                "title": "HTTPValidationError",
+                "type": "object",
+                "properties": {
+                    "detail": {
+                        "title": "Detail",
+                        "type": "array",
+                        "items": {"$ref": "#/components/schemas/ValidationError"},
+                    }
+                },
+            },
+        }
+    },
+}
+
+
+def test_openapi_schema():
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    assert response.json() == openapi_schema
+
+
+def test_default_query_values():
+    url = "/items/"
+    response = client.get(url)
+    assert response.status_code == 200
+    assert response.json() == {"q": ["foo", "bar"]}
+
+
+def test_multi_query_values():
+    url = "/items/?q=baz&q=foobar"
+    response = client.get(url)
+    assert response.status_code == 200
+    assert response.json() == {"q": ["baz", "foobar"]}