Come creare un package Python

Se ti stai chiedendo com creare un package, ovvero un pacchetto in Python sei nel posto giusto: ne parlo in questo articolo. Continua a leggere per scoprirlo!

Un package, ovvero un pacchetto Python, può essere una tua ambizione o hai semplicemente capito che il tuo stesso codice può essere di aiuto a tante persone.

Sì, se te lo stessi chiedendo, può anche essere un ottimo modo per iniziare a lavorare nel mondo dell’informatica o guadagnare mentre stai ancora studiando!

Ciò detto, per creare un package dobbiamo seguire una serie di passi ben definiti: scopriamo quali sono.

Ciao mi chiamo Lorenzo Neri e sono un informatico: realizzo contenuti per aiutare le persone a padroneggiare l’arte del nuovo millennio, ovvero l’informatica!

La struttura base

Un pacchetto prevede una struttura di file e cartelle basilare: segue la documentazione ufficiale sui pacchetti e moduli di Python.
Questa struttura base, prevede di dare un nome.

Il nome, è nient’altro che il nome del pacchetto.

E la struttura di cartelle e file che lo compongono, dev’essere come segue

package_esempio
 |________ nome_pacchetto
              |________ __init__.py

Per proseguire nell’articolo, accertati di essere all’interno della cartella “package_esempio” perché tutti i comandi che lanceremo saranno da eseguire al suo interno!

È probabile, nel frattempo che tu ti stia chiedendo: “Lorenzo ma a cosa serve il file __init__.py?”

Il file “__init__.py” è essenziale per far importare agli utilizzatori futuri del tuo pacchetto, come pacchetto Python a tutti gli effetti.

Trovi informazioni aggiuntive nel mio articolo 😉

Ah giusto: può essere anche un file vuoto per cominciare. Andiamo avanti

Creare i file del pacchetto

Per creare un package funzionante a tutti gli effetti, è necessario aggiungere altre cartelle e file all’interno di ciò che abbiamo già visto.

Per esempio la licenzia, il readme e anche i test.

Per fartela breve:

package_esempio
 |________ LICENSE
 |________ README.md
 |________ nome_pacchetto
              |________ __init__.py
 |________ setup.py
 |________ tests

Lo preciso per non creare confusione.

“tests” è una cartella, che serve per gli unit test del tuo pacchetto. Può essere lasciata vuota al momento.

Creare il file “setup.py”

Prima abbiamo aggiunto un altro file per dare vita al nostro Package.

Il file in questione è “setup.py”. Questo file serve per setuptools.

Per farla poco “tecnichese”, setuptools serve a specificare i dettagli (come nome e versione) del tuo pacchetto, così come di quali file ha bisogno per funzionare!

Per dare vita al package, è necessario inserire il seguente codice all’interno del file “setup.py”:

import setuptools
with open("README.md", "r", encoding="utf-8") as fh:
    long_description = fh.read()
setuptools.setup(
    name="nome_pacchetto-IL-TUO-NOME", # Ovviamente, metti il tuo nome ;)
    version="0.0.1",
    author="Esempio autore",
    author_email="la-tua@email.it",
    description="Un semplice esempio di pacchetto",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/ILTUOACCOUNT/ILTUOPACCHETTO",
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.7',
)

Cerchiamo di capire a cosa servono tutti questi dettagli dentro il file, specialmente la funzione “setup”:

• name è il nome del tuo pacchetto. Può contenere lettere, numeri, "_" , e “-". Inutile dirti che NON deve già essere presente su pypi.org. Assicurati che sia impostato anche il tuo username!
  
• version è la versione del pacchetto e ti consiglio di guardare PEP 440 per maggiori dettagli a riguardo.
  
• author e author_email ti lascio indovinare 😉
  
• description è una frase diciamo, che descrive le funzionalità del tuo pacchetto.
  
• long_description è una descrizione più dettagliata del tuo pacchetto. Possiamo anche dire una versione ridotta del README.
  
• long_description_content_type specifica che tipo di markup è usato per la descrizione lunga.
  
• url è l’indirizzo del progetto stesso che può essere il tuo account Github ad esempio!
  
• packages è la lista import packages che va inclusa nel Distribution Package. Anziché elencare i pacchetti manualmente, possiamo usare find_packages() per individuare tutti i packages e subpackages. Nel nostro caso, sarà solo example_pkg poiché è l’unico presente.
  
• classifiers danno all’index e a  pip offre maggiori meta-data sul tuo package.
  
  Nel nostro caso il pacchetto è compatibile con Python 3, licenza MIT, e indipendente da sistemi operativi.
  
  Devi includere sempre almeno le versioni Python con cui il tuo pacchetto funziona e con quali sistemi operativi.
  
  Se vuoi una lista completa di classifies, la trovi qui: https://pypi.org/classifiers/.

Come distribuire un package Python

Dopo aver creato tutto questo ben di dio, dobbiamo anche distribuirlo!

Dobbiamo creare un distribution packages per il pacchetto. Questi archivi sono caricati sul Package Index così che possa essere installato con pip.

Assicurati di avere installato setuptools e wheel prima di procedere:

python3 -m pip install --user --upgrade setuptools wheel

A questo punto, nella cartella del nostro package, o dove hai inserito il file “setup.py” lancia il seguente comando:

python3 setup.py sdist bdist_wheel

Questo comando, genera un sacco di testo e una volta completato, creerà due file nella cartella “dist”:

dist/
  nome_pacchetto-IL-TUO-NOME-0.0.1-py3-none-any.whl
  nome_pacchetto-IL-TUO-NOME-0.0.1.tar.gz

Il file “tar.gz” è l’archivio del codice sorgente.

Il file “.whl” è la distribuzione compilata del tuo pacchetto, in genere pip nelle sue versioni più nuove preferisce questa variante.

Come caricare e rendere disponibile il nostro package

Arrivati a questo punto, abbiamo creato il nostro package Python: dobbiamo renderlo pubblico.

Come? Registrandoti su “Test PyPI”, a distanza di un click qui: https://informatico.pypi.org/account/register

Una volta registrato e ottenuto il tuo API token puoi usare “twine” per eseguire l’upload:

python3 -m pip install --user --upgrade twine

Una volta installato, carichiamo l’intera cartella “dist” generata prima:

python3 -m twine upload --repository informaticopypi dist/*

Se la procedura è andata a buon fine, il tuo pacchetto sarà disponibile al seguente link:

https://informatico.pypi.org/project/nome_pacchetto-IL-TUO-NOME

Come far installare il tuo pacchetto

Per concludere, dopo aver visto come creare e caricare il tuo package Python, vorrai farlo usare alle persone no? 😀

Beh, dovranno lanciare il seguente comando:

python3 -m pip install --index-url https://informatico.pypi.org/simple/ --no-deps nome_pacchetto-IL-TUO-NOME