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.
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.
@ -24,10 +24,10 @@ We are going to enforce that even though `q` is optional, whenever it is provide
@ -35,13 +35,13 @@ FastAPI added support for `Annotated` (and started recommending it) in version 0
If you have an older version, you would get errors when trying to use `Annotated`.
If you have an older version, you would get errors when trying to use `Annotated`.
Make sure you [Upgrade the FastAPI version](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank} to at least 0.95.1 before using `Annotated`.
Make sure you [Upgrade the FastAPI version](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=\_blank} to at least 0.95.1 before using `Annotated`.
///
///
## Use `Annotated` in the type for the `q` parameter { #use-annotated-in-the-type-for-the-q-parameter }
## Use `Annotated` in the type for the `q` parameter { #use-annotated-in-the-type-for-the-q-parameter }
Remember I told you before that `Annotated` can be used to add metadata to your parameters in the [Python Types Intro](../python-types.md#type-hints-with-metadata-annotations){.internal-link target=_blank}?
Remember I told you before that `Annotated` can be used to add metadata to your parameters in the [Python Types Intro](../python-types.md#type-hints-with-metadata-annotations){.internal-link target=\_blank}?
Now it's the time to use it with FastAPI. 🚀
Now it's the time to use it with FastAPI. 🚀
@ -89,7 +89,7 @@ Now let's jump to the fun stuff. 🎉
Now that we have this `Annotated` where we can put more information (in this case some additional validation), add `Query` inside of `Annotated`, and set the parameter `max_length` to `50`:
Now that we have this `Annotated` where we can put more information (in this case some additional validation), add `Query` inside of `Annotated`, and set the parameter `max_length` to `50`:
As in this case (without using `Annotated`) we have to replace the default value `None` in the function with `Query()`, we now need to set the default value with the parameter `Query(default=None)`, it serves the same purpose of defining that default value (at least for FastAPI).
As in this case (without using `Annotated`) we have to replace the default value `None` in the function with `Query()`, we now need to set the default value with the parameter `Query(default=None)`, it serves the same purpose of defining that default value (at least for FastAPI).
You can define a <abbrtitle="A regular expression, regex or regexp is a sequence of characters that define a search pattern for strings.">regular expression</abbr>`pattern` that the parameter should match:
You can define a <abbrtitle="A regular expression, regex or regexp is a sequence of characters that define a search pattern for strings.">regular expression</abbr>`pattern` that the parameter should match:
This specific regular expression pattern checks that the received parameter value:
This specific regular expression pattern checks that the received parameter value:
*`^`: starts with the following characters, doesn't have characters before.
-`^`: starts with the following characters, doesn't have characters before.
*`fixedquery`: has the exact value `fixedquery`.
-`fixedquery`: has the exact value `fixedquery`.
*`$`: ends there, doesn't have any more characters after `fixedquery`.
-`$`: ends there, doesn't have any more characters after `fixedquery`.
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.
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.
@ -212,7 +211,7 @@ You can, of course, use default values other than `None`.
Let's say that you want to declare the `q` query parameter to have a `min_length` of `3`, and to have a default value of `"fixedquery"`:
Let's say that you want to declare the `q` query parameter to have a `min_length` of `3`, and to have a default value of `"fixedquery"`:
### 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 forces clients to send a value, even if the value represents `None`.
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:
Query parameters are always received as strings, so clients cannot send an actual
`None` value directly. If needed, you must explicitly handle a string representation
(for example, `"null"`) and convert it to `None` inside your application logic.
you would receive the multiple `q`*query parameters'* values (`foo` and `bar`) in a Python `list` inside your *path operation function*, in the *function parameter*`q`.
you would receive the multiple `q`_query parameters'_ values (`foo` and `bar`) in a Python `list` inside your _path operation function_, in the _function parameter_`q`.
So, the response to that URL would be:
So, the response to that URL would be:
@ -293,7 +297,7 @@ The interactive API docs will update accordingly, to allow multiple values:
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:
@ -386,7 +390,7 @@ The docs will show it like this:
To exclude a query parameter from the generated OpenAPI schema (and thus, from the automatic documentation systems), set the parameter `include_in_schema` of `Query` to `False`:
To exclude a query parameter from the generated OpenAPI schema (and thus, from the automatic documentation systems), set the parameter `include_in_schema` of `Query` to `False`:
@ -404,7 +408,7 @@ Pydantic also has <a href="https://docs.pydantic.dev/latest/concepts/validators/
For example, this custom validator checks that the item ID starts with `isbn-` for an <abbrtitle="ISBN means International Standard Book Number">ISBN</abbr> book number or with `imdb-` for an <abbrtitle="IMDB (Internet Movie Database) is a website with information about movies">IMDB</abbr> movie URL ID:
For example, this custom validator checks that the item ID starts with `isbn-` for an <abbrtitle="ISBN means International Standard Book Number">ISBN</abbr> book number or with `imdb-` for an <abbrtitle="IMDB (Internet Movie Database) is a website with information about movies">IMDB</abbr> movie URL ID:
Alberto Zambrano
6 months ago