Poetry : gérer les dépendances et publier un paquet Python

Définition

Écrire du code Python demande vite plus que du code : déclarer les bibliothèques utilisées, vérifier que leurs versions tiennent ensemble, les installer dans un environnement dédié, puis publier le résultat. La chaîne classique répond à ces besoins avec quatre outils séparés, que Poetry regroupe sous une seule commande.

Tout part d'un fichier unique, pyproject.toml, standardisé par une PEP et commun à l'écosystème. Poetry le lit et s'en sert pour trouver des versions compatibles, créer l'environnement virtuel qui les accueille, et fabriquer l'archive à publier.

Voici à quoi ressemble un tout premier usage, du projet vide au script qui tourne.

poetry new mon-projet              # crée pyproject.toml
cd mon-projet
poetry add requests                # résout, installe, verrouille
poetry run python -m mon_projet    # exécute dans l'environnement du projet

Ce que ces lignes remplacent : venv pour l'isolation, pip pour l'installation, requirements.txt pour la liste des dépendances, et le trio setup.py, wheel, twine pour publier sur PyPI. Moins de fichiers à synchroniser, moins de risques de les voir diverger.

Déclarer n'est pas résoudre

Voici la distinction qui justifie l'outil. Un fichier produit par pip freeze ne dit pas ce que le projet demande : il photographie ce qui se trouvait sur un ordinateur un jour donné, sans distinguer ce qui a été voulu de ce qui a été tiré derrière.

Poetry sépare les deux dans deux fichiers. Le premier, pyproject.toml, contient l'intention : par exemple, « ce projet a besoin de requests en version 2.x ». Le second, poetry.lock, contient le résultat du calcul, les versions exactes retenues pour tout l'arbre. Le premier se modifie à la main, le second jamais.

Le tableau résume ce que chaque approche garde, et ce qu'elle laisse au hasard.

Ce que le tableau ne montre pas, c'est la conséquence dans le temps : installer depuis le verrou redonne le même arbre six mois plus tard, sur une autre machine ou en intégration continue. Une simple liste de dépendances ne garantit rien de tel.

Les commandes du quotidien

Le manuel de Poetry compte plusieurs dizaines de commandes. Six suffisent à couvrir une semaine de travail ordinaire.

poetry add pandas               # ajoute, résout, installe, met à jour le verrou
poetry add --group dev pytest   # dépendance de développement seulement
poetry remove pandas            # retire le paquet et ce qu'il avait tiré
poetry install                  # rejoue le verrou à l'identique
poetry update                   # recalcule, dans les bornes déclarées
poetry run pytest               # exécute dans l'environnement du projet

Séparer dépendances normales et dépendances de développement répond à une vraie question : pourquoi installer pytest ou ruff sur le serveur de production, si personne n'y lance jamais de test ? Les ranger dans un groupe de développement règle le problème : ils s'installent chez vous, pas sur le serveur.

Deux autres commandes concernent la publication d'un package : poetry build fabrique l'archive, poetry publish l'envoie sur le dépôt. Elles remplacent un setup.py écrit à la main et deux outils supplémentaires.

L'erreur du premier jour

Elle est presque toujours la même : l'environnement existe bel et bien, mais le terminal, lui, n'est pas dedans. La commande d'ajout a installé la bibliothèque au bon endroit, puis python script.py lancé juste après passe par le Python du système, qui n'en a jamais entendu parler. Résultat, une ModuleNotFoundError sur une ligne d'import pourtant correcte.

Il suffit de préfixer la commande par poetry run, qui l'exécute dans l'environnement du projet. Cette forme fonctionne quelle que soit la version de l'outil, contrairement aux commandes de sous-shell renommées au fil des versions. Dans un éditeur, le réflexe équivalent consiste à sélectionner l'interpréteur du projet ; poetry env info --path en donne le chemin.

Quand il ne sert à rien

Un utilitaire de quarante lignes qui importe deux bibliothèques n'a rien à verrouiller : un seul arbre de dépendances est possible, trop simple pour réclamer un calcul. Un environnement virtuel et pip suffisent ; un verrou de plus n'ajoute qu'un fichier inutile.

Il y a aussi des cas où l'outil se met en travers du chemin : une chaîne de déploiement qui n'accepte qu'une liste de dépendances classique, un hébergeur qui ne lit que ce format-là, une équipe scientifique dont la moitié des paquets sont des binaires que conda installe mieux.

Alors, à partir de quand un verrou devient-il utile ? Dès que deux personnes installent le même projet, ou que le même projet s'installe sur deux machines à deux dates différentes.

Questions fréquentes

Oui pour une application, dont le but est de se réinstaller à l'identique partout. Pour une bibliothèque installée chez d'autres, le verrou ne sert qu'à vos tests : ce sont les bornes de version déclarées qui font foi.

Parce que trouver un jeu de versions compatibles est un problème combinatoire : l'outil récupère des métadonnées, essaie une combinaison, revient en arrière dès qu'une contrainte en contredit une autre. Ce calcul n'a lieu qu'une fois ; les installations suivantes se contentent de le rejouer.

Oui, et c'est même le cas normal. La commande de construction produit une archive standard, que n'importe qui installe ensuite avec pip. Une installation lancée à la main dans l'environnement du projet fonctionne, mais rien ne l'inscrit dans le verrou : elle disparaîtra à la prochaine reconstruction. Le module ajouté ainsi n'existe que sur votre machine.