Depuis que j’ai commencé à publier des projets, le paysage du packaging Python a radicalement changé : en 2026, on bénéficie d’outils modernes, de standards robustes et d’un chemin sécurisé vers *PyPI*. Dans cet article je vous guide, étape par étape, pour transformer un simple script en projet open source installable via pip, gérer le versionning, automatiser la publication et produire une documentation propre. Je m’appuie sur des retours d’expérience concrets, erreurs rencontrées et solutions testées pour que vous puissiez publier avec confiance. Vous apprendrez à structurer votre dépôt, écrire un pyproject.toml efficace, construire des distributions (sdist / wheel), tester sur TestPyPI, et adopter une publication approuvée via CI/CD pour éviter la gestion de tokens. Au fil du texte, je raconte comment *Aurélien*, développeur dans une petite startup, a transformé son utilitaire interne en une bibliothèque open source utilisée par plusieurs équipes, et je détaille les recettes qui l’ont aidé à réussir.
Réponse rapide : Créez un répertoire en src-layout, rédigez un pyproject.toml avec les métadonnées et dépendances, choisissez un backend de build (setuptools, hatchling, poetry), exécutez python -m build, testez sur TestPyPI avec twine, puis publiez sur PyPI en utilisant soit un token sécurisé soit la publication approuvée (OIDC) via votre pipeline CI. Vérifiez les tests, la doc et le versionning avant chaque release.
- En bref :
- Structurer votre projet avec un src/ propre pour éviter les importations accidentelles.
- Utiliser pyproject.toml comme source unique de vérité.
- Construire sdist + wheel puis tester sur TestPyPI.
- Automatiser la publication via CI/CD et privilégier la publication approuvée pour la sécurité.
- Maintenir tests, documentation et versionning sémantique.
Pourquoi emballer un projet open source Python et le publier sur PyPI
Emballer un projet permet de le rendre réutilisable et facilement installable par d’autres équipes. J’ai vu des scripts partagés en interne devenir des bibliothèques robustes simplement parce qu’on les a packagés correctement.
Les bénéfices sont clairs : distribution simple avec pip, gestion explicite des dépendances, suivi via versionning, et un cadre qui encourage la documentation et les tests. Pour *Aurélien*, la publication a réduit les erreurs de duplication et accéléré les intégrations.
Insight : un package bien packagé facilite l’adoption et la maintenance sur le long terme.
Structure moderne d’un package Python : src-layout et bonnes pratiques de dépôt
Adopter le src-layout évite les importations du code non installé et rend les tests plus représentatifs. Une arborescence minimale que j’utilise systématiquement :
my-package/ contient src/mypackage/, tests/, docs/, pyproject.toml, README.md et LICENSE. Cette séparation clarifie le rôle de chaque fichier.
En pratique, je sépare le code métier, les utilitaires et l’interface CLI, puis j’ajoute des tests unitaires et une documentation basique pour commencer. Résultat : des merges plus sûrs et une diffusion aisée.
Insight : structure claire = intégration plus rapide pour les contributeurs.
Le fichier pyproject.toml : centraliser la configuration
Depuis PEP 518/621, pyproject.toml est le standard. Il contient build-system, project (métadonnées, dépendances) et les sections pour les outils (black, pytest, mypy).
Exemple synthétique (à adapter) : name = « mypackage », version = « 0.1.0 », requires-python = « >=3.8 », dependencies = [« requests>=2.28.0 »]. Choisissez ensuite le backend : setuptools, hatchling, poetry ou flit selon vos besoins.
Insight : un pyproject bien conçu réduit les frictions lors de la construction et de la publication.
Construire, tester et distribuer : sdist, wheel, build et twine
Je construis toujours deux artefacts : la sdist (.tar.gz) et le wheel (.whl). Le wheel permet une installation rapide et sans compilation.
Commandes clés que j’exécute : pip install build, nettoyer dist/ puis python -m build. Avant d’uploader : pip install twine et twine check dist/*, puis twine upload –repository testpypi dist/* pour un premier essai.
Testez l’installation depuis TestPyPI avant la mise en production : pip install –index-url https://test.pypi.org/simple/ mypackage. Cela m’a évité plusieurs régressions liées à des fichiers manquants.
Insight : valider sur TestPyPI évite les erreurs coûteuses en production.
CI/CD et publication approuvée (OIDC) : déployer sans tokens
Automatiser la construction et la publication via GitHub Actions ou GitLab CI rend le processus reproductible. La publication approuvée (OIDC) permet d’authentifier la pipeline sans stocker de tokens, ce qui renforce la sécurité.
Un workflow typique : construire les distributions lors d’une release, stocker les artefacts puis publier en utilisant l’action officielle pypa/gh-action-pypi-publish avec permissions id-token. J’ai migré plusieurs dépôts vers cette méthode pour réduire la surface d’attaque liée aux tokens.
Insight : OIDC + règles d’environnement = déploiements traçables et sûrs.
Bonnes pratiques : versionning, tests, qualité et documentation
Le versionning sémantique (MAJOR.MINOR.PATCH) est non négociable pour moi. J’utilise bump2version pour automatiser les tags et commits. Toujours lier le numéro de version dans pyproject.toml et dans __init__.py.
Tests et qualité : pytest, coverage, black, flake8, mypy et pre-commit forment ma chaîne de confiance. Je recommande aussi d’installer en editable en dev : pip install -e « .[dev] » pour reproduire l’environnement CI localement.
Docs : je documente l’API et les exemples d’utilisation. Pour rédiger de bonnes docstrings et intégrer Sphinx, consultez ce guide pratique sur la génération de docstrings : documenter avec Sphinx. Et pour automatiser les tâches récurrentes du packaging, ce tutoriel m’a souvent servi : automatiser les tâches.
Insight : qualité et documentation sont les leviers d’adoption d’un package open source.
Pièges courants et checklist de publication
- Imports cassés : vérifiez le src-layout et include dans pyproject.
- Dépendances manquantes : listez tout dans dependencies du pyproject.
- Conflits de versions : utilisez des environnements virtuels et des versions minimales.
- Taille excessive : excluez tests/docs inutiles via MANIFEST.in.
- Plateforme : testez sur Linux, macOS et Windows dans CI.
Checklist avant publication : tous les tests passent, README complet, LICENSE incluse, CHANGELOG mis à jour, build OK, publication sur TestPyPI validée et repo tagué. Cette liste m’a sauvé plusieurs fois lors de releases critiques.
Insight : respecter la checklist évite les retours en urgence après publication.
Sujets avancés : CLI, plugins et extensions natives
Ajouter des points d’entrée CLI dans pyproject facilite l’adoption : [project.scripts] mypkg = « mypackage.cli:main ». J’ajoute souvent un petit CLI en Click pour les utilitaires.
Pour des performances extrêmes, on peut intégrer des extensions C via setuptools ou proposer un système de plugins découvert via entry-points. Ces techniques demandent plus de tests multi-plateformes mais ouvrent la voie à des usages industriels.
Insight : les fonctionnalités avancées augmentent l’attrait mais exigent une rigueur supplémentaire.
Comment tester ma publication sans affecter PyPI ?
Utilisez TestPyPI : construisez vos distributions (python -m build), téléversez-les sur TestPyPI avec twine (twine upload –repository testpypi dist/*) puis installez via pip en pointant l’index de TestPyPI pour vérifier le comportement.
Quel backend de build dois-je choisir ?
Si vous cherchez compatibilité et flexibilité, optez pour setuptools. Pour des builds rapides et simples, hatchling est une bonne option. Si vous voulez une gestion complète des dépendances et verrouillage, poetry est pertinent. Choisissez selon la complexité de votre projet.
Comment automatiser la publication sans stocker de tokens ?
Configurez la publication approuvée (OIDC) sur PyPI et un workflow CI qui émet un id-token lors des releases. Cette méthode évite l’utilisation de tokens persistants et améliore la traçabilité.
Que doit contenir mon pyproject.toml minimal ?
Les sections essentielles : [build-system] (backend et requires), [project] (name, version, description, requires-python, dependencies), et éventuellement [project.scripts] pour les CLI. Complétez avec tool.* pour black/pytest/mypy selon vos besoins.