Vai al contenuto
code-to-code

Apro l'indice…

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

Il progetto4. La cartella del progettop. 95

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

E a cosa serve ogni file, in una riga.

FileA cosa serve
CANVAS.mdIl canvas del capitolo 1: l'app in una pagina. Chi apre la cartella capisce cos'è
README.mdCome si avvia, in cinque righe
schema.sqlLe tabelle. La fonte vera: se c'è un dubbio, comanda lui
requirements.txtLa lista delle librerie. Chi scarica il progetto le installa con un comando
pytest.iniDice a pytest dove sono i test e dove trovare app/
.gitignoreI file che Git non deve vedere
.envLe impostazioni tue, come l'indirizzo del database. Mai su GitHub
.env.exampleLe stesse righe, senza segreti: il modello. Questo sì, su GitHub
app/__init__.pyVuoto. Dice a Python che app è un pacchetto
app/main.pyLa porta d'ingresso: crea l'app, ha GET /salute, monta i router
app/database.pyIl collegamento: DATABASE_URL, engine, Base, get_db
app/modelli.pyLe tabelle viste da Python: una classe XxxDB per tabella
app/schemi.pyGli stampi di Pydantic: cosa entra e cosa esce dall'API
app/rotte/oggetti.pyLe rotte degli oggetti, in un APIRouter. Una cosa, un file
tests/conftest.pyPrepara il database dei test e dà il finto browser
tests/test_salute.pyIl 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.

Terminale
cd ritrovato
git init -b main
git status
Initialized 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

Terminale
python3 -m venv .venv
source .venv/bin/activate
which python
~/ritrovato/.venv/bin/python

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

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

Terminale
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.9

pip 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
RigaCosa nascondePerché
.venv/Le librerie installatePesano centinaia di megabyte, e le rifà pip install
__pycache__/I file che Python scrive da soloSono avanzi: li rifà Python
.pytest_cache/La memoria di pytestStessa cosa
.envLe tue impostazioniPossono 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.sql

Con il .gitignore scritto:

?? .gitignore
?? CANVAS.md
?? requirements.txt
?? schema.sql

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

Terminale
cat .env.example
cp .env.example .env
git status --short
git check-ignore -v .env
DATABASE_URL=postgresql+psycopg:///ritrovato
?? .env.example
?? .gitignore
?? CANVAS.md
?? requirements.txt
?? schema.sql
.gitignore:4:.env	.env

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

Terminale
mkdir app
touch app/__init__.py
Python
from 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.

Terminale
fastapi dev app/main.py

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

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

Terminale
mkdir tests
Python
from 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:

ini
[pytest]
pythonpath = .
testpaths = tests

pythonpath = . 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.

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

Terminale
createdb ritrovato
psql -d ritrovato -f schema.sql
CREATE TABLE
CREATE TABLE
CREATE TABLE
CREATE TABLE

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

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:///ritrovato")

engine = create_engine(DATABASE_URL)


class Base(DeclarativeBase):
    pass


def get_db():
    with Session(engine) as db:
        yield db

Una riga alla volta, le nuove:

  • load_dotenv() legge il file .env e 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, engine e get_db sono 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.

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

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

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

  1. Il database dei test: se non c'è, lo crea.
  2. Le tabelle come nuove: prima di ogni test le butta e le rifà da schema.sql. Per questo schema.sql è la fonte vera: lo usano anche i test.
  3. Il client: il finto browser. Prima lo creava il file del test; ora lo presta il conftest.py a 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).

Python
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() == 0

Mettiamo un dato nel tuo database, e lanciamo i test:

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

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

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

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

Python
"""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: Stato

Guarda cosa non c'è, e perché:

  • OggettoNuovo non ha id (lo dà il database), né stato (parte da «in deposito»), né registrato_da (non lo scrive chi chiama: lo scrive il login, più avanti).
  • Oggetto non ha segno_particolare e non ha registrato_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):

Python
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))
Terminale
python prova.py
rm prova.py
descrizione='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.

Terminale
mkdir app/rotte
touch app/rotte/__init__.py
Python
from 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("") diventa GET /oggetti; un domani @router.get("/{oggetto_id}") sarà GET /oggetti/{oggetto_id}. Non lo ripeti ogni volta.
  • tags=["oggetti"] è il titoletto con cui /docs raggruppa 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:

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

Python
def test_il_router_degli_oggetti_e_montato(client):
    assert client.get("/oggetti").json() == []
Terminale
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.

Terminale
git add .
git status --short
A  .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.py

Controlla 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 solo
Terminale
git commit -m "Lo scheletro di Ritrovato: /salute verde, database collegato"
git log --oneline
915da36 Lo scheletro di Ritrovato: /salute verde, database collegato

La 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.sqlIn modelli.pyIn schemi.py
id SERIAL PRIMARY KEYid: Mapped[int] = mapped_column(primary_key=True)solo nello stampo di risposta: id: int. Non in quello nuovo
nome TEXT NOT NULLnome: 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 UNIQUEnome: 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 NULLtrovato_il: Mapped[date]trovato_il: date
inizio TIMESTAMP NOT NULLinizio: Mapped[datetime]inizio: datetime
categoria TEXT NOT NULL CHECK (categoria IN ('a', 'b'))categoria: Mapped[str], il CHECK resta in un commentocategoria: 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 falseproiettore: Mapped[bool] = mapped_column(server_default="false")proiettore: bool = False nello stampo nuovo
una colonna che non deve uscire (segno_particolare)c'è, come le altrenon 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:

  1. La cartella ha ogni file al suo posto, e un .gitignore che tiene fuori quello che deve stare fuori.
  2. GET /salute risponde, e un test lo prova.
  3. database.py si collega al database giusto: il tuo, o quello dei test.
  4. Ogni tabella di schema.sql ha la sua classe in modelli.py, e i due stampi di schemi.py dicono cosa entra e cosa esce.
  5. 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.
  • .env non va su GitHub; .env.example sì.
  • DATABASE_URL sta in una variabile d'ambiente: il codice non cambia da un computer all'altro.
  • I test usano un altro database, rifatto da schema.sql prima di ogni test: i tuoi dati non si toccano.
  • modelli.py ricopia schema.sql; schemi.py dice cosa entra e cosa esce.
  • Un APIRouter è un file di rotte con il suo prefisso; main.py lo monta con include_router.