La cartella del progetto
Lo scheletro vuoto, un file alla volta
- 20 minuti di lettura
Nives Corti tiene l'ufficio oggetti smarriti di Porta Codice. Ha un canvas, le entità e uno schema.sql. Ha un computer acceso. E davanti, una cartella vuota.
«Dove li metto, tutti questi pezzi?»
Questo capitolo risponde: la cartella di Ritrovato, file per file, e l'ordine in cui si crea. Ogni passo ha il suo comando e la sua prova. Alla fine hai uno scheletro vuoto: /salute risponde, il database è collegato, le tabelle sono scritte in Python. Rotte vere ancora nessuna. Quelle arrivano nel capitolo Un pezzo alla volta.
Qui non c'è niente di nuovo da imparare in FastAPI o in SQLAlchemy: li conosci dal libro Il database nell'API. Il lavoro nuovo è un altro: metterli in una cartella che regge. Ti servono il venv, PostgreSQL acceso e Git.
La cartella, intera
Questa è la cartella di Ritrovato a fine capitolo. Tutta insieme, una volta. Poi la costruiamo un pezzo per volta.
ritrovato/
├── CANVAS.md
├── README.md
├── schema.sql
├── requirements.txt
├── pytest.ini
├── .gitignore
├── .env
├── .env.example
├── app/
│ ├── __init__.py
│ ├── main.py
│ ├── database.py
│ ├── modelli.py
│ ├── schemi.py
│ └── rotte/
│ ├── __init__.py
│ └── oggetti.py
└── tests/
├── conftest.py
└── test_salute.pyE a cosa serve ogni file, in una riga.
| File | A cosa serve |
|---|---|
CANVAS.md | Il canvas del capitolo 1: l'app in una pagina. Chi apre la cartella capisce cos'è |
README.md | Come si avvia, in cinque righe |
schema.sql | Le tabelle. La fonte vera: se c'è un dubbio, comanda lui |
requirements.txt | La lista delle librerie. Chi scarica il progetto le installa con un comando |
pytest.ini | Dice a pytest dove sono i test e dove trovare app/ |
.gitignore | I file che Git non deve vedere |
.env | Le impostazioni tue, come l'indirizzo del database. Mai su GitHub |
.env.example | Le stesse righe, senza segreti: il modello. Questo sì, su GitHub |
app/__init__.py | Vuoto. Dice a Python che app è un pacchetto |
app/main.py | La porta d'ingresso: crea l'app, ha GET /salute, monta i router |
app/database.py | Il collegamento: DATABASE_URL, engine, Base, get_db |
app/modelli.py | Le tabelle viste da Python: una classe XxxDB per tabella |
app/schemi.py | Gli stampi di Pydantic: cosa entra e cosa esce dall'API |
app/rotte/oggetti.py | Le rotte degli oggetti, in un APIRouter. Una cosa, un file |
tests/conftest.py | Prepara il database dei test e dà il finto browser |
tests/test_salute.py | Il primo test |
L'ordine in cui si crea
Un passo, un comando, una prova. Se la prova non dà il risultato giusto, non vai avanti: il guaio che trovi al passo 7 quasi sempre è nato al passo 4.
1 · Git
Prima di tutto la cartella diventa un repository. Così ogni passo dopo si può salvare, e disfare.
cd ritrovato
git init -b main
git statusInitialized empty Git repository in ~/ritrovato/.git/
On branch main
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
CANVAS.md
schema.sql
nothing added to commit but untracked files present (use "git add" to track)La prova: git status vede i tuoi due file. Come si usa Git, passo per passo, è nel libro Git.
2 · Il venv
python3 -m venv .venv
source .venv/bin/activate
which python~/ritrovato/.venv/bin/pythonLa prova: which python dice un percorso dentro ritrovato/.venv. Se dice un altro percorso, il venv non è acceso e le librerie finirebbero nel Python di tutto il computer. Ogni terminale nuovo parte spento: source .venv/bin/activate, dalla cartella del progetto.
3 · requirements.txt
Il file è la lista della spesa: una libreria per riga, i nomi e basta.
fastapi[standard]
sqlalchemy
psycopg[binary]
python-dotenv
pytest
httpxLe parentesi quadre sono gli «extra»: fastapi[standard] porta anche il comando fastapi dev; psycopg[binary] porta il motore già pronto. httpx serve al finto browser dei test.
pip install -r requirements.txt
pip show fastapi sqlalchemy psycopg | grep -E "^(Name|Version)"Name: fastapi
Version: 0.165.0
Name: SQLAlchemy
Version: 2.1.9
Name: psycopg
Version: 3.3.9pip install scrive molte righe: ci vuole qualche minuto. La prova: pip show trova le librerie, con un numero di versione (il tuo può essere più recente).
4 · .gitignore
Non tutto va su GitHub. Il .gitignore è l'elenco di quello che Git deve far finta di non vedere.
.venv/
__pycache__/
.pytest_cache/
.env| Riga | Cosa nasconde | Perché |
|---|---|---|
.venv/ | Le librerie installate | Pesano centinaia di megabyte, e le rifà pip install |
__pycache__/ | I file che Python scrive da solo | Sono avanzi: li rifà Python |
.pytest_cache/ | La memoria di pytest | Stessa cosa |
.env | Le tue impostazioni | Possono contenere una password |
Prova a prevedere: prima di aprire, prova tu: git status --short con e senza il .gitignore. Cosa cambia?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Senza .gitignore, Git vede anche la cartella delle librerie. Con .gitignore, sparisce.
?? .venv/
?? CANVAS.md
?? requirements.txt
?? schema.sqlCon il .gitignore scritto:
?? .gitignore
?? CANVAS.md
?? requirements.txt
?? schema.sqlIl .venv/ non c'è più, e compare .gitignore: è un file del progetto, e va su GitHub anche lui.
La prova: git status --short non nomina più .venv/.
5 · .env e .env.example
Due file con le stesse righe e due destini diversi.
cat .env.example
cp .env.example .env
git status --short
git check-ignore -v .envDATABASE_URL=postgresql+psycopg:///ritrovato
?? .env.example
?? .gitignore
?? CANVAS.md
?? requirements.txt
?? schema.sql
.gitignore:4:.env .envLa riga DATABASE_URL=… è l'indirizzo del database, nello stesso modo di postgresql+psycopg:///… del libro sul database: nessun utente e nessuna password, perché PostgreSQL sul tuo computer si fida di te.
La prova: .env.example compare nell'elenco di Git (va su GitHub), .env no, e git check-ignore -v dice quale riga del .gitignore lo nasconde.
Perché due file, se oggi sono uguali? Il .env.example dice a chi scarica il progetto quali righe deve scrivere nel suo .env. Più avanti il tuo .env avrà dentro una chiave segreta, come nel capitolo sul login, e quello vero non deve mai partire. Il modello sì, con valori finti.
6 · app/main.py, e GET /salute
Nasce il pacchetto app/, con il suo __init__.py vuoto, e dentro la porta d'ingresso.
mkdir app
touch app/__init__.pyfrom fastapi import FastAPI
app = FastAPI(title="Ritrovato")
@app.get("/salute")
def salute() -> dict[str, str]:
return {"stato": "ok"}/salute è una rotta che non fa niente di utile: risponde «ci sono». Chi mette online un'app, e domani chiunque ci voglia controllare, la chiama per sapere se è viva. Per te è la prima prova che tutta la catena funziona.
fastapi dev app/main.pyIl server si accende (il terminale resta occupato: per fermarlo, Ctrl+C). In un secondo terminale, o nel browser, http://127.0.0.1:8000/salute:
curl -s http://127.0.0.1:8000/salute{"stato":"ok"}La prova: la risposta è {"stato":"ok"}, e /docs mostra una rotta sola.
7 · pytest.ini e il primo test
Il test è un altro modo di fare la stessa domanda, ma lo fa il computer, ogni volta, in un secondo.
mkdir testsfrom fastapi.testclient import TestClient
from app.main import app
client = TestClient(app)
def test_salute():
risposta = client.get("/salute")
assert risposta.status_code == 200
assert risposta.json() == {"stato": "ok"}È il file tests/test_salute.py. Lancia pytest, prima senza pytest.ini:
tests/test_salute.py:3: in <module>
from app.main import app
E ModuleNotFoundError: No module named 'app'
=========================== short test summary info ============================
ERROR tests/test_salute.py
!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!
=============================== 1 error in 0.16s ===============================Il test è dentro tests/, e da lì pytest non vede la cartella app/, che sta un piano sopra. Il pytest.ini glielo dice:
[pytest]
pythonpath = .
testpaths = testspythonpath = . vuol dire «aggiungi questa cartella ai posti dove Python cerca i pacchetti». Così app si trova, e from app.main import app funziona da qualunque punto. testpaths = tests dice dove cercare i test.
pytest============================= test session starts ==============================
platform darwin -- Python 3.12.13, pytest-9.2.0, pluggy-1.7.0
rootdir: ~/ritrovato
configfile: pytest.ini
testpaths: tests
plugins: anyio-4.16.0
collected 1 item
tests/test_salute.py . [100%]
============================== 1 passed in 0.13s ===============================La prova: un punto, 1 passed. È il primo test verde del progetto: da qui in poi, ogni cosa che aggiungi la proteggi con un test.
8 · database.py
Prima il database vero. Se non l'hai ancora creato:
createdb ritrovato
psql -d ritrovato -f schema.sqlCREATE TABLE
CREATE TABLE
CREATE TABLE
CREATE TABLEQuattro CREATE TABLE: stazioni, addetti, oggetti, restituzioni. Poi app/database.py, che è quello del libro sul database, con una differenza: l'indirizzo non è scritto nel codice.
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:///ritrovato")
engine = create_engine(DATABASE_URL)
class Base(DeclarativeBase):
pass
def get_db():
with Session(engine) as db:
yield dbUna riga alla volta, le nuove:
load_dotenv()legge il file.enve mette le sue righe tra le variabili d'ambiente.os.environ.get("DATABASE_URL", "…")legge la variabile; se non c'è, vale il secondo valore.Base,engineeget_dbsono quelli di sempre: la madre delle tabelle, la strada verso PostgreSQL, la sessione prestata a ogni rotta.
Perché una variabile e non l'indirizzo scritto? Lo stesso codice deve girare sul tuo computer, sul computer di un compagno, nei test e un giorno online: cambia l'indirizzo, non il codice. Lo cambi nel .env.
python -c "
from sqlalchemy import text
from app.database import DATABASE_URL, engine
print(DATABASE_URL)
with engine.connect() as conn:
print(conn.execute(text('SELECT current_database()')).scalar())
"postgresql+psycopg:///ritrovato
ritrovatoLa prova: Python parla con PostgreSQL e il database si chiama ritrovato.
9 · tests/conftest.py: i test non toccano il tuo database
C'è un problema. Se un test scrive nel database, scrive nel tuo: i tuoi dati di prova spariscono, e il test dipende da quello che c'era prima. La soluzione è già nel libro sui test con il database: i test usano un altro database, ritrovato_test, che si rifà da zero prima di ogni test.
import os
from pathlib import Path
import psycopg
import pytest
from fastapi.testclient import TestClient
from psycopg import sql as pezzi_di_sql
NOME_DB_TEST = "ritrovato_test"
os.environ["DATABASE_URL"] = f"postgresql+psycopg:///{NOME_DB_TEST}" # prima di importare l'app!
from app.main import app # noqa: E402 (l'import sta dopo la riga sopra, di proposito)
SCHEMA = Path(__file__).parent.parent / "schema.sql"
@pytest.fixture(scope="session", autouse=True)
def database_dei_test():
"""Una volta sola: se il database dei test non c'è, lo crea."""
with psycopg.connect(dbname="postgres", autocommit=True) as conn:
esiste = conn.execute("SELECT 1 FROM pg_database WHERE datname = %s", (NOME_DB_TEST,)).fetchone()
if esiste is None:
conn.execute(pezzi_di_sql.SQL("CREATE DATABASE {}").format(pezzi_di_sql.Identifier(NOME_DB_TEST)))
@pytest.fixture(autouse=True)
def tabelle_come_nuove(database_dei_test):
"""Prima di ogni test: le tabelle si buttano e si rifanno da schema.sql."""
with psycopg.connect(dbname=NOME_DB_TEST) as conn:
conn.execute("DROP SCHEMA public CASCADE")
conn.execute("CREATE SCHEMA public")
conn.execute(SCHEMA.read_text(encoding="utf-8"))
@pytest.fixture
def client():
return TestClient(app)Tre cose, tre fixture:
- Il database dei test: se non c'è, lo crea.
- Le tabelle come nuove: prima di ogni test le butta e le rifà da
schema.sql. Per questoschema.sqlè la fonte vera: lo usano anche i test. - Il client: il finto browser. Prima lo creava il file del test; ora lo presta il
conftest.pya ogni test che lo chiede.
Il punto delicato è la riga con os.environ: sta prima dell'import dell'app. load_dotenv() non sovrascrive una variabile che c'è già: se DATABASE_URL è già nell'ambiente quando database.py parte, il .env non conta. Ecco perché i test non toccano il tuo database, anche se il .env punta a quello.
Prima di aprire, prova tu: se l'ordine fosse l'opposto (prima l'import dell'app, poi la riga os.environ), quale indirizzo vedrebbe database.py?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Quello del .env: il tuo database vero. L'import ha già letto il .env, e cambiare la variabile dopo non serve più: i test scriverebbero nei tuoi dati. L'ordine delle due righe è tutto. Negli esercizi spiegati lo vedi con i comandi.
Il test si riscrive con il client prestato, e prende due compagni: uno che controlla il database dei test, uno che controllerà il router (lo scriviamo al passo 12).
from sqlalchemy import text
from app.database import engine
def test_salute(client):
risposta = client.get("/salute")
assert risposta.status_code == 200
assert risposta.json() == {"stato": "ok"}
def test_il_database_dei_test_e_collegato():
with engine.connect() as conn:
assert conn.execute(text("SELECT current_database()")).scalar() == "ritrovato_test"
assert conn.execute(text("SELECT count(*) FROM oggetti")).scalar() == 0Mettiamo un dato nel tuo database, e lanciamo i test:
psql -d ritrovato -c "INSERT INTO stazioni (nome) VALUES ('Porta Codice')"
pytest -v
psql -d ritrovato -c "SELECT * FROM stazioni"INSERT 0 1
============================= test session starts ==============================
platform darwin -- Python 3.12.13, pytest-9.2.0, pluggy-1.7.0 -- ~/ritrovato/.venv/bin/python3
cachedir: .pytest_cache
rootdir: ~/ritrovato
configfile: pytest.ini
testpaths: tests
plugins: anyio-4.16.0
collecting ... collected 2 items
tests/test_salute.py::test_salute PASSED [ 50%]
tests/test_salute.py::test_il_database_dei_test_e_collegato PASSED [100%]
============================== 2 passed in 0.21s ===============================
id | nome
----+--------------
1 | Porta Codice
(1 row)La prova: due test verdi, e la stazione di Porta Codice nel tuo database c'è ancora. Nel database dei test, invece, oggetti è vuota: lo dice il secondo test, e prova che schema.sql è stato caricato.
10 · modelli.py: schema.sql, riga per riga
Ora le tabelle diventano classi. modelli.py ricopia schema.sql, riga per riga, con il commento SQL accanto, come nel libro sul database. Niente Base.metadata.create_all: le tabelle le crea schema.sql, e Python si limita a descriverle.
"""Le tabelle di Ritrovato, viste da Python. Ricopiano schema.sql, riga per riga.
Se cambi una tabella, cambi prima schema.sql, poi questo file. Comanda sempre schema.sql.
Il nome finisce con DB, per non confonderle con gli stampi di Pydantic (schemi.py).
"""
from datetime import date
from sqlalchemy import ForeignKey
from sqlalchemy.orm import Mapped, mapped_column
from app.database import Base
class StazioneDB(Base):
__tablename__ = "stazioni" # CREATE TABLE stazioni
id: Mapped[int] = mapped_column(primary_key=True) # id SERIAL PRIMARY KEY
nome: Mapped[str] = mapped_column(unique=True) # nome TEXT NOT NULL UNIQUE
class AddettoDB(Base):
__tablename__ = "addetti" # CREATE TABLE addetti
id: Mapped[int] = mapped_column(primary_key=True) # id SERIAL PRIMARY KEY
nome: Mapped[str] # nome TEXT NOT NULL
email: Mapped[str] = mapped_column(unique=True) # email TEXT NOT NULL UNIQUE
password_hash: Mapped[str] # password_hash TEXT NOT NULL
class OggettoDB(Base):
__tablename__ = "oggetti" # CREATE TABLE oggetti
id: Mapped[int] = mapped_column(primary_key=True) # id SERIAL PRIMARY KEY
descrizione: Mapped[str] # descrizione TEXT NOT NULL
categoria: Mapped[str] # categoria TEXT NOT NULL CHECK (categoria IN (...))
colore: Mapped[str | None] # colore TEXT
segno_particolare: Mapped[str | None] # segno_particolare TEXT
stazione_id: Mapped[int] = mapped_column(ForeignKey("stazioni.id"))
# # stazione_id INTEGER NOT NULL REFERENCES stazioni(id)
trovato_il: Mapped[date] # trovato_il DATE NOT NULL
stato: Mapped[str] = mapped_column(server_default="in deposito")
# # stato TEXT NOT NULL DEFAULT 'in deposito' CHECK (...)
# # server_default: lo scrive il database, non Python
registrato_da: Mapped[int] = mapped_column(ForeignKey("addetti.id"))
# # registrato_da INTEGER NOT NULL REFERENCES addetti(id)
class RestituzioneDB(Base):
__tablename__ = "restituzioni" # CREATE TABLE restituzioni
id: Mapped[int] = mapped_column(primary_key=True) # id SERIAL PRIMARY KEY
oggetto_id: Mapped[int] = mapped_column(ForeignKey("oggetti.id"), unique=True)
# # oggetto_id INTEGER NOT NULL UNIQUE REFERENCES oggetti(id)
nome_passeggero: Mapped[str] # nome_passeggero TEXT NOT NULL
documento_finale: Mapped[str] # documento_finale TEXT NOT NULL CHECK (length(...) = 4)
restituito_il: Mapped[date] # restituito_il DATE NOT NULL
addetto_id: Mapped[int] = mapped_column(ForeignKey("addetti.id"))
# # addetto_id INTEGER NOT NULL REFERENCES addetti(id)Come si traduce una riga, e cosa non si traduce, è nella tabella qui sotto. Una sola riga merita due parole: stato. Ha un DEFAULT nel SQL, e SQLAlchemy non lo sa: se non gli dici niente, manda NULL, e il database rifiuta (la colonna è NOT NULL). server_default gli dice «questa colonna la riempie il database: tu non mandarla».
python -c "
from app.modelli import OggettoDB
print(list(OggettoDB.__table__.columns.keys()))
print(OggettoDB.__table__.c.colore.nullable, OggettoDB.__table__.c.stato.nullable)
"['id', 'descrizione', 'categoria', 'colore', 'segno_particolare', 'stazione_id', 'trovato_il', 'stato', 'registrato_da']
True FalseLa prova: le nove colonne di oggetti, nell'ordine di schema.sql, e colore facoltativa (True), stato no (False).
11 · schemi.py: cosa entra, cosa esce
Gli stampi di Pydantic non sono le tabelle: sono il contratto con chi chiama l'API. Ne bastano due, come nel libro sul database.
"""Gli stampi di Pydantic: cosa entra e cosa esce dall'API. Non sono le tabelle (modelli.py)."""
from datetime import date
from typing import Literal
from pydantic import BaseModel, ConfigDict
Categoria = Literal["ombrelli", "borse", "telefoni", "chiavi", "abbigliamento", "altro"]
Stato = Literal["in deposito", "restituito", "donato"]
class OggettoNuovo(BaseModel):
"""Il corpo del POST: quello che scrive l'addetto. Niente id, niente stato: li decide il database."""
descrizione: str
categoria: Categoria
colore: str | None = None
segno_particolare: str | None = None
stazione_id: int
trovato_il: date
class Oggetto(BaseModel):
"""La risposta pubblica. Il segno particolare non c'è: lo vede solo l'addetto."""
model_config = ConfigDict(from_attributes=True)
id: int
descrizione: str
categoria: Categoria
colore: str | None
stazione_id: int
trovato_il: date
stato: StatoGuarda cosa non c'è, e perché:
OggettoNuovonon haid(lo dà il database), néstato(parte da «in deposito»), néregistrato_da(non lo scrive chi chiama: lo scrive il login, più avanti).Oggettonon hasegno_particolaree non haregistrato_da. Quello che non è nello stampo della risposta non esce mai dall'API, nemmeno per sbaglio: il segno particolare serve a Nives per capire se chi chiede l'oggetto è davvero il proprietario, e nessun passeggero deve poterlo leggere.
Un foglio di prova, prova.py, nella cartella del progetto (poi lo cancelli):
from datetime import date
from pydantic import ValidationError
from app.modelli import OggettoDB
from app.schemi import Oggetto, OggettoNuovo
nuovo = OggettoNuovo(descrizione="Ombrello nero", categoria="ombrelli", stazione_id=3, trovato_il="2026-11-02")
print(nuovo)
try:
OggettoNuovo(descrizione="Una bici", categoria="biciclette", stazione_id=3, trovato_il="2026-11-02")
except ValidationError as e:
print(e)
riga = OggettoDB(
id=7, descrizione="Ombrello nero", categoria="ombrelli", colore="nero", segno_particolare="manico con nastro rosso",
stazione_id=3, trovato_il=date(2026, 11, 2), stato="in deposito", registrato_da=1,
)
print(Oggetto.model_validate(riga))python prova.py
rm prova.pydescrizione='Ombrello nero' categoria='ombrelli' colore=None segno_particolare=None stazione_id=3 trovato_il=datetime.date(2026, 11, 2)
1 validation error for OggettoNuovo
categoria
Input should be 'ombrelli', 'borse', 'telefoni', 'chiavi', 'abbigliamento' or 'altro' [type=literal_error, input_value='biciclette', input_type=str]
For further information visit https://errors.pydantic.dev/2.14/v/literal_error
id=7 descrizione='Ombrello nero' categoria='ombrelli' colore='nero' stazione_id=3 trovato_il=datetime.date(2026, 11, 2) stato='in deposito'Il foglio crea un OggettoNuovo giusto, poi uno con la categoria «biciclette» (rifiutato: la categoria è una lista fissa), e riempie un Oggetto da una riga OggettoDB che ha anche il segno particolare. La prova: l'oggetto in risposta ha tutto tranne il segno_particolare.
12 · rotte/ e l'APIRouter
Una sola novità vera di FastAPI in tutto il capitolo: l'APIRouter.
Finora ogni rotta stava in main.py. Con quattro rotte va bene; con venti, main.py diventa una scheda di mille righe dove non trovi più niente. Il router è un pezzo di app: un gruppo di rotte con un prefisso e un'etichetta, in un file a parte. Un file di rotte per ogni cosa: oggetti, stazioni, restituzioni.
mkdir app/rotte
touch app/rotte/__init__.pyfrom fastapi import APIRouter
from app.schemi import Oggetto
router = APIRouter(prefix="/oggetti", tags=["oggetti"])
@router.get("")
def elenco_oggetti() -> list[Oggetto]:
return [] # il segnaposto: le rotte vere arrivano nel capitolo «Un pezzo alla volta»È il file app/rotte/oggetti.py.
prefix="/oggetti"va davanti a ogni rotta del file.@router.get("")diventaGET /oggetti; un domani@router.get("/{oggetto_id}")saràGET /oggetti/{oggetto_id}. Non lo ripeti ogni volta.tags=["oggetti"]è il titoletto con cui/docsraggruppa le rotte.- La rotta di adesso è un segnaposto: risponde con l'elenco vuoto. Serve a provare che il router è montato.
Poi main.py lo monta, con una riga:
from fastapi import FastAPI
from app.rotte import oggetti
app = FastAPI(title="Ritrovato")
app.include_router(oggetti.router)
@app.get("/salute")
def salute() -> dict[str, str]:
return {"stato": "ok"}E si aggiunge il terzo test, in fondo a tests/test_salute.py:
def test_il_router_degli_oggetti_e_montato(client):
assert client.get("/oggetti").json() == []pytest -v============================= test session starts ==============================
platform darwin -- Python 3.12.13, pytest-9.2.0, pluggy-1.7.0 -- ~/ritrovato/.venv/bin/python3
cachedir: .pytest_cache
rootdir: ~/ritrovato
configfile: pytest.ini
testpaths: tests
plugins: anyio-4.16.0
collecting ... collected 3 items
tests/test_salute.py::test_salute PASSED [ 33%]
tests/test_salute.py::test_il_database_dei_test_e_collegato PASSED [ 66%]
tests/test_salute.py::test_il_router_degli_oggetti_e_montato PASSED [100%]
============================== 3 passed in 0.17s ===============================La prova: tre test verdi, e /docs ora mostra due gruppi: default con /salute, e oggetti con GET /oggetti.
13 · Il primo commit
Lo scheletro è fatto. Ultimo: lo salvi.
git add .
git status --shortA .env.example
A .gitignore
A CANVAS.md
A README.md
A app/__init__.py
A app/database.py
A app/main.py
A app/modelli.py
A app/rotte/__init__.py
A app/rotte/oggetti.py
A app/schemi.py
A pytest.ini
A requirements.txt
A schema.sql
A tests/conftest.py
A tests/test_salute.pyControlla l'elenco, riga per riga, prima di fare il commit. Mancano .env e .venv/: è giusto, e quello che vuoi. Il README.md che vedi in lista è questo:
# Ritrovato
Gli oggetti smarriti della Linea Menta: li registra l'ufficio di Porta Codice, li cerca chi ha perso qualcosa.
1. `python3 -m venv .venv`, poi `source .venv/bin/activate` e `pip install -r requirements.txt`
2. `cp .env.example .env`
3. `createdb ritrovato`, poi `psql -d ritrovato -f schema.sql`
4. `fastapi dev app/main.py`, poi nel browser `http://127.0.0.1:8000/docs`
5. `pytest`, dalla cartella `ritrovato/`: il database dei test se lo prepara da sologit commit -m "Lo scheletro di Ritrovato: /salute verde, database collegato"
git log --oneline915da36 Lo scheletro di Ritrovato: /salute verde, database collegatoLa prova: il commit c'è, e git ls-files non nomina .env. Lo scheletro è al sicuro.
La traduzione: schema.sql, modelli.py, schemi.py
Ogni riga di schema.sql diventa una riga in modelli.py e una riga in schemi.py. Impara la tabella, e le quattro colonne di Ritrovato (e di ogni altro progetto) si scrivono da sole.
In schema.sql | In modelli.py | In schemi.py |
|---|---|---|
id SERIAL PRIMARY KEY | id: Mapped[int] = mapped_column(primary_key=True) | solo nello stampo di risposta: id: int. Non in quello nuovo |
nome TEXT NOT NULL | nome: Mapped[str] | nome: str |
colore TEXT (facoltativo) | colore: Mapped[str | None] | colore: str | None = None nello stampo nuovo, colore: str | None nella risposta |
nome TEXT NOT NULL UNIQUE | nome: Mapped[str] = mapped_column(unique=True) | nome: str: l'unicità la controlla il database (se no, un 409) |
stazione_id INTEGER NOT NULL REFERENCES stazioni(id) | stazione_id: Mapped[int] = mapped_column(ForeignKey("stazioni.id")) | stazione_id: int |
trovato_il DATE NOT NULL | trovato_il: Mapped[date] | trovato_il: date |
inizio TIMESTAMP NOT NULL | inizio: Mapped[datetime] | inizio: datetime |
categoria TEXT NOT NULL CHECK (categoria IN ('a', 'b')) | categoria: Mapped[str], il CHECK resta in un commento | categoria: Literal["a", "b"] |
posti INTEGER NOT NULL CHECK (posti > 0) | posti: Mapped[int] | posti: int = Field(gt=0) |
stato TEXT NOT NULL DEFAULT 'in deposito' | stato: Mapped[str] = mapped_column(server_default="in deposito") | non c'è nello stampo nuovo; nella risposta stato: Stato |
proiettore BOOLEAN NOT NULL DEFAULT false | proiettore: Mapped[bool] = mapped_column(server_default="false") | proiettore: bool = False nello stampo nuovo |
una colonna che non deve uscire (segno_particolare) | c'è, come le altre | non c'è nello stampo di risposta |
Le righe posti, inizio e proiettore vengono da Prenota-sala, il progetto della palestra. Tre regole per leggere la tabella.
Il tipo Python dice se è obbligatoria. Senza | None la colonna è NOT NULL; con | None, può essere vuota. Vale in modelli.py e in schemi.py.
Il CHECK lo fa il database. In modelli.py si ricopia come commento; in schemi.py diventa un Literal (una lista fissa di parole) o un Field(gt=0). Il database lo rifiuta con un errore SQL; lo stampo lo rifiuta prima, con un 422 leggibile. Due controlli per lo stesso vincolo, e va bene: il secondo è il garbo, il primo è la sicurezza.
Un DEFAULT si dichiara due volte, con due verbi diversi. Nel SQL con DEFAULT; in modelli.py con server_default. Nello stampo nuovo, se l'utente può sceglierlo, con = valore (proiettore: bool = False); se non può, non c'è.
Perché ci sono i file __init__.py, e pythonpath = .
Due cose che sembrano magia, e non lo sono.
app/ è un pacchetto. Una cartella che contiene codice Python e un file __init__.py si chiama pacchetto. Il file può restare vuoto: la sua presenza dice a Python (e agli strumenti) «qui dentro ci sono moduli da importare». Con un pacchetto scrivi from app.database import engine: il percorso del file, con il punto al posto della barra.
I test lo trovano per il pythonpath. Python cerca app solo in alcuni posti: la cartella dello script che lanci e poche altre. I test stanno in tests/, quindi app/ sarebbe fuori. La riga pythonpath = . del pytest.ini aggiunge la cartella del progetto all'elenco. Per questo pytest si lancia sempre dalla cartella del progetto: se lo lanci da un'altra, il pytest.ini non lo trova e vedi di nuovo No module named 'app'.
E fastapi dev app/main.py, lanciato dalla cartella del progetto, fa la stessa cosa da solo: sa che app/ è un pacchetto.
Lo scheletro vuoto
Ricapitolo di dove sei, in cinque punti:
- La cartella ha ogni file al suo posto, e un
.gitignoreche tiene fuori quello che deve stare fuori. GET /saluterisponde, e un test lo prova.database.pysi collega al database giusto: il tuo, o quello dei test.- Ogni tabella di
schema.sqlha la sua classe inmodelli.py, e i due stampi dischemi.pydicono cosa entra e cosa esce. - Un router è montato, con una rotta segnaposto.
Cosa non c'è: nessuna rotta vera, nessun dato, nessun login. È voluto. Uno scheletro che funziona vale più di tre file scritti a metà. Dal prossimo capitolo, Un pezzo alla volta, si riempie una funzione per volta, da capo a fondo.
Ricorda
- Ogni passo ha un comando e una prova. Se la prova non passa, non vai avanti.
.envnon va su GitHub;.env.examplesì.DATABASE_URLsta in una variabile d'ambiente: il codice non cambia da un computer all'altro.- I test usano un altro database, rifatto da
schema.sqlprima di ogni test: i tuoi dati non si toccano. modelli.pyricopiaschema.sql;schemi.pydice cosa entra e cosa esce.- Un
APIRouterè un file di rotte con il suo prefisso;main.pylo monta coninclude_router.