Vai al contenuto
code-to-code

Apro l'indice…

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

Il progetto5. Un pezzo alla voltap. 162

Un pezzo alla volta, le soluzioni

Il ragionamento, il codice, le trappole

Per ogni esercizio, sempre lo stesso ordine: in italiano → il codice → le trappole. Per i più difficili, anche il passo per passo.

La tua soluzione è diversa ma i test sono verdi? Probabilmente va bene: spesso ci sono più strade giuste. Confronta il ragionamento, non le singole parole. E leggi comunque le trappole: alcune passano la risposta e si rompono su un test che guarda nel database.

Le soluzioni complete

La stessa cartella, con il codice al posto di pass. Aprila dopo averci provato: i test sono gli stessi.

progetto-un-pezzo-alla-volta-soluzioni.zip39 KB

Nei file dello zip le soluzioni hanno gli stampi e i commenti dello scheletro: qui sotto c'è solo il pezzo che hai scritto tu.


La palestra

1 · I campi

In italiano. Una domanda in due pezzi: da CampoDB, in ordine di nome. La eseguo con scalars e all, e restituisco la lista.

Python
@app.get("/campi")
def elenco_campi(db: Session = Depends(get_db)) -> list[Campo]:
    domanda = select(CampoDB).order_by(CampoDB.nome)
    return db.scalars(domanda).all()

È il pezzo più piccolo del capitolo: una tabella, nessun filtro, nessun 404. Se riesci a farlo, hai tutto il giro in mano: la tabella, il modello, lo stampo, la rotta.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
select(CampoDB), senza order_byNessun errore, ma il database non promette un ordine: i campi escono come sono stati scrittitest_elenco_campi_in_ordine_di_nome
return db.execute(domanda).all()Arrivano le righe, non gli oggetti: ogni riga ha dentro un oggetto solo, e FastAPI non trova i campi: ResponseValidationError … Field required per id, nome, copertotutti e quattro

Un errore che non rompe niente. return db.scalars(domanda) senza .all() fa passare tutti i test: FastAPI scorre da solo il risultato. Non è una lista, però: non la puoi contare né stampare. Tieni .all().


2 · La scheda di una prenotazione

In italiano. Cerco la prenotazione dal suo id. Se non c'è (None), rispondo 404. Se c'è, la restituisco.

Python
@app.get("/prenotazioni/{prenotazione_id}")
def scheda_prenotazione(prenotazione_id: int, db: Session = Depends(get_db)) -> Prenotazione:
    prenotazione = db.get(PrenotazioneDB, prenotazione_id)
    if prenotazione is None:
        raise HTTPException(status_code=404, detail="Prenotazione non trovata")
    return prenotazione

db.get cerca per chiave primaria e dà l'oggetto oppure None. Lo stampo Prenotazione poi lo fa FastAPI, leggendo gli attributi dell'oggetto.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
db.get(Prenotazione, prenotazione_id)Hai passato lo stampo di Pydantic, non la classe-tabella: NoInspectionAvailable: No inspection system is available for object of type <class 'pydantic._internal._model_construction.ModelMetaclass'>tutti e quattro
niente if prenotazione is Nonedb.get dà None, la rotta lo restituisce, e FastAPI non riesce a farne una prenotazione: ResponseValidationError … Input should be a valid dictionary or object to extract fields from. Il client riceve un 500 invece del 404test_scheda_una_che_non_c_e_da_404, test_scheda_il_numero_e_l_id_non_la_posizione

3 · Il tabellone con i filtri

In italiano. Parto dalla domanda senza filtri: tutte le prenotazioni, in ordine di giorno, ora e campo. Poi, per ogni filtro che c'è, aggiungo un where. I where si sommano: con due filtri, valgono tutti e due.

Python
@app.get("/prenotazioni")
def tabellone(
    giorno: date | None = None,
    campo_id: int | None = None,
    db: Session = Depends(get_db),
) -> list[Prenotazione]:
    domanda = select(PrenotazioneDB).order_by(PrenotazioneDB.giorno, PrenotazioneDB.ora, PrenotazioneDB.campo_id)
    if giorno is not None:
        domanda = domanda.where(PrenotazioneDB.giorno == giorno)
    if campo_id is not None:
        domanda = domanda.where(PrenotazioneDB.campo_id == campo_id)
    return db.scalars(domanda).all()

È la regola 4 del contratto al lavoro: un filtro può mancare, e senza filtro la lista è intera. Per questo = None nel def, e if … is not None nel codice.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
elif campo_id is not None al posto del secondo ifCon tutti e due i filtri, il secondo viene ignorato: arrivano le tre del giorno, non le due del Campo 1test_i_due_filtri_insieme
if not trovate: raise HTTPException(status_code=404, …)Un filtro che non trova niente non è un errore: 404 invece di 200 e []test_un_giorno_senza_prenotazioni_da_lista_vuota
select(PrenotazioneDB), senza order_byNessun errore, ma l'ora 9 della nuova prenotazione esce dopo l'ora 18: l'ordine è quello di scritturatest_l_ordine_e_giorno_poi_ora

4 · Una prenotazione nuova

In italiano.

  1. Con i dati arrivati costruisco un oggetto PrenotazioneDB. Non scrivo l'id: lo sceglie il database.
  2. Lo metto nel carrello (add).
  3. Consegno il carrello (commit): l'INSERT parte e viene confermato.
  4. Riprendo l'oggetto dal database (refresh), così ha l'id.
  5. Lo restituisco: il decoratore dice che il codice è 201.
Python
@app.post("/prenotazioni", status_code=status.HTTP_201_CREATED)
def nuova_prenotazione(dati: PrenotazioneNuova, db: Session = Depends(get_db)) -> Prenotazione:
    prenotazione = PrenotazioneDB(campo_id=dati.campo_id, giorno=dati.giorno, ora=dati.ora, nome=dati.nome)
    db.add(prenotazione)
    db.commit()
    db.refresh(prenotazione)
    return prenotazione

Il 422 per l'ora 23 non lo scrivi: lo dice Field(ge=8, le=21) negli stampi, e FastAPI risponde prima ancora che la rotta parta.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
niente db.commit()refresh su un oggetto mai salvato: InvalidRequestError: Instance '<PrenotazioneDB at 0x…>' is not persistent within this Sessiontest_prenotazione_nuova_risponde_201_con_l_id, test_prenotazione_nuova_e_nel_database, test_prenotazione_nuova_due_prenotazioni_due_id
db.flush() al posto di db.commit()La rotta risponde, con l'id giusto: flush manda l'INSERT nella transazione. Ma la transazione non è confermata, e quando la sessione si chiude, il database fa il rollback: la riga non c'ètest_prenotazione_nuova_e_nel_database
PrenotazioneDB(id=1, campo_id=…)L'id lo sceglie il database, non tu: UniqueViolation: duplicate key value violates unique constraint "prenotazioni_pkey" (l'1 c'è già)tutti e tre quelli di scrittura

Un errore che non rompe niente. Togliere db.refresh(prenotazione) fa passare tutti i test: dopo il commit l'oggetto si ricarica da solo la prima volta che lo guardi. Ma è meglio saperlo scritto: refresh dice «adesso l'oggetto è quello del database».


5 · Lo slot già preso

In italiano. La rotta dell'esercizio 4, con due controlli prima di scrivere.

  1. Il campo c'è? db.get(CampoDB, dati.campo_id). Se è None, 404.
  2. Lo slot è libero? Cerco una prenotazione con lo stesso campo, lo stesso giorno, la stessa ora. Se la trovo, 409.
  3. Solo adesso scrivo: le quattro mosse.
Python
@app.post(
    "/prenotazioni",
    status_code=status.HTTP_201_CREATED,
    responses={409: {"description": "Slot già preso"}},
)
def nuova_prenotazione(dati: PrenotazioneNuova, db: Session = Depends(get_db)) -> Prenotazione:
    campo = db.get(CampoDB, dati.campo_id)
    if campo is None:
        raise HTTPException(status_code=404, detail="Campo non trovato")

    gia_presa = db.scalar(
        select(PrenotazioneDB).where(
            PrenotazioneDB.campo_id == dati.campo_id,
            PrenotazioneDB.giorno == dati.giorno,
            PrenotazioneDB.ora == dati.ora,
        )
    )
    if gia_presa is not None:
        raise HTTPException(status_code=409, detail="Slot già preso")

    prenotazione = PrenotazioneDB(campo_id=dati.campo_id, giorno=dati.giorno, ora=dati.ora, nome=dati.nome)
    db.add(prenotazione)
    db.commit()
    db.refresh(prenotazione)
    return prenotazione

Passo per passo, con le tre richieste dei test.

Richiestadb.get del campodb.scalar dello slotCosa risponde
Campo 2, 7 dicembre, ore 20il Campo 2None (nessuno)scrive, 201
Campo 1, 5 dicembre, ore 18il Campo 1la prenotazione di Rosa Galli409, e il raise ferma la funzione: la scrittura non parte
Campo 9, 7 dicembre, ore 20None(non ci arriva)404

Il raise è il punto: ferma la funzione sul posto, quindi le righe sotto (che scrivono) non girano. I controlli prima della scrittura sono questo.

Il vincolo UNIQUE (campo_id, giorno, ora) del database è l'ultima difesa: anche senza il controllo, lo slot doppio non entra mai. Il controllo serve per rispondere come si deve, con un 409 che dice cosa è successo, invece di un 500.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
niente controllo dello slot (nessun if gia_presa …)Il database dice no da solo: IntegrityError: (psycopg.errors.UniqueViolation) duplicate key value violates unique constraint "prenotazioni_campo_id_giorno_ora_key". Il client riceve un 500, non un 409test_uno_slot_gia_preso_da_409, test_il_409_non_scrive_niente
il where senza PrenotazioneDB.campo_id == …Lo slot «alle 18» è considerato preso su tutti i campi: il Campo 3, libero, risponde 409test_la_stessa_ora_su_un_altro_campo_e_libera
il where senza PrenotazioneDB.ora == …Il Campo 1 è considerato preso tutto il giorno: alle 20, libero, risponde 409test_un_altra_ora_dello_stesso_campo_e_libera
niente controllo del campoIl database dice no da solo: IntegrityError: (psycopg.errors.ForeignKeyViolation) … Key (campo_id)=(9) is not present in table "campi". 500 invece di 404test_un_campo_che_non_c_e_da_404
niente db.commit()InvalidRequestError: Instance '<PrenotazioneDB at 0x…>' is not persistent within this Sessioni cinque che prenotano uno slot libero: test_uno_slot_libero_si_prenota, test_uno_slot_libero_e_nel_database, e i tre dello stesso slot su un altro campo, un altro giorno, un'altra ora

6 · La disdetta

In italiano. Cerco la prenotazione. Se non c'è, 404. Se c'è, la cancello e confermo. Il decoratore dice 204, e la funzione non restituisce niente.

Python
@app.delete("/prenotazioni/{prenotazione_id}", status_code=status.HTTP_204_NO_CONTENT)
def disdici(prenotazione_id: int, db: Session = Depends(get_db)) -> None:
    prenotazione = db.get(PrenotazioneDB, prenotazione_id)
    if prenotazione is None:
        raise HTTPException(status_code=404, detail="Prenotazione non trovata")
    db.delete(prenotazione)
    db.commit()

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
niente db.commit()Risponde 204, ma la riga è ancora nel database: la disdetta non è mai stata confermatatest_disdetta_toglie_la_riga_dal_database, test_disdetta_toglie_solo_quella, test_disdire_due_volte_la_seconda_da_404
niente if prenotazione is Nonedb.delete(None): UnmappedInstanceError: Class 'builtins.NoneType' is not mapped, 500 invece del 404test_disdetta_una_che_non_c_e_da_404, test_disdire_due_volte_la_seconda_da_404

La storia

La storia lavora nella cartella storia/ritrovato/: tutto quello che scrivi sta in app/. Per ogni livello, qui sotto, solo i pezzi che aggiungi.

Livello 1 · Le stazioni

In italiano. Il pezzo più piccolo: una tabella, nessun filtro. Ma è il giro intero, ed è quello che fa tre cose nuove: un file di rotte nuovo, uno stampo nuovo, un router da montare.

  1. Lo stampo. In app/schemi.py: Stazione, con id e nome, e from_attributes=True perché la rotta restituisce oggetti del database.
  2. La rotta. In un file nuovo, app/rotte/stazioni.py, con il suo APIRouter.
  3. Il router montato. In app/main.py: app.include_router(stazioni.router).
Python
# app/schemi.py (in fondo)
class Stazione(BaseModel):
    model_config = ConfigDict(from_attributes=True)

    id: int
    nome: str
Python
# app/rotte/stazioni.py
from fastapi import APIRouter, Depends
from sqlalchemy import select
from sqlalchemy.orm import Session

from app.database import get_db
from app.modelli import StazioneDB
from app.schemi import Stazione

router = APIRouter(prefix="/stazioni", tags=["stazioni"])


@router.get("")
def elenco_stazioni(db: Session = Depends(get_db)) -> list[Stazione]:
    domanda = select(StazioneDB).order_by(StazioneDB.nome)
    return db.scalars(domanda).all()
Python
# app/main.py
from app.rotte import oggetti, stazioni

# …
app.include_router(stazioni.router)
app.include_router(oggetti.router)

Il percorso è "" perché il prefisso /stazioni sta già nel router. Con "/", la richiesta GET /stazioni riceverebbe un 307 verso /stazioni/: funziona, ma è un giro in più.

Il pytest -k livello_1 deve dare quattro test verdi. Con pytest tests/test_stazioni.py sono cinque: c'è anche test_la_salute_c_e_ancora, che non deve rompersi mai.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
niente order_by(StazioneDB.nome)Nessun errore, ma il menu dei filtri esce nell'ordine di scrittura, non in ordine alfabeticotest_livello_1_in_ordine_di_nome

Un errore che non è nel codice. Il router scritto ma non montato (manca app.include_router(…)): GET /stazioni risponde 404 {"detail":"Not Found"}, esattamente come se la rotta non ci fosse. È la prima cosa da guardare, quando una rotta «non c'è».

Livello 2 · Gli oggetti in deposito

In italiano. GET /oggetti: la lista di quelli che si possono ritirare, cioè quelli «in deposito». Dal più recente (trovato_il, poi id a parità di giorno). La risposta è lo stampo Oggetto, che non ha il segno particolare: il campo non esce, perché lo stampo non lo dichiara.

Python
# app/rotte/oggetti.py
from fastapi import APIRouter, Depends
from sqlalchemy import select
from sqlalchemy.orm import Session

from app.database import get_db
from app.modelli import OggettoDB
from app.schemi import Oggetto

router = APIRouter(prefix="/oggetti", tags=["oggetti"])


@router.get("")
def cerca_oggetti(db: Session = Depends(get_db)) -> list[Oggetto]:
    domanda = select(OggettoDB).where(OggettoDB.stato == "in deposito").order_by(OggettoDB.trovato_il.desc(), OggettoDB.id)
    return db.scalars(domanda).all()

OggettoDB.stato == "in deposito" esclude gli oggetti già restituiti e quelli donati. .desc() mette il più recente per primo.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
niente where(OggettoDB.stato == "in deposito")Arrivano anche l'oggetto restituito e quello donato: nessun errore, e l'elenco mostra cose che non si possono più ritiraretest_livello_2_solo_gli_oggetti_in_deposito, test_livello_2_dal_piu_recente, e tre del livello 3 (per_categoria, per_stazione, due_filtri_insieme)
un Oggetto con segno_particolare nello stampoNessun errore: il segno esce nel JSON, e lo vede chiunque. Il segno serve a Nives per capire se chi chiede l'oggetto è il proprietario: se è pubblico, non serve piùtest_livello_2_non_mostra_il_segno_particolare, test_livello_4_la_scheda_di_un_oggetto, test_livello_4_la_scheda_senza_il_segno_particolare, test_livello_5_registro_un_oggetto_201_con_l_id

Livello 3 · I filtri

In italiano. Gli stessi oggetti, ristretti. Tre filtri facoltativi: stazione_id, categoria, giorno. Ogni filtro, se c'è, aggiunge un where. Il tipo di categoria è Categoria (il Literal di schemi.py): una categoria che non esiste dà 422 da sola.

Python
from datetime import date

from app.schemi import Categoria, Oggetto


@router.get("")
def cerca_oggetti(
    stazione_id: int | None = None,
    categoria: Categoria | None = None,
    giorno: date | None = None,
    db: Session = Depends(get_db),
) -> list[Oggetto]:
    domanda = select(OggettoDB).where(OggettoDB.stato == "in deposito").order_by(OggettoDB.trovato_il.desc(), OggettoDB.id)
    if stazione_id is not None:
        domanda = domanda.where(OggettoDB.stazione_id == stazione_id)
    if categoria is not None:
        domanda = domanda.where(OggettoDB.categoria == categoria)
    if giorno is not None:
        domanda = domanda.where(OggettoDB.trovato_il == giorno)
    return db.scalars(domanda).all()

È la rotta del livello 2, con tre if in più. Il pezzo più piccolo, se ti blocchi: un filtro solo, poi gli altri due.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
elif al posto dei due if successivi al primoFunziona con un filtro solo. Con due o tre, vale solo il primo: [6, 3, 1] invece di [1]test_livello_3_due_filtri_insieme, test_livello_3_tre_filtri_insieme, test_livello_3_nessun_risultato_e_una_lista_vuota
niente order_byNessun errore, ma gli oggetti escono nell'ordine di scrittura: il più recente non è il primotest_livello_2_dal_piu_recente, test_livello_2_non_mostra_il_segno_particolare, test_livello_3_per_stazione

Livello 4 · La scheda

In italiano. GET /oggetti/{oggetto_id}: un oggetto solo, dal suo id. Se non c'è, 404. È lo stesso db.get della palestra. La scheda c'è anche per un oggetto già restituito (stato «restituito»): è la sua storia.

Python
@router.get("/{oggetto_id}")
def scheda_oggetto(oggetto_id: int, db: Session = Depends(get_db)) -> Oggetto:
    oggetto = db.get(OggettoDB, oggetto_id)
    if oggetto is None:
        raise HTTPException(status_code=404, detail="Oggetto non trovato")
    return oggetto

(HTTPException va aggiunto all'import di fastapi.) Lo stampo di risposta è lo stesso Oggetto del livello 2: senza il segno particolare.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
niente if oggetto is Nonedb.get dà None, la rotta lo restituisce: ResponseValidationError … Input should be a valid dictionary or object to extract fields from, 500 invece del 404test_livello_4_un_oggetto_che_non_c_e_da_404

Livello 5 · Registro un oggetto

In italiano. POST /oggetti. Le quattro mosse di sempre (l'oggetto, add, commit, refresh), con tre cose in più.

  1. Il controllo della stazione. Se stazione_id non esiste, 422: la richiesta ha un valore che non si può usare. Si controlla prima di scrivere, con db.get(StazioneDB, …).
  2. Il valore finto. registrato_da è NOT NULL, ma il login non c'è: ci va 1, Nives. Lo metti in una costante, in un file solo.
  3. La risposta. È lo stampo pubblico Oggetto: con l'id e lo stato, senza il segno particolare (che è stato salvato, ma non esce).
Python
# app/finti.py (file nuovo)
"""I valori finti: quello che il login, un giorno, sostituirà. Si cercano con: grep -rn FINTO app/"""

ADDETTO_FINTO = 1  # FINTO: l'addetto che ha fatto il login. Per ora è sempre Nives, la numero 1.
Python
# app/rotte/oggetti.py
from app.finti import ADDETTO_FINTO
from app.modelli import OggettoDB, StazioneDB
from app.schemi import Categoria, Oggetto, OggettoNuovo


@router.post("", status_code=status.HTTP_201_CREATED)
def registra_oggetto(dati: OggettoNuovo, db: Session = Depends(get_db)) -> Oggetto:
    if db.get(StazioneDB, dati.stazione_id) is None:
        raise HTTPException(status_code=422, detail="La stazione non esiste")
    oggetto = OggettoDB(**dati.model_dump(), registrato_da=ADDETTO_FINTO)
    db.add(oggetto)
    db.commit()
    db.refresh(oggetto)
    return oggetto

OggettoDB(**dati.model_dump(), …): model_dump() dà un dizionario con i nomi dello stampo, che sono gli stessi delle colonne, e i ** lo aprono in argomenti con nome. Equivale a scriverli uno per uno (descrizione=dati.descrizione, …), ma se un giorno aggiungi una colonna, il codice non cambia. stato non lo scrivi: lo fa il DEFAULT del database.

Il commit del livello 5 è anche quello che chiude il valore finto: grep -rn FINTO app/ trova il file dei valori finti e ogni punto dove si usano.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
niente db.commit()InvalidRequestError: Instance '<OggettoDB at 0x…>' is not persistent within this Sessioncinque: test_livello_5_registro_un_oggetto_201_con_l_id, _l_oggetto_e_nel_database, _chi_l_ha_registrato_e_il_valore_finto, _il_colore_e_il_segno_sono_facoltativi, _il_nuovo_oggetto_compare_nell_elenco
niente registrato_da=…Il database dice no: IntegrityError: (psycopg.errors.NotNullViolation) null value in column "registrato_da" of relation "oggetti" violates not-null constraintgli stessi cinque
niente controllo della stazioneIntegrityError: (psycopg.errors.ForeignKeyViolation) … Key (stazione_id)=(9) is not present in table "stazioni": 500, invece del 422test_livello_5_una_stazione_che_non_c_e_da_422_e_non_scrive

Livello 6 · Restituisco

In italiano. POST /oggetti/{oggetto_id}/restituzioni. È la rotta che scrive in due tabelle: crea la riga in restituzioni e cambia lo stato dell'oggetto in «restituito». Le due scritture vanno insieme: un commit solo, in fondo.

  1. Gli stampi. RestituzioneNuova (il corpo: nome e ultime quattro cifre) e Restituzione (la risposta, con l'id, la data e l'addetto), in schemi.py.
  2. L'oggetto c'è? Se no, 404.
  3. È in deposito? Se no (già restituito, o donato), 409.
  4. Le due scritture, e un commit.
Python
# app/schemi.py (in fondo; Field va aggiunto all'import di pydantic)
class RestituzioneNuova(BaseModel):
    nome_passeggero: str = Field(min_length=1)
    documento_finale: str = Field(min_length=4, max_length=4)


class Restituzione(BaseModel):
    model_config = ConfigDict(from_attributes=True)

    id: int
    oggetto_id: int
    nome_passeggero: str
    documento_finale: str
    restituito_il: date
    addetto_id: int
Python
# app/rotte/restituzioni.py (file nuovo)
from datetime import date

from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.orm import Session

from app.database import get_db
from app.finti import ADDETTO_FINTO
from app.modelli import OggettoDB, RestituzioneDB
from app.schemi import Restituzione, RestituzioneNuova

router = APIRouter(prefix="/oggetti", tags=["restituzioni"])


@router.post(
    "/{oggetto_id}/restituzioni",
    status_code=status.HTTP_201_CREATED,
    responses={409: {"description": "L'oggetto non è in deposito"}},
)
def restituisci_oggetto(oggetto_id: int, dati: RestituzioneNuova, db: Session = Depends(get_db)) -> Restituzione:
    oggetto = db.get(OggettoDB, oggetto_id)
    if oggetto is None:
        raise HTTPException(status_code=404, detail="Oggetto non trovato")
    if oggetto.stato != "in deposito":
        raise HTTPException(status_code=409, detail="L'oggetto non è in deposito")

    restituzione = RestituzioneDB(
        oggetto_id=oggetto_id,
        nome_passeggero=dati.nome_passeggero,
        documento_finale=dati.documento_finale,
        restituito_il=date.today(),
        addetto_id=ADDETTO_FINTO,
    )
    oggetto.stato = "restituito"
    db.add(restituzione)
    db.commit()  # un commit solo: o vanno a buon fine tutte e due le scritture, o nessuna
    db.refresh(restituzione)
    return restituzione

E in app/main.py: app.include_router(restituzioni.router).

Passo per passo. oggetto.stato = "restituito" non scrive niente da sola: cambia l'attributo dell'oggetto, che la sessione sta già seguendo (l'ha caricato db.get). Il db.commit() finale manda al database tutte e due le modifiche, in una transazione: un UPDATE sull'oggetto e un INSERT in restituzioni. Se una delle due fallisce, nessuna delle due resta.

Richiestadb.getoggetto.statoCosa risponde
POST /oggetti/1/restituzionil'oggetto 1"in deposito"scrive tutte e due, 201
POST /oggetti/5/restituzionil'oggetto 5"restituito"409
POST /oggetti/7/restituzionil'oggetto 7"donato"409
POST /oggetti/99/restituzioniNone(non ci arriva)404

Il 409 sull'oggetto già restituito ha un secondo motivo: oggetto_id è UNIQUE in restituzioni, quindi anche senza il controllo il database direbbe no. Il controllo serve per rispondere bene.

Le trappole.

Il codice sbagliatoCosa succedeIl test rosso
niente oggetto.stato = "restituito"La restituzione viene scritta, ma l'oggetto resta «in deposito»: continua a comparire nell'elenco, e si può restituire due voltetest_livello_6_lo_stato_dell_oggetto_diventa_restituito, test_livello_6_l_oggetto_restituito_sparisce_dall_elenco, test_livello_6_restituirlo_due_volte_la_seconda_da_409
niente controllo oggetto.stato != "in deposito"Il database dice no da solo: IntegrityError: (psycopg.errors.UniqueViolation) duplicate key value violates unique constraint "restituzioni_oggetto_id_key". 500 invece di 409i tre test del 409
niente if oggetto is NoneAttributeError: 'NoneType' object has no attribute 'stato': 500 invece del 404test_livello_6_un_oggetto_che_non_c_e_da_404
niente db.commit()InvalidRequestError: Instance '<RestituzioneDB at 0x…>' is not persistent within this Sessioncinque test, tra cui test_livello_6_restituisco_un_oggetto_201

Un errore che non rompe niente. Due commit al posto di uno (uno dopo la restituzione, uno dopo lo stato) fa passare tutti i test. Ma se il secondo fallisce, la restituzione è già scritta e l'oggetto resta «in deposito»: i dati sono incoerenti, e nessun test lo vede. È il motivo per cui le due scritture hanno un commit solo.

Il finale

Il ragionamento. La signora cerca una borsa di tela, nera, trovata domenica 8 novembre. I filtri della tua API conoscono la categoria e il giorno, non il colore né il materiale: quelli li leggi tu, dalla risposta.

Prima di qualunque ritocco, a quel giorno ci sono tre borse in deposito:

$ curl -s "http://127.0.0.1:8000/oggetti?categoria=borse&giorno=2026-11-08"
[{"id":10,"descrizione":"borsa a tracolla in pelle","categoria":"borse","colore":"nera","stazione_id":5,"trovato_il":"2026-11-08","stato":"in deposito"},{"id":11,"descrizione":"borsa di tela","categoria":"borse","colore":"nera","stazione_id":2,"trovato_il":"2026-11-08","stato":"in deposito"},{"id":12,"descrizione":"borsa di tela","categoria":"borse","colore":"verde","stazione_id":3,"trovato_il":"2026-11-08","stato":"in deposito"}]

La numero 10 è di pelle, la 12 è verde: resta la 11, a Piazza Query (stazione_id 2). Se rispondi con quella, Nives ti ferma:

$ python ../verifica.py "Piazza Query"
Nives scuote la testa: «No, non è lì.»
Quella borsa l'ha già ritirata un signore, stamattina. Guarda il livello 6: dopo la restituzione, nell'elenco c'è ancora?

Dopo il livello 5, a Vecchia Fiera (stazione_id 4) c'è una borsa di tela nera in più, quella di Tullio:

{"id":25,"descrizione":"borsa di tela","categoria":"borse","colore":"nera","stazione_id":4,"trovato_il":"2026-11-08","stato":"in deposito"}

Dopo il livello 6, la numero 11 viene restituita a Corrado Bassi e sparisce dall'elenco: non è più in deposito. Quello che resta, per quel giorno:

$ curl -s "http://127.0.0.1:8000/oggetti?categoria=borse&giorno=2026-11-08"
[{"id":10,"descrizione":"borsa a tracolla in pelle","categoria":"borse","colore":"nera","stazione_id":5,"trovato_il":"2026-11-08","stato":"in deposito"},{"id":12,"descrizione":"borsa di tela","categoria":"borse","colore":"verde","stazione_id":3,"trovato_il":"2026-11-08","stato":"in deposito"},{"id":25,"descrizione":"borsa di tela","categoria":"borse","colore":"nera","stazione_id":4,"trovato_il":"2026-11-08","stato":"in deposito"}]

Di tela e nera, una sola: la 25, stazione_id 4. Il numero 4 lo traduci con GET /stazioni:

$ curl -s http://127.0.0.1:8000/stazioni
[{"id":3,"nome":"Largo Lista"},{"id":2,"nome":"Piazza Query"},{"id":5,"nome":"Ponte Ciclo"},{"id":1,"nome":"Porta Codice"},{"id":4,"nome":"Vecchia Fiera"}]

È Vecchia Fiera.

$ python ../verifica.py "Vecchia Fiera"
Nives Corti alza gli occhi dal registro e sorride, per la prima volta in tutta la mattina.
«Cerniera rotta, sì. Chiamo la signora Lombardi prima che chiuda l'ufficio.
E questa volta non ho dovuto cercare a memoria.»

Oggetto ritrovato.

Le altre due risposte sbagliate più probabili:

  • Ponte Ciclo (la borsa 10): «la signora ha parlato di tela. Quella borsa com'è?». È una borsa di pelle.
  • Largo Lista (la borsa 13, nera e di tela, ma del 9 novembre): «Una borsa di tela nera, a Largo Lista, c'è: ma è stata trovata il 9 novembre. La signora ha detto domenica 8.». Se rispondi così, hai cercato senza il filtro del giorno.

Ogni risposta sbagliata, nella storia, è un livello saltato o un filtro dimenticato.