Moduli e import in Python: import, from-import, pip e pacchetti

Un file è un modulo

Quando il tuo codice Python supera la dimensione di un singolo script, vorrai dividerlo in più file. Il sistema di moduli di Python è semplice: qualsiasi file .py è automaticamente un modulo, importabile per nome.

Supponi di avere un file util.py:

# util.py
def greet(name):
    return f"Hello, {name}"

PI = 3.14159

Da un altro file nella stessa cartella, main.py, puoi usarlo:

# main.py
import util

print(util.greet("Ada"))
print(util.PI)

Esegui python3 main.py e Python trova util.py, lo esegue una volta ed espone tutto ciò che è definito al livello principale (funzioni, variabili, classi) come attributi del modulo util.

Le tre forme di import

Importare l'intero modulo. A ciò che contiene si accede tramite il nome del modulo:

import math

print(math.sqrt(2))
print(math.pi)

Importare nomi specifici. Diventano disponibili direttamente:

from math import sqrt, pi

print(sqrt(2))
print(pi)

Importare con un alias. Utile quando il nome del modulo è lungo o quando due moduli hanno lo stesso nome:

import numpy as np
import pandas as pd

# Ora usa np.array(...), pd.DataFrame(...), ecc.

Esiste una quarta forma, from math import *, che porta tutto nel tuo namespace. Evitala al di fuori degli esperimenti nella REPL: rende impossibile capire da dove arriva un nome e crea collisioni di nomi silenziose.

Quando vengono eseguiti gli import

Python esegue il codice di primo livello di un modulo importato una sola volta, la prima volta che viene importato in un programma. Gli import successivi dello stesso modulo restituiscono la versione già caricata. Quindi questo:

# setup.py
print("setup module loading...")
VALUE = 42

# main.py
import setup
import setup  # importato due volte, ma "loading" viene stampato una sola volta
print(setup.VALUE)

Stampa "setup module loading..." una sola volta. È importante: se metti effetti collaterali (come aprire un file o stampare) al livello principale del modulo, avvengono al momento dell'import, e di solito non è quello che vuoi. Mettili dentro delle funzioni.

La libreria standard

Python include un'ampia libreria standard di moduli. Ne hai già visti alcuni. Eccone qualcuno che userai di continuo:

• math: sqrt, sin, log, costanti come pi ed e.
• random: numeri casuali, scelte, rimescolamenti.
• datetime: date e orari.
• json: leggere e scrivere JSON.
• os, os.path: percorsi e operazioni sul file system.
• pathlib: gestione moderna dei percorsi, spesso più comoda di os.path.
• re: espressioni regolari.
• collections: tipi di collezione specializzati (Counter, defaultdict, deque, ecc.).
• itertools, functools: strumenti per iteratori e funzioni.
• csv: leggere e scrivere file CSV.

La libreria standard è già installata: non c'è niente da installare con pip.

import random

items = ["red", "green", "blue"]
print(random.choice(items))
print(random.randint(1, 100))

Pacchetti di terze parti e pip

Per tutto ciò che la libreria standard non copre, il Python Package Index (PyPI) ospita centinaia di migliaia di pacchetti. Li installi con pip:

pip install requests
pip install pandas
pip install --upgrade requests
pip uninstall requests

Una volta installati, si importano come qualsiasi altra cosa:

import requests

response = requests.get("https://api.example.com/data")
print(response.status_code)

Qualche consiglio per gestire il tutto con giudizio:

Usa gli ambienti virtuali

Installare tutto a livello globale porta guai. Progetti diversi richiedono versioni diverse; alcuni pacchetti dipendono da versioni specifiche di Python; su alcuni sistemi le installazioni globali richiedono i permessi di amministratore. Un ambiente virtuale è un'installazione di Python isolata, riservata a un solo progetto:

python3 -m venv .venv
source .venv/bin/activate    # macOS/Linux
.venv\Scripts\activate       # Windows

pip install requests

Finché il venv è attivo, pip installa nella cartella del progetto, non nel sistema. Quando hai finito, disattivalo con deactivate.

Fissa le versioni delle dipendenze

Salva l'elenco dei pacchetti installati così che altri (compreso il te del futuro) possano ricreare lo stesso ambiente:

pip freeze > requirements.txt

E poi, più avanti:

pip install -r requirements.txt

Strumenti come Poetry, pipenv e uv gestiscono tutto questo in modo più comodo, ma il semplice flusso pip + requirements.txt va ancora benissimo per imparare.

Scrivere moduli tuoi

Quando hai funzioni che vuoi riutilizzare in più file, mettile in un modulo dedicato. Convenzioni di nomenclatura:

• I nomi dei file dovrebbero essere in lower_snake_case.py.
• Anche funzioni e variabili a livello di modulo in lower_snake_case.
• Le classi usano il PascalCase.

# shopping.py
PRICES = {"apple": 0.50, "bread": 2.00}

def total(items):
    return sum(PRICES[item] for item in items)

# main.py
from shopping import total, PRICES

print(total(["apple", "bread"]))
print(PRICES)

Se due file nella stessa cartella si importano a vicenda, puoi creare per sbaglio un import circolare. La soluzione abituale è spostare il codice condiviso in un terzo file importato da entrambi.

Pacchetti: cartelle di moduli

Quando hai più di una manciata di moduli, raggruppali in un pacchetto, cioè una cartella che contiene un file __init__.py:

myproject/
├── main.py
└── utils/
    ├── __init__.py
    ├── text.py
    └── numbers.py

Poi:

from utils.text import slugify
from utils import numbers

print(slugify("Hello, World"))
print(numbers.mean([1, 2, 3]))

__init__.py può essere vuoto: è la sua presenza a rendere utils un pacchetto. Il Python moderno supporta anche i "namespace package" senza __init__.py, ma per iniziare la versione esplicita è più chiara.

Una piccola checklist quando gli import si rompono

• "ModuleNotFoundError: No module named X". O il pacchetto non è installato, oppure stai eseguendo Python con un interprete diverso da quello su cui hai lanciato pip install. In un venv, assicurati che sia attivo.
• "ImportError: cannot import name Y from X". Il modulo esiste, ma il nome che hai chiesto non c'è. Controlla eventuali errori di battitura e guarda cosa contiene davvero il modulo.
• "Circular import". Due moduli si importano a vicenda. Sposta il codice condiviso in un terzo modulo.

Prossimo argomento: installare pacchetti di terze parti

I tuoi moduli ti portano lontano, ma la maggior parte dei progetti reali usa anche librerie da PyPI: requests, pandas, un framework di test. La prossima pagina parla di pip, di come installare i pacchetti in modo pulito e di come registrare le dipendenze del tuo progetto.