Poetry le gestionnaire

Mise à jour : 18/11/2024

Vous connaissez ce casse-tête : configurer vos projets Python, jongler entre des versions de bibliothèques incompatibles et des fichiers requirements.txt interminables ? Moi aussi, j’en ai perdu quelques cheveux. Mais un jour, j’ai découvert Poetry. Cet outil a tout changé : fini le chaos, place à l’organisation et à la simplicité.

Imaginez un majordome dédié à vos projets Python : il s’occupe de tout pour vous, des dépendances aux environnements virtuels, en passant par le packaging. Voilà, c’est Poetry ! Un outil pensé pour simplifier la vie des développeurs, qu’ils soient débutants ou expérimentés.

Un peu d’Histoire

Poetry est né d’un constat simple : gérer les projets Python devenait un véritable parcours du combattant. Entre les environnements virtuels à créer à la main, les fichiers requirements.txt souvent bancals et les outils existants comme pip ou pipenv, il manquait un outil tout-en-un, simple et fiable. C’est là qu’intervient Sébastien Eustace, un développeur qui, en 2018, décide de prendre les choses en main et de créer Poetry.

Son idée ? Proposer une alternative qui regroupe le meilleur des deux mondes : la gestion des dépendances et des environnements virtuels, tout en intégrant des pratiques modernes comme le fichier pyproject.toml introduit par PEP 518. En quelques années, Poetry a séduit la communauté Python grâce à son approche élégante et efficace.

Aujourd’hui, Poetry est maintenu par une communauté active et se positionne comme une référence incontournable. Ce succès témoigne d’un besoin clair dans l’écosystème Python : des outils simples qui permettent de se concentrer sur l’essentiel, c’est-à-dire coder. Et franchement, qui ne préfère pas une bonne dose de simplicité ?

Fonctionnalités de Poetry

Voici les principales fonctionnalités qui rendent Poetry indispensable :

Gestion des dépendances intelligente : Ajout, suppression, et mise à jour des bibliothèques avec gestion automatique des conflits de versions.
Fichier pyproject.toml : Centralisation des dépendances, des métadonnées du projet et des configurations de build.
Environnements virtuels intégrés : Création et gestion automatique d’environnements isolés pour chaque projet.
Packaging pour PyPI : Génération et publication de packages prêts à être distribués sur la plateforme PyPI.
Versionnement sémantique : Gestion simplifiée des versions du projet, avec incréments automatiques selon les règles de versionnement sémantique.
Support des environnements multiples : Organisation des dépendances par groupe, selon les besoins (développement, production, tests, etc.).
Scripts intégrés : Automatisation des tâches avec des commandes configurables directement dans le fichier de projet.

Avec ces fonctionnalités, Poetry s’impose comme un outil complet et polyvalent pour tout projet Python.

Installation

L’installation de Poetry est rapide et accessible, quel que soit votre système. Voici un guide détaillé pour vous accompagner pas à pas, avec une mention spéciale pour les fans de asdf-vm.

Prérequis

Avant d’installer Poetry, assurez-vous d’avoir :

Python 3.7 ou supérieur : Poetry ne fonctionne pas avec des versions antérieures. Vous pouvez vérifier votre version de Python avec :
Terminal window
```
python3 --version
```
Un gestionnaire de téléchargement : Soit curl (pour les commandes shell), soit pip (préinstallé avec Python).
Facultatif : Si vous utilisez déjà [asdf-vm](/docs/outils/systeme/asdf-vm/ pour gérer vos versions d’outils et langages, Poetry dispose d’un plugin officiel. On y revient plus tard dans ce chapitre.

Méthode standard

La manière la plus simple et universelle d’installer Poetry est d’utiliser le script officiel. Exécutez la commande suivante :

curl -sSL https://install.python-poetry.org | python3 -

Ce script télécharge et configure Poetry pour qu’il soit utilisable sur votre machine. Par défaut, il installe Poetry dans ~/.local/bin sur Linux/MacOS ou %APPDATA%\Python\Scripts sur Windows.

Vérification de l’installation

Pour vérifier que l’installation s’est bien déroulée, lancez :

poetry --version

Si tout fonctionne, vous verrez un message indiquant la version installée de Poetry.

Si la commande poetry n’est pas reconnue, il se peut que son emplacement ne soit pas dans le PATH de votre système. Voici comment l’ajouter :

Linux/MacOS : Ajoutez cette ligne dans votre fichier ~/.bashrc ou ~/.zshrc :
Terminal window
```
export PATH="$HOME/.local/bin:$PATH"
```
Rechargez ensuite votre shell avec :
Terminal window
```
source ~/.bashrc
```
Windows : Ajoutez %APPDATA%\Python\Scripts au PATH via les paramètres système.

Méthode alternative : installation avec asdf

Si vous utilisez asdf-vm, un gestionnaire polyvalent pour les versions de langages et d’outils, vous pouvez installer Poetry en tant que plugin. Voici comment :

Assurez-vous que [asdf-vm](/docs/outils/systeme/asdf-vm/ est installé sur votre machine.
Ajoutez le plugin Poetry à asdf avec la commande :
Terminal window
```
asdf plugin add poetry
```
Installez la version souhaitée de Poetry :
Terminal window
```
asdf install poetry latest
```
Définissez cette version comme globale (ou locale pour un projet spécifique) :
Terminal window
```
asdf global poetry latest
```
Vérifiez l’installation :
Terminal window
```
poetry --version
```

Utiliser asdf est une excellente solution si vous travaillez sur plusieurs projets nécessitant différentes versions de Poetry. Cela garantit un environnement propre et cohérent.

Utilisation de base

Maintenant que Poetry est installé, il est temps de passer à l’action et de découvrir les bases de son utilisation. Que vous souhaitiez initialiser un projet, ajouter des dépendances, ou gérer vos environnements virtuels, Poetry rend tout cela simple et fluide.

Initialiser un projet

La première étape pour utiliser Poetry est de créer un projet. Poetry configure tout pour vous, générant un fichier pyproject.toml pour centraliser la configuration.

poetry init

Vous serez guidé à travers une série de questions interactives :

Nom du projet
Version initiale
Description
Auteur(s)
Dépendances et compatibilité Python

Si vous préférez sauter les questions, utilisez l’option --no-interaction pour une initialisation rapide avec des valeurs par défaut.

Ajouter des dépendances

Besoin d’ajouter une bibliothèque à votre projet ? Poetry rend cela incroyablement simple. Par exemple, pour installer Flask :

poetry add flask
Creating virtualenv test-poetry-wuC4HPt9-py3.12 in /home/bob/.cache/pypoetry/virtualenvs
Using version ^3.1.0 for flask

Updating dependencies
Resolving dependencies... (0.4s)

Package operations: 7 installs, 0 updates, 0 removals

  - Installing markupsafe (3.0.2)
  - Installing blinker (1.9.0)
  - Installing click (8.1.7)
  - Installing itsdangerous (2.2.0)
  - Installing jinja2 (3.1.4)
  - Installing werkzeug (3.1.3)
  - Installing flask (3.1.0)

Writing lock file

Quelques points à noter :

Poetry télécharge automatiquement la version compatible la plus récente.
Les dépendances sont ajoutées au fichier pyproject.toml.
Vous pouvez spécifier une version particulière ou un intervalle, comme flask@^2.0.

Pour des dépendances spécifiques à un environnement (par exemple, des outils de développement) :

poetry add pytest --group dev

Using version ^8.3.3 for pytest

Updating dependencies
Resolving dependencies... (0.2s)

Package operations: 4 installs, 0 updates, 0 removals

  - Installing iniconfig (2.0.0)
  - Installing packaging (24.2)
  - Installing pluggy (1.5.0)
  - Installing pytest (8.3.3)

Writing lock file

Poetry crée un fichier poetry.lock, qui verrouille les versions exactes des bibliothèques installées pour garantir la reproductibilité.

Gestion des environnements virtuels

Un des avantages majeurs de Poetry est sa gestion intégrée des environnements virtuels.

Activer l’environnement virtuel :
Terminal window
```
poetry shell
```
Cela vous connecte directement à l’environnement virtuel du projet.
Lancer une commande dans l’environnement sans l’activer :
Terminal window
```
poetry run python script.py
```

Vérifier où est situé l’environnement virtuel :

poetry env info
Virtualenv
Python:         3.12.3
Implementation: CPython
Path:           /home/bob/.cache/pypoetry/virtualenvs/test-poetry-wuC4HPt9-py3.12
Executable:     /home/bob/.cache/pypoetry/virtualenvs/test-poetry-wuC4HPt9-py3.12/bin/python
Valid:          True

Base
Platform:   linux
OS:         posix
Python:     3.12.3
Path:       /usr
Executable: /usr/bin/python3.12

Poetry crée automatiquement un environnement virtuel pour chaque projet, sauf si vous le désactivez via :

poetry config virtualenvs.create false

Supprimer une dépendance

Pour désinstaller une bibliothèque, utilisez simplement :

poetry remove flask

Cela met à jour automatiquement les fichiers pyproject.toml et poetry.lock.

Mettre à jour les dépendances

Besoin de mettre vos bibliothèques à jour vers les dernières versions compatibles ? Poetry s’en charge :

poetry update

Pour une bibliothèque spécifique :

poetry update flask

Vérifier l’état des dépendances

Pour une vue d’ensemble des bibliothèques installées et de leurs versions :

poetry show

Vous pouvez également voir les bibliothèques obsolètes avec :

poetry show --outdated

Gérer les scripts

Si votre projet comporte des scripts ou des commandes spécifiques, vous pouvez les configurer dans le fichier pyproject.toml. Par exemple :

[tool.poetry.scripts]
run = "mon_projet.main:run"

Ensuite, exécutez-les simplement avec :

poetry run run

Ça me fait penser à un groupe de musique, pas vous ?

Avec ces commandes de base, vous êtes déjà bien équipé pour gérer vos projets Python avec Poetry. Le prochain niveau ? Découvrir les fonctionnalités avancées pour aller encore plus loin !

Utilisation avancée de Poetry

Après avoir maîtrisé les bases de Poetry, il est temps d’explorer ses fonctionnalités avancées. Ces outils permettent de gérer des projets complexes, de travailler efficacement en équipe, et de tirer parti de tout le potentiel de l’outil.

Travailler avec des bibliothèques locales

Lors du développement d’un projet qui dépend d’un autre module local, Poetry peut le gérer facilement :

Ajouter une dépendance locale :
Terminal window
```
poetry add ../mon_autre_projet
```

Cela crée un lien symbolique vers le projet local.

Gestion avancée des versions

Poetry facilite le versionnement grâce à la commande version, qui suit le versionnement sémantique (SemVer). Vous pouvez incrémenter automatiquement les parties majeures, mineures ou correctives de votre version :

poetry version patch   # Incrémente 1.0.0 -> 1.0.1
poetry version minor   # Incrémente 1.0.0 -> 1.1.0
poetry version major   # Incrémente 1.0.0 -> 2.0.0

Cela met à jour la version dans le fichier pyproject.toml.

Dépendances spécifiques à un environnement

Poetry permet de scinder vos dépendances en groupes, comme développement, tests ou production. Cela vous permet d’éviter d’installer des outils inutiles en production.

Ajouter une dépendance pour le développement :
Terminal window
```
poetry add black --group dev
```
Installer uniquement un groupe spécifique :
Terminal window
```
poetry install --with dev
```
Ignorer certains groupes, par exemple en production :
Terminal window
```
poetry install --without dev
```

Définir des contraintes de compatibilité

Pour un contrôle précis des versions de vos dépendances, Poetry utilise des opérateurs tels que :

^ : Compatible avec cette version (par exemple ^2.0 inclut 2.x mais pas 3.0).
~ : Permet les mises à jour dans la même version mineure (par exemple ~2.1 inclut 2.1.x mais pas 2.2).

Dans pyproject.toml, une contrainte pourrait ressembler à ceci :

[tool.poetry.dependencies]
flask = "^2.0"

Verrouillage des versions exactes

Le fichier poetry.lock garantit que tous les membres de l’équipe utilisent les mêmes versions de bibliothèques. Pour forcer une réinstallation complète basée sur ce fichier :

poetry install --no-root

Publier un package sur PyPI

Vous souhaitez partager votre projet avec la communauté ? Poetry simplifie le packaging et la publication.

Construire le package :
Terminal window
```
poetry build
```
Cela génère des fichiers .tar.gz et .whl prêts à être envoyés sur PyPI.
Publier sur PyPI :
Terminal window
```
poetry publish --username <votre_nom_utilisateur> --password <votre_mot_de_passe>
```
Pour plus de sécurité, vous pouvez utiliser un token API.

Configurations globales

Poetry propose des options de configuration globale pour personnaliser son comportement. Par exemple, pour désactiver la création d’environnements virtuels globaux :

poetry config virtualenvs.create false

Vous pouvez voir toutes les configurations en cours avec :

poetry config --list

Déboguer avec Poetry

Lorsque des problèmes surviennent, utilisez ces commandes pour obtenir des informations utiles :

Voir les dépendances et leurs relations :

poetry show --tree
black 24.10.0 The uncompromising code formatter.
├── click >=8.0.0
│   └── colorama *
├── mypy-extensions >=0.4.3
├── packaging >=22.0
├── pathspec >=0.9.0
└── platformdirs >=2
flask 3.1.0 A simple framework for building complex web applications.
├── blinker >=1.9
├── click >=8.1.3
│   └── colorama *
├── itsdangerous >=2.2
├── jinja2 >=3.1.2
│   └── markupsafe >=2.0
└── werkzeug >=3.1
    └── markupsafe >=2.1.1
pytest 8.3.3 pytest: simple powerful testing with Python
├── colorama *
├── iniconfig *
├── packaging *
└── pluggy >=1.5,<2

Obtenir des informations sur l’environnement virtuel :
Terminal window
```
poetry env info
```

Utilisation avec Docker

Si vous travaillez avec Docker, intégrez Poetry directement dans vos images :

Installez Poetry dans le Dockerfile :

RUN curl -sSL https://install.python-poetry.org | python3 -

Assurez-vous d’utiliser l’option --no-root dans vos commandes pour éviter les conflits liés aux environnements.

Avec ces fonctionnalités avancées, Poetry devient un outil essentiel pour les projets Python complexes ou collaboratifs. Une fois maîtrisé, il simplifie non seulement la gestion des dépendances, mais aussi le développement et la publication de vos applications.

Conclusion

Vous voilà armé pour dompter Poetry et simplifier la gestion de vos projets Python. Avec son approche moderne et sa capacité à centraliser les dépendances, les environnements virtuels et le packaging, il transforme ce qui pouvait autrefois être un casse-tête en une expérience fluide et productive.

Et maintenant, vous êtes prêt pour aller encore plus loin. Dagger, l’orchestrateur de pipelines CI/CD, a fait le choix judicieux d’intégrer Poetry dans la version Python de son SDK pour gérer ses packages. Une preuve supplémentaire de la puissance et de la fiabilité de Poetry, même pour des projets complexes et ambitieux.