From 68c3d86f6ef88cc245302b4c6db01f2c28ffc5c6 Mon Sep 17 00:00:00 2001 From: Fitrat Gulmamadov Date: Wed, 25 Mar 2026 02:14:37 +0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Clarify=20that=20HTTP=20query=20?= =?UTF-8?q?params=20cannot=20be=20Python=20None?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/en/docs/tutorial/query-params-str-validations.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/en/docs/tutorial/query-params-str-validations.md b/docs/en/docs/tutorial/query-params-str-validations.md index 4765b36cbe..66f5366450 100644 --- a/docs/en/docs/tutorial/query-params-str-validations.md +++ b/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 } -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: {* ../../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 } 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.