Aller au contenu

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
from units import * from constants import *

Plus bas, le code utilise Settler, RESSOURCES_FILEPATHS, 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

FormeExempleCe qu'on écrit ensuiteLisibilité
Importer le moduleimport constantsconstants.MAX_LAYERSOn voit toujours l'origine
Importer des noms précisfrom units import Settler, CitySettler(...)L'origine est en haut du fichier
Tout importerfrom 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
from units import Unit, Settler, City, Farm from constants import RESSOURCES_FILEPATHS, NORMAL_RESSOURCES, PLAYERS_COLORS

Pour un fichier de constantes très utilisé, la première forme est agréable :

Python
import constants as c if len(regional_tiles) >= c.MAXIMUM_TILES_PER_CITY:

L'ordre des imports

La convention, du plus général au plus local, avec une ligne vide entre les groupes :

Python
import json # 1. bibliothèque standard de Python import math import pygame # 2. bibliothèques installées from constants import W, H # 3. modules du projet from map import Map

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
class Unit: def __init__(self, game, tile_linked, owner): self.game = game def move(self, tile): self.game.ui.button_handler.look_selected_tile(...)

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.

Le test

Peut-on importer ce module et utiliser ses fonctions dans un petit script, sans lancer le reste du programme ? Si non, il a des dépendances cachées.

Organiser en paquets

Quand un dossier contient plus d'une dizaine de modules, on les regroupe.

Code
src/ ├── core/ │ ├── hex.py │ ├── world.py │ └── commands.py ├── ui/ │ ├── composants/ │ │ └── button.py │ └── pages/ └── main.py

L'import suit le chemin :

Python
from core.hex import find_neighbors from ui.composants.button import Button

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 :

PaquetPeut importerNe doit pas importer
data/rientout le reste
core/data/ui/, render/, pygame
render/core/, pygameui/
ui/core/, render/, pygame

Et de la vérifier en une commande :

TerminalBash
grep -rn "import pygame" src/core/

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
def main(): pygame.init() game = Game() game.game_loop() main()

Si un autre fichier fait import main, le jeu se lance. La forme standard évite ça :

Python
if __name__ == "__main__": main()

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

  1. Remplacer from units import * dans players.py par des imports nommés. Combien de noms sont réellement utilisés ?
  2. Faire de même pour from players import * dans map.py.
  3. Ajouter if __name__ == "__main__": dans main.py.
  4. Créer src/hex.py avec find_neighbors en fonction simple, et l'importer dans map.py. Ce module a-t-il des dépendances cachées ?