Browse Source

📝 Clarify that HTTP query params cannot be Python None

Add a note to the "Required, can be None" section explaining that
HTTP query parameters are always strings over the network, and clients
cannot explicitly send a Python `None`. The `None` type annotation
reflects Python-level typing, not what clients can actually transmit.

Closes #12419
pull/15213/head
Fitrat Gulmamadov 4 months ago
parent
commit
68c3d86f6e
  1. 8
      docs/en/docs/tutorial/query-params-str-validations.md

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

@ -222,12 +222,18 @@ So, when you need to declare a value as required while using `Query`, you can si
### Required, can be `None` { #required-can-be-none } ### Required, can be `None` { #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`. You can declare that a parameter can accept `None`, but that it's still required. This would force clients to send the parameter, but the value can be `None` in your Python code if the client sends no value for it.
To do that, you can declare that `None` is a valid type but simply do not declare a default value: To do that, you can declare that `None` is a valid type but simply do not declare a default value:
{* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *} {* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *}
/// note
HTTP query parameters are always strings when sent by clients over the network. There is no way for a client to explicitly send a Python `None` as a query parameter — the parameter is either present as a string or absent entirely. The `None` in the type annotation tells FastAPI (and Python) that the value is allowed to be `None` at the Python level, but if the parameter is required (no default value), FastAPI will return a validation error when the client omits it.
///
## Query parameter list / multiple values { #query-parameter-list-multiple-values } ## Query parameter list / multiple values { #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. 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.

Loading…
Cancel
Save