Kurs Python · Moduł 5: Flask i aplikacje webowe

Flask-WTF - formularze i walidacja

10 min czytania ·
W tej lekcji13

Witaj ponownie! Darwin tutaj, gotowy pokazać Ci profesjonalne formularze z Flask-WTF!

Do tej pory obsługiwałeś/aś formularze ręcznie przez request.form. To działa, ale nie ma walidacji, nie ma ochrony CSRF, i jest podatne na błędy!

Analogia Safari: Ręczna obsługa formularzy to jak ręczne sprawdzanie każdego turysty bez listy kontrolnej - łatwo coś pominąć! Flask-WTF to jak profesjonalny formularz zgłoszeniowy z automatyczną walidacją - wszystko jest sprawdzone!

Problem z ręcznymi formularza

@app.route('/add-species', methods=['POST'])
def add_species():
    name = request.form.get('name')
    population = request.form.get('population')

    # Brak walidacji - co jeśli name jest puste?
    # Brak walidacji typu - co jeśli population to tekst?
    # Brak ochrony CSRF
    # Trzeba ręcznie sprawdzać wszystko

    if not name:
        return "Błąd: Nazwa jest wymagana", 400

    try:
        population = int(population)
    except ValueError:
        return "Błąd: Populacja musi być liczbą", 400

    # Dodaj do bazy...

Problemy: Długi kod walidacji Brak ochrony CSRF (Cross-Site Request Forgery) Trzeba powtarzać walidację dla każdego formularza Brak automatycznego wyświetlania błędów Trudne w utrzymaniu

Rozwiązanie - Flask-WTF

Flask-WTF to rozszerzenie integrujące WTForms (library do formularzy) z Flask.

Co daje Flask-WTF? Automatyczna walidacja - nie musisz sprawdzać ręcznie Ochrona CSRF - bezpieczeństwo out-of-the-box Klasy formularzy - czytelny, DRY kod Renderowanie w templates - łatwe wyświetlanie Komunikaty błędów - automatyczne wyświetlanie

Instalacja Flask-WTF

pip install Flask-WTF

Flask-WTF automatycznie instaluje WTForms (core library).

Dodaj do requirements.txt

pip freeze > requirements.txt

Konfiguracja Flask-WTF

Flask-WTF wymaga secret key do ochrony CSRF:

# app.py
from flask import Flask
from flask_wtf import FlaskForm

app = Flask(__name__)

# SECRET_KEY jest wymagany dla CSRF protection
app.config['SECRET_KEY'] = 'twój-super-tajny-klucz-12345'  # Zmień w produkcji!

# Alternatywnie - użyj os.urandom()
import os
app.config['SECRET_KEY'] = os.urandom(24)

WAŻNE: W produkcji używaj zmiennych środowiskowych zamiast hardcoded key!

import os
app.config['SECRET_KEY'] = os.environ.get('SECRET_KEY') or 'dev-key-123'

Tworzenie klasy formularza

Formularz to klasa dziedzicząca z FlaskForm:

# forms.py
from flask_wtf import FlaskForm
from wtforms import StringField, IntegerField, TextAreaField, SelectField, SubmitField
from wtforms.validators import DataRequired, Length, NumberRange, Optional

class AddSpeciesForm(FlaskForm):
    name = StringField('Nazwa gatunku',
                      validators=[DataRequired(message='Nazwa jest wymagana'),
                                 Length(min=2, max=100, message='Nazwa musi mieć 2-100 znaków')])

    scientific_name = StringField('Nazwa naukowa',
                                 validators=[DataRequired(),
                                            Length(min=2, max=150)])

    population = IntegerField('Populacja',
                             validators=[DataRequired(),
                                        NumberRange(min=0, message='Populacja nie może być ujemna')])

    habitat = SelectField('Siedlisko',
                         choices=[('savanna', 'Sawanna'),
                                 ('forest', 'Las'),
                                 ('desert', 'Pustynia'),
                                 ('wetland', 'Mokradło')],
                         validators=[DataRequired()])

    notes = TextAreaField('Notatki',
                         validators=[Optional(), Length(max=500)])

    submit = SubmitField('Dodaj gatunek')

Pola formularza:

  • StringField - pole tekstowe (input type="text")
  • IntegerField - liczba całkowita (input type="number")
  • TextAreaField - wieloliniowy tekst (textarea)
  • SelectField - lista rozwijana (select)
  • SubmitField - przycisk submit (button type="submit")

Inne typy pól:

  • EmailField - email z walidacją
  • PasswordField - hasło (input type="password")
  • BooleanField - checkbox
  • DateField - data
  • FileField - upload pliku
  • RadioField - radio buttons
  • DecimalField - liczba zmiennoprzecinkowa

Validatory - walidacja danych

WTForms ma wbudowane validatory:

from wtforms.validators import (
    DataRequired,    # Pole jest wymagane
    Optional,        # Pole opcjonalne
    Length,          # Długość tekstu
    Email,           # Walidacja email
    EqualTo,         # Równe innemu polu (hasła)
    NumberRange,     # Zakres liczb
    Regexp,          # Regex
    URL,             # Walidacja URL
    AnyOf,           # Jedna z wartości
    NoneOf           # Żadna z wartości
)

Przykłady:

from wtforms import StringField, IntegerField, PasswordField
from wtforms.validators import DataRequired, Length, Email, EqualTo, NumberRange

class RegistrationForm(FlaskForm):
    username = StringField('Username',
                          validators=[DataRequired(),
                                     Length(min=4, max=20)])

    email = EmailField('Email',
                      validators=[DataRequired(), Email()])

    password = PasswordField('Hasło',
                            validators=[DataRequired(),
                                       Length(min=8)])

    confirm_password = PasswordField('Potwierdź hasło',
                                    validators=[DataRequired(),
                                               EqualTo('password', message='Hasła muszą być identyczne')])

    age = IntegerField('Wiek',
                      validators=[NumberRange(min=13, max=120,
                                            message='Wiek musi być między 13 a 120')])

Używanie formularza w route

# app.py
from flask import Flask, render_template, redirect, url_for, flash
from forms import AddSpeciesForm

app = Flask(__name__)
app.config['SECRET_KEY'] = 'your-secret-key-123'

species_db = {}
next_id = 1

@app.route('/species/add', methods=['GET', 'POST'])
def add_species():
    form = AddSpeciesForm()

    # POST request + walidacja przeszła
    if form.validate_on_submit():
        global next_id

        # Pobierz dane z formularza
        new_species = {
            'id': next_id,
            'name': form.name.data,
            'scientific_name': form.scientific_name.data,
            'population': form.population.data,
            'habitat': form.habitat.data,
            'notes': form.notes.data
        }

        species_db[next_id] = new_species
        next_id += 1

        # Flash message - komunikat sukcesu
        flash(f'Gatunek {new_species["name"]} został dodany!', 'success')

        return redirect(url_for('list_species'))

    # GET request lub walidacja nie przeszła
    return render_template('add_species.html', form=form)

Jak to działa?

  1. GET request → renderuje formularz
  2. POST request → form.validate_on_submit() sprawdza:
    • Czy metoda to POST?
    • Czy token CSRF jest poprawny?
    • Czy wszystkie validatory przeszły?
  3. Jeśli walidacja OK → przetwórz dane (form.nazwa_pola.data)
  4. Jeśli walidacja FAILED → ponownie renderuje formularz z błędami

Renderowanie formularza w template

{% extends 'base.html' %}

{% block title %}Dodaj gatunek - Safari Database{% endblock %}

{% block content %}
    <h2>Dodaj nowy gatunek</h2>

    <form method="POST" novalidate>
        {{ form.hidden_tag() }}  <!-- CSRF token -->

        <div style="margin: 15px 0;">
            {{ form.name.label }}
            {{ form.name(size=40) }}

            {% if form.name.errors %}
                <ul style="color: red; margin: 5px 0;">
                    {% for error in form.name.errors %}
                        <li>{{ error }}</li>
                    {% endfor %}
                </ul>
            {% endif %}
        </div>

        <div style="margin: 15px 0;">
            {{ form.scientific_name.label }}
            {{ form.scientific_name(size=40) }}

            {% if form.scientific_name.errors %}
                <ul style="color: red; margin: 5px 0;">
                    {% for error in form.scientific_name.errors %}
                        <li>{{ error }}</li>
                    {% endfor %}
                </ul>
            {% endif %}
        </div>

        <div style="margin: 15px 0;">
            {{ form.population.label }}
            {{ form.population() }}

            {% if form.population.errors %}
                <ul style="color: red; margin: 5px 0;">
                    {% for error in form.population.errors %}
                        <li>{{ error }}</li>
                    {% endfor %}
                </ul>
            {% endif %}
        </div>

        <div style="margin: 15px 0;">
            {{ form.habitat.label }}
            {{ form.habitat() }}

            {% if form.habitat.errors %}
                <ul style="color: red; margin: 5px 0;">
                    {% for error in form.habitat.errors %}
                        <li>{{ error }}</li>
                    {% endfor %}
                </ul>
            {% endif %}
        </div>

        <div style="margin: 15px 0;">
            {{ form.notes.label }}
            {{ form.notes(rows=5, cols=40) }}

            {% if form.notes.errors %}
                <ul style="color: red; margin: 5px 0;">
                    {% for error in form.notes.errors %}
                        <li>{{ error }}</li>
                    {% endfor %}
                </ul>
            {% endif %}
        </div>

        <div style="margin-top: 20px;">
            {{ form.submit(style='padding: 10px 20px; background: #2c5f2d; color: white; border: none; border-radius: 4px; cursor: pointer;') }}
        </div>
    </form>

    <p style="margin-top: 20px;">
        <a href="{{ url_for('list_species') }}">← Powrót do listy</a>
    </p>
{% endblock %}

Kluczowe elementy:

  1. {{ form.hidden_tag() }} - CSRF token (wymagane!)
  2. {{ form.field_name.label }} - label pola
  3. {{ form.field_name() }} - pole formularza
  4. {% if form.field_name.errors %} - wyświetl błędy

Flash messages - komunikaty

Flask ma wbudowany system flash messages do wyświetlania komunikatów:

from flask import flash

@app.route('/species/add', methods=['POST'])
def add_species():
    form = AddSpeciesForm()

    if form.validate_on_submit():
        # ... dodaj gatunek ...

        flash('Gatunek został dodany!', 'success')
        return redirect(url_for('list_species'))

    # Błąd walidacji
    flash('Popraw błędy w formularzu.', 'error')
    return render_template('add_species.html', form=form)

Kategorie flash:

  • 'success' - sukces (zielony)
  • 'error' - błąd (czerwony)
  • 'warning' - ostrzeżenie (pomarańczowy)
  • 'info' - informacja (niebieski)

Wyświetlanie flash messages w templates

W base.html dodaj:

<!DOCTYPE html>
<html>
<head>...</head>
<body>
    <header>...</header>

    <!-- Flash messages -->
    {% with messages = get_flashed_messages(with_categories=true) %}
        {% if messages %}
            <div style="max-width: 900px; margin: 20px auto;">
                {% for category, message in messages %}
                    <div style="padding: 15px; margin: 10px 0; border-radius: 4px;
                               {% if category == 'success' %}background: #d4edda; color: #155724; border: 1px solid #c3e6cb;
                               {% elif category == 'error' %}background: #f8d7da; color: #721c24; border: 1px solid #f5c6cb;
                               {% elif category == 'warning' %}background: #fff3cd; color: #856404; border: 1px solid #ffeaa7;
                               {% else %}background: #d1ecf1; color: #0c5460; border: 1px solid #bee5eb;{% endif %}">
                        {{ message }}
                    </div>
                {% endfor %}
            </div>
        {% endif %}
    {% endwith %}

    <main>{% block content %}{% endblock %}</main>
</body>
</html>

Makro dla renderowania pól - DRY

Zamiast powtarzać kod dla każdego pola, stwórz makro:

{# templates/macros.html #}
{% macro render_field(field) %}
    <div style="margin: 15px 0;">
        {{ field.label }}
        {{ field(size=40, **kwargs) }}

        {% if field.errors %}
            <ul style="color: #d62828; margin: 5px 0; padding-left: 20px;">
                {% for error in field.errors %}
                    <li>{{ error }}</li>
                {% endfor %}
            </ul>
        {% endif %}
    </div>
{% endmacro %}

{# Użycie w formularzu #}
{% from 'macros.html' import render_field %}

<form method="POST" novalidate>
    {{ form.hidden_tag() }}

    {{ render_field(form.name) }}
    {{ render_field(form.scientific_name) }}
    {{ render_field(form.population) }}
    {{ render_field(form.habitat) }}
    {{ render_field(form.notes) }}

    <div style="margin-top: 20px;">
        {{ form.submit(style='...') }}
    </div>
</form>

Formularz edycji - wypełnianie danymi

# forms.py
class EditSpeciesForm(FlaskForm):
    name = StringField('Nazwa', validators=[DataRequired(), Length(min=2, max=100)])
    scientific_name = StringField('Nazwa naukowa', validators=[DataRequired()])
    population = IntegerField('Populacja', validators=[DataRequired(), NumberRange(min=0)])
    habitat = SelectField('Siedlisko',
                         choices=[('savanna', 'Sawanna'), ('forest', 'Las'),
                                 ('desert', 'Pustynia'), ('wetland', 'Mokradło')])
    notes = TextAreaField('Notatki', validators=[Optional(), Length(max=500)])
    submit = SubmitField('Zapisz zmiany')

# app.py
@app.route('/species/<int:species_id>/edit', methods=['GET', 'POST'])
def edit_species(species_id):
    species = species_db.get(species_id)

    if not species:
        flash('Gatunek nie znaleziony.', 'error')
        return redirect(url_for('list_species'))

    form = EditSpeciesForm()

    if form.validate_on_submit():
        # Aktualizuj dane
        species['name'] = form.name.data
        species['scientific_name'] = form.scientific_name.data
        species['population'] = form.population.data
        species['habitat'] = form.habitat.data
        species['notes'] = form.notes.data

        flash(f'Gatunek {species["name"]} został zaktualizowany!', 'success')
        return redirect(url_for('show_species', species_id=species_id))

    elif request.method == 'GET':
        # Wypełnij formularz aktualnymi danymi
        form.name.data = species['name']
        form.scientific_name.data = species['scientific_name']
        form.population.data = species['population']
        form.habitat.data = species['habitat']
        form.notes.data = species.get('notes', '')

    return render_template('edit_species.html', form=form, species=species)

Logika:

  • GET - wypełnij formularz danymi z bazy
  • POST + valid - zapisz zmiany
  • POST + invalid - wyświetl błędy

Custom validatory

Możesz stworzyć własne validatory:

from wtforms.validators import ValidationError

class AddSpeciesForm(FlaskForm):
    name = StringField('Nazwa', validators=[DataRequired()])
    scientific_name = StringField('Nazwa naukowa', validators=[DataRequired()])
    population = IntegerField('Populacja', validators=[DataRequired()])

    # Custom validator - metoda validate_<field_name>
    def validate_name(self, field):
        # Sprawdź, czy gatunek już istnieje
        for species in species_db.values():
            if species['name'].lower() == field.data.lower():
                raise ValidationError('Gatunek o tej nazwie już istnieje!')

    def validate_scientific_name(self, field):
        # Sprawdź format nazwy naukowej (Genus species)
        parts = field.data.split()
        if len(parts) != 2:
            raise ValidationError('Nazwa naukowa musi mieć format: Genus species')

        # Sprawdź, czy zaczyna się wielką literą
        if not parts[0][0].isupper() or not parts[1][0].islower():
            raise ValidationError('Format: pierwsza wielka, druga mała litera')

Custom validator function:

def validate_population_range(form, field):
    if field.data < 10:
        raise ValidationError('Populacja musi wynosić co najmniej 10 osobników')
    if field.data > 1000000:
        raise ValidationError('Populacja przekracza realistyczny zakres')

class AddSpeciesForm(FlaskForm):
    population = IntegerField('Populacja',
                             validators=[DataRequired(), validate_population_range])

Kompletny przykład - Safari Database z formularzami

forms.py

from flask_wtf import FlaskForm
from wtforms import StringField, IntegerField, TextAreaField, SelectField, SubmitField
from wtforms.validators import DataRequired, Length, NumberRange, Optional, ValidationError

class AddSpeciesForm(FlaskForm):
    name = StringField('Nazwa gatunku',
                      validators=[DataRequired(message='Nazwa jest wymagana'),
                                 Length(min=2, max=100)])

    scientific_name = StringField('Nazwa naukowa',
                                 validators=[DataRequired(), Length(min=5, max=150)])

    population = IntegerField('Populacja',
                             validators=[DataRequired(), NumberRange(min=0)])

    habitat = SelectField('Siedlisko',
                         choices=[('savanna', 'Sawanna'), ('forest', 'Las'),
                                 ('desert', 'Pustynia'), ('wetland', 'Mokradło')],
                         validators=[DataRequired()])

    notes = TextAreaField('Notatki', validators=[Optional(), Length(max=500)])

    submit = SubmitField('Dodaj gatunek')

    def validate_scientific_name(self, field):
        parts = field.data.split()
        if len(parts) < 2:
            raise ValidationError('Nazwa naukowa musi mieć format: Genus species')

app.py

from flask import Flask, render_template, redirect, url_for, flash
from forms import AddSpeciesForm

app = Flask(__name__)
app.config['SECRET_KEY'] = 'your-secret-key-here'

species_db = {
    1: {'id': 1, 'name': 'Lew', 'scientific_name': 'Panthera leo',
        'population': 120, 'habitat': 'savanna', 'notes': ''},
}
next_id = 2

@app.route('/')
def home():
    return render_template('home.html', species_count=len(species_db))

@app.route('/species')
def list_species():
    return render_template('species_list.html', species=list(species_db.values()))

@app.route('/species/add', methods=['GET', 'POST'])
def add_species():
    form = AddSpeciesForm()

    if form.validate_on_submit():
        global next_id

        new_species = {
            'id': next_id,
            'name': form.name.data,
            'scientific_name': form.scientific_name.data,
            'population': form.population.data,
            'habitat': form.habitat.data,
            'notes': form.notes.data
        }

        species_db[next_id] = new_species
        next_id += 1

        flash(f'Gatunek {new_species["name"]} został dodany!', 'success')
        return redirect(url_for('show_species', species_id=new_species['id']))

    return render_template('add_species.html', form=form)

@app.route('/species/<int:species_id>')
def show_species(species_id):
    species = species_db.get(species_id)
    return render_template('species_detail.html', species=species)

if __name__ == '__main__':
    app.run(debug=True)

Analogia Safari finalna: Flask-WTF to jak profesjonalny formularz zgłoszeniowy safari z automatyczną walidacją - sprawdza wiek turysty (NumberRange), wymaga podpisu (DataRequired), weryfikuje email (Email), i chroni przed fałszowaniem dokumentów (CSRF)! Nie musisz ręcznie sprawdzać każdego pola!

Następna lekcja: Darwin pokaże Ci Flask-Login - autentykację użytkowników (logowanie, rejestracja, ochrona routes)!

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Jak zainstalować Flask-WTF?

  2. 2. Po jakiej klasie dziedziczy formularz Flask-WTF?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Układanie w pionie

    Ułóż definicję klasy formularza w Flask-WTF:

  • Klikanie w kolejności

    Ułóż definicję pola StringField z walidatorem DataRequired:

  • Edytor kodu

    Napisz klasę SpeciesForm z polami name (string, wymagane), population (int) i submit.

  • Układanie w poziomie

    Jak sprawdzić czy formularz przeszedł walidację?

  1. PytanieInstalacja Flask-WTF
  2. PytanieKlasa bazowa formularza
  3. PytanieWalidator DataRequired
  4. Ułóż w kolejnościDefinicja formularza
  5. Kliknij w kolejnościStringField z walidatorem
  6. Zadanie z kodemFormularz dodawania gatunku
  7. Ułóż w kolejnościWalidacja formularza

Przydatne artykuły