Moduli e file
Il codice in più file, i dati fuori dal codice
- 15 minuti di lettura
Fino a qui ogni programma stava in un file solo, e i dati erano scritti dentro il codice: treni = ["M12", "M14"]. I programmi veri fanno due cose in più:
- si dividono in più file, uno per argomento, che si usano a vicenda con
import; - leggono e scrivono i dati in altri file: un registro di testo, un CSV, un JSON.
Prendi un programma che legge un CSV, riceve il nome del file da sys.argv e manda gli avvisi su stderr. Qui ritrovi tutti i pezzi, uno alla volta.
Il disegno
Tre posti da tenere separati: la cartella da cui lanci il programma, la cartella del programma, i file di dati. Qui il terminale è aperto in ~/linea-menta, e il comando è quello in alto.
python programmi/conta.py dati/salite.csv
─────────┬──────── ───────┬───────
│ └── il file da leggere
└── il programma
~/linea-menta/ ◀── la cartella da cui lanci:
│ da qui partono i percorsi relativi
├── dati/
│ └── salite.csv ◀── "dati/salite.csv"
└── programmi/ ◀── Path(__file__).parent
├── conta.py ◀── il programma: __name__ è "__main__"
├── tariffe.py ◀── import tariffe lo trova qui
└── fermate.txt ◀── Path(__file__).parent / "fermate.txt"Il disegno si legge con due regole, e quasi tutti i guai del capitolo nascono dal confonderle:
importcerca accanto al programma.import tariffetrovatariffe.pyperché sta nella stessa cartella diconta.py.opencerca a partire da dove lanci."dati/salite.csv"è un percorso relativo: Python lo attacca alla cartella del terminale,~/linea-menta. Lanciato da un'altra cartella, lo stesso percorso porta da un'altra parte.
Le altre frecce, __name__ e Path(__file__), le spiega il resto della pagina, una alla volta.
Un file è un modulo
Ogni file .py è già un modulo: un pacchetto di funzioni e costanti che un altro file può usare.
# tariffe.py
PREZZO_CORSA = 2.2
def prezzo(corse: int) -> float:
return round(corse * PREZZO_CORSA, 2)Da conta.py, nella stessa cartella, ci sono due modi per usarlo:
import tariffe # porta qui il modulo intero
tariffe.prezzo(2) # 4.4: modulo, punto, nome
tariffe.PREZZO_CORSA # 2.2
from tariffe import prezzo # porta qui solo il nome che ti serve
prezzo(2) # 4.4: senza il puntoIl nome del modulo è il nome del file senza .py. I test della palestra usano la seconda forma: from avvisi import leggi_avvisi. Per i moduli della libreria standard si usa quasi sempre la prima, così si vede da dove arriva ogni nome: math.ceil, sys.argv, csv.reader.
if __name__ == "__main__":
Quando importi un modulo, Python lo esegue tutto, dall'alto in basso. Le def creano le funzioni, e fin qui va bene. Ma se in fondo al file c'erano delle prove con print, partono anche quelle, ogni volta che qualcuno lo importa.
Per questo le prove si mettono in un blocco speciale:
# tariffe.py, in fondo
if __name__ == "__main__":
print("Prova:", prezzo(3))__name__ è una variabile che Python riempie da solo, in ogni modulo:
| Come usi il file | __name__ vale | Il blocco parte? |
|---|---|---|
Lo lanci: python tariffe.py | "__main__" | Sì |
Lo importi: import tariffe | "tariffe" | No |
È per questo che i file della palestra finiscono tutti con quel blocco. pytest fa from avvisi import leggi_avvisi, e le prove in fondo non partono; tu, con python palestra/avvisi.py, le vedi.
La libreria standard
Python arriva con tanti moduli già pronti: si importano senza installare niente. Quelli che servono in questo capitolo:
| Modulo | A cosa serve | Per esempio |
|---|---|---|
math | I conti che non sono + - * / | math.ceil(2.1) dà 3 (per eccesso), math.floor(2.9) dà 2, math.sqrt(16) dà 4.0 |
random | Il caso | random.choice(fermate) dà una fermata a caso, random.randint(1, 6) un intero da 1 a 6. Ogni volta un risultato diverso |
csv | Leggere i file CSV | csv.reader(f), csv.DictReader(f) |
json | Leggere e scrivere JSON | json.load(f), json.dump(dati, f) |
sys | Parlare con il terminale | sys.argv, sys.stderr, sys.exit(1) |
pathlib | I percorsi | Path(__file__).parent |
Leggere un file
with open("fermate.txt", encoding="utf-8") as f:
testo = f.read()Pezzo per pezzo:
open(percorso, encoding="utf-8")apre il file in lettura.encoding="utf-8"dice a Python come sono scritte le lettere. Senza, su certi computerèdiventaè, o arriva unUnicodeDecodeError. Mettilo sempre.as fdà un nome al file aperto, per tutto il blocco.withchiude il file alla fine del blocco, da solo, anche se nel mezzo c'è un errore.
Dentro il blocco ci sono tre modi di leggere. Con un fermate.txt di tre righe:
| Si scrive | Cosa dà |
|---|---|
f.read() | Tutto il file in una stringa: 'Porta Codice\nVia Variabile\nLargo Lista\n' |
f.readlines() | Una lista, una riga per scatola: ['Porta Codice\n', 'Via Variabile\n', 'Largo Lista\n'] |
for riga in f: | Una riga per giro: 'Porta Codice\n', poi 'Via Variabile\n', poi 'Largo Lista\n' |
Il disegno. Il risultato di readlines(): una lista, e ogni riga è una stringa con il suo \n.
Guarda la fine di ogni riga: \n, l'a capo. Nel file non lo vedi, ma c'è, e resta attaccato alla riga. Prima di confrontare o dividere una riga, si toglie con strip(), che toglie anche gli spazi in più all'inizio e alla fine:
with open("fermate.txt", encoding="utf-8") as f:
for riga in f:
riga = riga.strip() # 'Porta Codice\n' diventa 'Porta Codice'
if riga == "":
continue # riga vuota: salta al giro dopo
print(riga)continue è il fratello di break: invece di uscire dal ciclo, salta il resto di questo giro e passa al prossimo. È il modo più comodo per dire «questa riga non mi interessa».
Scrivere un file
Per scrivere, open vuole un secondo argomento: il modo.
with open("diario.txt", "w", encoding="utf-8") as f:
f.write("06:00 apertura\n")
f.write("06:12 primo treno\n")| Modo | Si scrive | Se il file c'è già | Se non c'è |
|---|---|---|---|
| Leggere | open(p, encoding="utf-8") | Lo legge | FileNotFoundError |
| Scrivere | open(p, "w", encoding="utf-8") | Lo svuota, poi scrive | Lo crea |
| Aggiungere | open(p, "a", encoding="utf-8") | Scrive in fondo, il resto resta | Lo crea |
Due cose che sorprendono tutti, la prima volta:
"w"cancella il contenuto appena apri, prima ancora di scrivere. Per aggiungere in fondo a un registro,"a".writenon va a capo da sola, e vuole solo testo. L'a capo lo metti tu, e i numeri passano da una f-string:f.write(f"{treno},{minuti}\n").
Da dove parte il percorso
open("dati/salite.csv") cerca il file a partire dalla cartella da cui hai lanciato il programma: quella del terminale, non quella del file .py. Torna al disegno:
| Terminale aperto in | Comando | "dati/salite.csv" diventa |
|---|---|---|
~/linea-menta | python programmi/conta.py dati/salite.csv | ~/linea-menta/dati/salite.csv, che c'è |
~/linea-menta/programmi | python conta.py dati/salite.csv | ~/linea-menta/programmi/dati/salite.csv, che non c'è: FileNotFoundError |
La cartella del terminale la vedi con pwd. In VS Code, il pulsante ▶ e F5 di solito lanciano dalla cartella che hai aperto con Open Folder.
Per i file che il programma si porta dietro, che stanno sempre accanto al .py, c'è un modo che non dipende da dove lanci:
from pathlib import Path
cartella = Path(__file__).parent # la cartella di questo file: programmi/
percorso = cartella / "fermate.txt" # / unisce i pezzi di un percorso
with open(percorso, encoding="utf-8") as f:
fermate = f.readlines()__file__ è il percorso del file .py che contiene questa riga, .parent la sua cartella. Così il programma trova fermate.txt da qualsiasi cartella lo lanci.
Quale dei due usare? Se il file lo sceglie chi usa il programma (lo passa da terminale), il percorso parte da dove lancia, ed è giusto così. Se il file fa parte del programma (i dati della storia, gli esempi della palestra), Path(__file__).parent.
Il CSV
Un CSV è un file di testo che fa da tabella: una riga per ogni record, la virgola tra una colonna e l'altra, e la prima riga, l'intestazione, che dà il nome alle colonne.
ora,stazione,salite
07:00,Porta Codice,120
07:00,Largo Lista,45A mano, con quello che sai già:
with open("salite.csv", encoding="utf-8") as f:
righe = f.readlines()
for riga in righe[1:]: # la riga 0 è l'intestazione
ora, stazione, quante = riga.strip().split(",")
print(stazione, int(quante)) # dal file arriva testo: "120" non è 120Tre cose, sempre: salta l'intestazione, strip() prima di split(","), e int() o float() per i numeri.
Con il modulo csv. A mano funziona finché nessun campo contiene una virgola. Ma se una colonna è un testo libero, la virgola ci finisce dentro, e allora il campo si scrive tra virgolette:
stazione,segnalazione
Largo Lista,"scala mobile ferma, uscita A"split(",") taglia anche quella virgola. Il modulo csv invece conosce le virgolette:
import csv
with open("segnalazioni.csv", encoding="utf-8") as f:
for riga in csv.DictReader(f):
print(riga["stazione"], "→", riga["segnalazione"]) # Largo Lista → scala mobile ferma, uscita Acsv.DictReader usa l'intestazione per le chiavi: ogni riga diventa un dizionario, {'stazione': 'Largo Lista', 'segnalazione': 'scala mobile ferma, uscita A'}. csv.reader invece dà una lista per riga, intestazione compresa:
with open("segnalazioni.csv", encoding="utf-8") as f:
lettore = csv.reader(f)
intestazione = next(lettore) # ['stazione', 'segnalazione']
for campi in lettore: # ['Largo Lista', 'scala mobile ferma, uscita A']
print(campi[1])next(lettore) prende la prossima riga e va avanti: il for riparte da quella dopo.
Con csv o a mano, i valori sono sempre testo. E csv capisce le virgolette, ma non pulisce niente: spazi, campi mancanti e numeri scritti male restano affari tuoi. È la storia di questo capitolo.
Il JSON, in breve
Il JSON è il formato di testo delle API: quando una rotta di FastAPI restituisce un dizionario, al client arriva un JSON. Somiglia ai dizionari e alle liste di Python, con poche differenze:
| JSON | Python |
|---|---|
{"treno": "M12"} | dict |
["M12", "M14"] | list |
"testo", solo virgolette doppie | str |
4, 2.5 | int, float |
true, false | True, False |
null | None |
import json
treno = {"codice": "M12", "vagoni": 4, "fermate": ["Porta Codice", "Piazza Query"]}
with open("treno.json", "w", encoding="utf-8") as f:
json.dump(treno, f, indent=2) # dal dizionario al file; indent=2 lo rende leggibile
with open("treno.json", encoding="utf-8") as f:
letto = json.load(f) # dal file al dizionario
print(letto["fermate"][0]) # Porta Codiceload e dump lavorano con un file aperto. loads e dumps, con la s di string, lavorano con una stringa: json.dumps({"treno": "M12"}) dà il testo '{"treno": "M12"}'. È quello che fa FastAPI per te, prima di rispondere.
Gli argomenti: sys.argv
Quello che scrivi dopo il nome del programma arriva al programma in sys.argv:
# programmi/argomenti.py
import sys
print(sys.argv)python programmi/argomenti.py dati/salite.csv 7['programmi/argomenti.py', 'dati/salite.csv', '7']Il terminale spezza il comando agli spazi, e Python mette i pezzi in una lista di stringhe:
sys.argv[0]è sempre il programma, così come l'hai scritto. Gli argomenti veri partono dasys.argv[1].- Sono sempre testo:
'7', non7. Un numero va convertito conint(). - Quindi
sys.argvnon è mai vuota: per sapere se manca il file si chiedelen(sys.argv) < 2.
if len(sys.argv) < 2:
print("Si usa così: python conta_righe.py <file>", file=sys.stderr)
sys.exit(1)sys.exit(1) ferma il programma lì. Il numero è per il terminale: 0 vuol dire «tutto bene», qualsiasi altro numero «qualcosa è andato storto».
stdout e stderr
print scrive su stdout, l'uscita normale del programma. Con file=sys.stderr scrive su stderr, il canale degli avvisi e degli errori. Nel terminale li vedi tutti e due, uno sotto l'altro: la differenza si vede quando mandi l'uscita in un file.
# due_canali.py
import sys
print("M12 per Piazza Query, binario 2")
print("Riga 3 ignorata: M14,Porta Codice", file=sys.stderr)$ python due_canali.py > partenze.txt
Riga 3 ignorata: M14,Porta Codice
$ cat partenze.txt
M12 per Piazza Query, binario 2 ┌─ print(...) ──▶ stdout ──▶ schermo, o il file dopo >
due_canali.py ──┤
└─ print(..., file=sys.stderr) ──▶ stderr ──▶ schermo, o il file dopo 2>Il risultato del programma va su stdout, ed è quello che i test confrontano. Gli avvisi («ho saltato una riga») vanno su stderr: si vedono, ma non sporcano il risultato. I test guardano solo stdout, per questo motivo.
Dopo questo capitolo
- Saltare una riga che fa scattare un errore, come
int("31.002"), si fa contryedexcept ValueError. Lo assaggi nella storia; il capitolo intero è try, except, raise. - Il JSON torna in tutte le API: Il viaggio di una richiesta.
- Tutte le mosse di questa pagina, in una tabella: il prontuario File e moduli.
Ricorda
- Un file
.pyè un modulo:import tariffeofrom tariffe import prezzo, senza.py. if __name__ == "__main__":parte solo quando lanci il file, non quando lo importi.with open(p, encoding="utf-8") as f:, sempre con l'encoding."w"svuota,"a"aggiunge.- Ogni riga si porta dietro il suo
\n:strip()prima di confrontare o dividere. openparte dalla cartella da cui lanci,importda quella del programma.Path(__file__).parentnon dipende da dove lanci.- Dai file e da
sys.argvarriva sempre testo. Il risultato su stdout, gli avvisi su stderr.