fastapi/docs/uk/docs/tutorial/request-form-models.md

Моделі форм

У FastAPI ви можете використовувати Pydantic-моделі для оголошення полів форми.

/// note | Примітка

Щоб використовувати форми, спочатку встановіть python-multipart.

Додайте його до вашого проєкту:

$ uv add python-multipart

///

/// note | Примітка

Це підтримується, починаючи з FastAPI версії 0.113.0. 🤓

///

Pydantic-моделі для форм

Вам просто потрібно оголосити Pydantic-модель з полями, які ви хочете отримати як поля форми, а потім оголосити параметр як Form:

{* ../../docs_src/request_form_models/tutorial001_an_py310.py hl[9:11,15] *}

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

Для прапорців HTML оголошуйте булеві поля зі значенням за замовчуванням False.

Перевірте документацію

Ви можете перевірити це в UI документації за /docs:

Забороніть додаткові поля форми

У деяких особливих випадках (ймовірно, не дуже поширених) ви можете обмежити поля форми лише тими, які були оголошені в Pydantic-моделі. І заборонити будь-які додаткові поля.

/// note | Примітка

Це підтримується, починаючи з FastAPI версії 0.114.0. 🤓

///

Ви можете використати конфігурацію Pydantic-моделі, щоб заборонити forbid будь-які додаткові extra поля:

{* ../../docs_src/request_form_models/tutorial002_an_py310.py hl[12] *}

Якщо клієнт спробує надіслати додаткові дані, він отримає відповідь з помилкою.

Наприклад, якщо клієнт спробує надіслати поля форми:

• username: Rick
• password: Portal Gun
• extra: Mr. Poopybutthole

Він отримає відповідь із помилкою, яка повідомляє, що поле extra не дозволено:

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["body", "extra"],
            "msg": "Extra inputs are not permitted",
            "input": "Mr. Poopybutthole"
        }
    ]
}

Поєднуйте моделі форм

Ви можете поєднувати кілька моделей форм з окремими параметрами Form.

{* ../../docs_src/request_form_models/tutorial003_an_py310.py hl[9:14,19:21] *}

Клієнт надсилає name, tags і token як поля форми. Кожна модель перевіряє поля форми незалежно.

Конфігурація extra кожної моделі застосовується до всіх полів форми, зокрема полів і файлів, оголошених в інших параметрах або залежностях. З extra="forbid" будь-яке поле поза цією моделлю відхиляється. З extra="allow" ці поля включаються як додаткові поля моделі.

Якщо кілька оголошень використовують однакове ім'я поля форми, кожне перевіряє значення цього поля. Використовуйте сумісні типи й обмеження для спільних полів, щоб схема OpenAPI могла описувати їх узгоджено.

Необов'язкові моделі форм

Оголосіть модель форми з | None і значенням за замовчуванням None, щоб зробити групу необов'язковою.

{* ../../docs_src/request_form_models/tutorial005_an_py310.py hl[17] *}

Якщо не надіслано ані name, ані age, profile має значення None. Якщо надіслано хоча б одне з них, FastAPI перевіряє модель і вимагає обидва поля. Надіслане порожнє значення також вважається наданням поля.

Використання | None без значення за замовчуванням залишає параметр обов'язковим.

Додаткові поля обробляються відповідно до конфігурації extra моделі. Ігноровані додаткові поля не роблять модель присутньою.

Необов'язкова модель, що містить лише невстановлені прапорці, пропускається. Надішліть значення, наприклад enabled=false, щоб надати її явно.

Необов'язкові об'єднання моделей форм

Ви також можете використовувати необов'язкове об'єднання моделей.

{* ../../docs_src/request_form_models/tutorial006_an_py310.py hl[9:16,21] *}

Якщо жодного поля форми не надіслано, contact має значення None. Надішліть kind=person разом із name або kind=company разом із company_name. Дискримінатор вибирає модель для перевірки.

Поєднуйте об'єднання моделей форм

Ви можете поєднувати об'єднання з іншими моделями форм, окремими параметрами Form і параметрами File. Кожне об'єднання перевіряється незалежно.

{* ../../docs_src/request_form_models/tutorial007_an_py310.py hl[31:35] *}

Надсилайте всі поля в одній формі. Наприклад, надішліть contact_type=person, name=Rick, notification_type=email, email=rick@example.com і token=secret.

Не надсилайте поля сповіщення, щоб залишити notification зі значенням None.

Моделі форм і файли

Ви також можете поєднувати модель форми з параметрами файлів.

{* ../../docs_src/request_form_models/tutorial004_an_py310.py hl[14] *}

Тут клієнт надсилає поле name і файл avatar, використовуючи multipart/form-data.

Підсумок

У FastAPI ви можете використовувати Pydantic-моделі для оголошення полів форми. 😎