Точно так же, как вы можете объявлять дополнительные валидации и метаданные для параметров запроса с помощью Query, вы можете объявлять тот же тип валидаций и метаданных для параметров пути с помощью Path.
Сначала импортируйте Path из fastapi и импортируйте Annotated:
fromtypingimportAnnotatedfromfastapiimportFastAPI,Path,Queryapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_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}ifq:results.update({"q":q})returnresults
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
fromfastapiimportFastAPI,Path,Queryapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_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}ifq:results.update({"q":q})returnresults
Примечание
FastAPI добавил поддержку Annotated (и начал рекомендовать его) в версии 0.95.0.
Если у вас более старая версия, при попытке использовать Annotated вы получите ошибки.
Убедитесь, что вы обновили версию FastAPI как минимум до 0.95.1, прежде чем использовать Annotated.
Вы можете объявить все те же параметры, что и для Query.
Например, чтобы объявить значение метаданных title для параметра пути item_id, вы можете написать:
fromtypingimportAnnotatedfromfastapiimportFastAPI,Path,Queryapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_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}ifq:results.update({"q":q})returnresults
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
fromfastapiimportFastAPI,Path,Queryapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_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}ifq:results.update({"q":q})returnresults
Примечание
Параметр пути всегда обязателен, так как он должен быть частью пути. Даже если вы объявите его с None или установите значение по умолчанию, это ни на что не повлияет, он всё равно будет всегда обязательным.
Вероятно, это не так важно и не так необходимо, если вы используете Annotated.
Допустим, вы хотите объявить параметр запроса q как обязательный str.
И вам не нужно объявлять что-либо ещё для этого параметра, поэтому вам на самом деле не нужно использовать Query.
Но вам всё ещё нужно использовать Path для параметра пути item_id. И вы не хотите использовать Annotated по какой-то причине.
Python выдаст ошибку, если вы поставите значение со значением «по умолчанию» перед значением, у которого нет «значения по умолчанию».
Но вы можете изменить их порядок и поставить значение без значения по умолчанию (параметр запроса q) первым.
Для FastAPI это не имеет значения. Он определит параметры по их именам, типам и объявлениям значений по умолчанию (Query, Path и т.д.), порядок ему не важен.
Итак, вы можете объявить вашу функцию как:
fromfastapiimportFastAPI,Pathapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_items(q:str,item_id:int=Path(title="The ID of the item to get")):results={"item_id":item_id}ifq:results.update({"q":q})returnresults
🤓 Другие версии и варианты
fromtypingimportAnnotatedfromfastapiimportFastAPI,Pathapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_items(q:str,item_id:Annotated[int,Path(title="The ID of the item to get")]):results={"item_id":item_id}ifq:results.update({"q":q})returnresults
Но имейте в виду, что если вы используете Annotated, у вас не будет этой проблемы, это не будет иметь значения, поскольку вы не используете значения по умолчанию параметров функции для Query() или Path().
fromtypingimportAnnotatedfromfastapiimportFastAPI,Pathapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_items(q:str,item_id:Annotated[int,Path(title="The ID of the item to get")]):results={"item_id":item_id}ifq:results.update({"q":q})returnresults
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
fromfastapiimportFastAPI,Pathapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_items(q:str,item_id:int=Path(title="The ID of the item to get")):results={"item_id":item_id}ifq:results.update({"q":q})returnresults
Вероятно, это не так важно и не так необходимо, если вы используете Annotated.
Вот маленький трюк, который может пригодиться, но он вам не часто понадобится.
Если вы хотите:
объявить параметр запроса q без Query и без значения по умолчанию
объявить параметр пути item_id с помощью Path
расположить их в другом порядке
не использовать Annotated
...у Python есть для этого небольшой специальный синтаксис.
Передайте * в качестве первого параметра функции.
Python ничего не сделает с этим *, но он будет знать, что все следующие параметры должны передаваться как именованные аргументы (пары ключ-значение), также известные как kwargs. Даже если у них нет значения по умолчанию.
fromfastapiimportFastAPI,Pathapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_items(*,item_id:int=Path(title="The ID of the item to get"),q:str):results={"item_id":item_id}ifq:results.update({"q":q})returnresults
🤓 Другие версии и варианты
fromtypingimportAnnotatedfromfastapiimportFastAPI,Pathapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_items(item_id:Annotated[int,Path(title="The ID of the item to get")],q:str):results={"item_id":item_id}ifq:results.update({"q":q})returnresults
Имейте в виду, что если вы используете Annotated, поскольку вы не используете значения по умолчанию параметров функции, у вас не будет этой проблемы, и вам, вероятно, не понадобится использовать *.
fromtypingimportAnnotatedfromfastapiimportFastAPI,Pathapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_items(item_id:Annotated[int,Path(title="The ID of the item to get")],q:str):results={"item_id":item_id}ifq:results.update({"q":q})returnresults
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
fromfastapiimportFastAPI,Pathapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_items(*,item_id:int=Path(title="The ID of the item to get"),q:str):results={"item_id":item_id}ifq:results.update({"q":q})returnresults
С Query и Path (и другими, которые вы увидите позже) вы можете объявлять числовые ограничения.
Здесь, с ge=1, item_id должен быть целым числом «greater than or equal» (больше или равно) 1.
fromtypingimportAnnotatedfromfastapiimportFastAPI,Pathapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_items(item_id:Annotated[int,Path(title="The ID of the item to get",ge=1)],q:str):results={"item_id":item_id}ifq:results.update({"q":q})returnresults
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
fromfastapiimportFastAPI,Pathapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_items(*,item_id:int=Path(title="The ID of the item to get",ge=1),q:str):results={"item_id":item_id}ifq:results.update({"q":q})returnresults
fromtypingimportAnnotatedfromfastapiimportFastAPI,Pathapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_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}ifq:results.update({"q":q})returnresults
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
fromfastapiimportFastAPI,Pathapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_items(*,item_id:int=Path(title="The ID of the item to get",gt=0,le=1000),q:str,):results={"item_id":item_id}ifq:results.update({"q":q})returnresults
Числовые валидации: числа с плавающей точкой, больше и меньше¶
Числовые валидации также работают для значений float.
Вот где становится важным уметь объявлять gt, а не только ge. Поскольку с его помощью вы можете требовать, например, чтобы значение было больше 0, даже если оно меньше 1.
Таким образом, 0.5 будет допустимым значением. Но 0.0 или 0 — нет.
И то же самое для lt.
fromtypingimportAnnotatedfromfastapiimportFastAPI,Path,Queryapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_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}ifq:results.update({"q":q})ifsize:results.update({"size":size})returnresults
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
fromfastapiimportFastAPI,Path,Queryapp=FastAPI()@app.get("/items/{item_id}")asyncdefread_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}ifq:results.update({"q":q})ifsize:results.update({"size":size})returnresults
С Query, Path (и другими, которые вы ещё не видели) вы можете объявлять метаданные и строковые валидации так же, как и в разделе Параметры запроса и валидация строк.
И вы также можете объявлять числовые валидации:
gt: greater than (больше чем)
ge: greater than or equal (больше или равно)
lt: less than (меньше чем)
le: less than or equal (меньше или равно)
Примечание
Query, Path и другие классы, которые вы увидите позже, являются подклассами общего класса Param.
Все они используют одни и те же параметры для дополнительной валидации и метаданных, которые вы видели.
Технические детали
Когда вы импортируете Query, Path и другие из fastapi, на самом деле это функции.
Которые при вызове возвращают экземпляры классов с тем же именем.
Итак, вы импортируете Query, который является функцией. И когда вы вызываете её, она возвращает экземпляр класса, также называемого Query.
Эти функции существуют (вместо простого использования классов напрямую), чтобы ваш редактор не помечал ошибки об их типах.
Таким образом, вы можете использовать свой обычный редактор и инструменты программирования без необходимости добавлять пользовательские конфигурации, чтобы игнорировать эти ошибки.