Periodo 3 · Introduzione a Flask

Avete già costruito un server con i socket: ora vediamo come Flask fa (dietro le quinte) le stesse cose, ma con il protocollo HTTP già pronto all'uso. È il primo passo verso quello che approfondirete in quinta.

marzo – maggio · ~8 settimane · 24 ore · 4 moduli + progetto

Come lavoriamo in questo periodo

Ogni modulo ha un kit da scaricare: un progetto già funzionante, con la grafica pronta. Non si parte mai dal foglio bianco.

1. Scaricate il kit ed estraetelo (non lavorate dentro lo zip!).
2. Avviatelo e guardate cosa fa nel browser.
3. Leggete il codice insieme alla spiegazione di questa pagina: ogni riga importante è commentata.
4. Fate le missioni: piccole modifiche, dalla più facile (⭐) alla più impegnativa (⭐⭐⭐). Le ⭐ le fanno tutti, le ⭐⭐⭐ sono per chi vuole spingersi oltre.

In ogni zip trovate anche COME-AVVIARE.txt (i comandi e gli errori più comuni) e MISSIONI.txt.

Prima di tutto: installare Flask

Serve una volta sola, nel terminale di Visual Studio Code:

pip install flask

Se il comando pip non viene trovato, provate con py -m pip install flask. Per controllare che sia installato: python -c "import flask" non deve dare errori.

3.1 Da socket a framework web

Durata indicativa: 2 settimane

• flask4-1-primo-server.zipIl primo server: quattro route da provare e modificare

Nel Periodo 2 avete scritto un server con socket: apre una porta, aspetta un client, riceve e manda byte. Flask fa esattamente questo sotto il cofano, ma vi risparmia tutta la parte "artigianale".

Che cosa succede quando aprite una pagina

  BROWSER                                   SERVER FLASK (app.py)
  ───────                                   ─────────────────────
  scrivo 127.0.0.1:5000/saluto/Mario
        │  richiesta HTTP:  GET /saluto/Mario
        └──────────────────────────────────►  cerca la route che corrisponde:
                                              @app.route("/saluto/<nome>")
                                              chiama  saluto(nome="Mario")
        ┌──────────────────────────────────   return "<h1>Ciao Mario!</h1>"
        │  risposta HTTP:  200 OK + l'HTML
  mostra la pagina "Ciao Mario!"

Una route è un collegamento tra un indirizzo e una funzione Python. Quando il browser chiede quell'indirizzo, Flask esegue la funzione e manda indietro quello che la funzione restituisce con return.

Il codice del kit, pezzo per pezzo

Aprite app.py. Le prime righe creano l'applicazione:

from flask import Flask
app = Flask(__name__)

Poi c'è la prima route, quella della pagina principale /:

@app.route("/")
def home():
    return "<h1>Ciao! Questo è il mio primo server Flask</h1>"

La riga che comincia con @ si chiama decoratore: "attacca" l'indirizzo / alla funzione home. Quello che restituite può contenere HTML: il browser lo interpreta.

Le route con parametri

Una parte dell'indirizzo può essere variabile: si scrive tra < > e Flask la passa alla funzione con lo stesso nome.

@app.route("/saluto/<nome>")
def saluto(nome):
    return f"<h1>Ciao {nome}!</h1>"

/saluto/Mario → nome vale "Mario"; /saluto/Giulia → nome vale "Giulia".

Se vi servono numeri, aggiungete il tipo: <int:a> accetta solo interi e li converte già in int.

@app.route("/somma/<int:a>/<int:b>")
def somma(a, b):
    return f"{a} + {b} = <b>{a + b}</b>"

Provate /somma/3/ciao: Flask risponde 404 (pagina non trovata) senza nemmeno chiamare la funzione. È il convertitore int che controlla per voi.

L'avvio del server

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000, debug=True)

• host="0.0.0.0": il server accetta collegamenti anche dagli altri PC del laboratorio (come il bind("0.0.0.0", …) dei socket). Un compagno può aprire http://IL-VOSTRO-IP:5000.
• port=5000: la porta, come la 5050 dei socket.
• debug=True: quando salvate il file il server si riavvia da solo, e gli errori compaiono nel browser con la riga sbagliata. Comodissimo in laboratorio, ma mai su un server pubblico.

Missioni

Domanda di confronto (orale): quante righe vi sono servite per un server che risponde a 5 indirizzi diversi? Quante ne servirebbero con i socket del Periodo 2?

3.2 Pagine vere con i template

Durata indicativa: 2 settimane

• flask4-2-template.zipGameDB: il catalogo dei videogiochi, con template, CSS e pagina 404

Scrivere l'HTML dentro le stringhe Python va bene per due righe, ma per una pagina vera diventa un disastro. La soluzione sono i template: file HTML normali, con dei "buchi" che Flask riempie con i dati. Il motore che lo fa si chiama Jinja2 ed è già incluso in Flask.

Da qui in avanti lavoriamo su GameDB, il catalogo dei videogiochi della classe.

Le cartelle del progetto

flask4-2-template/
├── app.py              ← il server: route e dati
├── templates/          ← le pagine HTML (Flask le cerca QUI)
│   ├── base.html       ← la struttura comune: testata, menu, piè di pagina
│   ├── index.html      ← l'elenco dei giochi
│   ├── gioco.html      ← la scheda di un gioco
│   └── 404.html        ← pagina "non trovato"
└── static/             ← file che non cambiano (Flask li cerca QUI)
    └── css/style.css   ← la grafica (già pronta)

I nomi templates e static vanno scritti esattamente così: Flask li cerca con questi nomi. Se rinominate la cartella, compare l'errore TemplateNotFound.

Dal Python al template: render_template

In app.py i giochi sono una lista di dizionari:

giochi = [
    {"id": 1, "titolo": "Minecraft", "anno": 2011, "genere": "sandbox", "voto": 9},
    {"id": 2, "titolo": "Rocket League", "anno": 2015, "genere": "sport", "voto": 8},
    # ...
]

@app.route("/")
def home():
    return render_template("index.html", giochi=giochi)

render_template("index.html", giochi=giochi) vuol dire: prendi il file templates/index.html, dagli la variabile giochi e restituisci l'HTML finito. Il nome a sinistra dell'uguale è il nome che la variabile avrà nel template.

Le tre "parole" di Jinja2

Ecco il cuore di index.html, con un ciclo e una condizione:

{% for g in giochi %}
  <div class="scheda">
    <h3>{{ g.titolo }}</h3>
    <p class="meta">{{ g.anno }} · {{ g.genere }}</p>

    {% if g.voto >= 9 %}
      <span class="etichetta verde">Capolavoro · {{ g.voto }}</span>
    {% elif g.voto >= 7 %}
      <span class="etichetta">Bello · {{ g.voto }}</span>
    {% else %}
      <span class="etichetta rossa">Così così · {{ g.voto }}</span>
    {% endif %}
  </div>
{% endfor %}

È Python "travestito" da HTML: il for ripete il blocco per ogni gioco, l'if sceglie quale etichetta mostrare. Attenzione: a differenza di Python, qui i blocchi si chiudono con {% endfor %} e {% endif %}.

Nel template si scrive g.titolo invece di g["titolo"]: Jinja2 accetta entrambe le forme, ma il punto è più leggibile.

I filtri

Un filtro trasforma un valore e si scrive con la barra verticale |:

L'ereditarietà: base.html

Tutte le pagine hanno la stessa testata e lo stesso piè di pagina. Invece di copiarli in ogni file, li scriviamo una volta in base.html e lasciamo dei blocchi da riempire:

<!-- base.html -->
<title>{% block titolo %}GameDB{% endblock %} · GameDB</title>
...
<main>
  {% block contenuto %}{% endblock %}
</main>

Ogni pagina "figlia" dice da chi eredita e riempie i blocchi:

<!-- gioco.html -->
{% extends "base.html" %}

{% block titolo %}{{ gioco.titolo }}{% endblock %}

{% block contenuto %}
  <h1>{{ gioco.titolo }}</h1>
  <p>Voto della classe: {{ gioco.voto }}/10</p>
{% endblock %}

Volete aggiungere una voce al menu? La scrivete in base.html e compare in tutte le pagine.

I link: url_for

Nei template non scriviamo gli indirizzi a mano, ma chiediamo a Flask di costruirli a partire dal nome della funzione:

<a href="{{ url_for('home') }}">Tutti i giochi</a>                        → /
<a href="{{ url_for('scheda', id_gioco=g.id) }}">{{ g.titolo }}</a>      → /gioco/3
<link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">

Se un giorno cambiate l'indirizzo nella @app.route, tutti i link si aggiornano da soli.

La pagina 404

@app.route("/gioco/<int:id_gioco>")
def scheda(id_gioco):
    gioco = cerca_gioco(id_gioco)
    if gioco is None:
        abort(404)
    return render_template("gioco.html", gioco=gioco)

@app.errorhandler(404)
def non_trovata(errore):
    return render_template("404.html"), 404

abort(404) interrompe la funzione; @app.errorhandler(404) decide cosa mostrare al posto della pagina grezza di Flask. Provate /gioco/99.

Missioni

3.3 I form: l'utente manda i dati

Durata indicativa: 1-2 settimane

• flask4-3-form.zipGameDB con la ricerca (form GET) e la pagina "Aggiungi gioco" (form POST con controlli)

Finora il server manda dati al browser. Con un form succede il contrario: è l'utente che manda dati al server. Ci sono due modi, e nel kit li trovate entrambi.

La ricerca: un form GET

<form method="get" action="{{ url_for('home') }}">
  <input name="q" value="{{ q }}" placeholder="Cerca per titolo...">
  <button>Cerca</button>
</form>

Cercando "mario", il browser apre /?q=mario. In Python:

@app.route("/")
def home():
    q = request.args.get("q", "")       # "" se nell'indirizzo non c'è ?q=
    if q:
        risultati = [g for g in giochi if q.lower() in g["titolo"].lower()]
    else:
        risultati = giochi
    return render_template("index.html", giochi=risultati, q=q)

L'attributo name="q" del campo HTML e la parola tra virgolette in request.args.get("q") devono essere uguali. È l'errore più frequente: se non coincidono, il server non riceve niente.

Aggiungere un gioco: un form POST

La stessa route fa due cose diverse in base al metodo della richiesta:

  GET  /nuovo   → l'utente apre la pagina    → mostro il form vuoto
  POST /nuovo   → l'utente preme "Salva"     → controllo i dati
                                                 ├─ ci sono errori → rimostro il form con gli errori
                                                 └─ tutto ok       → salvo e vado alla scheda del gioco

@app.route("/nuovo", methods=["GET", "POST"])
def nuovo():
    errori = []
    if request.method == "POST":
        titolo = request.form.get("titolo", "").strip()
        voto = request.form.get("voto", "")
        # ... anno e genere

        if titolo == "":
            errori.append("Scrivi il titolo del gioco")
        if not voto.isdigit() or not (1 <= int(voto) <= 10):
            errori.append("Il voto deve essere un numero da 1 a 10")

        if not errori:
            # ... aggiungo il gioco alla lista
            return redirect(url_for("scheda", id_gioco=nuovo_id))

    return render_template("nuovo.html", errori=errori, generi=GENERI)

Tre cose da capire bene:

1. methods=["GET", "POST"]: senza, la route accetta solo GET e premendo "Salva" otterreste l'errore 405 Method Not Allowed.
2. I controlli si fanno nel server, sempre. Gli attributi HTML come min="1" aiutano l'utente, ma chiunque può mandare una richiesta POST senza passare dal form (lo farete con Thunder Client nel prossimo modulo).
3. Dopo aver salvato si fa redirect, non si restituisce una pagina. Così, se l'utente preme F5, il browser non rimanda il form e il gioco non viene salvato due volte.

Missioni

3.4 Le API: dati per altri programmi

Durata indicativa: 1-2 settimane

• flask4-4-api.zipGameDB con un'API JSON (GET e POST) e client.py, un programma che la usa con requests

Le pagine HTML sono fatte per le persone. Un'API invece restituisce dati "grezzi", in formato JSON, pensati per un altro programma: un'app per il telefono, un altro server, uno script Python. È la stessa cosa che avete fatto nel Periodo 1 con requests, ma stavolta l'API la scrivete voi.

  pagina HTML  (per una persona)          API JSON  (per un programma)
  GET /gioco/1                             GET /api/giochi/1
  ┌──────────────────────┐                 {
  │  Minecraft           │                   "id": 1,
  │  Anno: 2011          │                   "titolo": "Minecraft",
  │  Voto: 9/10          │                   "anno": 2011,
  └──────────────────────┘                   "voto": 9
                                           }

Leggere: GET

@app.route("/api/giochi")
def api_elenco():
    return jsonify(giochi)

@app.route("/api/giochi/<int:id_gioco>")
def api_gioco(id_gioco):
    gioco = cerca_gioco(id_gioco)
    if gioco is None:
        return jsonify({"errore": "gioco non trovato"}), 404
    return jsonify(gioco)

jsonify() trasforma liste e dizionari Python in JSON e aggiunge l'intestazione Content-Type: application/json, così chi riceve sa come leggere la risposta. Notate che anche l'errore è in JSON, con il codice di stato giusto (404): un programma non legge le frasi, legge i codici.

Scrivere: POST

@app.route("/api/giochi", methods=["POST"])
def api_aggiungi():
    dati = request.get_json(silent=True)    # il JSON mandato dal client, o None
    if not dati or not dati.get("titolo"):
        return jsonify({"errore": "serve almeno il titolo"}), 400
    # ... creo il gioco e lo aggiungo alla lista
    return jsonify(gioco), 201              # 201 = Created

Provare l'API

Il browser sa fare solo GET: per le altre richieste serve uno strumento come Thunder Client (estensione di VS Code) o Postman. Per una POST: metodo POST, indirizzo http://127.0.0.1:5000/api/giochi, scheda Body → JSON:

{ "titolo": "Tetris", "anno": 1984, "genere": "puzzle", "voto": 10 }

Nel kit c'è anche client.py: un programma Python che usa la vostra API con requests. Avviate il server in un terminale e client.py in un secondo terminale (nel terminale di VS Code c'è il pulsante +).

risposta = requests.get("http://127.0.0.1:5000/api/giochi", timeout=5)
giochi = risposta.json()            # il JSON diventa una lista Python

Avete appena fatto parlare due programmi attraverso la rete: il client e il server. È lo stesso schema client-server dei socket, ma con HTTP e JSON al posto dei byte.

Missioni

3.5 Progetto del periodo: la chat diventa web

Durata indicativa: 2 settimane

• flask4-5-chat-web.zipUna chat web funzionante: pagina, API JSON e JavaScript che la aggiorna ogni 2 secondi

  browser di Giulia                 server Flask                 browser di Marco
  ─────────────────                 ────────────                 ────────────────
  ogni 2 s: GET /api/messaggi ───►  restituisce la lista   ◄───  ogni 2 s: GET /api/messaggi
  "Invia":  POST /api/messaggi ──►  aggiunge alla lista

academy-pc.it · materiale didattico — Modulo Introduzione a Flask, TPSIT quarta