La cartella del progetto, le soluzioni
Prenota-sala completata, il ragionamento, le trappole
Per ogni esercizio, sempre lo stesso ordine: in italiano → il file → passo per passo (per i più difficili) → le trappole.
Questa volta le strade giuste sono più di una: i test guardano cosa fa il file, non come l'hai scritto. Una riga di commento in più, un ordine diverso nelle librerie, Mapped[str] con o senza mapped_column() vuoto: va bene. Quello che conta è il ragionamento. Confrontalo con quello qui sotto, e leggi comunque le trappole.
Le soluzioni complete
La stessa cartella, con il codice al posto di pass. Aprila dopo averci provato: i test sono gli stessi.
La palestra
1 · Il requirements.txt
In italiano.
Una libreria per riga, i nomi senza versione. Due hanno un extra tra parentesi quadre: fastapi[standard] (porta il comando fastapi dev) e psycopg[binary] (porta il motore già pronto). httpx c'è per il finto browser dei test.
fastapi[standard]
sqlalchemy
psycopg[binary]
python-dotenv
pytest
httpxLe trappole.
Senza httpx. Il TestClient funziona solo se httpx è installato. Sul tuo computer c'è, perché l'hai installato a mano: l'errore lo vede chi scarica il progetto da GitHub e lancia pip install -r requirements.txt. È la trappola più subdola: il tuo test è verde e il suo no.
fastapi[standard]
sqlalchemy
psycopg[binary]
python-dotenv
pytestDiventano rossi: test_ci_sono_pytest_e_httpx.
Senza l'extra. fastapi da solo installa la libreria, non il comando fastapi dev.
fastapi
sqlalchemy
psycopg[binary]
python-dotenv
pytest
httpxDiventano rossi: test_ci_sono_fastapi_con_l_extra_standard.
2 · Il .gitignore
In italiano.
Quattro righe: due cartelle che Python o pip riempiono da soli (.venv/ e __pycache__/), la memoria di pytest (.pytest_cache/) e il file con i segreti (.env). Il modello, .env.example, resta fuori dalla lista: deve arrivare su GitHub.
.venv/
__pycache__/
.pytest_cache/
.envLe trappole.
L'asterisco. .env* sembra una scorciatoia furba («tutto quello che comincia con .env»), e nasconde anche .env.example. Chi scarica il progetto non trova il modello, e non sa cosa scrivere nel suo .env.
.venv/
__pycache__/
.pytest_cache/
.env*Diventano rossi: test_non_ignora_env_example.
Il .env dimenticato. È la dimenticanza più cara: le altre righe ci sono, i test della cartella passano a metà, e la password del database parte con il primo git push.
.venv/
__pycache__/
.pytest_cache/Diventano rossi: test_ignora_il_file_env.
Il nome scritto a orecchio. pycache/ non è __pycache__/: Python scrive la cartella con i due trattini bassi, e Git guarda il nome esatto.
.venv/
pycache/
.pytest_cache/
.envDiventano rossi: test_ignora_le_cartelle_pycache.
3 · Il .env.example
In italiano.
Una riga, NOME=valore. Il valore è l'indirizzo del database di Prenota-sala, senza utente e senza password: sul tuo computer PostgreSQL si fida di te. È un modello: quello che ci scrivi lo vede il mondo.
DATABASE_URL=postgresql+psycopg:///prenota_salaLe trappole.
Il modello con la password vera. Succede quando si copia il .env invece di riscriverlo. Il file va su GitHub, e con lui la password.
DATABASE_URL=postgresql+psycopg://livia:segreta@localhost/prenota_salaDiventano rossi: test_punta_al_database_di_prenota_sala e test_non_ci_sono_segreti.
4 · main.py, la porta d'ingresso
In italiano.
Due pezzi: l'app, con il titolo; e una rotta GET /salute che risponde con un dizionario. Il router delle sale, che arriva all'esercizio 8, è già nel file qui sotto: nella tua versione, per ora, quelle due righe non ci sono.
from fastapi import FastAPI
from app.rotte import sale
app = FastAPI(title="Prenota-sala")
app.include_router(sale.router)
@app.get("/salute")
def salute() -> dict[str, str]:
return {"stato": "ok"}Passo per passo.
FastAPI(title="Prenota-sala")crea l'app. Il titolo compare in/docs.@app.get("/salute")dice «le richiesteGETa/salutevanno a questa funzione».- La funzione restituisce
{"stato": "ok"}: FastAPI lo trasforma in JSON e risponde200. -> dict[str, str]è la forma della risposta: serve a/docs.
Le trappole.
Il percorso sbagliato. /health è un nome molto usato, e il test chiede /salute: il programma funziona, il test no. Una rotta si chiama come dice il contratto, non come ti viene in mente.
@app.get("/health")
def salute() -> dict[str, str]:
return {"stato": "ok"}Diventano rossi: test_salute e test_la_salute_compare_in_docs.
5 · database.py, il collegamento
In italiano.
Quattro pezzi, nell'ordine in cui vanno: leggere il .env, leggere la variabile (con un valore di riserva), creare la strada verso PostgreSQL, prestare una sessione a chi la chiede. Base c'era già.
import os
from dotenv import load_dotenv
from sqlalchemy import create_engine
from sqlalchemy.orm import DeclarativeBase, Session
load_dotenv()
DATABASE_URL = os.environ.get("DATABASE_URL", "postgresql+psycopg:///prenota_sala")
engine = create_engine(DATABASE_URL)
class Base(DeclarativeBase):
"""La madre delle classi-tabella (modelli.py)."""
def get_db():
with Session(engine) as db:
yield dbPasso per passo.
load_dotenv()legge il.enve mette le sue righe tra le variabili d'ambiente. Se una variabile c'è già, non la tocca.os.environ.get("DATABASE_URL", "…")legge la variabile. Se manca, vale il valore di riserva: il database di Prenota-sala sul tuo computer.create_enginenon si collega subito: aspetta la prima richiesta.get_dbusawith Session(engine) as db:eyield db. Ilwithchiude la sessione alla fine, anche se la rotta è andata in errore.
Le trappole.
Senza load_dotenv. L'indirizzo arriva solo dalle variabili del terminale: il .env è un file che nessuno legge. Sul tuo computer sembra funzionare, perché c'è il valore di riserva, finché il database non cambia nome.
# manca la riga load_dotenv()
DATABASE_URL = os.environ.get("DATABASE_URL", "postgresql+psycopg:///prenota_sala")Diventano rossi: test_load_dotenv_legge_il_file_env.
Senza valore di riserva. Tra le quadre, os.environ["DATABASE_URL"] dà un KeyError se la variabile manca: il programma non parte nemmeno, su un computer senza .env.
DATABASE_URL = os.environ["DATABASE_URL"]Diventano rossi: test_il_valore_di_riserva.
La sessione senza il with. Funziona finché una rotta non va in errore: la sessione resta aperta, e dopo qualche richiesta il database non ha più connessioni libere.
def get_db():
db = Session(engine)
yield dbDiventano rossi: test_get_db_presta_una_sessione_e_la_chiude.
6 · modelli.py, da schema.sql alle classi
In italiano.
Una classe per tabella, una riga per colonna, nello stesso ordine di schema.sql. Il tipo Python dice se la colonna è obbligatoria (str) o facoltativa (str | None). Il CHECK non si traduce: lo controlla il database. Il DEFAULT sì, con server_default.
from datetime import datetime
from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column
from app.database import Base
class SalaDB(Base):
__tablename__ = "sale" # CREATE TABLE sale
id: Mapped[int] = mapped_column(primary_key=True) # id SERIAL PRIMARY KEY
nome: Mapped[str] = mapped_column(unique=True) # nome TEXT NOT NULL UNIQUE
piano: Mapped[str] # piano TEXT NOT NULL CHECK (piano IN (...))
posti: Mapped[int] # posti INTEGER NOT NULL CHECK (posti > 0)
proiettore: Mapped[bool] = mapped_column(server_default="false")
# # proiettore BOOLEAN NOT NULL DEFAULT false
note: Mapped[str | None] # note TEXT
class PrenotazioneDB(Base):
__tablename__ = "prenotazioni" # CREATE TABLE prenotazioni
id: Mapped[int] = mapped_column(primary_key=True) # id SERIAL PRIMARY KEY
sala_id: Mapped[int] = mapped_column(ForeignKey("sale.id"))
# # sala_id INTEGER NOT NULL REFERENCES sale(id)
organizzatore: Mapped[str] # organizzatore TEXT NOT NULL
inizio: Mapped[datetime] # inizio TIMESTAMP NOT NULL
fine: Mapped[datetime] # fine TIMESTAMP NOT NULL CHECK (fine > inizio)Passo per passo.
sale:nomeèUNIQUE(unique=True),noteè l'unica facoltativa (str | None),pianoepostihanno unCHECKche resta un commento.proiettoreha unDEFAULT:server_default="false"dice a SQLAlchemy «questa colonna la riempie il database».prenotazioni:sala_idè una chiave esterna (ForeignKey("sale.id")), dentro le virgolettetabella.colonna.inizioefinesonoTIMESTAMPin SQL,datetimein Python.- Ogni riga ha accanto il suo commento SQL: chi legge vede la corrispondenza senza aprire
schema.sql.
Le trappole.
Il default dimenticato. SQLAlchemy non sa del DEFAULT del database: senza server_default, quando salvi una sala senza dire nulla del proiettore manda NULL, e PostgreSQL risponde con un NotNullViolation.
proiettore: Mapped[bool] = mapped_column()Diventano rossi: test_il_default_lo_scrive_il_database e test_una_prenotazione_si_salva (anche lì si salva una sala senza proiettore).
La colonna facoltativa scritta obbligatoria. Mapped[str] dice «NOT NULL», e note in schema.sql non lo è. Le sale che hanno note vuote ora, per Python, sono un errore.
note: Mapped[str]Diventano rossi: test_obbligatorie_e_facoltative.
L'unico perso. Senza unique=True, Python non sa che il nome è irripetibile. Il database lo controlla lo stesso: ma il modello ha smesso di ricopiare schema.sql.
nome: Mapped[str]Diventano rossi: test_chiavi_primarie_e_colonne_uniche.
La freccia che non c'è. sala_id: Mapped[int] è un numero qualunque: manca ForeignKey. Quando nel libro sul database collegherai le due classi, non si collegano.
sala_id: Mapped[int]Diventano rossi: test_le_chiavi_esterne.
7 · schemi.py, gli stampi
In italiano.
SalaNuova ha tutto quello che serve a chi crea una sala, tranne l'id. Sala parte da SalaNuova e aggiunge l'id e from_attributes. Il piano è un Literal (il CHECK di schema.sql diventa una lista fissa di parole); i posti hanno Field(gt=0) (il CHECK (posti > 0)).
from typing import Literal
from pydantic import BaseModel, ConfigDict, Field
Piano = Literal["terra", "primo", "secondo"]
class SalaNuova(BaseModel):
nome: str
piano: Piano
posti: int = Field(gt=0)
proiettore: bool = False
note: str | None = None
class Sala(SalaNuova):
model_config = ConfigDict(from_attributes=True)
id: intPasso per passo.
Piano = Literal[...]è un nome per la lista di tre parole: lo si può riusare dove serve.proiettore: bool = Falseenote: str | None = None: chi chiama può non scriverli.class Sala(SalaNuova)eredita i cinque campi.from_attributes=Truefa leggere lo stampo da un oggettoSalaDB, non solo da un dizionario.
Le trappole.
L'id nello stampo nuovo. Chi crea una sala non sa che id avrà: lo decide il database. Con id: int nello stampo nuovo, ogni POST senza id risponde 422.
class SalaNuova(BaseModel):
id: int
nome: str
…Diventano rossi: test_lo_stampo_nuovo_non_ha_l_id, test_i_valori_di_partenza e test_il_piano_e_uno_di_tre.
Senza from_attributes. Lo stampo si riempie solo da un dizionario. Con un oggetto: Input should be a valid dictionary or instance of Sala.
class Sala(SalaNuova):
id: intDiventano rossi: test_la_risposta_si_riempie_da_un_oggetto.
I posti senza limite. posti: int accetta anche 0 e -3. Il database li rifiuterebbe con un errore SQL, ma l'utente vedrebbe un 500 invece di un 422 che spiega.
posti: intDiventano rossi: test_i_posti_sono_maggiori_di_zero.
8 · sale.py, il router
In italiano.
Il router ha prefisso /sale e tag sale; la rotta sotto ha "" come percorso, e il prefisso fa il resto: GET /sale. In main.py due righe: l'import del file e include_router.
from fastapi import APIRouter
from app.schemi import Sala
router = APIRouter(prefix="/sale", tags=["sale"])
@router.get("")
def elenco_sale() -> list[Sala]:
return [] # il segnapostoIn main.py, le due righe nuove sono quelle già viste:
from app.rotte import sale
app.include_router(sale.router)Le trappole.
Il prefisso dentro la rotta. Funziona lo stesso: GET /sale risponde. Ma il prefisso sta ripetuto in ogni rotta del file, e il giorno che ne scrivi dieci, uno lo dimentichi.
router = APIRouter(tags=["sale"])
@router.get("/sale")Diventano rossi: test_il_router_ha_il_prefisso_e_il_tag.
Il tag dimenticato. Le rotte funzionano, ma in /docs finiscono nel gruppo default, in mezzo a /salute.
router = APIRouter(prefix="/sale")Diventano rossi: test_il_router_ha_il_prefisso_e_il_tag e test_la_rotta_compare_in_docs_con_il_suo_tag.
Il router mai montato
Non è una trappola dei test, ma è l'errore che vedrai di più: il router c'è, il file è perfetto, e GET /sale risponde 404 Not Found. Manca app.include_router(sale.router) in main.py: un router che nessuno monta è un gruppo di rotte che nessuno vede. La prova è sempre /docs: se la rotta non compare, non è montata.
Dopo la palestra
Lancia pytest da solo: quaranta test verdi. Poi apri la teoria e confronta: quello che hai appena fatto, in piccolo, è la cartella di Ritrovato, passo per passo. Se vuoi un altro giro, rifallo da capo con il tuo progetto: è l'ultimo punto della palestra. Poi vai al capitolo Un pezzo alla volta: lì si riempie lo scheletro, una funzione alla volta.