Параметр запроса q имеет тип str | None, что означает, что он имеет тип str, но также может быть None, и действительно, значение по умолчанию — None, поэтому FastAPI поймёт, что он необязательный.
Примечание
FastAPI поймёт, что значение q не является обязательным, из-за значения по умолчанию = None.
Наличие str | None позволит вашему редактору обеспечить лучшую поддержку и обнаружение ошибок.
Теперь, когда у нас есть этот Annotated, куда мы можем поместить больше информации (в данном случае некоторую дополнительную валидацию), добавьте Query внутрь Annotated и установите параметр max_length равным 50:
Обратите внимание, что значение по умолчанию по-прежнему None, поэтому параметр по-прежнему необязательный.
Но теперь, имея Query(max_length=50) внутри Annotated, мы сообщаем FastAPI, что хотим, чтобы для этого значения была дополнительная валидация, мы хотим, чтобы оно имело максимум 50 символов. 😎
Совет
Здесь мы используем Query(), потому что это параметр запроса. Позже мы увидим другие, такие как Path(), Body(), Header() и Cookie(), которые также принимают те же аргументы, что и Query().
Теперь FastAPI будет:
Валидировать данные, убедившись, что максимальная длина составляет 50 символов
Показывать понятную ошибку клиенту, когда данные недействительны
Документировать параметр в схеме OpenAPI операции пути (поэтому он появится в автоматическом интерфейсе документации)
Альтернатива (старая): Query как значение по умолчанию¶
Предыдущие версии FastAPI (до 0.95.0) требовали использовать Query в качестве значения по умолчанию для вашего параметра вместо помещения его в Annotated; есть большая вероятность, что вы увидите код, использующий его, поэтому я объясню это вам.
Совет
Для нового кода и всегда, когда это возможно, используйте Annotated, как объяснено выше. Есть несколько преимуществ (объяснённых ниже) и никаких недостатков. 🍰
Вот как вы бы использовали Query() в качестве значения по умолчанию для параметра функции, установив параметр max_length равным 50:
Как и в этом случае (без использования Annotated), нам нужно заменить значение по умолчанию None в функции на Query(), теперь нам нужно установить значение по умолчанию с помощью параметра Query(default=None), это служит той же цели определения значения по умолчанию (по крайней мере, для FastAPI).
Итак:
q:str|None=Query(default=None)
...делает параметр необязательным со значением по умолчанию None, так же как:
q:str|None=None
Но версия с Query явно объявляет его как параметр запроса.
Затем мы можем передать больше параметров в Query. В данном случае параметр max_length, который применяется к строкам:
q:str|None=Query(default=None,max_length=50)
Это будет валидировать данные, показывать понятную ошибку, когда данные недействительны, и документировать параметр в схеме OpenAPI операции пути.
Использование Annotated рекомендуется вместо значения по умолчанию в параметрах функции, это лучше по нескольким причинам. 🤓
Значение по умолчанию для параметра функции — это фактическое значение по умолчанию, что более интуитивно понятно в Python в целом. 😌
Вы могли бы вызвать ту же функцию в других местах без FastAPI, и она бы работала как ожидалось. Если есть обязательный параметр (без значения по умолчанию), ваш редактор сообщит вам об ошибке, Python также выдаст ошибку, если вы запустите его без передачи обязательного параметра.
Когда вы не используете Annotated и вместо этого используете (старый) стиль со значением по умолчанию, если вы вызовете эту функцию без FastAPI в других местах, вам нужно помнить, чтобы передавать аргументы функции, чтобы она работала правильно, иначе значения будут отличаться от ожидаемых (например, QueryInfo или что-то подобное вместо str). И ваш редактор не будет жаловаться, и Python не будет жаловаться при запуске этой функции, только когда операции внутри неё завершатся ошибкой.
Поскольку Annotated может иметь более одной аннотации метаданных, вы теперь можете даже использовать одну и ту же функцию с другими инструментами, такими как Typer. 🚀
Этот конкретный шаблон регулярного выражения проверяет, что полученное значение параметра:
^: начинается со следующих символов, перед ними нет символов.
fixedquery: имеет точное значение fixedquery.
$: заканчивается здесь, после fixedquery нет никаких других символов.
Если вы чувствуете себя потерянным со всеми этими идеями «регулярных выражений», не волнуйтесь. Это сложная тема для многих людей. Вы всё ещё можете делать много вещей, пока не нуждаясь в регулярных выражениях.
Теперь вы знаете, что когда они вам понадобятся, вы можете использовать их в FastAPI.
Когда нам не нужно объявлять дополнительные валидации или метаданные, мы можем сделать параметр запроса q обязательным, просто не объявляя значение по умолчанию, например:
q:str
вместо:
q:str|None=None
Но теперь мы объявляем его с помощью Query, например так:
q:Annotated[str|None,Query(min_length=3)]=None
Итак, когда вам нужно объявить значение как обязательное при использовании Query, вы можете просто не объявлять значение по умолчанию:
Вы можете объявить, что параметр может принимать None, но при этом он всё равно обязателен. Это заставит клиентов отправлять значение, даже если это значение None.
Для этого вы можете объявить, что None является допустимым типом, но просто не объявлять значение по умолчанию:
Когда вы определяете параметр запроса явно с помощью Query, вы также можете объявить его для получения списка значений, или, другими словами, для получения нескольких значений.
Например, чтобы объявить параметр запроса q, который может появляться в URL несколько раз, вы можете написать:
Эта информация будет включена в сгенерированный OpenAPI и использоваться пользовательскими интерфейсами документации и внешними инструментами.
Примечание
Имейте в виду, что разные инструменты могут иметь разный уровень поддержки OpenAPI.
Некоторые из них могут ещё не отображать всю дополнительную объявленную информацию, хотя в большинстве случаев отсутствующая функция уже запланирована к разработке.
fromtypingimportAnnotatedfromfastapiimportFastAPI,Queryapp=FastAPI()@app.get("/items/")asyncdefread_items(q:Annotated[str|None,Query(title="Query string",description="Query string for the items to search in the database that have a good match",min_length=3,),]=None,):results={"items":[{"item_id":"Foo"},{"item_id":"Bar"}]}ifq:results.update({"q":q})returnresults
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
fromfastapiimportFastAPI,Queryapp=FastAPI()@app.get("/items/")asyncdefread_items(q:str|None=Query(default=None,title="Query string",description="Query string for the items to search in the database that have a good match",min_length=3,),):results={"items":[{"item_id":"Foo"},{"item_id":"Bar"}]}ifq:results.update({"q":q})returnresults
Теперь допустим, вам больше не нравится этот параметр.
Вам нужно оставить его на некоторое время, потому что его используют клиенты, но вы хотите, чтобы документация чётко показывала его как устаревший.
Затем передайте параметр deprecated=True в Query:
fromtypingimportAnnotatedfromfastapiimportFastAPI,Queryapp=FastAPI()@app.get("/items/")asyncdefread_items(q:Annotated[str|None,Query(alias="item-query",title="Query string",description="Query string for the items to search in the database that have a good match",min_length=3,max_length=50,pattern="^fixedquery$",deprecated=True,),]=None,):results={"items":[{"item_id":"Foo"},{"item_id":"Bar"}]}ifq:results.update({"q":q})returnresults
🤓 Другие версии и варианты
Совет
По возможности предпочитайте версию с Annotated.
fromfastapiimportFastAPI,Queryapp=FastAPI()@app.get("/items/")asyncdefread_items(q:str|None=Query(default=None,alias="item-query",title="Query string",description="Query string for the items to search in the database that have a good match",min_length=3,max_length=50,pattern="^fixedquery$",deprecated=True,),):results={"items":[{"item_id":"Foo"},{"item_id":"Bar"}]}ifq:results.update({"q":q})returnresults
Чтобы исключить параметр запроса из сгенерированной схемы OpenAPI (и, следовательно, из систем автоматической документации), установите параметр include_in_schema у Query в False:
Могут быть случаи, когда вам нужно выполнить пользовательскую валидацию, которую нельзя сделать с помощью параметров, показанных выше.
В таких случаях вы можете использовать функцию пользовательского валидатора, которая применяется после обычной валидации (например, после проверки того, что значение является str).
Например, этот пользовательский валидатор проверяет, что ID элемента начинается с isbn- для номера книги ISBN или с imdb- для URL-ID фильма IMDB:
importrandomfromtypingimportAnnotatedfromfastapiimportFastAPIfrompydanticimportAfterValidatorapp=FastAPI()data={"isbn-9781529046137":"The Hitchhiker's Guide to the Galaxy","imdb-tt0371724":"The Hitchhiker's Guide to the Galaxy","isbn-9781439512982":"Isaac Asimov: The Complete Stories, Vol. 2",}defcheck_valid_id(id:str):ifnotid.startswith(("isbn-","imdb-")):raiseValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')returnid@app.get("/items/")asyncdefread_items(id:Annotated[str|None,AfterValidator(check_valid_id)]=None,):ifid:item=data.get(id)else:id,item=random.choice(list(data.items()))return{"id":id,"name":item}
Примечание
Это доступно в Pydantic версии 2 или выше. 😎
Совет
Если вам нужно выполнить какую-либо валидацию, требующую взаимодействия с каким-либо внешним компонентом, например с базой данных или другим API, вместо этого вам следует использовать зависимости FastAPI, о которых вы узнаете позже.
Эти пользовательские валидаторы предназначены для вещей, которые можно проверить, используя только те же данные, предоставленные в запросе.
Вы заметили? Строка, использующая value.startswith(), может принимать кортеж, и она проверит каждое значение в кортеже:
# Код выше опущен 👆defcheck_valid_id(id:str):ifnotid.startswith(("isbn-","imdb-")):raiseValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')returnid# Код ниже опущен 👇
👀 Предпросмотр полного файла
importrandomfromtypingimportAnnotatedfromfastapiimportFastAPIfrompydanticimportAfterValidatorapp=FastAPI()data={"isbn-9781529046137":"The Hitchhiker's Guide to the Galaxy","imdb-tt0371724":"The Hitchhiker's Guide to the Galaxy","isbn-9781439512982":"Isaac Asimov: The Complete Stories, Vol. 2",}defcheck_valid_id(id:str):ifnotid.startswith(("isbn-","imdb-")):raiseValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')returnid@app.get("/items/")asyncdefread_items(id:Annotated[str|None,AfterValidator(check_valid_id)]=None,):ifid:item=data.get(id)else:id,item=random.choice(list(data.items()))return{"id":id,"name":item}
С помощью data.items() мы получаем итерируемый объект с кортежами, содержащими ключ и значение для каждого элемента словаря.
Мы преобразуем этот итерируемый объект в настоящий list с помощью list(data.items()).
Затем с помощью random.choice() мы можем получить случайное значение из списка, то есть мы получаем кортеж (id, name). Это будет что-то вроде ("imdb-tt0371724", "The Hitchhiker's Guide to the Galaxy").
Затем мы присваиваем эти два значения из кортежа переменным id и name.
Таким образом, если пользователь не предоставил ID элемента, он всё равно получит случайное предложение.
...мы делаем всё это в одной простой строке. 🤯 Разве вы не любите Python? 🐍
# Код выше опущен 👆@app.get("/items/")asyncdefread_items(id:Annotated[str|None,AfterValidator(check_valid_id)]=None,):ifid:item=data.get(id)else:id,item=random.choice(list(data.items()))return{"id":id,"name":item}
👀 Предпросмотр полного файла
importrandomfromtypingimportAnnotatedfromfastapiimportFastAPIfrompydanticimportAfterValidatorapp=FastAPI()data={"isbn-9781529046137":"The Hitchhiker's Guide to the Galaxy","imdb-tt0371724":"The Hitchhiker's Guide to the Galaxy","isbn-9781439512982":"Isaac Asimov: The Complete Stories, Vol. 2",}defcheck_valid_id(id:str):ifnotid.startswith(("isbn-","imdb-")):raiseValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')returnid@app.get("/items/")asyncdefread_items(id:Annotated[str|None,AfterValidator(check_valid_id)]=None,):ifid:item=data.get(id)else:id,item=random.choice(list(data.items()))return{"id":id,"name":item}