✨ Add support for not needing `...` as default value in required Query(), Path(), Header(), etc. (#4906)
* ✨ Do not require default value in Query(), Path(), Header(), etc
* 📝 Update source examples for docs with default and required values
* ✅ Update tests with new default values and not required Ellipsis
* 📝 Update docs for Query params and update info about default value, required, Ellipsis
The query parameter `q` is of type `Optional[str]` (or `str | None` in Python 3.10), that means that it's of type `str` but could also be `None`, and indeed, the default value is `None`, so FastAPI will know it's not required.
The query parameter `q` is of type `Union[str, None]` (or `str | None` in Python 3.10), that means that it's of type `str` but could also be `None`, and indeed, the default value is `None`, so FastAPI will know it's not required.
!!! note
FastAPI will know that the value of `q` is not required because of the default value `= None`.
The `Optional` in `Optional[str]` is not used by FastAPI, but will allow your editor to give you better support and detect errors.
The `Union` in `Union[str, None]` will allow your editor to give you better support and detect errors.
## Additional validation
@ -59,24 +59,24 @@ And now use it as the default value of your parameter, setting the parameter `ma
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`in the function with `Query()`, we can now set the default value with the parameter `Query(default=None)`, it serves the same purpose of defining that default value.
So:
```Python
q: Optional[str] = Query(None)
q: Union[str, None] = Query(default=None)
```
...makes the parameter optional, the same as:
```Python
q: Optional[str] = None
q: Union[str, None] = None
```
And in Python 3.10 and above:
```Python
q: str | None = Query(None)
q: str | None = Query(default=None)
```
...makes the parameter optional, the same as:
@ -97,17 +97,17 @@ But it declares it explicitly as being a query parameter.
or the:
```Python
= Query(None)
= Query(default=None)
```
as it will use that `None` as the default value, and that way make the parameter **not required**.
The `Optional` part allows your editor to provide better support, but it is not what tells FastAPI that this parameter is not required.
The `Union[str, None]` part allows your editor to provide better support, but it is not what tells FastAPI that this parameter is not required.
Then, we can pass more parameters to `Query`. In this case, the `max_length` parameter that applies to strings:
If you hadn't seen that `...` before: it is a special single value, it is <ahref="https://docs.python.org/3/library/constants.html#Ellipsis"class="external-link"target="_blank">part of Python and is called "Ellipsis"</a>.
It is used by Pydantic and FastAPI to explicitly declare that a value is required.
This will let **FastAPI** know that this parameter is required.
### Required with `None`
You can declare that a parameter can accept `None`, but that it's still required. This would force clients to send a value, even if the value is `None`.
To do that, you can declare that `None` is a valid type but still use `default=...`:
Pydantic, which is what powers all the data validation and serialization in FastAPI, has a special behavior when you use `Optional` or `Union[Something, None]` without a default value, you can read more about it in the Pydantic docs about <ahref="https://pydantic-docs.helpmanual.io/usage/models/#required-optional-fields"class="external-link"target="_blank">Required Optional fields</a>.
### Use Pydantic's `Required` instead of Ellipsis (`...`)
If you feel uncomfortable using `...`, you can also import and use `Required` from Pydantic:
Remember that in most of the cases, when something is required, you can simply omit the `default` parameter, so you normally don't have to use `...` nor `Required`.
## Query parameter list / multiple values
When you define a query parameter explicitly with `Query` you can also declare it to receive a list of values, or said in other way, to receive multiple values.
Sebastián Ramírez
3 years ago
GitHub