Form Data (Datos de Formulario)¶
Cuando necesitas recibir campos de formulario en lugar de JSON, puedes usar Form.
Nota
Para usar formularios, primero instala python-multipart.
Asegúrate de crear un entorno virtual, activarlo, y luego instalarlo, por ejemplo:
$ pip install python-multipart
Importar Form¶
Importa Form de 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}
🤓 Otras versiones y variantes
Consejo
Preferible usar la versión con Annotated si es posible.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login/")
async def login(username: str = Form(), password: str = Form()):
return {"username": username}
Definir parámetros 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}
🤓 Otras versiones y variantes
Consejo
Preferible usar la versión con Annotated si es posible.
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 que la especificación OAuth2 puede ser usada (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 como JSON.
Con Form puedes declarar las mismas configuraciones que con Body (y Query, Path, Cookie), incluyendo validación, ejemplos, un alias (ej. user-name en lugar de username), etc.
Nota
Form es una clase que hereda directamente de Body.
Consejo
Para declarar cuerpos de formulario, necesitas usar Form explícitamente, porque sin él los parámetros serían interpretados como parámetros de query o de cuerpo (JSON).
Sobre "Campos de Formulario"¶
La forma 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 asegurará de leer esos datos del lugar correcto en lugar de JSON.
Detalles Técnicos
Los datos de los formularios se codifican normalmente usando el "media type" application/x-www-form-urlencoded.
Pero cuando el formulario incluye archivos, se codifica como multipart/form-data. Leerás sobre el manejo de archivos en el próximo capítulo.
Si quieres leer más sobre estas codificaciones y campos de formulario, dirígete a la documentación web de MDN para POST.
Aviso
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 la request tendrá el cuerpo 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.
Resumen¶
Usa Form para declarar parámetros de entrada de form data.