Vai al contenuto
code-to-code

Apro l'indice…

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

Il progetto4. La cartella del progettop. 119

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.

progetto-la-cartella-del-progetto.zip17 KB

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:

Terminale
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:

  1. Apri il file dell'esercizio. In alto, nei commenti: la storia, cosa fai, come provi.
  2. Scrivi quello che chiede, nel punto che indica.
  3. Lancia il suo test: pytest tests/test_requirements.py -v, oppure la provetta di VS Code.
  4. 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.

#FileCosa devi saper fareDifficoltà
1requirements.txtla lista della spesa, con gli extra★
2.gitignorecosa Git non deve vedere★
3.env.exampleil modello del .env★
4app/main.pyl'app e la rotta /salute★
5app/database.pyla variabile d'ambiente, l'engine, la sessione★★
6app/modelli.pyda schema.sql alle classi★★★
7app/schemi.pylo stampo nuovo e la risposta★★
8app/rotte/sale.pyil 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
Una libreria per riga. Gli extra si scrivono attaccati al nome, tra parentesi quadre: li hai visti nella teoria.
Aiutino 2
Gli extra servono a due sole righe: fastapi e psycopg. Le altre quattro sono nomi semplici.
Aiutino 3
Il test dice «Manca httpx»? Controlla di averlo scritto con quel nome, tutto minuscolo, senza spazi. Una riga che comincia con # 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
Quattro righe. Le cartelle si scrivono con la barra in fondo: .venv/.
Aiutino 2
Il file è .env, il modello è .env.example: due nomi quasi uguali. Un modello come .env* li nasconde tutti e due.
Aiutino 3
Rosso su .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
Una riga, nella forma NOME=valore, senza spazi attorno all'uguale e senza virgolette.
Aiutino 2
Il valore comincia come l'indirizzo che hai visto: postgresql+psycopg:///, e subito dopo il nome del database.
Aiutino 3
Il test rifiuta una @ 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
Due cose in poche righe: app = FastAPI(title=...), e sotto una funzione con @app.get("/salute").
Aiutino 2
La funzione restituisce un dizionario con una chiave sola, stato, e il valore "ok". Il codice di risposta, 200, lo dà FastAPI da solo.
Aiutino 3
Il test del titolo vuole esattamente 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
Apri schema.sql accanto a modelli.py. Una colonna, una riga, nello stesso ordine: ogni test lo controlla.
Aiutino 2
Obbligatoria: solo il tipo (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
Una colonna ha un 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
Se il test dice «Input should be a valid dictionary or instance of Sala», manca 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
Il router è una riga sola, in 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.