Es gibt eine Alternative, die explizit deklariert, dass ein Wert erforderlich ist. Sie können als Default das <abbrtitle='Zeichenfolge, die einen Wert direkt darstellt, etwa 1, "hallowelt", True, None'>Literal</abbr>`...` setzen:
Falls Sie das `...` bisher noch nicht gesehen haben: Es ist ein spezieller einzelner Wert, <ahref="https://docs.python.org/3/library/constants.html#Ellipsis"class="external-link"target="_blank">Teil von Python und wird „Ellipsis“ genannt</a> (Deutsch: Ellipse).
Es wird von Pydantic und FastAPI verwendet, um explizit zu deklarieren, dass ein Wert erforderlich ist.
///
Dies wird **FastAPI** wissen lassen, dass dieser Parameter erforderlich ist.
### Erforderlich, kann `None` sein
Sie können deklarieren, dass ein Parameter `None` akzeptiert, aber dennoch erforderlich ist. Das zwingt Clients, den Wert zu senden, selbst wenn er `None` ist.
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.
The query parameter `q` is of type `str | None`, 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 `Union` in `Union[str, None]` will allow your editor to give you better support and detect errors.
Having `str | None` will allow your editor to give you better support and detect errors.
///
@ -25,29 +25,9 @@ We are going to enforce that even though `q` is optional, whenever it is provide
To achieve that, first import:
* `Query` from `fastapi`
* `Annotated` from `typing` (or from `typing_extensions` in Python below 3.9)
* `Annotated` from `typing`
//// tab | Python 3.10+
In Python 3.9 or above, `Annotated` is part of the standard library, so you can import it from `typing`.
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*.
@ -201,7 +150,7 @@ This will validate the data, show a clear error when the data is not valid, and
Keep in mind that when using `Query` inside of `Annotated` you cannot use the `default` parameter for `Query`.
Instead use the actual default value of the function parameter. Otherwise, it would be inconsistent.
Instead, use the actual default value of the function parameter. Otherwise, it would be inconsistent.
For example, this is not allowed:
@ -255,7 +204,7 @@ This specific regular expression pattern checks that the received parameter valu
If you feel lost with all these **"regular expression"** ideas, don't worry. They are a hard topic for many people. You can still do a lot of stuff without needing regular expressions yet.
But whenever you need them and go and learn them, know that you can already use them directly in **FastAPI**.
Now you know that whenever you need them you can use them in **FastAPI**.
### Pydantic v1 `regex` instead of `pattern`
@ -296,7 +245,7 @@ q: str
instead of:
```Python
q: Union[str, None] = None
q: str | None = None
```
But we are now declaring it with `Query`, for example like:
@ -304,15 +253,7 @@ But we are now declaring it with `Query`, for example like:
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, can be `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 `...` as the default:
To do that, you can declare that `None` is a valid type but simply do not declare a default value:
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://docs.pydantic.dev/2.3/usage/models/#required-optional-fields"class="external-link"target="_blank">Required fields</a>.
///
/// tip
Remember that in most of the cases, when something is required, you can simply omit the default, so you normally don't have to use `...`.
///
## 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 another way, to receive multiple values.
@ -396,7 +309,7 @@ The interactive API docs will update accordingly, to allow multiple values:
### Query parameter list / multiple values with defaults
And you can also define a default `list` of values if none are provided:
You can also define a default `list` of values if none are provided:
Si no habías visto eso `...` antes: es un valor especial único, es <ahref="https://docs.python.org/3/library/constants.html#Ellipsis"class="external-link"target="_blank">parte de Python y se llama "Ellipsis"</a>.
Se usa por Pydantic y FastAPI para declarar explícitamente que un valor es requerido.
///
Esto le permitirá a **FastAPI** saber que este parámetro es requerido.
### Requerido, puede ser `None`
Puedes declarar que un parámetro puede aceptar `None`, pero que aún así es requerido. Esto obligaría a los clientes a enviar un valor, incluso si el valor es `None`.
Если вы ранее не сталкивались с `...`: это специальное значение, <ahref="https://docs.python.org/3/library/constants.html#Ellipsis"class="external-link"target="_blank">часть языка Python и называется "Ellipsis"</a>.
Используется в Pydantic и FastAPI для определения, что значение требуется обязательно.
///
Таким образом, **FastAPI** определяет, что параметр является обязательным.
### Обязательный параметр с `None`
Вы можете определить, что параметр может принимать `None`, но всё ещё является обязательным. Это может потребоваться для того, чтобы пользователи явно указали параметр, даже если его значение будет `None`.
@ -321,18 +305,6 @@ Pydantic, мощь которого используется в FastAPI для
///
### Использование Pydantic's `Required` вместо Ellipsis (`...`)
Если вас смущает `...`, вы можете использовать `Required` из Pydantic:
Запомните, когда вам необходимо объявить query-параметр обязательным, вы можете просто не указывать параметр `default`. Таким образом, вам редко придётся использовать `...` или `Required`.
///
## Множество значений для query-параметра
Для query-параметра `Query` можно указать, что он принимает список значений (множество значений).
Sebastián Ramírez
2 months ago
GitHub