Création de packages distribuables (wheels, source distributions)

Pourquoi créer un package distribuable ?

Lorsque vous développez un projet Python que vous souhaitez partager avec d'autres (que ce soit des collègues, des collaborateurs, ou la communauté open source), il est important de le packager correctement.

Un package distribuable est une archive (un fichier compressé) qui contient tout le nécessaire pour installer et utiliser votre code :

• Le code source de votre projet (modules et packages).
• Les métadonnées du projet (nom, version, auteur, description, etc.).
• Les dépendances (si votre projet utilise d'autres bibliothèques).
• (Optionnellement) Des fichiers de données, des scripts exécutables, etc.

En créant un package distribuable, vous permettez aux autres d'installer facilement votre code avec `pip` :

pip install votre_package

Il existe deux principaux formats de distribution pour les packages Python :

• Source distributions (sdist) : Une archive contenant le code source de votre projet. Lors de l'installation, le code source doit être compilé (si nécessaire) et installé.
• Built distributions (wheel) : Une archive contenant une version "construite" (built) de votre projet, prête à être installée. Le format wheel (`.whl`) est le format standard pour les distributions binaires Python. Il permet une installation plus rapide et plus fiable que les distributions source.

Outils pour créer des packages : setuptools et build

Les outils principaux pour créer des packages Python sont :

• `setuptools` : Une bibliothèque Python qui fournit des outils pour construire, distribuer et installer des packages Python. C'est l'outil "traditionnel" pour le packaging Python.
• `build` : Un outil plus récent (PEP 517) pour construire des packages Python à partir d'un projet (en utilisant un backend de build, comme `setuptools`, `flit`, `poetry`, etc.). `build` est recommandé pour construire des packages à partir de la ligne de commande.

Vous aurez également besoin de `wheel` pour construire des distributions au format wheel.

Installation des outils :

pip install setuptools wheel build

Pour créer un package, vous devez d'abord décrire votre projet et ses métadonnées. Cela se fait traditionnellement dans un fichier `setup.py` (avec `setuptools`), ou de plus en plus avec un fichier `pyproject.toml` (standard moderne).

Nous avons déjà vu des exemples de `setup.py` et `pyproject.toml` dans la section précédente.

Créer une distribution source (sdist)

Une distribution source (sdist) contient le code source de votre projet, ainsi que les fichiers nécessaires pour le construire (comme `setup.py` ou `pyproject.toml`).

Pour créer une distribution source, vous pouvez utiliser la commande suivante (si vous avez un `setup.py`) :

python setup.py sdist

Ou, de manière plus moderne (et recommandée), avec `build` et un fichier `pyproject.toml` :

python -m build --sdist

Cela créera une archive `.tar.gz` (sur Unix/macOS) ou `.zip` (sur Windows) dans un sous-répertoire `dist/`.

Lorsqu'un utilisateur installe une distribution source avec `pip`, `pip` doit d'abord construire le projet (compiler le code C, si nécessaire), puis l'installer. Cela peut prendre plus de temps que d'installer une distribution binaire (wheel).

Créer une distribution binaire (wheel)

Une distribution binaire (wheel) contient une version "construite" (built) de votre projet, prête à être installée. Elle contient le code compilé (si nécessaire), ainsi que les métadonnées du projet.

Le format wheel (`.whl`) est un format standardisé pour les distributions binaires Python. Il permet une installation plus rapide et plus fiable que les distributions source, car il n'est pas nécessaire de compiler le code lors de l'installation.

Pour créer une distribution wheel, vous pouvez utiliser la commande suivante (si vous avez un `setup.py`) :

python setup.py bdist_wheel

Ou, de manière plus moderne (et recommandée), avec `build` et un fichier `pyproject.toml` :

python -m build --wheel  # Ou simplement : python -m build

Cela créera un fichier `.whl` dans un sous-répertoire `dist/`.

Il est recommandé de distribuer à la fois une distribution source et une distribution wheel, pour assurer la compatibilité avec différents systèmes et différentes versions de Python.

Construire les deux formats (sdist et wheel) en une seule commande

Avec `build`, la commande la plus simple pour construire à la fois une distribution source et une distribution wheel est :

python -m build

Cela créera les deux types de distributions dans le répertoire `dist/`.

Installer un package localement (pour le développement)

Si vous voulez installer votre package localement (par exemple, pour le tester avant de le publier), vous pouvez utiliser `pip` avec l'option `-e` (editable) :

pip install -e .

Cela installera votre package en "mode développement". Les modifications que vous apporterez au code source seront immédiatement prises en compte, sans avoir besoin de réinstaller le package.

Notez le point (`.`) à la fin de la commande, qui indique que le package à installer se trouve dans le répertoire courant.

Publier un package sur PyPI (Python Package Index)

Une fois que vous avez créé des distributions de votre package (sdist et wheel), vous pouvez les publier sur PyPI (Python Package Index), le dépôt central de packages Python. Cela permettra à d'autres utilisateurs d'installer votre package avec `pip install votre_package`.

Pour publier un package sur PyPI, vous aurez besoin de :

• Créer un compte sur PyPI (pypi.org).
• Installer l'outil `twine` : `pip install twine`.
• Construire les distributions de votre package (avec `python -m build`).
• Utiliser `twine` pour téléverser les distributions sur PyPI : `twine upload dist/*`.

Consultez la documentation de PyPI et de `twine` pour des instructions détaillées sur la publication de packages.