Form Data¶
AI coding agents
Use the official FastAPI skill for your installed version. Install it from your project directory:
uvx library-skills
See Develop with AI.
🌐 Traducción por IA y humanos
Esta traducción fue hecha por IA guiada por humanos. 🤝
Podría tener errores al interpretar el significado original, o sonar poco natural, etc. 🤖
Puedes mejorar esta traducción ayudándonos a guiar mejor al LLM de IA.
Cuando necesitas recibir campos de formulario en lugar de JSON, puedes usar Form.
Nota
Para usar formularios, primero instala python-multipart.
Añádelo a tu proyecto:
$ uv add python-multipart
Importa Form¶
Importa Form desde fastapi:
from typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
return {"username": username}
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
return {"username": username}
Define parámetros de Form¶
Crea parámetros de formulario de la misma manera que lo harías para Body o Query:
from typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: Annotated[str, Form()], password: Annotated[str, Form()]):
return {"username": username}
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
return {"username": username}
Por ejemplo, en una de las formas en las que se puede usar la especificación OAuth2 (llamada "password flow") se requiere enviar un username y password como campos de formulario.
La especificación requiere que los campos se llamen exactamente username y password, y que se envíen como campos de formulario, no JSON.
Con Form puedes declarar las mismas configuraciones que con Body (y Query, Path, Cookie), incluyendo validación, ejemplos, un alias (por ejemplo, user-name en lugar de username), etc.
Nota
Form es una clase que hereda directamente de Body.
Consejo
Para declarar bodies de formularios, necesitas usar Form explícitamente, porque sin él, los parámetros se interpretarían como parámetros de query o como parámetros de body (JSON).
Campos de formulario booleanos¶
Los navegadores omiten las casillas de verificación no marcadas al enviar formularios HTML. Declara un parámetro de formulario booleano con un valor por defecto de False para recibir False cuando la casilla no esté marcada:
from typing import Annotated
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/preferences/")
async def update_preferences(subscribe: Annotated[bool, Form()] = False):
return {"subscribe": subscribe}
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/preferences/")
async def update_preferences(subscribe: bool = Form(default=False)):
return {"subscribe": subscribe}
Una casilla de verificación marcada envía su valor, que por defecto es "on". FastAPI acepta "on" como True.
Sobre "Campos de formulario"¶
La manera en que los formularios HTML (<form></form>) envían los datos al servidor normalmente usa una codificación "especial" para esos datos, es diferente de JSON.
FastAPI se encargará de leer esos datos del lugar correcto en lugar de JSON.
Detalles técnicos
Los datos de formularios normalmente se codifican usando el "media type" application/x-www-form-urlencoded.
Pero cuando el formulario incluye archivos, se codifica como multipart/form-data. Leerás sobre la gestión de archivos en el próximo capítulo.
Puedes usar Form(media_type="multipart/form-data") para describir un formulario multipart en OpenAPI. Basta con configurarlo en un parámetro al combinar parámetros de formulario o modelos.
Si quieres leer más sobre estas codificaciones y campos de formulario, dirígete a la documentación web de MDN para POST.
Advertencia
Puedes declarar múltiples parámetros Form en una path operation, pero no puedes también declarar campos Body que esperas recibir como JSON, ya que el request tendrá el body codificado usando application/x-www-form-urlencoded en lugar de application/json.
Esto no es una limitación de FastAPI, es parte del protocolo HTTP.
Recapitulación¶
Usa Form para declarar parámetros de entrada de form data.