Vai al contenuto
code-to-code

Apro l'indice…

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

Il progetto4. La cartella del progettop. 125

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.

progetto-la-cartella-del-progetto-soluzioni.zip15 KB

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
httpx

Le 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
pytest

Diventano 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
httpx

Diventano 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/
.env

Le 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/
.env

Diventano 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_sala

Le 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_sala

Diventano 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.

Python
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.

  1. FastAPI(title="Prenota-sala") crea l'app. Il titolo compare in /docs.
  2. @app.get("/salute") dice «le richieste GET a /salute vanno a questa funzione».
  3. La funzione restituisce {"stato": "ok"}: FastAPI lo trasforma in JSON e risponde 200.
  4. -> 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.

Python
@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à.

Python
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 db

Passo per passo.

  1. load_dotenv() legge il .env e mette le sue righe tra le variabili d'ambiente. Se una variabile c'è già, non la tocca.
  2. os.environ.get("DATABASE_URL", "…") legge la variabile. Se manca, vale il valore di riserva: il database di Prenota-sala sul tuo computer.
  3. create_engine non si collega subito: aspetta la prima richiesta.
  4. get_db usa with Session(engine) as db: e yield db. Il with chiude 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.

Python
# 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.

Python
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.

Python
def get_db():
    db = Session(engine)
    yield db

Diventano 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.

Python
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.

  1. sale: nome è UNIQUE (unique=True), note è l'unica facoltativa (str | None), piano e posti hanno un CHECK che resta un commento.
  2. proiettore ha un DEFAULT: server_default="false" dice a SQLAlchemy «questa colonna la riempie il database».
  3. prenotazioni: sala_id è una chiave esterna (ForeignKey("sale.id")), dentro le virgolette tabella.colonna.
  4. inizio e fine sono TIMESTAMP in SQL, datetime in Python.
  5. 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.

Python
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.

Python
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.

Python
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.

Python
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)).

Python
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: int

Passo per passo.

  1. Piano = Literal[...] è un nome per la lista di tre parole: lo si può riusare dove serve.
  2. proiettore: bool = False e note: str | None = None: chi chiama può non scriverli.
  3. class Sala(SalaNuova) eredita i cinque campi.
  4. from_attributes=True fa leggere lo stampo da un oggetto SalaDB, 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.

Python
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.

Python
class Sala(SalaNuova):
    id: int

Diventano 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.

Python
posti: int

Diventano 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.

Python
from fastapi import APIRouter

from app.schemi import Sala

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


@router.get("")
def elenco_sale() -> list[Sala]:
    return []  # il segnaposto

In main.py, le due righe nuove sono quelle già viste:

Python
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.

Python
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.

Python
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.