# 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

| Forme | Exemple | Ce qu'on écrit ensuite | Lisibilité |
| --- | --- | --- | --- |
| Importer le module | `import constants` | `constants.MAX_LAYERS` | 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
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.

<Mermaid
  chart={`flowchart TB
    main[main.py] --> game[game.py]
    game --> ui[ui.py]
    game --> map[map.py]
    game --> saves[saves_handler.py]
    map --> players[players.py]
    players --> units[units.py]
    ui --> constants[constants.py]
    map --> constants
    players --> constants
    units --> constants
    saves --> constants`}
/>

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.

:::tip{title="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.

```text
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 :

| 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
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 ?
