Formations — 1 037 leçons en français

Accueil › Python › Packages et structure d'un projet

Packages et structure d'un projet

Modules, environnements et typageintermediaire

Un package est un dossier de modules qu'on peut importer. L'arborescence devient le chemin d'import :

boutique/
    __init__.py
    modeles.py          ->  boutique.modeles
    panier.py           ->  boutique.panier
    services/
        __init__.py
        facture.py      ->  boutique.services.facture
from boutique.services.facture import editer      # import absolu

Dans facture.py, on peut aussi écrire des imports relatifs au package :

from ..modeles import Commande      # deux points : on remonte à boutique
from .remise import appliquer       # un point : même dossier

Le fichier __init__.py est le corps du package : il s'exécute au premier import et sert à exposer une interface courte.

# boutique/__init__.py
from .panier import total_ttc

__all__ = ["total_ttc"]

Les utilisateurs écrivent alors from boutique import total_ttc sans connaître l'organisation interne. Vous pouvez déplacer panier.py plus tard sans casser leur code : c'est tout l'intérêt.

Deux règles résument le reste. D'abord, un module lancé directement n'est dans aucun package : son __name__ vaut "__main__", et tout import relatif échoue. Pour exécuter un module interne, utilisez python -m boutique.services.facture depuis la racine du projet. Ensuite, les dépendances doivent aller dans un seul sens : boutique.services importe boutique.modeles, jamais l'inverse. L'arborescence sert justement à rendre cette règle visible — un import qui remonte à contre-courant se repère à l'œil.

Pour qu'un import boutique fonctionne depuis n'importe où, on installe le projet dans son environnement (pip install -e .) plutôt que de manipuler sys.path.

Les termes à connaître

Package

Un dossier qui contient des modules et qu'on peut importer. boutique/panier.py donne le module boutique.panier. Un package est lui-même un module : il a un __name__, des attributs, et son propre fichier d'initialisation.

__init__.py

Le fichier exécuté quand on importe le package. Il définit ce que le package expose directement. Vide, il ne fait que marquer le dossier comme package « classique » ; depuis Python 3.3, un dossier sans ce fichier est un namespace package, importable lui aussi — mais le fichier explicite reste recommandé.

Import relatif

from .panier import total ou from ..modeles import Client : le chemin part du package courant. Un point pour le même package, deux pour le parent. Ne fonctionne qu'à l'intérieur d'un package, jamais dans un fichier lancé directement.

Disposition `src`

Convention qui place le code du projet dans src/boutique/ plutôt qu'à la racine. Elle force à installer le projet pour l'importer, donc à tester ce qui sera réellement distribué plutôt que le dossier de travail.

pyproject.toml

Le fichier de description standard d'un projet Python : nom, version, dépendances, outil de construction. C'est le fichier que lisent les installateurs et la plupart des outils de qualité.

__pycache__

Dossier que Python crée pour stocker le bytecode compilé des modules importés. Il se régénère seul et n'a rien à faire dans le dépôt de code.

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.