Librerie Python: guida completa per installare, importare e creare

Link rapidi

• Che cosa sono le librerie Python?

• Come installare librerie Python

• Importare una libreria Python intera

• Importare parte di una libreria (solo in sessione interattiva)

• Creare e importare le tue librerie Python

Con le librerie puoi evitare di riscrivere codice comune: la comunità Python è ricca di moduli per analisi dati, sviluppo web, grafica, e molto altro. Di seguito trovi spiegazioni pratiche, esempi, metodi alternativi, errori comuni, e checklist pronte per l’uso.

Che cosa sono le librerie Python?

Una libreria (o modulo) è una raccolta di codice riutilizzabile: funzioni, classi e costanti che puoi importare in un tuo programma. In Python il termine “modulo” indica solitamente un file .py, mentre “pacchetto” è una raccolta di moduli organizzata in una directory con un file init.py.

Vantaggi principali:

• Risparmio di tempo: non devi reinventare funzioni comuni.
• Affidabilità: le librerie mature sono testate e manutenute dalla comunità.
• Estendibilità: molte librerie interoperano facilmente tra loro.

Quando sono particolarmente utili: analisi dati, manipolazione testi, accesso a database, networking, test automatici e automazione.

Nota rapida: “namespace” è il meccanismo che evita collisioni fra nomi di funzioni; i moduli isolano i loro nomi nel proprio namespace.

Come installare librerie Python

Esistono diversi approcci per installare librerie Python; la scelta dipende da permessi di sistema, ambiente di sviluppo e requisiti di progetto.

Principali strumenti di installazione:

• pip: il package installer standard per PyPI.
• conda / mamba: gestori di pacchetti e ambienti, molto usati per data science (mamba è un’alternativa più veloce a conda).
• poetry, pipenv: strumenti per la gestione delle dipendenze e packaging oriented al progetto.
• gestori di pacchetti del sistema (apt, dnf, brew): installano pacchetti a livello di distribuzione, spesso con prefissi python-.

Esempio base con pip:

pip install numpy

Se lavori in un progetto è buona pratica usare un ambiente isolato per evitare conflitti tra dipendenze.

Creare un ambiente virtuale con il modulo venv integrato:

python -m venv .venv
source .venv/bin/activate  # Linux / macOS
.\.venv\Scripts\activate   # Windows PowerShell o CMD
pip install -r requirements.txt

Con mamba (o conda) per ambienti condivisi nei progetti di data science:

mamba create -n stats python=3.10
mamba activate stats
mamba install numpy pandas scipy

Installazione senza permessi di root:

• pip –user per installare nella directory dell’utente: pip install –user nome_pacchetto
• ambienti virtuali locali (venv, virtualenv)

Salvare le dipendenze del progetto:

pip freeze > requirements.txt
pip install -r requirements.txt

Alternative di distribuzione e packaging (quando rilasci il tuo modulo): usa setup.py, pyproject.toml o tools come poetry per costruire wheel e pubblicare su PyPI.

Importante: preferisci strumenti di gestione delle dipendenze dedicati (poetry/pip-tools) per progetti con dipendenze complesse, perché risolvono meglio le versioni e la riproducibilità.

Importare una libreria Python intera

Per usare una libreria in uno script o nella REPL, importala con import:

import numpy

Questo crea un oggetto modulo con il suo namespace: per accedere alle sue funzioni scrivi numpy.mean(numbers).

Alias comuni per comodità:

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

L’uso di alias è accettato quando è uno standard di fatto nella comunità (ad es. np, pd, plt). Mantiene il codice leggibile e coerente.

Concetto chiave: importare il modulo intero evita di sovrascrivere nomi nella namespace globale; è una pratica raccomandata per script e librerie distribuite.

Importare parte di una libreria (raccomandato solo in sessione interattiva)

Nella REPL o in IPython può essere comodo importare funzioni singole:

from numpy import mean, median
mean(numbers)
median(numbers)

Questo può rendere il lavoro interattivo più rapido, ma in script pubblici aumenta il rischio di conflitti di nome e rende il codice meno esplicito. Evita from module import * nei moduli di produzione.

Esempio di problema:

from statistics import mean
from numpy import mean  # sovrascrive la mean precedente

In caso di conflitti, i nomi importati per ultimi sovrascrivono quelli precedenti, causando bug difficili da tracciare.

Creare e importare le tue librerie Python

Un modulo Python è semplicemente un file .py che contiene funzioni e classi. Per trasformare uno script in una libreria:

1. Isola le funzioni utili in funzioni e classi riutilizzabili.
2. Metti il codice eseguibile sotto un controllo di entrypoint:

if __name__ == "__main__":
    main()

3. Organizza il codice in pacchetti, con una directory e un file init.py se necessario.
4. Gestisci il percorso di ricerca dei moduli con PYTHONPATH o sys.path quando importi da directory non standard.

Esempi pratici:

A. Rendere eseguibile un modulo:

# my_library.py

def saluta():
    print("Ciao!")

if __name__ == "__main__":
    saluta()

B. Importare da un’altra directory usando PYTHONPATH (Linux/macOS):

export PYTHONPATH="$PYTHONPATH:/percorso/ai/miei/moduli"
python script_che_importa.py

C. Modificare sys.path in runtime (usalo con cautela):

import sys
sys.path.append('/percorso/ai/miei/moduli')
import my_library

Permessi: non è necessario che il file .py abbia il bit eseguibile per poterlo importare; chmod +x è necessario solo se vuoi eseguirlo come script dalla shell (./my_library.py).

Best practice e stile

• Separazione delle responsabilità: una funzione fa una cosa sola.
• Documenta le API con docstring e usa typing hints quando possibile.
• Versiona le tue dipendenze e usa file di lock (poetry.lock, conda-lock, pip-tools).
• Evita import circolari ripensando la struttura dei moduli (estrai codice comune in un modulo separato).
• Testa i moduli con unit test (pytest/unittest) e integra i test in CI.

Sicurezza e valutazione delle dipendenze

Rischi comuni:

• Pacchetti mal mantenuti o abbandonati.
• Pacchetti malevoli o typosquatting su PyPI.
• Vulnerabilità note nelle versioni delle librerie.

Mitigazioni pratiche:

• Controlla la reputazione della libreria (stargazers, manutentori, frequenza dei rilasci).
• Preferisci pacchetti ufficiali o dalle organizzazioni note.
• Usa strumenti di scansione vulnerabilità (bandit, safety, dependabot) nelle pipeline CI.
• Pinna le versioni delle dipendenze nei requisiti di produzione.

Note sulla privacy e GDPR (se usi dati personali):

• Le librerie che processano dati devono rispettare i requisiti di minimizzazione e sicurezza.
• Verifica che le dipendenze non inviino dati a terzi senza consenso.
• Documenta la gestione dei dati quando fornisci librerie che trattano informazioni sensibili.

Quando una libreria non è la soluzione giusta

Controesempi e casi in cui non conviene usare una libreria esterna:

• Requisiti di performance estremi: a volte una soluzione ad hoc in C/Cython è necessaria.
• Dipendenza critica con licenza incompatibile: preferisci implementazioni interne o librerie con licenze compatibili.
• Progetti estremamente piccoli: aggiungere una dipendenza può aumentare la superficie di attacco e la complessità.

Alternative:

• Vendoring: includere solo il codice necessario di una libreria nel tuo repository per eliminare la dipendenza esterna (usalo con attenzione rispetto alle licenze).
• Containerizzazione: isolare l’ambiente con Docker per avere riproducibilità e controllo totale delle versioni.

Mappa mentale: modello mentale per le dipendenze

• Namespace: ogni modulo ha il proprio spazio dei nomi.
• Graph delle dipendenze: progetti -> dipendenze -> sottodipendenze.
• Isolamento: ambiente virtuale o container per separare progetti.
• Riproducibilità: file di lock e registri dei pacchetti.

Confronto rapido dei gestori di pacchetti

Playbook rapido: aggiungere una nuova dipendenza a un progetto

1. Valuta la necessità e alternative.
2. Controlla licenza e manutenzione del pacchetto.
3. Aggiungi in un ambiente isolato (venv/conda).
4. Esegui test locali.
5. Aggiorna requirements.txt o pyproject.toml + lock.
6. Esegui scan di sicurezza e CI.
7. Deploy e monitora.

Snippet utile:

# creazione ambiente e installazione
python -m venv .venv
source .venv/bin/activate
pip install nome_pacchetto
pip freeze > requirements.txt

# con mamba
mamba create -n progetto python=3.10 nome_pacchetto
mamba activate progetto
mamba env export > environment.yml

Checklist per ruolo

Sviluppatore:

• Usare ambienti virtuali.
• Pinning delle versioni in requirements o lock file.
• Scrivere test di unità per le integrazioni.
• Usare alias standard per librerie comuni.

DevOps / SRE:

• Automatizzare la risoluzione e il lock delle dipendenze in CI.
• Scansione vulnerabilità e policy denylist.
• Definire processi di rollback in caso di regressioni dovute a dipendenze.

Data scientist / Analista:

• Usare conda/mamba per gestire dipendenze binarie.
• Documentare l’ambiente (environment.yml o conda-lock).
• Verificare compatibilità tra librerie scientifiche e versioni Python.

Debug e casi limite

Problemi comuni e come risolverli:

• ImportError: controlla sys.path e se il modulo è nel PYTHONPATH o nella stessa directory.
• Versioni incompatibili: usa pip install ‘pacchetto==x.y.z’ o strumenti di risoluzione.
• Import circolare: estrai funzioni comuni in un modulo a parte.

Esempio di ispezione di sys.path:

import sys
print('\n'.join(sys.path))

Esempi pratici estesi

Calcolare media e mediana con NumPy e fallback a statistics builtin quando NumPy non è disponibile:

try:
    import numpy as np
    def mean(xs):
        return float(np.mean(xs))
    def median(xs):
        return float(np.median(xs))
except ImportError:
    import statistics as stats
    def mean(xs):
        return stats.mean(xs)
    def median(xs):
        return stats.median(xs)

Questo pattern è utile quando vuoi offrire funzionalità base anche senza dipendenze pesanti.

Decisione: installare globale, locale o vendor? (diagramma)

flowchart TD
    A[Hai accesso root?] -->|Sì| B{È per tutti gli utenti?}
    A -->|No| C[Usa ambiente virtuale o --user]
    B -->|Sì| D[Installa con il package manager del sistema]
    B -->|No| C
    C --> E{Hai bisogno di pacchetti binari?}
    E -->|Sì| F[Usa conda/mamba]
    E -->|No| G[Usa pip in virtualenv]
    F --> H[Blocca environment.yml per riproducibilità]
    G --> I[Usa requirements.txt o poetry]

Maturità delle librerie: come valutare

Indicatori qualitativi di maturità:

• Frequenza di rilascio: aggiornamenti regolari indicano manutenzione.
• Copertura test: progetti con test e CI sono più affidabili.
• Documentazione: API chiare e guide d’uso.
• Comunità e contributori: segnalano supporto e resilienza.

Non è necessario che una libreria sia perfetta; valuta il trade-off tra funzionalità, qualità e costo di integrazione.

Compatibilità e migrazione

• Sii esplicito sulla versione minima di Python nel tuo packaging (pyproject.toml / setup.cfg).
• Evita dipendenze non mantenute durante le migrazioni di versione.
• Testa il progetto con la matrice di versioni in CI (ad esempio, test con Python 3.8, 3.9, 3.10).

Glossario (una riga ciascuno)

• Modulo: file .py contenente codice riutilizzabile.
• Pacchetto: directory con moduli e un init.py.
• PyPI: repository pubblico di pacchetti Python.
• pip: installer dei pacchetti Python.
• conda/mamba: gestori di pacchetti e ambienti, utili per pacchetti binari.
• virtualenv / venv: strumenti per creare ambienti isolati.

Rischi e mitigazioni (matrice semplificata)

• Rischio: dipendenza vulnerabile | Mitigazione: scansione automatica + pinning
• Rischio: rottura API dopo aggiornamento | Mitigazione: test automatizzati + controllo di versione
• Rischio: licenza incompatibile | Mitigazione: verifica licenze prima dell’adozione

Casi di test / criteri di accettazione per una nuova dipendenza

• Il pacchetto si installa senza errori in ambiente isolato.
• Tutti i test del progetto passano con la nuova dipendenza.
• Non ci sono collisioni di namespace con librerie esistenti.
• La licenza è compatibile con l’uso previsto.

Conclusione e raccomandazioni finali

Le librerie sono il cuore dell’ecosistema Python: imparare a gestirle bene significa scrivere codice più veloce, sicuro e mantenibile. Usa ambienti isolati, valuta le dipendenze prima di aggiungerle e automatizza la gestione delle librerie in CI. Per i progetti di data science valuta mamba/conda per la gestione dei pacchetti binari; per applicazioni Python pure considera poetry per la gestione delle dipendenze e del packaging.

Con le librerie giuste e una buona disciplina nella gestione delle dipendenze, puoi ampliare enormemente ciò che è possibile fare con Python risparmiando tempo e aumentando l’affidabilità del tuo software.