Browse Source

Clarify documentation for required query params with None type

Fixes #12419

**Problem:**
The documentation section "Required, can be None" was misleading. It suggested
that you could force clients to send a None value, but HTTP query parameters
cannot send literal None - they're either strings or omitted entirely.

The example showed `q: Annotated[str | None, Query(min_length=3)]` without a
default value, which makes the parameter required. However, there's no way for
a client to satisfy this by sending None via HTTP query parameters.

**Solution:**
Updated the documentation to:
1. Rename the section to "Required with None type" to be more accurate
2. Add a detailed note explaining HTTP query parameter limitations
3. Clarify that omitting the parameter results in a validation error
4. Explain this pattern is more useful for dependencies than HTTP endpoints
5. Show the correct pattern for optional parameters that can be omitted

**Testing:**
The existing tests in test_tutorial006c.py are already marked as xfail with a
reference to this issue, confirming the example doesn't work as described. This
documentation update clarifies the behavior instead of changing the example to
something that would work differently.

This helps developers understand when to use this pattern (dependencies) vs
when to use optional parameters with defaults (HTTP endpoints).
pull/14871/head
Varun Chawla 5 months ago
parent
commit
226e064009
  1. 20
      docs/en/docs/tutorial/query-params-str-validations.md

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

@ -244,14 +244,26 @@ So, when you need to declare a value as required while using `Query`, you can si
{* ../../docs_src/query_params_str_validations/tutorial006_an_py39.py hl[9] *}
### Required, can be `None` { #required-can-be-none }
### Required with `None` type { #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 simply do not declare a default value:
You can declare that a parameter has a type that includes `None` (like `str | None`) but without a default value, which makes it required:
{* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *}
/// note
**Important**: Even though the type includes `None`, the parameter is still **required** because there's no default value. This means clients **must** provide the parameter.
In practice, HTTP query parameters are sent as strings. While the type annotation `str | None` indicates the parameter could theoretically be `None`, there's no standard way to send a literal `None` value in HTTP query parameters - you can only send string values or omit the parameter entirely.
**Omitting the parameter will result in a validation error** since it's required.
This pattern is more commonly useful for **dependencies** (where you might pass `None` programmatically) rather than direct HTTP endpoints.
For an optional query parameter that can be omitted, use: `q: Annotated[str | None, Query(min_length=3)] = None`
///
## 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.

Loading…
Cancel
Save