Maîtriser l'emballage et la distribution Python : des scripts locaux à PyPI

La force de Python réside dans son vaste écosystème de bibliothèques tierces. Cependant, pour de nombreux développeurs, le parcours entre l'écriture d'un script et la distribution d'un package robuste reste une boîte noire. Comprendre comment emballer, construire et distribuer correctement les projets Python est essentiel pour tout développeur intermédiaire à avancé qui souhaite partager du code, collaborer sur des projets open source ou publier des outils internes sur un index privé.

Dans ce guide, nous démystifierons le paysage moderne de l'emballage Python. Nous dépasserons le monolithe obsolète setup.py et adopterons les normes plus récentes et plus robustes recommandées par l'autorité de l'emballage Python (PyPA).

Le passage de Setuptools à PEP 517/518

Historiquement, l'emballage Python reposait fortement sur setuptools et un fichier setup.py verbeux. Bien que fonctionnel, cette approche conduisait souvent à des builds fragiles et à une dispersion de la configuration. La communauté s'est depuis orientée vers des backends de build standardisés définis dans PEP 517 et PEP 518.

La nouvelle norme introduit deux fichiers clés :

1. pyproject.toml : Déclare les exigences de build et les métadonnées du projet.
2. backend de build : Un outil comme setuptools, poetry ou flit qui effectue le build réel.

Définir la structure de votre projet

Une structure de projet propre est la base d'un package maintenable. Bien qu'il existe de nombreuses variantes, une disposition moderne courante ressemble à ceci :

my_package/
├── pyproject.toml
├── README.md
├── LICENSE
└── src/
    └── my_package/
        ├── __init__.py
        ├── core.py
        └── utils.py

L'utilisation d'une disposition src/ est fortement recommandée. Elle empêche les importations accidentelles de fichiers locaux lors des tests et garantit que le package installé est toujours celui qui est testé, et non le code source dans votre répertoire actuel.

Configuration de pyproject.toml

Le fichier pyproject.toml est la seule source de vérité pour les métadonnées de votre projet. Voici un exemple de configuration utilisant setuptools comme backend de build, qui est la norme la plus largement adoptée.

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-awesome-package"
version = "0.1.0"
description = "Un exemple de package Python pour la démonstration."
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.8"
authors = [
  {name = "Jane Developer", email = "jane@example.com"},
]
dependencies = [
  "requests>=2.28.0",
  "click>=8.0.0",
]

[project.optional-dependencies]
dev = [
  "pytest>=7.0.0",
  "black>=22.0.0",
]

Points clés à noter dans cette configuration :

• Métadonnées dynamiques : Vous pouvez conserver les numéros de version dans des fichiers séparés pour éviter les mises à jour manuelles.
• Dépendances optionnelles : Les utilisateurs peuvent installer les outils de développement via pip install my-package[dev].
• Contrainte de version Python : La définition explicite de requires-python assure les vérifications de compatibilité.

pip install build twine

python -m build

Creating sdist archive: dist/my_awesome_package-0.1.0.tar.gz
Creating  wheel archive: dist/my_awesome_package-0.1.0-py3-none-any.whl

twine upload --repository testpypi dist/*

pip install --index-url https://test.pypi.org/simple/ --no-deps my-awesome-package