Un py module mal testé ou mal packagé ne passera pas la phase de build sur PyPI, et encore moins l’installation côté utilisateur. Nous partons du principe que votre code source est fonctionnel et que vous disposez d’un fichier pyproject.toml valide. Voici les étapes que nous recommandons pour fiabiliser le cycle complet, du test local à la publication.
Stratégie de tests avant le build d’un py module
Pytest reste le framework de test dominant, mais le choix du runner ne suffit pas. Ce qui fait la différence entre un module fiable et un module qui casse à l’installation, c’est la couverture des cas limites liés au packaging lui-même.
A découvrir également : Automatisez votre messagerie académique à Rouen pour gagner du temps
Nous recommandons de tester systématiquement trois niveaux distincts :
- Les tests unitaires classiques sur la logique métier, exécutés via
pytestavec un rapport de couverture (pluginpytest-cov). - Un test d’import après installation locale en mode editable (
pip install -e .), qui détecte les erreurs de déclaration dans le champpackagesdu pyproject.toml. - Un test d’installation depuis le fichier wheel buildé (
pip install dist/votre_package-0.1.0-py3-none-any.whl), qui reproduit exactement ce que l’utilisateur final exécutera aprèspip install.
Le deuxième niveau est celui que la majorité des tutoriels ignorent. Un module qui s’importe correctement en mode editable peut échouer une fois packagé, parce qu’un sous-répertoire n’a pas été déclaré ou qu’un fichier __init__.py manque dans l’arborescence.
A lire aussi : Accédez aisément à votre webmail AC Normandie : astuces et conseils pratiques
Pyproject.toml : les champs qui provoquent des rejets sur PyPI
Le fichier pyproject.toml concentre la configuration de build, les métadonnées et les dépendances. Setuptools, Hatch ou Flit l’utilisent tous comme source de vérité. Deux erreurs reviennent constamment lors de la première soumission.
Conflit de name et version
Le champ name doit être unique sur PyPI. Avant toute tentative d’upload, vérifiez manuellement sur pypi.org que le nom n’est pas déjà pris, ni qu’un nom quasi identique existe (typosquatting). Un nom de package déjà utilisé provoque un rejet silencieux lors de l’upload via twine.
Le champ version doit respecter PEP 440. Une version comme 1.0-beta sera refusée. Utilisez 1.0b1 ou 1.0.0rc1.
Déclaration des packages et fichiers inclus
Avec setuptools, le champ [tool.setuptools.packages.find] dans pyproject.toml remplace l’ancien find_packages() de setup.py. Si votre module contient des sous-répertoires, déclarez explicitement le répertoire racine via where. Un oubli ici produit un wheel vide, installable mais inutilisable.
Documenter un module Python avec des docstrings exploitables
La documentation d’un py module ne se limite pas à un README.md. Les docstrings au format Google ou NumPy, intégrées directement dans le code, permettent de générer une documentation HTML via Sphinx ou MkDocs sans effort supplémentaire.
Nous observons que les modules les mieux notés sur PyPI ont des docstrings sur chaque fonction publique. Ce n’est pas un hasard : pip et les IDE exploitent ces docstrings pour l’autocomplétion et l’aide contextuelle.
Le README.md reste le point d’entrée principal sur PyPI. Il s’affiche directement sur la page du package. Déclarez-le dans pyproject.toml via le champ readme pour que le build l’intègre automatiquement dans les métadonnées du sdist et du wheel.
Build et upload : sdist, wheel et twine vers TestPyPI
La commande python -m build génère deux fichiers dans le répertoire dist/ : un sdist (archive tar.gz des sources) et un wheel (fichier .whl prêt à installer). Les deux sont nécessaires pour une publication complète.
Avant de publier sur PyPI en production, passez systématiquement par TestPyPI. C’est une instance séparée qui permet de valider le cycle complet d’upload et d’installation sans polluer l’index réel.
- Créez un compte sur test.pypi.org (distinct de votre compte pypi.org).
- Générez un jeton API dédié, avec un scope limité au projet concerné.
- Uploadez via
twine upload --repository testpypi dist/*. - Testez l’installation depuis TestPyPI :
pip install --index-url https://test.pypi.org/simple/ votre-package.
Si l’installation fonctionne et que l’import se passe sans erreur, vous pouvez publier sur PyPI avec twine upload dist/*.
Sécurité des jetons PyPI dans un pipeline CI/CD
Les campagnes d’empoisonnement de packages sur PyPI se sont multipliées depuis quelques années. Pour un auteur de module, la première ligne de défense concerne la gestion des jetons de publication.
Traitez vos jetons PyPI comme des secrets critiques : stockez-les exclusivement dans les secrets de votre plateforme CI (GitHub Actions, GitLab CI), jamais dans le code source ni dans un fichier .pypirc versionné. La rotation régulière des jetons réduit la fenêtre d’exposition en cas de fuite.
Nous recommandons d’intégrer un outil de scan de secrets (GitGuardian, TruffleHog ou Gitleaks) dans le pipeline, avant l’étape de build. Un jeton PyPI qui fuite dans un commit public permet à un attaquant de publier une version malveillante de votre package en quelques minutes.
La publication automatisée via GitHub Actions reste le workflow le plus répandu. Configurez un job déclenché uniquement sur la création d’un tag de version, avec les étapes build, twine check et twine upload enchaînées. Le twine check dist/* valide le format des métadonnées avant l’envoi, ce qui évite les rejets côté serveur.
Un dernier point souvent négligé : vérifiez que le nom de votre package n’est pas imité par un paquet malveillant. Surveillez les téléchargements anormaux via l’API BigQuery de PyPI si votre module gagne en popularité. La supply chain Python est une cible active, et la vigilance commence dès la première publication.
