Parâmetros de path e validações numéricas¶

Da mesma forma que você pode declarar mais validações e metadados para parâmetros de consulta com Query, você pode declarar o mesmo tipo de validações e metadados para parâmetros de path com Path.

Importe `Path`¶

Primeiro, importe Path de fastapi, e importe Annotated:

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")],
    q: Annotated[str | None, Query(alias="item-query")] = None,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

🤓 Other versions and variants

Python 3.9+Python 3.8+Python 3.10+ - non-AnnotatedPython 3.8+ - non-Annotated

from typing import Annotated, Union

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")],
    q: Annotated[Union[str, None], Query(alias="item-query")] = None,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

from typing import Union

from fastapi import FastAPI, Path, Query
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")],
    q: Annotated[Union[str, None], Query(alias="item-query")] = None,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(title="The ID of the item to get"),
    q: str | None = Query(default=None, alias="item-query"),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Tip

Prefer to use the Annotated version if possible.

from typing import Union

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(title="The ID of the item to get"),
    q: Union[str, None] = Query(default=None, alias="item-query"),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Informação

O FastAPI adicionou suporte a Annotated (e passou a recomendá-lo) na versão 0.95.0.

Se você tiver uma versão mais antiga, verá erros ao tentar usar Annotated.

Certifique-se de Atualizar a versão do FastAPI para pelo menos 0.95.1 antes de usar Annotated.

Declare metadados¶

Você pode declarar todos os mesmos parâmetros que em Query.

Por exemplo, para declarar um valor de metadado title para o parâmetro de path item_id você pode digitar:

Python 3.10+

from typing import Annotated

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")],
    q: Annotated[str | None, Query(alias="item-query")] = None,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

🤓 Other versions and variants

Python 3.9+Python 3.8+Python 3.10+ - non-AnnotatedPython 3.8+ - non-Annotated

from typing import Annotated, Union

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")],
    q: Annotated[Union[str, None], Query(alias="item-query")] = None,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

from typing import Union

from fastapi import FastAPI, Path, Query
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")],
    q: Annotated[Union[str, None], Query(alias="item-query")] = None,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(title="The ID of the item to get"),
    q: str | None = Query(default=None, alias="item-query"),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Tip

Prefer to use the Annotated version if possible.

from typing import Union

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: int = Path(title="The ID of the item to get"),
    q: Union[str, None] = Query(default=None, alias="item-query"),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Nota

Um parâmetro de path é sempre obrigatório, pois precisa fazer parte do path. Mesmo que você o declare como None ou defina um valor padrão, isso não afetaria nada, ele ainda seria sempre obrigatório.

Ordene os parâmetros de acordo com sua necessidade¶

Dica

Isso provavelmente não é tão importante ou necessário se você usar Annotated.

Vamos supor que você queira declarar o parâmetro de consulta q como uma str obrigatória.

E você não precisa declarar mais nada para esse parâmetro, então você realmente não precisa usar Query.

Mas você ainda precisa usar Path para o parâmetro de path item_id. E você não quer usar Annotated por algum motivo.

O Python vai reclamar se você colocar um valor com “padrão” antes de um valor que não tem “padrão”.

Mas você pode reordená-los e colocar primeiro o valor sem padrão (o parâmetro de consulta q).

Isso não faz diferença para o FastAPI. Ele vai detectar os parâmetros pelos seus nomes, tipos e declarações de padrão (Query, Path, etc.), sem se importar com a ordem.

Então, você pode declarar sua função assim:

Python 3.8+ - non-Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(q: str, item_id: int = Path(title="The ID of the item to get")):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

🤓 Other versions and variants

Python 3.9+Python 3.8+

from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    q: str, item_id: Annotated[int, Path(title="The ID of the item to get")]
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

from fastapi import FastAPI, Path
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    q: str, item_id: Annotated[int, Path(title="The ID of the item to get")]
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Mas tenha em mente que, se você usar Annotated, você não terá esse problema, não fará diferença, pois você não está usando valores padrão de parâmetros de função para Query() ou Path().

Python 3.9+

from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    q: str, item_id: Annotated[int, Path(title="The ID of the item to get")]
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

🤓 Other versions and variants

Python 3.8+Python 3.8+ - non-Annotated

from fastapi import FastAPI, Path
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    q: str, item_id: Annotated[int, Path(title="The ID of the item to get")]
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(q: str, item_id: int = Path(title="The ID of the item to get")):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Ordene os parâmetros de acordo com sua necessidade, truques¶

Dica

Isso provavelmente não é tão importante ou necessário se você usar Annotated.

Aqui vai um pequeno truque que pode ser útil, mas você não vai precisar dele com frequência.

Se você quiser:

declarar o parâmetro de consulta q sem um Query nem qualquer valor padrão
declarar o parâmetro de path item_id usando Path
tê-los em uma ordem diferente
não usar Annotated

...o Python tem uma pequena sintaxe especial para isso.

Passe *, como o primeiro parâmetro da função.

O Python não fará nada com esse *, mas saberá que todos os parâmetros seguintes devem ser chamados como argumentos nomeados (pares chave-valor), também conhecidos como kwargs. Mesmo que eles não tenham um valor padrão.

Python 3.8+ - non-Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(*, item_id: int = Path(title="The ID of the item to get"), q: str):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

🤓 Other versions and variants

Python 3.9+Python 3.8+

from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")], q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

from fastapi import FastAPI, Path
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")], q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Melhor com `Annotated`¶

Tenha em mente que, se você usar Annotated, como você não está usando valores padrão de parâmetros de função, você não terá esse problema e provavelmente não precisará usar *.

Python 3.9+

from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")], q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

🤓 Other versions and variants

Python 3.8+Python 3.8+ - non-Annotated

from fastapi import FastAPI, Path
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get")], q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(*, item_id: int = Path(title="The ID of the item to get"), q: str):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Validações numéricas: maior que ou igual¶

Com Query e Path (e outras que você verá depois) você pode declarar restrições numéricas.

Aqui, com ge=1, item_id precisará ser um número inteiro “greater than or equal” a 1.

Python 3.9+

from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get", ge=1)], q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

🤓 Other versions and variants

Python 3.8+Python 3.8+ - non-Annotated

from fastapi import FastAPI, Path
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get", ge=1)], q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *, item_id: int = Path(title="The ID of the item to get", ge=1), q: str
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Validações numéricas: maior que e menor que ou igual¶

O mesmo se aplica a:

gt: maior que (greater than)
le: menor que ou igual (less than or equal)

Python 3.9+

from typing import Annotated

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get", gt=0, le=1000)],
    q: str,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

🤓 Other versions and variants

Python 3.8+Python 3.8+ - non-Annotated

from fastapi import FastAPI, Path
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="The ID of the item to get", gt=0, le=1000)],
    q: str,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Path

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *,
    item_id: int = Path(title="The ID of the item to get", gt=0, le=1000),
    q: str,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

Validações numéricas: floats, maior que e menor que¶

Validações numéricas também funcionam para valores float.

Aqui é onde se torna importante poder declarar gt e não apenas ge. Com isso você pode exigir, por exemplo, que um valor seja maior que 0, mesmo que seja menor que 1.

Assim, 0.5 seria um valor válido. Mas 0.0 ou 0 não seriam.

E o mesmo para lt.

Python 3.9+

from typing import Annotated

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *,
    item_id: Annotated[int, Path(title="The ID of the item to get", ge=0, le=1000)],
    q: str,
    size: Annotated[float, Query(gt=0, lt=10.5)],
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    if size:
        results.update({"size": size})
    return results

🤓 Other versions and variants

Python 3.8+Python 3.8+ - non-Annotated

from fastapi import FastAPI, Path, Query
from typing_extensions import Annotated

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *,
    item_id: Annotated[int, Path(title="The ID of the item to get", ge=0, le=1000)],
    q: str,
    size: Annotated[float, Query(gt=0, lt=10.5)],
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    if size:
        results.update({"size": size})
    return results

Tip

Prefer to use the Annotated version if possible.

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_items(
    *,
    item_id: int = Path(title="The ID of the item to get", ge=0, le=1000),
    q: str,
    size: float = Query(gt=0, lt=10.5),
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    if size:
        results.update({"size": size})
    return results

Recapitulando¶

Com Query, Path (e outras que você ainda não viu) você pode declarar metadados e validações de string do mesmo modo que em Parâmetros de consulta e validações de string.

E você também pode declarar validações numéricas:

gt: maior que (greater than)
ge: maior que ou igual (greater than or equal)
lt: menor que (less than)
le: menor que ou igual (less than or equal)

Informação

Query, Path e outras classes que você verá depois são subclasses de uma classe comum Param.

Todas elas compartilham os mesmos parâmetros para validação adicional e metadados que você viu.

Detalhes Técnicos

Quando você importa Query, Path e outras de fastapi, elas são na verdade funções.

Que, quando chamadas, retornam instâncias de classes de mesmo nome.

Então, você importa Query, que é uma função. E quando você a chama, ela retorna uma instância de uma classe também chamada Query.

Essas funções existem (em vez de usar diretamente as classes) para que seu editor não marque erros sobre seus tipos.

Dessa forma, você pode usar seu editor e ferramentas de codificação normais sem precisar adicionar configurações personalizadas para desconsiderar esses erros.

Parâmetros de path e validações numéricas¶

Importe Path¶

Declare metadados¶

Ordene os parâmetros de acordo com sua necessidade¶

Ordene os parâmetros de acordo com sua necessidade, truques¶

Melhor com Annotated¶

Validações numéricas: maior que ou igual¶

Validações numéricas: maior que e menor que ou igual¶

Validações numéricas: floats, maior que e menor que¶

Recapitulando¶

Importe `Path`¶

Melhor com `Annotated`¶