Creation de librairie Python : structure, packaging, distribution

Modules, packages, pyproject.toml, distribution

📁

Structure d'une librairie

Arborescence recommandee- Une structure standard facilite la comprehension par d'autres developpeurs et la compatibilite avec les outils de build.

ma_librairie/
    ma_librairie/       # le code source, dans un dossier du meme nom
        __init__.py     # rend le dossier importable comme un package
        core.py
        utils.py
    tests/
        test_core.py
    pyproject.toml      # configuration et metadonnees du projet
    README.md           # description affichee sur PyPI
    LICENSE             # licence d'utilisation (MIT, GPL...)

📦

Modules et packages

Module- Un module est simplement un fichier .py : chaque fichier Python est un module que l'on peut importer ailleurs.

# core.py
def addition(a, b):
    return a + b
# utilisation depuis un autre fichier :
# from core import addition

Package- Un package est un dossier contenant plusieurs modules, avec un fichier __init__.py qui definit ce qui est expose lors d'un 'import ma_librairie'.

# __init__.py
from .core import addition    # le . = import relatif (dans le meme package)
from .utils import formater
# permet ensuite : from ma_librairie import addition

Import absolu vs relatif- A l'interieur d'un package, on peut importer entre modules du meme package avec un point (relatif) ou le chemin complet (absolu).

# import relatif (depuis un fichier du meme package)
from .utils import formater
# import absolu (fonctionne partout, plus explicite)
from ma_librairie.utils import formater

⚙️

pyproject.toml

Configuration minimale- Fichier standard moderne (remplace setup.py) qui decrit le projet : nom, version, dependances, outil de build utilise.

[project]
name = "ma_librairie"
version = "1.0.0"
description = "Librairie Python exemple"
authors = [{name="Robin HENRY"}]
dependencies = ["requests>=2.28"]   # dependances necessaires au fonctionnement
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

Installation locale en mode editable- Pendant le developpement, installer sa propre librairie en mode 'editable' permet de tester les modifications sans avoir a la reinstaller a chaque fois.

pip install -e .    # installe depuis le dossier courant, en mode editable
# tout changement dans le code source est immediatement pris en compte

🚀

Distribution

Build- Genere les fichiers pretes a etre distribues : un .whl (wheel, format binaire rapide a installer) et une archive source .tar.gz.

python -m build
# genere le dossier dist/ avec :
#   ma_librairie-1.0.0-py3-none-any.whl
#   ma_librairie-1.0.0.tar.gz

Publication sur PyPI- twine envoie les fichiers generes sur PyPI (ou un depot prive) pour les rendre installables via pip install.

twine upload dist/*
# demande un identifiant/token PyPI
# une fois publie, n'importe qui peut faire :
# pip install ma_librairie

🧪

Tests

pytest- Les tests valident que la librairie fonctionne comme prevu avant chaque publication. Ils se placent generalement dans le dossier tests/.

# tests/test_core.py
from ma_librairie.core import addition
def test_addition():
    assert addition(2, 3) == 5
# executer tous les tests :
# pytest tests/