Articolo originale: How to Build Your Very First Python Package

Alcuni mesi fa, ho deciso di rilasciare Caer, un pacchetto (package) per la visione artificiale (computer vision) disponibile in Python. Ho trovato l'intero processo estremamente complicato e frustrante. Probabilmente puoi immaginarne il motivo: documentazione scarsa (e confusa), mancanza di buoni tutorial, e così via.

Ho così deciso di scrivere questo articolo nella speranza di aiutare chi sta affrontando le stesse difficoltà nel creare un package in Python. Realizzeremo un modulo molto semplice e lo renderemo disponibile a chiunque in tutto il mondo.  

Il contenuto di questo modulo segue una struttura molto basilare. In totale sono riportati quattro file Python, ciascuno dei quali contiene un singolo metodo. Per questo tutorial adottiamo appositamente uno schema molto semplice.

base-verysimplemodule  --> Cartella base
└── verysimplemodule   --> Modulo effettivo
    ├── extras
    │   ├── multiply.py
    │   ├── divide.py
    ├── add.py
    ├── subtract.py

Puoi notare che abbiamo una cartella chiamata  verysimplemodule, la quale, a sua volta, contiene i due file Python add.py e subtract.py. C'è anche una sottocartella chiamata extras (che contiene i file multiply.py e divide.py). La cartella verysimplemodule costituirà la base del nostro modulo Python.

Creare i file __ init __.py

Una cosa che si trova sempre in qualsiasi package di Python è un file  __init__.py. Questo file comunica a Python di considerare le cartelle come moduli (o sotto-moduli).

Molto semplicemente, questo file conserva i nomi di tutti i metodi contenuti in tutti i file Python che si trovano nella sua stessa cartella.

Un tipico file __init__.py ha il seguente formato:

from file import method 

# 'method' è un funzione presente nel file denominato 'file.py'

Per creare un package in Python, occorre aggiungere un file __init__.py  in ogni sottocartella del tuo package. Queste sottocartelle diventano i sottomoduli del tuo package.

Nel nostro caso, aggiungiamo i nostri file __init__.py alla cartella del modulo effettivo, denominata verysimplemodule, in questo modo:

from add import add
from subtract import subtract

e facciamo lo stesso per la sottocartella extras, in questo modo:

from multiply import multiply
from divide import divide

Una volta fatto questo, siamo praticamente a metà dell'opera!

Come impostare il file setup.py

All'interno della cartella base-verysimplemodule (e nella stessa cartella del nostro modulo verysimplemodule), dobbiamo aggiungere il file setup.py. Questo file è essenziale se si intende effettuare il build del modulo in questione.

Nota: si può nominare il file setup.py a piacimento. Questo file non deve avere un nome specifico, a differenza del file __init__.py.

Alcune possibili scelte per il nome possono essere setup_my_very_awesome_python_package.py e python_package_setup.py, ma di solito è buona pratica utilizzare setup.py.

Il file setup.py conterrà informazioni sul tuo package, specificamente il nome del package, la sua versione, le dipendenze dalle diverse piattaforme e molto altro.

Per i nostri scopi, non sono richieste meta-informazioni avanzate, così il seguente codice dovrebbe andare bene per la maggior parte dei pacchetti che creerai:

from setuptools import setup, find_packages

VERSION = '0.0.1' 
DESCRIPTION = 'Il mio primo package in Pyhton'
LONG_DESCRIPTION = 'Il mio primo package in Python con una descrizione un po più lunga'

# Impostazioni
setup(
       # il nome deve essere uguale a quello della cartella 'verysimplemodule'
        name="verysimplemodule", 
        version=VERSION,
        author="Jason Dsouza",
        author_email="<youremail@email.com>",
        description=DESCRIPTION,
        long_description=LONG_DESCRIPTION,
        packages=find_packages(),
        install_requires=[], # aggiungi qualsiasi package addizionale che 
        # deve essere installato insieme al tuo package. Ad Es. 'caer'
        
        keywords=['python', 'first package'],
        classifiers= [
            "Development Status :: 3 - Alpha",
            "Intended Audience :: Education",
            "Programming Language :: Python :: 2",
            "Programming Language :: Python :: 3",
            "Operating System :: MacOS :: MacOS X",
            "Operating System :: Microsoft :: Windows",
        ]
)

Una volta fatto questo, possiamo lanciare il seguente comando nella stessa cartella di base-verysimplemodule:

python setup.py sdist bdist_wheel

Questo comando permetterà di effettuare il build di tutti i pacchetti necessari richiesti da Python. Il comandi sdist e bdist_wheel permettono di creare una distribuzione sorgente (source distribution) e una distribuzione binaria in formato wheel (.whl) che potrai successivamente caricare su PyPi.

PyPi — eccoci arrivati!

PyPi è l'archivio ufficiale di Python dove sono conservati tutti i package Python. Si può considerarlo un pò come il Github per i Package di Python.

Per rendere il tuo package disponibile agli utenti in tutto il mondo, devi attivare un account PyPi.

Fatto ciò, saremo pronti per caricare il nostro package su PyPi. Ricordi la distribuzione sorgente e la distribuzione binaria Wheel che sono state costruite quando è stato lanciato il comando python setup.py? Bene, è proprio ciò che verrà effettivamente caricato su PyPi.

Ma prima di fare tutto questo, devi installare twine se non lo hai già installato. L'operazione è molto semplice e si esegue lanciando il comando pip install twine.

Come caricare il tuo package su PyPi

Assumendo di avere installato twine , procediamo lanciando il seguente comando:

twine upload dist/*

Questo comando caricherà i contenuti della cartella dist, che è stata generata automaticamente quando abbiamo lanciato il comando python setup.py. Verrà visualizzato un prompt che chiederà lo username e la password dell'account PyPi, quindi procediamo ed inseriamoli come richiesto.

A questo punto, se hai seguito questo tutorial alla lettera, potresti ottenere un errore del tipo il repository è già esistente.

Questo accade di solito perché c'è un conflitto tra i nomi del tuo package e di un package già esistente. In altre parole, cambia il nome del tuo package - quel nome è già stato utilizzato.

Ed è tutto!

Per installare orgogliosamente il tuo modulo tramite pip, avvia un terminale e lancia il comando:

pip install <nome_package> 

# nel nostro caso:
pip install verysimplemodule

Osserva come Python installa accuratamente il tuo package dai file binari che sono stati generati prima.

Apri una shell interattiva di Python e prova ad importare il tuo package:

>> import verysimplemodule as vsm

>> vsm.add(2,5)
7
>> vsm.subtract(5,4)
1

Per accedere ai metodi per divisione emoltiplicazione ( ricordi che erano in una sottocartella chiamata extras?), lancia il comandi:

>> import verysimplemodule as vsm

>> vsm.extras.divide(4,2)
2
>> vsm.extras.multiple(5,3)
15

È proprio così semplice.

Congratulazioni! Hai appena creato il tuo primo package in Python. Anche se molto semplice, il tuo package è adesso disponibile per il download da chiunque in tutto il mondo (premesso che abbia Python, ovviamente).

Qual è il prossimo passo?

Test PyPi

Il package che abbiamo usato in questo tutorial era un modulo estremamente semplice - le operazioni matematiche basilari di addizione, sottrazione, moltiplicazione e divisione. Non ha senso caricarlo direttamente in PyPi specialmente se lo stai provando per la prima volta.

Fortunatamente per noi, esiste Test PyPi, una istanza separata di PyPi dove puoi testare e sperimentare il tuo pacchetto (è necessario iscriverti ad un account separato sulla piattaforma).

Il processo da seguire per caricare su Test PyPi è praticamente lo stesso, con qualche piccola modifica.

# Il seguente comando caricherà il package su Test PyPi
# Ti verrà chiesto di fornire le tue credenziali di accesso a Test PyPi

twine upload --repository testpypi dist/*

Per scaricare progetti da Test PyPi:

pip install --index-url "https://test.pypi.org/simple/<nome_package>"

Meta-informazioni avanzate

Le meta-informazioni che abbiamo usato nel file setup.py erano molto basilari. Puoi aggiungere ulteriori informazioni come manutentori multipli (se ci sono), email dell'autore, informazioni sulla licenza ed un gran numero di altri dati.

Questo articolo si rivelerà particolarmente utile se intendi farlo.

Dai un'occhiata ad altri repository

Vedere come gli altri repository hanno costruito i loro pacchetti si può rivelare molto utile.

Mentre realizzavo Caer, osservavo costantemente come Numpy e Sonnet impostavano il loro pacchetti. Raccomanderei di dare un'occhiata ai repository di Caer, Numpy e Tensorflow se stai pianificando di realizzare pacchetti leggermente più avanzati.