Тіло - Вкладені моделі¶

ЗFastAPI ви можете визначати, перевіряти, документувати та використовувати моделі, які можуть бути вкладені на будь-яку глибину (завдяки Pydantic).

Поля списку¶

Ви можете визначити атрибут як підтип. Наприклад, Python-список (list):

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:list=[]@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item):results={"item_id":item_id,"item":item}returnresults

Це зробитьtags списком, хоча не визначається тип елементів списку.

Поля списку з параметром типу¶

Але Python має специфічний спосіб оголошення списків з внутрішніми типами або «параметрами типу»:

Оголошенняlist з параметром типу¶

Щоб оголосити типи з параметрами типу (внутрішніми типами), такими якlist,dict,tuple,передайте внутрішні тип(и) як «параметри типу», використовуючи квадратні дужки:[ and]

my_list:list[str]

Це стандартний синтаксис Python для оголошення типів.

Використовуйте той самий стандартний синтаксис для атрибутів моделей з внутрішніми типами.

Отже, у нашому прикладі, ми можемо зробитиtags саме «списком рядків»:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:list[str]=[]@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item):results={"item_id":item_id,"item":item}returnresults

Типи множин¶

Але потім ми подумали, що теги не повинні повторюватися, вони, ймовірно, повинні бути унікальними рядками.

І Python має спеціальний тип даних для множин унікальних елементів — цеset.

Тому ми можемо оголоситиtags як множину рядків:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:set[str]=set()@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item):results={"item_id":item_id,"item":item}returnresults

Навіть якщо ви отримаєте запит з дубльованими даними, він буде перетворений у множину унікальних елементів.

І коли ви будете виводити ці дані, навіть якщо джерело містить дублікати, вони будуть виведені як множина унікальних елементів.

І це буде анотовано/документовано відповідно.

Вкладені моделі¶

Кожен атрибут моделі Pydantic має тип.

Але цей тип сам може бути іншою моделлю Pydantic.

Отже, ви можете оголосити глибоко вкладені JSON «об'єкти» з конкретними іменами атрибутів, типами та перевірками.

Усе це, вкладене без обмежень.

Визначення підмоделі¶

Наприклад, ми можемо визначити модельImage:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classImage(BaseModel):url:strname:strclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:set[str]=set()image:Image|None=None@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item):results={"item_id":item_id,"item":item}returnresults

Використання підмоделі як типу¶

А потім ми можемо використовувати її як тип атрибута:

fromfastapiimportFastAPIfrompydanticimportBaseModelapp=FastAPI()classImage(BaseModel):url:strname:strclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:set[str]=set()image:Image|None=None@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item):results={"item_id":item_id,"item":item}returnresults

Це означатиме, щоFastAPI очікуватиме тіло запиту такого вигляду:

{"name":"Foo","description":"The pretender","price":42.0,"tax":3.2,"tags":["rock","metal","bar"],"image":{"url":"http://example.com/baz.jpg","name":"The Foo live"}}

Завдяки такій декларації уFastAPI ви отримуєте:

• Підтримку в редакторі (автозавершення тощо), навіть для вкладених моделей
• Конвертацію даних
• Валідацію даних
• Автоматичну документацію

Спеціальні типи та валідація¶

Окрім звичайних типів, таких якstr,int,float, та ін. ви можете використовувати складніші типи, які наслідуютьstr.

Щоб побачити всі доступні варіанти, ознайомтеся з оглядомтипів у Pydantic. Деякі приклади будуть у наступних розділах.

Наприклад, у моделіImage є полеurl, тому ми можемо оголосити його якHttpUrl від Pydantic замістьstr:

fromfastapiimportFastAPIfrompydanticimportBaseModel,HttpUrlapp=FastAPI()classImage(BaseModel):url:HttpUrlname:strclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:set[str]=set()image:Image|None=None@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item):results={"item_id":item_id,"item":item}returnresults

Рядок буде перевірено як дійсну URL-адресу і задокументовано в JSON Schema / OpenAPI як URL.

Атрибути зі списками підмоделей¶

У Pydantic ви можете використовувати моделі як підтипи дляlist,set тощо:

fromfastapiimportFastAPIfrompydanticimportBaseModel,HttpUrlapp=FastAPI()classImage(BaseModel):url:HttpUrlname:strclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:set[str]=set()images:list[Image]|None=None@app.put("/items/{item_id}")asyncdefupdate_item(item_id:int,item:Item):results={"item_id":item_id,"item":item}returnresults

Це означає, щоFastAPI буде очікувати (конвертувати, валідувати, документувати тощо) JSON тіло запиту у вигляді:

{"name":"Foo","description":"The pretender","price":42.0,"tax":3.2,"tags":["rock","metal","bar"],"images":[{"url":"http://example.com/baz.jpg","name":"The Foo live"},{"url":"http://example.com/dave.jpg","name":"The Baz"}]}

Глибоко вкладені моделі¶

Ви можете визначати вкладені моделі довільної глибини:

fromfastapiimportFastAPIfrompydanticimportBaseModel,HttpUrlapp=FastAPI()classImage(BaseModel):url:HttpUrlname:strclassItem(BaseModel):name:strdescription:str|None=Noneprice:floattax:float|None=Nonetags:set[str]=set()images:list[Image]|None=NoneclassOffer(BaseModel):name:strdescription:str|None=Noneprice:floatitems:list[Item]@app.post("/offers/")asyncdefcreate_offer(offer:Offer):returnoffer

Тіла запитів, що складаються зі списків¶

Якщо верхній рівень JSON тіла, яке ви очікуєте, є JSONмасивом (у Python —list), ви можете оголосити тип у параметрі функції, як і в моделях Pydantic:

images:list[Image]

наприклад:

fromfastapiimportFastAPIfrompydanticimportBaseModel,HttpUrlapp=FastAPI()classImage(BaseModel):url:HttpUrlname:str@app.post("/images/multiple/")asyncdefcreate_multiple_images(images:list[Image]):returnimages

Підтримка в редакторі всюди¶

Ви отримаєте підтримку в редакторі всюди.

Навіть для елементів у списках:

Ви не змогли б отримати таку підтримку в редакторі, якби працювали напряму зіdict, а не з моделями Pydantic.

Але вам не потрібно турбуватися про це: вхідні dict'и автоматично конвертуються, а вихідні дані автоматично перетворюються в JSON.

Тіла з довільнимиdict¶

Ви також можете оголосити тіло якdict з ключами одного типу та значеннями іншого типу.

Це корисно, якщо ви не знаєте наперед, які імена полів будуть дійсними (як у випадку з моделями Pydantic).

Це буде корисно, якщо ви хочете приймати ключі, які заздалегідь невідомі.

Це також зручно, якщо ви хочете мати ключі іншого типу (наприклад,int).

Ось що ми розглянемо далі.

У цьому випадку ви можете приймати будь-якийdict, якщо його ключі — цеint, а значення —float:

fromfastapiimportFastAPIapp=FastAPI()@app.post("/index-weights/")asyncdefcreate_index_weights(weights:dict[int,float]):returnweights

Підсумок¶

ЗFastAPI ви маєте максимальну гнучкість завдяки моделям Pydantic, зберігаючи при цьому код простим, коротким та елегантним.

А також отримуєте всі переваги:

• Підтримка в редакторі (автодоповнення всюди!)
• Конвертація даних (парсинг/сериалізація)
• Валідація даних
• Документація схем
• Автоматичне створення документації