Un pezzo alla volta, la palestra
Sei pezzi del padel del dopolavoro, con i test
- 90–120 minuti di lavoro
Il dopolavoro della Linea Menta ha tre campi da padel, e una lavagna con le prenotazioni. Sei esercizi, dal ★ al ★★★, sono i sei pezzi di una piccola API che la sostituisce: la lista dei campi, la scheda di una prenotazione, il tabellone con i filtri, la prenotazione, lo slot già preso, la disdetta.
Ogni esercizio è un pezzo da capo a fondo: la tabella (campi e prenotazioni, in padel.sql), il modello e lo stampo sono già lì, e tu scrivi la rotta. Ognuno ha il suo file di test: quando è tutto verde, hai finito. Per il resto del giro (provarlo in /docs, farne un commit) il capitolo Un pezzo alla volta ti ha dato la regola.
Gli esercizi da scaricare
Una cartella con i file da completare e i test già pronti. Come si usa: la guida in cinque passi.
Nello stesso zip c'è anche la storia del capitolo, Ritrovato: la trovi nella pagina dopo.
Prima di iniziare
Scompatta lo zip e segui il README.md che c'è dentro: venv, pip install, il tuo database padel, code .. Se è la prima volta, la pagina Come si usa un esercizio lo fa con te, un comando alla volta. PostgreSQL deve essere acceso.
Ogni esercizio, sempre gli stessi passi:
- Apri il file in
palestra/. In alto: la storia, il pezzo, cosa fai, come provi. Sotto, gli stampi già scritti e la rotta, con il suo contratto in commento. - Al posto della riga
raise HTTPException(status_code=501, …)scrivi il codice della rotta. pytest palestra/test_<nome>.py -v, oppure la provetta di VS Code.- Rosso? Leggi l'ultima riga del messaggio: i test dicono cosa manca, in italiano. Bloccato da 15 minuti? Apri il primo aiutino, non la soluzione.
- Verde? Prova il pezzo anche a mano, come nel passo 6 del giro:
fastapi dev palestra/<nome>.py, poihttp://127.0.0.1:8000/docs.
I test non hanno bisogno del server acceso: usano TestClient e un database tutto loro (progetto_un_pezzo_alla_volta_test), che torna come nuovo prima di ogni test. Dopo ogni scrittura guardano anche dentro il database: una rotta che risponde 201 senza aver fatto il commit non passa. È la lezione dell'esempio D.
Il server lavora sul tuo database padel. Per riavere i dati di partenza: psql -d padel -f palestra/padel.sql.
| # | Il pezzo | Le mosse | Difficoltà |
|---|---|---|---|
| 1 | I campi | select, order_by, scalars | ★ |
| 2 | La scheda di una prenotazione | get e il 404 | ★ |
| 3 | Il tabellone con i filtri | due filtri facoltativi, un where alla volta | ★★ |
| 4 | Una prenotazione nuova | add, commit, refresh, il 201 | ★★ |
| 5 | Lo slot già preso | due controlli prima di scrivere: il 404 e il 409 | ★★★ |
| 6 | La disdetta | delete, commit, il 204 | ★★ |
1 · I campi ★
palestra/elenco_campi.py
Il dopolavoro ha tre campi. Chi vuole prenotare comincia dalla lista, in ordine di nome.
| Richiesta | Risposta |
|---|---|
GET /campi | 200, i campi in ordine di nome: {"id": 1, "nome": "Campo 1", "coperto": true}, poi il Campo 2, poi il Campo 3 |
Come provi: pytest palestra/test_elenco_campi.py -v
Aiutino 1
select, un order_by, e la lista.Aiutino 2
db.scalars(domanda).all() dà la lista di oggetti. Non execute, che darebbe le righe intere.2 · La scheda di una prenotazione ★
palestra/scheda_prenotazione.py
Chi ha prenotato vuole rivedere la sua prenotazione dal numero che ha ricevuto. Se il numero non c'è, la risposta è un 404 chiaro.
| Richiesta | Risposta |
|---|---|
GET /prenotazioni/2 | 200, {"id": 2, "campo_id": 2, "giorno": "2026-12-05", "ora": 18, "nome": "Piero Conti"} |
GET /prenotazioni/99 | 404, {"detail": "Prenotazione non trovata"} |
Come provi: pytest palestra/test_scheda_prenotazione.py -v
Aiutino 1
id: quale delle mosse cerca per chiave primaria? Il primo argomento è la classe-tabella (PrenotazioneDB), non lo stampo Prenotazione.Aiutino 2
db.get dà l'oggetto, oppure None. Se è None, la prenotazione non c'è: il 404 lo decidi tu, con un if e un raise HTTPException(…).3 · Il tabellone con i filtri ★★
palestra/prenotazioni_del_giorno.py
Chi gestisce i campi guarda il tabellone: tutte le prenotazioni, oppure solo quelle di un giorno, oppure solo quelle di un campo, oppure i due filtri insieme. In ordine di giorno, poi di ora, poi di campo.
| Richiesta | Risposta |
|---|---|
GET /prenotazioni | 200, tutte e cinque, in ordine |
GET /prenotazioni?giorno=2026-12-05 | 200, le tre di quel giorno |
GET /prenotazioni?campo_id=1 | 200, le tre del Campo 1 |
GET /prenotazioni?giorno=2026-12-05&campo_id=1 | 200, le due del Campo 1 in quel giorno |
GET /prenotazioni?giorno=2026-12-25 | 200, []: un filtro che non trova niente non è un errore |
Come provi: pytest palestra/test_prenotazioni_del_giorno.py -v
Aiutino 1
Aiutino 2
domanda = select(…).order_by(…)). Ogni filtro, se c'è, la restringe con un where: if giorno is not None:, domanda = domanda.where(…).Aiutino 3
if separati i filtri si sommano. Con un if e un elif, il secondo filtro viene ignorato quando c'è il primo.4 · Una prenotazione nuova ★★
palestra/nuova_prenotazione.py
Rosa Galli prenota un campo. Il numero della prenotazione non lo sceglie lei: lo sceglie il database, e la risposta lo deve dire. L'ora va dalle 8 alle 21: gli stampi lo dicono già, e FastAPI risponde 422 da solo.
| Richiesta | Risposta |
|---|---|
POST /prenotazioni con {"campo_id": 2, "giorno": "2026-12-07", "ora": 20, "nome": "Giada Serra"} | 201, la prenotazione con "id": 6 |
POST /prenotazioni con "ora": 23 | 422, e non scrive niente |
Come provi: pytest palestra/test_nuova_prenotazione.py -v
Aiutino 1
PrenotazioneDB (senza id: lo sceglie il database), add, commit, refresh. Poi lo restituisci.Aiutino 2
commit. Se c'è un InvalidRequestError … is not persistent within this Session, manca il commit prima del refresh.5 · Lo slot già preso ★★★
palestra/slot_gia_preso.py
Piero Conti prova a prenotare il Campo 1 alle 18 di sabato 5 dicembre: c'è già Rosa Galli. E Anna Neri sbaglia il numero del campo: il Campo 9 non esiste. La rotta è quella dell'esercizio 4, con due controlli prima di scrivere.
| Richiesta | Risposta |
|---|---|
POST /prenotazioni con {"campo_id": 2, "giorno": "2026-12-07", "ora": 20, …} | 201, la prenotazione con il suo id |
POST /prenotazioni con {"campo_id": 1, "giorno": "2026-12-05", "ora": 18, …} | 409, {"detail": "Slot già preso"} |
POST /prenotazioni con "campo_id": 9 | 404, {"detail": "Campo non trovato"} |
Lo slot è campo + giorno + ora. La stessa ora su un altro campo, o lo stesso campo a un'altra ora, è libera.
Come provi: pytest palestra/test_slot_gia_preso.py -v
Aiutino 1
Aiutino 2
db.get(CampoDB, dati.campo_id), e se è None il 404. Lo slot: una domanda con select e tre condizioni nel where (campo, giorno, ora), e db.scalar per averne una sola.Aiutino 3
db.scalar ha trovato una prenotazione, lo slot è preso: raise HTTPException(status_code=409, …). Il raise ferma la funzione: la scrittura sta sotto, e non parte.6 · La disdetta ★★
palestra/disdetta.py
Luca Moro non può venire: disdice la sua prenotazione, e la riga sparisce dal tabellone. Se il numero non c'è, 404.
| Richiesta | Risposta |
|---|---|
DELETE /prenotazioni/5 | 204, senza corpo |
DELETE /prenotazioni/99 | 404, {"detail": "Prenotazione non trovata"} |
Come provi: pytest palestra/test_disdetta.py -v
Aiutino 1
db.get, e se è None il 404.Aiutino 2
db.delete(prenotazione) e db.commit(). Senza commit la riga resta. Il 204 lo dice già il decoratore: la funzione non restituisce niente.Per il tuo progetto
Questo non ha un test, e vale più degli altri sei. Prendi il canvas del tuo progetto, e scrivi in un file ROTTE.md:
- La tabella delle rotte, una riga per azione del riquadro 7, con le cinque regole dei percorsi (Il contratto).
- L'ordine dei lavori: numera le righe con le tre regole (leggere prima di scrivere, una tabella prima di due, senza permessi prima che con). Il login e il «se avanza tempo» vanno in fondo.
- Il primo pezzo, scritto in una frase: «Il primo pezzo è
GET …, perché …».
Poi fai il primo pezzo, da capo a fondo: la riga, la tabella e il modello, gli stampi, il test rosso, la rotta, /docs, il commit. Fermati lì. Il secondo, domani.