Comment créer votre tout premier package Python

Il y a quelques mois, j'ai décidé de sortir Caer, un package Computer Vision disponible en Python. J'ai trouvé le processus extrêmement douloureux. Vous pouvez probablement deviner pourquoi — peu de documentation (et déroutante), manque de bons tutoriels, etc.

J'ai donc décidé d'écrire cet article dans l'espoir qu'il aidera les personnes qui ont du mal à y parvenir. Nous allons créer un module très simple et le rendre accessible à tous dans le monde.

Le contenu de ce module suit une structure très basique. Il existe au total quatre fichiers Python, chacun contenant une seule méthode. Nous allons garder cela très simple pour l’instant.

base-verysimplemodule  --> Base
└── verysimplemodule   --> Actual Module
    ├── extras
    │   ├── multiply.py
    │   ├── divide.py
    ├── add.py
    ├── subtract.py

Vous remarquerez que j'ai un dossier appelé verysimplemodule qui, à son tour, contient deux fichiers Python add.py et subtract.py. Il existe également un dossier appelé extras (qui contient multiply.py et divide.py). Ce dossier constituera la base de notre module Python.

Faire ressortir les inits

Quelque chose que vous trouverez toujours dans chaque package Python est un fichier __init__.py. Ce fichier indiquera à Python de traiter les répertoires comme des modules (ou sous-modules).

Très simplement, il contiendra les noms de toutes les méthodes de tous les fichiers Python qui se trouvent dans son répertoire immédiat.

Un fichier __init__.py typique a le format suivant :

from file import method 

# 'method' is a function that is present in a file called 'file.py'

Lors de la création de packages en Python, vous devez ajouter un fichier __init__.py dans chaque sous-répertoire de votre package. Ces sous-répertoires sont les sous-modules de votre package.

Dans notre cas, nous ajouterons nos fichiers __init__.py au répertoire « module actuel » verysimplemodule, comme ceci :

from add import add
from subtract import subtract

et nous allons faire la même chose pour le dossier extras, comme ceci :

from multiply import multiply
from divide import divide

Une fois cela fait, nous sommes à peu près à la moitié du processus !

Comment configurer setup.py

Dans le dossier base-verysimplemodule (et dans le même répertoire que notre module verysimplemodule ), nous devons ajouter un fichier setup.py. Ce fichier est essentiel si vous avez l'intention de construire le module en question.

Remarque : N'hésitez pas à nommer le fichier setup.py comme vous le souhaitez. Ce fichier n'est pas spécifique à un nom comme l'est notre fichier __init__.py.

Les choix de noms possibles sont setup_my_very_awesome_python_package.py et python_package_setup.py , mais il est généralement préférable de s'en tenir à setup.py.

Le fichier setup.py contiendra des informations sur votre package, en particulier le nom du package, sa version, les dépendances de la plate-forme et bien d'autres choses encore. plus.

Pour nos besoins, nous n’aurons pas besoin de méta-informations avancées, le code suivant devrait donc convenir à la plupart des packages que vous créez :

from setuptools import setup, find_packages

VERSION = '0.0.1' 
DESCRIPTION = 'My first Python package'
LONG_DESCRIPTION = 'My first Python package with a slightly longer description'

# Setting up
setup(
       # the name must match the folder name 'verysimplemodule'
        name="verysimplemodule", 
        version=VERSION,
        author="Jason Dsouza",
        author_email="<youremail@email.com>",
        description=DESCRIPTION,
        long_description=LONG_DESCRIPTION,
        packages=find_packages(),
        install_requires=[], # add any additional packages that 
        # needs to be installed along with your package. Eg: '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",
        ]
)

Cela fait, il ne nous reste plus qu'à exécuter la commande suivante dans le même répertoire que base-verysimplemodule :

python setup.py sdist bdist_wheel

Cela créera tous les packages nécessaires dont Python aura besoin. Les commandes sdist et bdist_wheel créeront une distribution source et une roue que vous pourrez ensuite télécharger sur PyPi.

PyPi — nous voilà !

PyPi est le référentiel Python officiel où tous les packages Python sont stockés. Vous pouvez le considérer comme le Github pour les packages Python.

Pour rendre votre package Python accessible aux personnes du monde entier, vous devez disposer d'un compte avec PyPi.

Cela fait, nous sommes tous prêts à télécharger notre package sur PyPi. Vous vous souvenez de la distribution source et de la roue qui ont été construites lorsque nous avons exécuté python setup.py ? Eh bien, c'est ce qui sera réellement téléchargé sur PyPi.

Mais avant de faire cela, vous devez installer twine si vous ne l'avez pas déjà installé. C'est aussi simple que pip install twine.

Comment télécharger votre package sur PyPi

En supposant que twine soit installé, continuez et exécutez :

twine upload dist/*

Cette commande téléchargera le contenu du dossier dist qui a été automatiquement généré lorsque nous avons exécuté python setup.py. Vous recevrez une invite vous demandant votre nom d'utilisateur et votre mot de passe PyPi, alors allez-y et saisissez-les.

Maintenant, si vous avez suivi ce didacticiel jusqu'au bout, vous pourriez obtenir une erreur du type le référentiel existe déjà.

Cela est généralement dû à un conflit de noms entre le nom de votre package et celui d'un package qui existe déjà. En d'autres termes, changez le nom de votre package — quelqu'un d'autre a déjà pris ce nom.

Et c'est tout!

Pour installer fièrement votre module avec pip, lancez un terminal et exécutez :

pip install <package_name> 

# in our case, this is
pip install verysimplemodule

Regardez comment Python installe proprement votre package à partir des binaires générés précédemment.

Ouvrez un shell interactif Python et essayez d'importer votre package :

>> import verysimplemodule as vsm

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

Pour accéder aux méthodes de division et de multiplication (rappelez-vous qu'elles se trouvaient dans un dossier appelé extras ?), exécutez :

>> import verysimplemodule as vsm

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

C'est aussi simple que ça.

Toutes nos félicitations! Vous venez de créer votre premier package Python. Bien que très simple, votre package peut désormais être téléchargé par n'importe qui dans le monde (à condition qu'il dispose de Python, bien sûr).

Et après?

Tester PyPi

Le package que nous avons utilisé dans ce didacticiel était un module extrêmement simple — opérations mathématiques de base d'addition, de soustraction, de multiplication et de division. Cela n'a pas de sens de les télécharger directement sur PyPi surtout que vous essayez cela pour la première fois.

Heureusement pour nous, il existe Test PyPi, une instance distincte de PyPi où vous pouvez tester et expérimenter votre package (vous devrez créer un compte distinct sur la plateforme).

Le processus que vous suivez pour télécharger sur Test PyPi est à peu près le même avec quelques modifications mineures.

# The following command will upload the package to Test PyPi
# You will be asked to provide your Test PyPi credentials

twine upload --repository testpypi dist/*

Pour télécharger des projets depuis Test PyPi :

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

Méta-informations avancées

Les méta-informations que nous avons utilisées dans le fichier setup.py étaient très basiques. Vous pouvez ajouter des informations supplémentaires telles que plusieurs responsables (le cas échéant), l'e-mail de l'auteur, les informations de licence et toute une série d'autres données.

Cet article s’avérera particulièrement utile si vous avez l’intention de le faire.

Regardez d'autres référentiels

Regarder comment d'autres référentiels ont construit leurs packages peut s'avérer très utile pour vous.

Lors de la construction de Caer, je regardais constamment comment Numpy et Sonnet configuraient leurs packages. Je recommanderais de jeter un œil aux référentiels de Caer, Numpy et Tensorflow si vous envisagez de créer des packages légèrement plus avancés.