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:
- Prevedi: prima di aprire, prova tu, su un foglio.
- In italiano: cosa fa il codice, a parole.
- Passo per passo: le decisioni, una alla volta.
- 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 salaPrima 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.pyIl 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.
| Riquadro | Dove finisce | Quando |
|---|---|---|
| 1, 2, 3, 4 (le parole) | CANVAS.md, e la frase anche nel README.md | già fatto |
| 6 · I dati | schema.sql, poi modelli.py | questo capitolo |
| 7 · Le azioni | rotte/*.py, con i loro stampi in schemi.py | il prossimo capitolo |
| 8 · Chi può fare cosa | il login: una riga nelle rotte che lo vogliono | dopo il login |
| 5 · Le schermate | l'interfaccia: un'altra cartella, più avanti | molto 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_StoreIl .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.sqlNé .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_StoreIn 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.
| Cosa | Su GitHub? | Perché |
|---|---|---|
.venv/ | No | Pesa e si rifà con pip install -r requirements.txt |
app/__pycache__/ | No | Avanzi che Python rifà da solo |
.pytest_cache/ | No | La memoria di pytest |
.env | No, mai | Può avere una password |
.env.example | Sì | Il modello: dice quali righe scrivere nel proprio .env |
schema.sql, requirements.txt, app/main.py | Sì | È il progetto |
.gitignore | Sì | Lo scarica anche chi clona il progetto |
.DS_Store | No | Lo 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.sqlIl .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.sqlMa 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_suLa 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:
from fastapi import FastAPI
app = FastAPI(title="Prenota-sala")Livia vuole sapere se è accesa: serve GET /salute. Prima il test, tests/test_salute.py:
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 vedi | Cosa vuol dire | Cosa fai |
|---|---|---|
ModuleNotFoundError: No module named 'app' | Il test è in tests/ e app/ sta fuori: Python non la trova | pythonpath = . nel pytest.ini, e lancia pytest dalla cartella del progetto |
404 == 200 | L'app c'è, ma la rotta no | Aggiungi la rotta a main.py |
1 passed | La rotta risponde | Vai avanti |
La rotta che chiude il giro:
@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:
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?
- Nessun
.env, nessuna variabile nel terminale. - Un
.envconDATABASE_URL=postgresql+psycopg:///prenota_sala_prova. - Lo stesso
.env, e nel terminaleDATABASE_URL=postgresql+psycopg:///dal_terminaledavanti al comando. - Come il 2, ma il programma mette
DATABASE_URLaprenota_sala_testprima di importareapp.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_salaIl 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_provaIl numero 2: load_dotenv() ha letto il file.
$ DATABASE_URL=postgresql+psycopg:///dal_terminale python -c "..."
postgresql+psycopg:///dal_terminaleIl 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_testIl numero 4: lo stesso meccanismo, usato apposta.
Il quarto lancio era questo:
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?
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 lancia | Dove scrive DATABASE_URL | Il database che si usa |
|---|---|---|
Tu, con fastapi dev | Nel tuo .env | Il tuo: prenota_sala |
| I test | Nel conftest.py, prima di importare l'app | Quello dei test: …_test |
| Il computer online, un giorno | Nelle impostazioni del servizio | Quello 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:
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.
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 TEXTfrom 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: intLa prova: un foglio, prova.py, che crea un ordine giusto, lo salva con la tabella vera, e prova due ordini storti.
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 0In 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.
| Colonna | In modelli.py | In schemi.py | Perché |
|---|---|---|---|
id SERIAL PRIMARY KEY | mapped_column(primary_key=True) | id: int, solo in Ordine | Lo dà il database: chi crea un ordine non lo manda |
cliente, panino TEXT NOT NULL | Mapped[str] | str | Senza | None, obbligatoria |
formato … CHECK … IN | Mapped[str], CHECK nel commento | Literal[...] | 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 false | mapped_column(server_default="false") | bool = False | Il database riempie la colonna, chi chiama può non scriverla |
ritiro_alle TIMESTAMP | Mapped[datetime] | datetime | Data e ora insieme |
nota TEXT | Mapped[str | None] | str | None = None | Facoltativa: 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).