Vai al contenuto
code-to-code

Apro l'indice…

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

Python7. Moduli e filep. 190

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:

  1. import cerca accanto al programma. import tariffe trova tariffe.py perché sta nella stessa cartella di conta.py.
  2. open cerca 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.

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

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

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

Python
# 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__ valeIl 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:

ModuloA cosa servePer esempio
mathI conti che non sono + - * /math.ceil(2.1) dà 3 (per eccesso), math.floor(2.9) dà 2, math.sqrt(16) dà 4.0
randomIl casorandom.choice(fermate) dà una fermata a caso, random.randint(1, 6) un intero da 1 a 6. Ogni volta un risultato diverso
csvLeggere i file CSVcsv.reader(f), csv.DictReader(f)
jsonLeggere e scrivere JSONjson.load(f), json.dump(dati, f)
sysParlare con il terminalesys.argv, sys.stderr, sys.exit(1)
pathlibI percorsiPath(__file__).parent

Leggere un file

Python
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 un UnicodeDecodeError. Mettilo sempre.
  • as f dà un nome al file aperto, per tutto il blocco.
  • with chiude 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 scriveCosa 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.

righe = ["Porta Codice\n", "Via Variabile\n", "Largo Lista\n"]righelist"Porta Codice\n"0"Via Variabile\n"1"Largo Lista\n"2
Dopo readlines() su fermate.txt

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:

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

Python
with open("diario.txt", "w", encoding="utf-8") as f:
    f.write("06:00 apertura\n")
    f.write("06:12 primo treno\n")
ModoSi scriveSe il file c'è giàSe non c'è
Leggereopen(p, encoding="utf-8")Lo leggeFileNotFoundError
Scrivereopen(p, "w", encoding="utf-8")Lo svuota, poi scriveLo crea
Aggiungereopen(p, "a", encoding="utf-8")Scrive in fondo, il resto restaLo 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".
  • write non 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 inComando"dati/salite.csv" diventa
~/linea-mentapython programmi/conta.py dati/salite.csv~/linea-menta/dati/salite.csv, che c'è
~/linea-menta/programmipython 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:

Python
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,45

A mano, con quello che sai già:

Python
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 è 120

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

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

csv.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:

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

JSONPython
{"treno": "M12"}dict
["M12", "M14"]list
"testo", solo virgolette doppiestr
4, 2.5int, float
true, falseTrue, False
nullNone
Python
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 Codice
letto = {"codice": "M12", "vagoni": 4, "fermate": ["Porta Codice", "Piazza Query"]}lettodict"codice""M12""vagoni"4"fermate"list"Porta Codice"0"Piazza Query"1
Il dizionario letto dal file

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

Python
# programmi/argomenti.py
import sys

print(sys.argv)
Terminale
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 da sys.argv[1].
  • Sono sempre testo: '7', non 7. Un numero va convertito con int().
  • Quindi sys.argv non è mai vuota: per sapere se manca il file si chiede len(sys.argv) < 2.
Python
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.

Python
# 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 con try ed except 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 tariffe o from 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.
  • open parte dalla cartella da cui lanci, import da quella del programma. Path(__file__).parent non dipende da dove lanci.
  • Dai file e da sys.argv arriva sempre testo. Il risultato su stdout, gli avvisi su stderr.