Modules et imports
En Python, chaque fichier .py est un module, et un dossier de modules est un paquet. Ce cours explique comment les organiser pour qu'un projet reste lisible en grandissant.
Le problème
En haut de players.py :
Python
Plus bas, le code utilise Settler, RESSOURCES_, randint. D'où vient chacun ? Impossible à dire sans ouvrir les deux autres fichiers. L'auteur s'est posé la question lui-même dans ses notes : « est-ce un problème de faire from units import * dans map.py et dans players.py ? »
Oui, et voici pourquoi.
Les formes d'import
| Forme | Exemple | Ce qu'on écrit ensuite | Lisibilité |
|---|---|---|---|
| Importer le module | import constants | constants. | On voit toujours l'origine |
| Importer des noms précis | from units import Settler, City | Settler(...) | L'origine est en haut du fichier |
| Tout importer | from units import * | Settler(...) | On ne sait pas d'où ça vient |
Ce que fait vraiment l'étoile
from units import * copie tous les noms de units.py, y compris ceux que units.py a lui-même importés. Comme units.py fait from constants import * et from random import randint, importer units avec une étoile apporte aussi toutes les constantes et randint.
Trois conséquences :
- On ne sait plus d'où vient un nom. L'éditeur non plus, parfois.
- Deux modules peuvent définir le même nom. Le dernier importé gagne, sans avertissement.
- Supprimer un import ailleurs peut casser ce fichier.
La correction est mécanique :
Python
Pour un fichier de constantes très utilisé, la première forme est agréable :
Python
L'ordre des imports
La convention, du plus général au plus local, avec une ligne vide entre les groupes :
Python
Le graphe de dépendances
Chaque import est une flèche : « ce fichier a besoin de celui-là ». L'ensemble forme un graphe.
Un bon graphe a deux propriétés :
- Pas de boucle. Si A importe B et B importe A, Python peut échouer au démarrage, et aucun des deux n'est compréhensible seul.
- Des couches. Les flèches vont toutes dans le même sens, du plus spécifique vers le plus général.
Le graphe du jeu est correct sur ces deux points. Le problème est ailleurs.
Les dépendances qui ne se voient pas
Un import n'est pas la seule façon de dépendre d'un autre module. Quand une classe reçoit un objet qui donne accès à tout, elle dépend de tout, sans aucun import.
Python
units.py n'importe pas ui.py. Pourtant il ne peut pas fonctionner sans. C'est une dépendance cachée, et elle forme une boucle : l'interface dépend des unités, les unités dépendent de l'interface.
La page Les fichiers de la documentation du jeu montre le graphe réel du projet, avec ces flèches.
Organiser en paquets
Quand un dossier contient plus d'une dizaine de modules, on les regroupe.
Code
L'import suit le chemin :
Python
Le nom du paquet devient une information : core. dit « règle du jeu », ui. dit « interface ».
Une règle par paquet
L'intérêt d'un paquet est de pouvoir énoncer une règle sur ses imports :
| Paquet | Peut importer | Ne doit pas importer |
|---|---|---|
data/ | rien | tout le reste |
core/ | data/ | ui/, render/, pygame |
render/ | core/, pygame | ui/ |
ui/ | core/, render/, pygame |
Et de la vérifier en une commande :
Bash
Ce qui se passe quand on importe
Importer un module exécute tout son code, une fois. C'est pourquoi main.py a un défaut :
Python
Si un autre fichier fait import main, le jeu se lance. La forme standard évite ça :
Python
Cette condition n'est vraie que si le fichier est lancé directement.
Même raison pour laquelle constants.py parcourt le dossier du tutoriel dès qu'on l'importe : il lit le disque à l'import. Un test qui veut seulement une constante déclenche cette lecture, et échoue s'il n'est pas lancé depuis le bon dossier.
À retenir
- Jamais
from module import *: nommer ce qu'on importe. - Les flèches d'import vont dans un seul sens, sans boucle.
- Un objet qui donne accès à tout crée des dépendances invisibles.
- Un paquet se définit par ce qu'il a le droit d'importer.
- Protéger le point d'entrée avec
if __.name__ == "__ main__ ":
Exercices
- Remplacer
from units import *dansplayers.pypar des imports nommés. Combien de noms sont réellement utilisés ? - Faire de même pour
from players import *dansmap.py. - Ajouter
if __dansname__ == "__ main__ ": main.py. - Créer
src/hex.pyavecfind_en fonction simple, et l'importer dansneighbors map.py. Ce module a-t-il des dépendances cachées ?