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

# Ruta del archivo: app.py
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

# Ruta del archivo: app/forms.py (archivo nuevo)
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 campoEtiqueta HTMLDescripció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

ValidadorFunció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

# Ruta del archivo: app/blueprints/auth.py (register y login refactorizados)
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

<!-- Ruta del archivo: app/templates/register.html -->
{% 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

Aspectorequest.form manualFlask-WTF
Líneas de códigoRepetir tres pasos (obtener/validar/reportar) para cada campoDefinir la clase de formulario una vez
Protección CSRFRequiere implementación manualAutomática
Validación personalizadaif/else manualMétodo validate_xxx
Visualización de erroresConcatenación manualform.field.errors se recopila automáticamente
Escenarios de aplicaciónFormularios 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