Publication d'un Paquet Python sur PyPI avec Poetry | Guide

Publication d'un paquet Python sur PyPI : Automatisation du processus avec Poetry

Publier son propre paquet Python sur le dépôt PyPI est une étape essentielle pour les développeurs qui souhaitent réutiliser leur code. L'outil Poetry simplifie grandement ce processus en gérant les dépendances et en construisant les artefacts. Ce guide couvre en détail la préparation du projet, la configuration de l'environnement et la publication du paquet, y compris le travail avec les jetons API et les dépendances optionnelles.

Configuration du compte et génération du jeton API

La première étape consiste à créer un compte sur le site officiel de PyPI. Après l'inscription, générez un jeton API pour l'authentification lors de la publication. Dans le tableau de bord de votre compte, allez à la section des jetons API et cliquez sur Generate API token. Indiquez un nom pour le jeton et sélectionnez son étendue. Pour les nouveaux projets, un jeton au niveau du compte (Entire account) convient bien car vous n'avez pas encore de paquets enregistrés. Important : Copiez le jeton généré immédiatement après sa création — il ne sera plus affiché par la suite.

Le processus de génération inclut :

• Connexion à votre compte PyPI
• Navigation vers la section de gestion des jetons API
• Spécification du nom et de l'étendue du jeton
• Confirmation de la création et sauvegarde de la valeur du jeton

Poetry utilisera ce jeton pour une publication sécurisée sans nécessiter votre identifiant et mot de passe. Stockez-le en toute sécurité, comme un mot de passe.

Initialisation du projet avec Poetry

Créez le répertoire racine du projet et configurez un environnement virtuel :

python3 -m venv .venv
source .venv/bin/activate

Installez Poetry via pip et lancez l'initialisation :

pip install poetry
poetry init

En mode interactif, fournissez les paramètres de base : nom du paquet, version, description, auteur et version Python supportée. Les principaux champs dans le fichier pyproject.toml généré :

• name — nom unique du paquet dans PyPI (doit correspondre au nom en snake_case du répertoire de code)
• version — version sémantique du paquet
• python — plage de versions d'interpréteur supportées
• readme — chemin vers le fichier de description
• packages — pointeur vers le répertoire de code source

Après l'initialisation, créez un répertoire pour le code (convertissez le name en remplaçant les tirets par des underscores) et ajoutez la structure de fichiers de base.

Structure et configuration du projet

Une structure de projet typique ressemble à ceci :

my-package/
├── LICENSE
├── poetry.lock
├── pyproject.toml
├── README.md
└── my_package/
    ├── __init__.py
    └── core.py

Il est absolument crucial que le nom du paquet dans pyproject.toml corresponde au nom du répertoire de code. Par exemple, pour name = "my-package", le répertoire doit s'appeler my_package. Dans le fichier __init__.py, il est recommandé d'importer les fonctions principales pour une utilisation aisée.

Exemple d'implémentation dans core.py :

PREPEND_STR = 'prepend_'

def modify_str(string: str) -> str:
    return f'{PREPEND_STR}{string}'

Assurez-vous d'ajouter un fichier de licence (de préférence MIT) et un README.md avec une description de la fonctionnalité. Verrouillez les dépendances avec poetry lock avant la publication.

Construction et publication du paquet

Avant le téléversement vers le dépôt, construisez les artefacts :

poetry build

Cette commande génère une distribution source (.tar.gz) et un fichier wheel (.whl) dans le répertoire dist/. Ensuite, configurez Poetry pour utiliser le jeton API :

poetry config pypi-token.pypi pypi-XXXXXXXX

Remplacez pypi-XXXXXXXX par votre jeton. Publiez maintenant :

poetry publish

Si la publication réussit, vous verrez une confirmation du téléversement sur PyPI. Vous pouvez vérifier la publication en cherchant sur le site PyPI ou en installant le paquet localement :

pip install my-package

Gestion des dépendances optionnelles

Pour implémenter des composants optionnels (installés via pip install package[extra]), configurez pyproject.toml comme ceci :

[tool.poetry.dependencies]
python = "^3.10"
pydantic = {version=">=1.9", optional = true}

[tool.poetry.extras]
pydantic = ["pydantic"]

Ici, la dépendance pydantic est marquée comme optionnelle avec optional = true, et la section extras crée un groupe pydantic qui inclut cette bibliothèque. Les utilisateurs peuvent installer les extras avec pip install my-package[pydantic].

Points clés

• Assurez une correspondance stricte entre le nom du paquet dans pyproject.toml et le nom du répertoire de code (tirets → underscores)
• Incluez toujours une licence et un README.md détaillé pour instaurer la confiance des utilisateurs
• Utilisez des jetons API au lieu de l'identifiant/mot de passe pour une publication sécurisée
• Pour les dépendances optionnelles, configurez correctement les sections dependencies et extras
• Avant la publication, vérifiez la construction avec poetry build

— Editorial Team