La cartella del progetto, la palestra
Prenota-sala, uno scheletro da completare un pezzo per volta
- 90–120 minuti di lavoro
Otto esercizi, dal ★ al ★★★. Lo zip è la cartella di un progetto vero, Prenota-sala: le sale riunioni della centrale della Linea Menta. Livia Pellegri, della segreteria, vuole smettere di girare i corridoi con un foglio. Lo scheletro c'è già, ma otto file sono incompleti: li completi in ordine, uno per volta. Ognuno ha il suo test, e il test dice quando hai finito.
Gli esercizi da scaricare
Una cartella con i file da completare e i test già pronti. Come si usa: la guida in cinque passi.
Questa volta non c'è la storia a livelli: la storia di questo libro, Ritrovato, è nel capitolo dopo, e riparte proprio dalla cartella che qui impari a costruire.
Prima di iniziare
Scompatta lo zip e apri il terminale nella cartella (su Windows quello di Ubuntu). Una volta sola:
cd ~/Downloads/progetto-la-cartella-del-progetto
python3 -m venv .venv
source .venv/bin/activate
pip install "fastapi[standard]" sqlalchemy "psycopg[binary]" python-dotenv pytest httpx
pg_isready
git --version
code .pg_isready deve rispondere accepting connections: se no, PostgreSQL è spento (come si accende). Non devi creare nessun database: i test si fanno da soli il loro, progetto_la_cartella_del_progetto_test.
Sì, requirements.txt ora è vuoto: è il primo esercizio. Intanto le librerie le installi a mano, con il comando sopra; l'esercizio è scrivere nel file la stessa lista.
Ogni esercizio, sempre gli stessi quattro passi:
- Apri il file dell'esercizio. In alto, nei commenti: la storia, cosa fai, come provi.
- Scrivi quello che chiede, nel punto che indica.
- Lancia il suo test:
pytest tests/test_requirements.py -v, oppure la provetta di VS Code. - Rosso? Leggi l'ultima riga del messaggio e riprova. Verde? Passa al file dopo.
I test non toccano il tuo lavoro: usano un database loro, che prima di ogni test si butta e si rifà da schema.sql. Lo fa tests/conftest.py, già pronto: lo hai letto nella teoria.
| # | File | Cosa devi saper fare | Difficoltà |
|---|---|---|---|
| 1 | requirements.txt | la lista della spesa, con gli extra | ★ |
| 2 | .gitignore | cosa Git non deve vedere | ★ |
| 3 | .env.example | il modello del .env | ★ |
| 4 | app/main.py | l'app e la rotta /salute | ★ |
| 5 | app/database.py | la variabile d'ambiente, l'engine, la sessione | ★★ |
| 6 | app/modelli.py | da schema.sql alle classi | ★★★ |
| 7 | app/schemi.py | lo stampo nuovo e la risposta | ★★ |
| 8 | app/rotte/sale.py | il router, e main.py che lo monta | ★★ |
1 · Il requirements.txt ★
requirements.txt
Chi scarica Prenota-sala da GitHub trova una cartella senza il venv. Deve poter installare tutto con un comando solo: pip install -r requirements.txt. Il file è la lista della spesa.
Serve: FastAPI (con l'extra standard), SQLAlchemy, psycopg (con l'extra binary), python-dotenv, pytest e httpx. Una libreria per riga, i nomi senza numeri di versione.
Come provi: pytest tests/test_requirements.py -v. A lavoro finito sono cinque test verdi.
Aiutino 1
Aiutino 2
fastapi e psycopg. Le altre quattro sono nomi semplici.Aiutino 3
# per il test non esiste.2 · Il .gitignore ★
.gitignore
Livia sta per fare il primo commit di Prenota-sala. Nella cartella ci sono file che su GitHub non devono finire, e altri che devono arrivarci.
Una riga per ognuna di queste quattro cose, e nessun'altra: la cartella del venv, le cartelle __pycache__, la cartella della cache di pytest, il file .env. Il file .env.example deve restare fuori dalla lista: quello va su GitHub.
Cosa fanno i test: creano un piccolo repository di prova con il tuo .gitignore e chiedono a Git, per ogni file, «questo lo ignori?». Servono Git e il terminale: git --version.
Come provi: pytest tests/test_gitignore.py -v. A lavoro finito sono sei test verdi.
Aiutino 1
.venv/.Aiutino 2
.env, il modello è .env.example: due nomi quasi uguali. Un modello come .env* li nasconde tutti e due.Aiutino 3
.env.example: hai un asterisco di troppo. Rosso su __pycache__: controlla i due trattini bassi, prima e dopo.3 · Il .env.example ★
.env.example
Il .env vero, con le impostazioni di Livia, non va su GitHub. Chi scarica il progetto deve però sapere quali righe scrivere nel suo: per questo c'è il modello, che su GitHub ci va.
Una riga sola: la variabile DATABASE_URL con l'indirizzo del database di Prenota-sala, che si chiama prenota_sala (PostgreSQL sul tuo computer, driver psycopg, come nella teoria). Nessuna password, nessun segreto: è un modello.
Come provi: pytest tests/test_env_example.py -v. A lavoro finito sono tre test verdi.
Aiutino 1
NOME=valore, senza spazi attorno all'uguale e senza virgolette.Aiutino 2
postgresql+psycopg:///, e subito dopo il nome del database.Aiutino 3
@ e la parola «password»: se ti viene voglia di scriverle, stai copiando il .env invece del modello.4 · main.py, la porta d'ingresso ★
app/main.py
Livia vuole sapere, con una richiesta sola, se Prenota-sala è acceso. Serve una rotta «di salute».
Nel file ci sono già i commenti numerati. Per ora fai i primi due punti: crea l'app (titolo Prenota-sala) e aggiungi GET /salute, che risponde 200 e {"stato": "ok"}. Il terzo punto lo lasci: è l'esercizio 8.
Come provi: pytest tests/test_main.py -v. A lavoro finito sono tre test verdi.
Aiutino 1
app = FastAPI(title=...), e sotto una funzione con @app.get("/salute").Aiutino 2
stato, e il valore "ok". Il codice di risposta, 200, lo dà FastAPI da solo.Aiutino 3
Prenota-sala, con il trattino. Se i test dicono 404 == 200, la rotta non c'è: controlla di aver scritto /salute con la barra davanti.5 · database.py, il collegamento ★★
app/database.py
Prenota-sala deve parlare con PostgreSQL. L'indirizzo del database non si scrive nel codice: sul tuo computer è uno, sul computer di chi la farà girare online sarà un altro. Sta in una variabile d'ambiente, DATABASE_URL, che di solito arriva dal file .env.
Il file ha quattro punti numerati. Il primo legge il .env; il secondo legge DATABASE_URL (con il valore di riserva postgresql+psycopg:///prenota_sala); il terzo crea l'engine; il quarto è get_db, che presta una sessione e la chiude alla fine. Base c'è già.
Cosa fanno i test: tre li fanno su una copia di app/, in una cartella vuota, con e senza il file .env: così il tuo .env e le variabili del tuo terminale non c'entrano. Gli altri guardano engine e get_db.
Come provi: pytest tests/test_database.py -v. A lavoro finito sono sei test verdi.
Aiutino 1
load_dotenv() è una riga sola e va prima di leggere la variabile. L'import c'è già, in cima al file.Aiutino 2
os.environ.get("NOME", "valore di riserva"): il secondo argomento vale solo se la variabile non c'è.Aiutino 3
get_db è quella dei libri sul database: with Session(engine) as db: e, sotto, yield db. Se il test dice «la sessione è rimasta aperta», ti manca il with.6 · modelli.py, da schema.sql alle classi ★★★
app/modelli.py
Livia ha scritto schema.sql: due tabelle, sale e prenotazioni. Ora Python deve conoscerle. modelli.py ricopia schema.sql, riga per riga, e accanto a ogni colonna c'è il commento con la riga SQL che le corrisponde.
Due classi, con questi nomi: SalaDB (la tabella sale) e PrenotazioneDB (la tabella prenotazioni). Una colonna per ogni colonna, con lo stesso nome e nello stesso ordine. Le regole di traduzione sono nell'intestazione del file e nella tabella della teoria.
Cosa fanno i test: guardano il database vero, fatto da schema.sql, e lo mettono accanto alle tue classi: i nomi delle tabelle e delle colonne, i tipi, quali colonne possono essere vuote, la chiave primaria, le colonne uniche, le chiavi esterne. Poi due prove con la sessione: salvano una sala senza dire se ha il proiettore (il DEFAULT lo mette il database) e una prenotazione.
Come provi: pytest tests/test_modelli.py -v. A lavoro finito sono otto test verdi.
Aiutino 1
schema.sql accanto a modelli.py. Una colonna, una riga, nello stesso ordine: ogni test lo controlla.Aiutino 2
Mapped[str]). Facoltativa: Mapped[str | None]. Unica: mapped_column(unique=True). Chiave esterna: mapped_column(ForeignKey("sale.id")). I CHECK non si traducono: restano un commento.Aiutino 3
DEFAULT nel SQL: proiettore. Senza mapped_column(server_default="false"), SQLAlchemy manda NULL al database, e il database lo rifiuta. Il test di nome il_default_lo_scrive_il_database ti dice se è questo.7 · schemi.py, gli stampi ★★
app/schemi.py
Chi prenota manda i dati di una sala nuova; l'API risponde con la sala, che ha anche l'id deciso dal database. Due stampi di Pydantic, come nel libro Il database nell'API.
Scrivi Piano (terra, primo o secondo: il CHECK di schema.sql diventa un Literal), SalaNuova (il corpo del POST: nome, piano, posti maggiori di 0, proiettore, se manca è False, note, se manca è None; niente id) e Sala (la risposta: tutto quello che c'è in SalaNuova, più l'id, e riempibile anche da un oggetto).
Come provi: pytest tests/test_schemi.py -v. A lavoro finito sono sei test verdi.
Aiutino 1
Sala può partire da SalaNuova: eredita tutti i campi, e tu ci aggiungi id: int.Aiutino 2
Literal["terra", "primo", "secondo"] per il piano. Field(gt=0) per i posti: gt è «greater than», maggiore di.Aiutino 3
model_config = ConfigDict(from_attributes=True). Se dice che SalaNuova ha id, ce l'hai messo anche lì.8 · sale.py, il router ★★
app/rotte/sale.py e app/main.py
Le rotte delle sale avranno un file tutto loro. Qui c'è già una rotta segnaposto, GET /sale, che risponde con l'elenco vuoto: la riempirai nel capitolo dopo. Manca il router.
Due pezzi: in sale.py crea il router, con prefisso /sale e tag sale; in main.py importalo e montalo con include_router (è il punto 3 dei commenti).
Come provi: pytest tests/test_sale.py -v. A lavoro finito sono tre test verdi. Poi lancia pytest da solo: quaranta verdi, e Prenota-sala è uno scheletro che funziona.
Aiutino 1
sale.py. In main.py ne servono due: l'import del file e il montaggio.Aiutino 2
APIRouter(prefix="/sale", tags=["sale"]). La rotta già scritta ha "" come percorso: il prefisso fa il resto.Aiutino 3
NameError: name 'router' is not defined: manca la riga del router. Un 404 su /sale: manca app.include_router(sale.router) in main.py.E poi: la cartella del tuo progetto
Non è un esercizio da testare, ed è il più importante. Prendi CANVAS.md e schema.sql del tuo progetto, e costruisci la sua cartella seguendo i tredici passi della teoria: git init, venv, requirements.txt, .gitignore, .env, main.py con /salute, pytest.ini e il primo test, database.py, conftest.py, modelli.py, schemi.py, rotte/, il primo commit.
Ti sei fermato quando? Se ogni passo ha avuto la sua prova verde, hai uno scheletro. Se non sai da dove cominciare, parti da modelli.py: una classe per ogni tabella del tuo schema.sql, con la tabella di traduzione sotto gli occhi.
Poi passa la cartella a un compagno: deve riuscire ad avviarla leggendo solo il README.md. Se non ci riesce, il README.md ha un passo che manca. Il passo successivo è il capitolo Un pezzo alla volta.