Manejo de formularios — Flask-WTF
En este capítulo aprenderás a manejar formularios de forma estandarizada con Flask-WTF: definir clases de formulario, protección automática CSRF, validación de campos y mensajes de error.
¿Por qué usar Flask-WTF?
Los formularios de registro e inicio de sesión del capítulo anterior fueron escritos a mano: manualmente desderequest.form.get()obtener valores, validar manualmente y mostrar errores manualmente.
Flask-WTFBasado en WTForms para Flask, proporciona:
- Definición de clases de formulario, gestión centralizada de campos + reglas de validación
- Protección CSRF automática
- Renderizar campos y mensajes de error en plantillas
form.validate_on_submit()Manejo unificado de la evaluación de GET/POST y la validación
Instalación y configuración
(venv) $ pip install flask-wtf
Configura SECRET_KEY en app.py (el Token CSRF depende de esta clave):
Ejemplo
app.config['SECRET_KEY'] = 'your-secret-key' # En producción, usa variables de entorno
app.config['WTF_CSRF_ENABLED'] = True # Habilitado por defecto, se declara explícitamente
Definir la clase de formulario
Ejemplo
from flask_wtf import FlaskForm
from wtforms import StringField, PasswordField, EmailField, BooleanField
from wtforms.validators import DataRequired, Length, Email, EqualTo, ValidationError
from app.models import User
class RegisterForm(FlaskForm):
"""Formulario de registro"""
username = StringField('Nombre de usuario', validators=[
DataRequired(message='El nombre de usuario no puede estar vacío'),
Length(min=3, max=50, message='El nombre de usuario debe tener entre 3 y 50 caracteres')
])
email = EmailField('Correo electrónico', validators=[
DataRequired(message='El correo electrónico no puede estar vacío'),
Email(message='Por favor, introduce una dirección de correo válida')
])
password = PasswordField('Contraseña', validators=[
DataRequired(message='La contraseña no puede estar vacía'),
Length(min=6, message='La contraseña debe tener al menos 6 caracteres')
])
confirm_password = PasswordField('Confirmar contraseña', validators=[
DataRequired(message='Por favor, introduce la contraseña nuevamente'),
EqualTo('password', message='Las contraseñas no coinciden')
])
# Validador personalizado: verifica si el nombre de usuario ya está registrado
def validate_username(self, field):
if User.query.filter_by(username=field.data).first():
raise ValidationError('Ese nombre de usuario ya está en uso.')
def validate_email(self, field):
if User.query.filter_by(email=field.data).first():
raise ValidationError('Ese correo electrónico ya está registrado.')
class LoginForm(FlaskForm):
"""Formulario de inicio de sesión"""
username = StringField('Nombre de usuario', validators=[
DataRequired(message='El nombre de usuario no puede estar vacío')
])
password = PasswordField('Contraseña', validators=[
DataRequired(message='La contraseña no puede estar vacía')
])
remember = BooleanField('Recuérdame')
Tipos de campos comunes
| Clase de campo | Etiqueta HTML | Descripción |
|---|---|---|
| StringField | <input type="text"> | Texto de una sola línea |
| PasswordField | <input type="password"> | Campo de contraseña |
| EmailField | <input type="email"> | Campo de correo electrónico |
| TextAreaField | <textarea> | Texto de varias líneas |
| BooleanField | <input type="checkbox"> | Casilla de verificación |
| SelectField | <select> | Selección desplegable |
Validadores comunes
| Validador | Función |
|---|---|
| DataRequired() | El campo no puede estar vacío |
| Length(min=, max=) | Límite de longitud de caracteres |
| Email() | Validación de formato de correo electrónico |
| EqualTo('field_name') | Coincide con el valor de otro campo |
| Optional() | Permite que el campo esté vacío (omite validadores posteriores) |
Usar formularios en funciones de vista
Ejemplo
from flask import Blueprint, render_template, redirect, url_for, flash
from flask_login import login_user, logout_user, login_required, current_user
from app.forms import RegisterForm, LoginForm
from app.models import User, db
auth_bp = Blueprint('auth', __name__)
@auth_bp.route("/register", methods=['GET', 'POST'])
def register():
if current_user.is_authenticated:
return redirect(url_for('main.index'))
form = RegisterForm()
# form.validate_on_submit() valida el formulario en las solicitudes POST
# Devuelve False en solicitudes GET o cuando falla la validación
if form.validate_on_submit():
user = User(username=form.username.data, email=form.email.data)
user.set_password(form.password.data)
db.session.add(user)
db.session.commit()
login_user(user)
flash(f'¡Registro exitoso, bienvenido, {user.username}!', 'success')
return redirect(url_for('main.index'))
# En solicitudes GET o cuando falla la validación, renderiza la plantilla con el formulario
return render_template('register.html', form=form)
@auth_bp.route("/login", methods=['GET', 'POST'])
def login():
if current_user.is_authenticated:
return redirect(url_for('main.index'))
form = LoginForm()
if form.validate_on_submit():
user = User.query.filter_by(username=form.username.data).first()
if user is None or not user.check_password(form.password.data):
flash('Nombre de usuario o contraseña incorrectos.', 'error')
return render_template('login.html', form=form)
login_user(user, remember=form.remember.data)
flash(f'¡Bienvenido de nuevo, {user.username}!', 'success')
next_page = request.args.get('next')
return redirect(next_page or url_for('main.index'))
return render_template('login.html', form=form)
Renderizar formularios en plantillas
Ejemplo
{% extends 'base.html' %}
{% block title %}Registro - Blog de EJEMPLO{% endblock %}
{% block content %}
<div class="auth-form">
<h2>Registro</h2>
<form method="post">
<!-- form.hidden_tag() genera automáticamente el campo oculto del Token CSRF -->
{{ form.hidden_tag() }}
<div class="form-group">
{{ form.username.label }}
{{ form.username(class="form-input") }}
{% if form.username.errors %}
{% for error in form.username.errors %}
<span class="field-error">{{ error }}</span>
{% endfor %}
{% endif %}
</div>
<div class="form-group">
{{ form.email.label }}
{{ form.email(class="form-input") }}
{% for error in form.email.errors %}
<span class="field-error">{{ error }}</span>
{% endfor %}
</div>
<div class="form-group">
{{ form.password.label }}
{{ form.password(class="form-input") }}
{% for error in form.password.errors %}
<span class="field-error">{{ error }}</span>
{% endfor %}
</div>
<div class="form-group">
{{ form.confirm_password.label }}
{{ form.confirm_password(class="form-input") }}
{% for error in form.confirm_password.errors %}
<span class="field-error">{{ error }}</span>
{% endfor %}
</div>
{{ form.submit(class="btn-submit") }}
</form>
<p class="form-footer">
¿Ya tienes cuenta?<a href="{{ url_for('auth.login') }}">Inicia sesión ahora</a>
</p>
</div>
{% endblock %}
La protección CSRF de Flask-WTF es automática:
form.hidden_tag()Genera un campo oculto<input>que contiene un Token aleatorio. El servidor verifica este Token antes de aceptar solicitudes POST. Cualquier formulario enviado desde un sitio externo será rechazado por no tener el Token correcto.
Comparación de request.form manual vs Flask-WTF
| Aspecto | request.form manual | Flask-WTF |
|---|---|---|
| Líneas de código | Repetir tres pasos (obtener/validar/reportar) para cada campo | Definir la clase de formulario una vez |
| Protección CSRF | Requiere implementación manual | Automática |
| Validación personalizada | if/else manual | Método validate_xxx |
| Visualización de errores | Concatenación manual | form.field.errors se recopila automáticamente |
| Escenarios de aplicación | Formularios simples (como un cuadro de búsqueda) | Formularios complejos (registro, inicio de sesión, edición de perfil) |
Resumen del capítulo
En este capítulo refactorizaste los formularios de autenticación con Flask-WTF: FlaskForm define campos y validadores, validate_xxx para validación personalizada, form.validate_on_submit() maneja uniformemente la validación POST, form.hidden_tag() para protección CSRF automática, y renderizado de mensajes de error en plantillas.
El manejo de formularios ahora es más estandarizado y seguro.
Otras extensiones