Ho sempre sostenuto che nella “cassetta degli attrezzi” di un programmatore Python debbano esserci svariati strumenti utili sia allo sviluppo che alla manutenzione di un progetto.
In questo articolo vi parlerò di Poetry e vedremo come esso rappresenti una valida aggiunta alla nostra cassetta.
In che cosa consiste Poetry?
Questo progetto Python combina il controllo delle dipendenze di un progetto con la gestione del suo ciclo di vita: l’inizializzazione, lo sviluppo e il versionamento del codice e infine la pubblicazione del pacchetto in repository pubblici o privati. E non è tutto. Poetry offre altri vantaggi tra cui la gestione degli ambienti Python e un’interfaccia per definire i plugin con i quali interagire.
Per convincervi delle comodità e dell’utilità garantite dallo strumento, ecco qualche dettaglio aggiuntivo.
- I file di configurazione del progetto (setup.py, requirements.txt, ecc.) vengono rimpiazzati da un unico file pyproject.toml, pratico e leggibile. Questo file contiene i dati relativi al progetto, le definizioni delle sue dipendenze (permettendone all’occorrenza la suddivisione in sottogruppi distinti) e le informazioni relative ad altri strumenti integrati.
- La gestione degli ambienti avviene in maniera automatica, dato che Poetry crea un nuovo spazio qualora non ce ne fosse già uno impostato, seguendo le specifiche del file di configurazione scritto in formato TOML.
- La riproducibilità di un ambiente Python viene assicurata dal file lock in cui sono racchiuse le esatte versioni delle dipendenze scaricate durante la prima installazione. Poetry, inoltre, installa di default il progetto corrente in editable mode, permettendone l’interazione tramite l’interprete Python qualora fosse necessario.
Vediamo ora come integrare il tool all’interno di un nuovo progetto, partendo dalla sua installazione fino all’integrazione con il task runner Poe the Poet.
Come installo Poetry?
Nello specifico, la versione che andremo a utilizzare è la 1.2.2.
Seguendo la guida ufficiale, Poetry viene installato automaticamente in un ambiente Python dedicato, in modo da non interferire con altre installazioni presenti nella macchina.
Possiamo verificare l’esito dell’operazione eseguendo, da terminale, il comando poetry --version che ci restituirà, auspicabilmente, l’informazione relativa versione appena installata.
Come si utilizza Poetry?
Preparazione dell’ambiente
Creiamo un nuovo progetto poetry_demo e gestiamone l’ambiente Python attraverso il tool.
La struttura iniziale del nostro progetto è la seguente:
Sebbene Poetry permetta di creare un nuovo progetto tramite il comando poetry new <nome_progetto>, in questo tutorial optiamo per la creazione manuale in modo da vedere come utilizzare altri comandi basilari. Detto ciò, abbiamo aggiunto il modulo __main__.py per invocare più comodamente le funzioni che andremo a definire.
Nel primo paragrafo vi ho parlato del file in formato TOML. Come viene aggiunto questo file al progetto? La risposta è semplice, basta digitare il comando poetry init e, dopo aver risposto ad alcune semplici domande, otterremo un risultato simile a quello mostrato di seguito per il file pyproject.toml:
Procediamo ora alla creazione dell’ambiente Python. Poetry ci viene ovviamente incontro, mettendo a disposizione il comando poetry install che, come detto in precedenza, crea in automatico un ambiente Python in cui verranno installate le dipendenze richieste.
Riassumendo, in soli tre comandi abbiamo: inizializzato il progetto, definito il file che conterrà le sue dipendenze e creato un ambiente Python in cui installarle. Niente male!
Gestione delle dipendenze
Supponiamo ora di voler definire una semplice interfaccia da riga di comando tramite l’utilizzo del package click.
Poetry, tramite il comando poetry add click, non solo installerà la nuova libreria, la registrerà anche all’interno del file pyproject.toml.
Per il momento abbiamo aggiunto una sola dipendenza al nostro progetto, spesso però i pacchetti necessari sono tanti e tendono ad aumentare con il passare del tempo.
Per migliorare la leggibilità e la gestione delle dipendenze, potremmo suddividerle in gruppi distinti. Come esempio raggruppiamo le dipendenze utili solamente in fase di sviluppo nel gruppo dev, e a tale scopo possiamo inaugurare quest’ultimo aggiungendo al progetto il framework pytest, utile per la scrittura di test. Eseguiamo quindi il comando poetry add pytest --group dev in modo da poterne evitare l’installazione, qualora necessario, tramite il comando poetry install --without dev.
Tutte le modifiche fatte finora sono riportate nel file pyproject.toml, così aggiornato:
Plugin
Poe the Poet è un’interfaccia che serve a eseguire istruzioni definite direttamente all’interno del file pyproject.toml. Come avrete già intuito, è uno dei package disponibili per Poetry e tramite il comando poetry add poethepoet --group dev verrà installato nel nostro progetto, come dipendenza di sviluppo.
Non vi ho ancora parlato di formattazione del codice, un aspetto importante nel nostro lavoro. Anche per questo esiste un package, black, che importiamo alla stessa maniera degli altri: poetry add black --group dev.
Per utilizzare black da riga di comando dobbiamo definire il relativo comando per poethepoet, sempre all’interno del file pyproject.toml. Aggiungiamo quindi la sezione nel file:
[tool.poe.tasks]
format = "black poetry_demo"
Quanto fatto ora ci permette di eseguire il comando prescelto per la formattazione digitando, sempre da riga di comando, poe format. Ciò ci permette di evitare di dover ricorrere ad altri strumenti, come per esempio Makefile.
Conclusioni
Spero che questa breve introduzione a Poetry vi abbia dato modo di conoscere questo semplice e utile strumento che vi semplificherà la gestione dei progetti Python.