Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

Il progetto4. La cartella del progettop. 110

La cartella del progetto, esercizi spiegati

Cinque esempi, dal canvas alla prima tabella in Python

  • 30 minuti di lettura

Cinque esempi, uno per ogni idea della teoria. Questa volta non lavori su Ritrovato: ci lavori nella palestra, con un'altra app. Qui ce ne sono due, piccole.

  • Prenota-sala: le sale riunioni della centrale. La segreteria, con Livia Pellegri, vuole smettere di girare i corridoi con un foglio. È anche il progetto della palestra.
  • Panino-su: il furgone dei panini di Ponte Ciclo. Osvaldo Brera ordina la mattina, i colleghi ritirano all'ora di pranzo.

Ognuno ha lo stesso ritmo:

  1. Prevedi: prima di aprire, prova tu, su un foglio.
  2. In italiano: cosa fa il codice, a parole.
  3. Passo per passo: le decisioni, una alla volta.
  4. Cosa portiamo a casa: la cosa da ricordare.

A · Dal canvas alla cartella

Il canvas di Prenota-sala, nei riquadri che servono:

1 · La frase     Prenota-sala aiuta chi organizza una riunione in centrale
                 a trovare una sala libera senza girare i corridoi.
4 · Le funzioni  1. cerco le sale, per piano e per posti
                 2. prenoto una sala
                 3. annullo una prenotazione
5 · Le schermate l'elenco delle sale · la prenotazione · le mie prenotazioni
6 · I dati       le sale: nome, piano, posti, proiettore, note
                 le prenotazioni: quale sala, chi, da quando a quando
7 · Le azioni    cerco: leggo le sale · prenoto: scrivo una prenotazione
                 annullo: cancello una prenotazione
8 · Chi può      tutti prenotano e annullano la propria; solo la segreteria
                 aggiunge una sala

Prima di aprire: prova tu. Scrivi l'elenco dei file e delle cartelle della cartella prenota-sala/ a fine capitolo, e accanto a ognuno il riquadro del canvas da cui nasce.

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
prenota-sala/
├── CANVAS.md              i riquadri 1–8, scritti
├── README.md              la frase (riquadro 1), come si avvia
├── schema.sql             le tabelle: il riquadro 6, in SQL
├── requirements.txt
├── pytest.ini
├── .gitignore
├── .env
├── .env.example
├── app/
│   ├── __init__.py
│   ├── main.py            la porta d'ingresso
│   ├── database.py
│   ├── modelli.py         il riquadro 6, in Python
│   ├── schemi.py          i riquadri 4 e 7: cosa entra, cosa esce
│   └── rotte/
│       ├── __init__.py
│       └── sale.py        le azioni «cerco» e, poi, «prenoto»: il riquadro 7
└── tests/
    ├── conftest.py
    └── test_salute.py

Il riquadro 5 (le schermate) e il riquadro 8 (chi può fare cosa) non hanno ancora un file: le schermate arrivano con l'interfaccia, chi può fare cosa con il login.

In italiano. Ogni riquadro del canvas che diventa codice ha una casa in questa cartella. I dati (riquadro 6) sono schema.sql e modelli.py. Le azioni (riquadro 7) sono le rotte: ogni azione, una rotta in un file di rotte/. Cosa entra e cosa esce da quelle rotte lo dicono gli stampi di schemi.py.

Passo per passo.

RiquadroDove finisceQuando
1, 2, 3, 4 (le parole)CANVAS.md, e la frase anche nel README.mdgià fatto
6 · I datischema.sql, poi modelli.pyquesto capitolo
7 · Le azionirotte/*.py, con i loro stampi in schemi.pyil prossimo capitolo
8 · Chi può fare cosail login: una riga nelle rotte che lo voglionodopo il login
5 · Le schermatel'interfaccia: un'altra cartella, più avantimolto dopo

Nella cartella, le tabelle sono due (sale, prenotazioni): non una per ogni schermata. E le rotte non sono tre per ogni tabella: ne parliamo nel prossimo capitolo.

Cosa portiamo a casa. Non inventi la cartella: la ricavi dal canvas. Se un file non sai da quale riquadro nasce, non serve ancora.


B · Cosa va nel .gitignore, cosa nel .env

Panino-su ha dieci file e cartelle. Osvaldo vuole fare il primo commit, ma una parte non deve arrivare su GitHub.

.venv/                    app/__pycache__/
.pytest_cache/            .env
.env.example              .gitignore
schema.sql                requirements.txt
app/main.py               .DS_Store

Il .gitignore che conosci ha quattro righe: .venv/, __pycache__/, .pytest_cache/, .env. Prova tu: quali dei dieci arrivano su GitHub, e quali no? C'è qualcuno che né l'uno né l'altro?

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.

Con quelle quattro righe, non arrivano su GitHub: .venv/, app/__pycache__/, .pytest_cache/ e .env. Arrivano: .env.example, .gitignore, schema.sql, requirements.txt, app/main.py. E il decimo, .DS_Store, è quello che sfugge: lo crea il Finder del Mac in ogni cartella, e il .gitignore non lo nomina. Git lo mostra:

$ git status --short
?? .DS_Store
?? .env.example
?? .gitignore
?? app/
?? requirements.txt
?? schema.sql

Né .venv/ né .env compaiono. Il .DS_Store sì, e va aggiunto:

$ echo ".DS_Store" >> .gitignore
$ git status --short
?? .env.example
?? .gitignore
?? app/
?? requirements.txt
?? schema.sql
$ git check-ignore -v .env .venv/bin/python .DS_Store
.gitignore:4:.env	.env
.gitignore:1:.venv/	.venv/bin/python
.gitignore:5:.DS_Store	.DS_Store

In italiano. «Git guarda il .gitignore: ogni riga è un nome, o un modello, di file da far finta di non vedere. Quello che ci sta dentro non compare in git status e non finisce nei commit.»

Passo per passo.

CosaSu GitHub?Perché
.venv/NoPesa e si rifà con pip install -r requirements.txt
app/__pycache__/NoAvanzi che Python rifà da solo
.pytest_cache/NoLa memoria di pytest
.envNo, maiPuò avere una password
.env.exampleSìIl modello: dice quali righe scrivere nel proprio .env
schema.sql, requirements.txt, app/main.pySìÈ il progetto
.gitignoreSìLo scarica anche chi clona il progetto
.DS_StoreNoLo scrive il Mac, non è del progetto: una riga in più nel .gitignore

git check-ignore -v è il modo di fare la domanda a Git: dice quale riga del .gitignore nasconde quel file. Se non risponde niente, quel file non è nascosto.

E se il .env è già su Git? Il .gitignore non toglie quello che c'è già: Git lo segue lo stesso. Succede a chi fa il primo commit prima del .gitignore. Lo vedi così:

$ git ls-files
.DS_Store
.env
.env.example
.pytest_cache/README.md
.venv/bin/python
app/__pycache__/main.cpython-312.pyc
app/main.py
requirements.txt
schema.sql

Il .env è nell'elenco, anche se adesso il .gitignore lo nomina. Aggiungi il .gitignore (git add .gitignore), cambia il .env, e Git se ne accorge:

$ echo "DATABASE_URL=postgresql+psycopg://dina:nuova@localhost/panino_su" > .env
$ git status --short
 M .env
A  .gitignore

M .env: modificato. Il .gitignore non lo protegge più. Si toglie da Git senza cancellarlo dal disco:

$ git rm --cached .env
rm '.env'
$ git status --short
D  .env
A  .gitignore
$ git commit -m "Tolgo .env da Git"
$ git ls-files
.DS_Store
.env.example
.gitignore
.pytest_cache/README.md
.venv/bin/python
app/__pycache__/main.cpython-312.pyc
app/main.py
requirements.txt
schema.sql

Ma la storia ricorda:

$ git log --oneline
3587e76 Tolgo .env da Git
cf18556 Primo commit (sbagliato)
$ git show HEAD~1:.env
DATABASE_URL=postgresql+psycopg://dina:segreta@localhost/panino_su

La password è ancora nel primo commit. Una password finita su GitHub è bruciata: anche se la togli dopo, cambia la password. Per questo si scrive il .gitignore prima del primo commit, e si guarda git status prima di ogni git add ..

Cosa portiamo a casa. Prima il .gitignore, poi git add. Il .env ha i segreti e resta sul tuo computer; il .env.example è il modello e va su GitHub.


C · Il primo test verde

Prenota-sala ha un app/main.py con l'app e basta:

Python
from fastapi import FastAPI

app = FastAPI(title="Prenota-sala")

Livia vuole sapere se è accesa: serve GET /salute. Prima il test, tests/test_salute.py:

Python
from fastapi.testclient import TestClient

from app.main import app

client = TestClient(app)


def test_salute():
    risposta = client.get("/salute")
    assert risposta.status_code == 200
    assert risposta.json() == {"stato": "ok"}

Il pytest.ini c'è, ma ha una riga sola: testpaths = tests. Lancia pytest. Prima di aprire, prova tu: cosa dice? E dopo aver aggiunto la riga pythonpath = . al pytest.ini? E dopo aver scritto la rotta?

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.

Tre risposte diverse, in ordine.

Senza pythonpath: pytest non arriva nemmeno ai test.

tests/test_salute.py:3: in <module>
    from app.main import app
E   ModuleNotFoundError: No module named 'app'
=========================== short test summary info ============================
ERROR tests/test_salute.py
!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!
=============================== 1 error in 0.20s ===============================

Con pythonpath = ., ma senza la rotta: i test partono, e uno è rosso.

tests/test_salute.py F                                                   [100%]

=================================== FAILURES ===================================
_________________________________ test_salute __________________________________

    def test_salute():
        risposta = client.get("/salute")
>       assert risposta.status_code == 200
E       assert 404 == 200
E        +  where 404 = <Response [404 Not Found]>.status_code

tests/test_salute.py:10: AssertionError
=========================== short test summary info ============================
FAILED tests/test_salute.py::test_salute - assert 404 == 200
============================== 1 failed in 0.13s ===============================

Con la rotta:

tests/test_salute.py .                                                   [100%]

============================== 1 passed in 0.14s ===============================

In italiano. «Chiedo /salute. Mi aspetto 200 e {"stato": "ok"}.» Il TestClient fa la richiesta senza accendere nessun server: è un finto browser che parla con l'app, in memoria.

Passo per passo.

Cosa vediCosa vuol direCosa fai
ModuleNotFoundError: No module named 'app'Il test è in tests/ e app/ sta fuori: Python non la trovapythonpath = . nel pytest.ini, e lancia pytest dalla cartella del progetto
404 == 200L'app c'è, ma la rotta noAggiungi la rotta a main.py
1 passedLa rotta rispondeVai avanti

La rotta che chiude il giro:

Python
@app.get("/salute")
def salute() -> dict[str, str]:
    return {"stato": "ok"}

Quelle due righe di errore sono informazioni. Il primo rosso non è un guaio: è il test che ti dice dove sei. È lo stesso schema del TDD: prima il rosso, poi il verde.

Cosa portiamo a casa. Il primo test è l'attrezzatura, non la funzione: prova che il pacchetto, il pytest.ini e il finto browser funzionano. Senza, il primo test «vero» fallisce per un motivo che non c'entra con lui.


D · database.py e la variabile d'ambiente

Prenota-sala ha il suo app/database.py, uguale a quello di Ritrovato nella teoria, con prenota_sala al posto di ritrovato:

Python
load_dotenv()

DATABASE_URL = os.environ.get("DATABASE_URL", "postgresql+psycopg:///prenota_sala")

Quattro lanci di Python, uno dopo l'altro. Prima di aprire, prova tu: cosa stampa DATABASE_URL in ognuno?

  1. Nessun .env, nessuna variabile nel terminale.
  2. Un .env con DATABASE_URL=postgresql+psycopg:///prenota_sala_prova.
  3. Lo stesso .env, e nel terminale DATABASE_URL=postgresql+psycopg:///dal_terminale davanti al comando.
  4. Come il 2, ma il programma mette DATABASE_URL a prenota_sala_test prima di importare app.database.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
$ python -c "from app.database import DATABASE_URL; print(DATABASE_URL)"
postgresql+psycopg:///prenota_sala

Il numero 1: niente .env, vale il valore di riserva.

$ cat .env
DATABASE_URL=postgresql+psycopg:///prenota_sala_prova
$ python -c "from app.database import DATABASE_URL; print(DATABASE_URL)"
postgresql+psycopg:///prenota_sala_prova

Il numero 2: load_dotenv() ha letto il file.

$ DATABASE_URL=postgresql+psycopg:///dal_terminale python -c "..."
postgresql+psycopg:///dal_terminale

Il numero 3: la variabile che c'è già vince sul .env. load_dotenv() non sovrascrive.

$ python (come fa conftest.py: prima la variabile, poi app)
postgresql+psycopg:///prenota_sala_test

Il numero 4: lo stesso meccanismo, usato apposta.

Il quarto lancio era questo:

Terminale
python -c "
import os
os.environ['DATABASE_URL'] = 'postgresql+psycopg:///prenota_sala_test'
from app.database import DATABASE_URL
print(DATABASE_URL)
"

E se l'ordine è l'inverso, prima l'import e poi la variabile?

Terminale
python -c "
import os
from app.database import DATABASE_URL
os.environ['DATABASE_URL'] = 'postgresql+psycopg:///prenota_sala_test'
print(DATABASE_URL)
"
postgresql+psycopg:///prenota_sala_prova

È il database del .env: il tuo. Quando database.py parte, legge una volta sola; cambiare la variabile dopo non serve più.

In italiano. «La variabile d'ambiente è la valigetta con le impostazioni: chi lancia il programma la prepara. .env è un modo comodo di prepararla. Il codice legge dalla valigetta; non sa chi l'ha riempita.»

Passo per passo.

Chi lanciaDove scrive DATABASE_URLIl database che si usa
Tu, con fastapi devNel tuo .envIl tuo: prenota_sala
I testNel conftest.py, prima di importare l'appQuello dei test: …_test
Il computer online, un giornoNelle impostazioni del servizioQuello online

Il conftest.py scrive la variabile come prima riga di codice, prima di qualunque import app. Se dimentichi l'ordine, i test girano sul tuo database, e prima o poi ne cancellano i dati: tabelle_come_nuove le butta e le rifà.

Cosa portiamo a casa. Il codice non cambia da un computer all'altro: cambia la variabile. E per i test: la variabile si mette prima dell'import.


E · Da schema.sql a modelli.py e schemi.py

Osvaldo ha disegnato la sua tabella, schema.sql:

SQL
CREATE TABLE ordini (
    id             SERIAL PRIMARY KEY,
    cliente        TEXT NOT NULL,
    panino         TEXT NOT NULL,
    formato        TEXT NOT NULL CHECK (formato IN ('piccolo', 'normale', 'maxi')),
    quantita       INTEGER NOT NULL CHECK (quantita > 0),
    senza_glutine  BOOLEAN NOT NULL DEFAULT false,
    ritiro_alle    TIMESTAMP NOT NULL,
    nota           TEXT
);

Servono OrdineDB in modelli.py e due stampi in schemi.py: OrdineNuovo (il corpo del POST) e Ordine (la risposta). Con la tabella di traduzione della teoria sotto gli occhi: scrivili tu, riga per riga. Alla fine, controlla se formato e quantita sono rifiutati nel posto giusto.

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Python
from datetime import datetime

from sqlalchemy.orm import Mapped, mapped_column

from app.database import Base


class OrdineDB(Base):
    __tablename__ = "ordini"                                    # CREATE TABLE ordini

    id: Mapped[int] = mapped_column(primary_key=True)           # id SERIAL PRIMARY KEY
    cliente: Mapped[str]                                        # cliente TEXT NOT NULL
    panino: Mapped[str]                                         # panino TEXT NOT NULL
    formato: Mapped[str]                                        # formato TEXT NOT NULL CHECK (formato IN (...))
    quantita: Mapped[int]                                       # quantita INTEGER NOT NULL CHECK (quantita > 0)
    senza_glutine: Mapped[bool] = mapped_column(server_default="false")
    #                                                           # senza_glutine BOOLEAN NOT NULL DEFAULT false
    ritiro_alle: Mapped[datetime]                               # ritiro_alle TIMESTAMP NOT NULL
    nota: Mapped[str | None]                                    # nota TEXT
Python
from datetime import datetime
from typing import Literal

from pydantic import BaseModel, ConfigDict, Field

Formato = Literal["piccolo", "normale", "maxi"]


class OrdineNuovo(BaseModel):
    cliente: str
    panino: str
    formato: Formato
    quantita: int = Field(gt=0)
    senza_glutine: bool = False
    ritiro_alle: datetime
    nota: str | None = None


class Ordine(OrdineNuovo):
    model_config = ConfigDict(from_attributes=True)

    id: int

La prova: un foglio, prova.py, che crea un ordine giusto, lo salva con la tabella vera, e prova due ordini storti.

Python
from pydantic import ValidationError
from sqlalchemy.orm import Session

from app.database import engine
from app.modelli import OrdineDB
from app.schemi import Ordine, OrdineNuovo

dati = {"cliente": "Dina", "panino": "Crudo e fontina", "formato": "normale", "quantita": 2, "ritiro_alle": "2026-11-20T12:30"}

nuovo = OrdineNuovo(**dati)
print(nuovo)

with Session(engine) as db:
    riga = OrdineDB(**nuovo.model_dump())
    db.add(riga)
    db.commit()
    print(Ordine.model_validate(riga))

for storto in ({"formato": "gigante"}, {"quantita": 0}):
    try:
        OrdineNuovo(**{**dati, **storto})
    except ValidationError as e:
        print(e.errors()[0]["loc"], e.errors()[0]["msg"])
$ python prova.py
cliente='Dina' panino='Crudo e fontina' formato='normale' quantita=2 senza_glutine=False ritiro_alle=datetime.datetime(2026, 11, 20, 12, 30) nota=None
cliente='Dina' panino='Crudo e fontina' formato='normale' quantita=2 senza_glutine=False ritiro_alle=datetime.datetime(2026, 11, 20, 12, 30) nota=None id=1
('formato',) Input should be 'piccolo', 'normale' or 'maxi'
('quantita',) Input should be greater than 0

In italiano. «Ogni colonna ha una riga in modelli.py e una in schemi.py. Il CHECK si ricopia come commento nel modello e diventa un controllo nello stampo.»

Passo per passo.

ColonnaIn modelli.pyIn schemi.pyPerché
id SERIAL PRIMARY KEYmapped_column(primary_key=True)id: int, solo in OrdineLo dà il database: chi crea un ordine non lo manda
cliente, panino TEXT NOT NULLMapped[str]strSenza | None, obbligatoria
formato … CHECK … INMapped[str], CHECK nel commentoLiteral[...]Le tre parole ammesse: l'errore dice quali
quantita … CHECK (quantita > 0)Mapped[int]Field(gt=0)Input should be greater than 0
senza_glutine … DEFAULT falsemapped_column(server_default="false")bool = FalseIl database riempie la colonna, chi chiama può non scriverla
ritiro_alle TIMESTAMPMapped[datetime]datetimeData e ora insieme
nota TEXTMapped[str | None]str | None = NoneFacoltativa: ogni ordine non ce l'ha

Quello che il test ha dimostrato: l'ordine entra con senza_glutine=False senza che nessuno l'abbia scritto (il valore è partito dallo stampo, = False), e il formato «gigante» e la quantità zero si fermano prima di toccare il database, con un messaggio che dice cosa non va.

Cosa portiamo a casa. Le due colonne facoltative e i due CHECK sono il posto dove si sbaglia di più. Quando traduci una tabella, rileggi la lista: NOT NULL o no (| None), CHECK (commento, e Literal o Field), DEFAULT (server_default), e chi non deve vedere cosa (la risposta).