Python main - Maîtrisez __name__, -m et la structure idéale

Le sujet python main renvoie surtout au bloc d’exécution principal d’un programme Python, celui qui décide ce qui se passe quand un fichier est lancé directement et non importé. J’explique ici comment fonctionne __name__, pourquoi if __name__ == "__main__": reste utile, comment structurer un main() propre et quand python -m ou __main__.py sont plus adaptés. L’objectif est simple : garder un code réutilisable, testable et sans effets de bord inutiles.

Ce que fait réellement __name__ quand un module démarre

J’aime partir de l’idée la plus simple possible : en Python, un fichier peut être soit exécuté, soit importé. Quand il est lancé directement, la variable spéciale __name__ prend la valeur __main__. Quand le même fichier est importé, __name__ contient son vrai nom de module.

Cette différence est fondamentale, parce qu’elle permet à un même fichier d’avoir deux vies très différentes. Dans le premier cas, il joue le rôle de point d’entrée. Dans le second, il se comporte comme une brique réutilisable par d’autres modules.

# demo.py
print(__name__)

def info():
    return "utilisable partout"

Si j’exécute ce fichier directement, il affiche __main__. Si je l’importe depuis un autre module, il affichera demo. Le code de niveau supérieur s’exécute dans les deux cas, mais le nom du module change, et c’est précisément ce signal qui permet de distinguer l’entrée du programme d’un simple import. C’est ce mécanisme qui rend le test suivant réellement utile.

Pourquoi le test if __name__ == "__main__": reste utile

Je considère ce test comme une frontière nette entre code d’application et code de bibliothèque. Sans lui, tout ce que tu écris en haut niveau s’exécute dès qu’un autre fichier importe ton module. Dans un petit script, ce n’est pas grave. Dans un projet avec plusieurs modules, des tests, des connexions réseau ou des traitements lourds, ça devient vite gênant.

La logique est simple :

• si le fichier est exécuté directement, le bloc s’exécute ;
• si le fichier est importé, le bloc ne s’exécute pas ;
• les fonctions, classes et constantes restent disponibles dans les deux cas.

Je vois souvent des projets où un import déclenche une lecture de fichier, une connexion à une base ou une initialisation de client HTTP. C’est une mauvaise idée, parce qu’un import doit rester prévisible. Un module importé doit définir des objets, pas démarrer des effets de bord. Dès qu’on garde cette règle en tête, la structure du fichier devient plus saine et le besoin d’un vrai main() apparaît naturellement.

Écrire un main() propre au lieu d’empiler du code au bas du fichier

La documentation officielle de Python recommande de garder ce bloc aussi court que possible, et je suis pleinement d’accord avec cette approche. Le bon réflexe n’est pas de tout mettre dans le if, mais d’y appeler une fonction main() qui orchestre le programme. Cette fonction peut analyser les arguments, appeler des fonctions métier, gérer les erreurs et renvoyer un code de sortie clair.

import sys

def build_message(name: str) -> str:
    return f"Bonjour, {name}"

def main(argv=None) -> int:
    argv = sys.argv if argv is None else argv

    if len(argv) < 2:
        print("Usage: python app.py ")
        return 1

    print(build_message(argv[1]))
    return 0

if __name__ == "__main__":
    sys.exit(main())

Ce schéma a trois avantages très concrets. D’abord, il rend le code testable, parce que la logique utile est dans des fonctions séparées. Ensuite, il évite de polluer l’espace global avec des variables temporaires. Enfin, il permet de gérer proprement le code de retour du programme, ce qui compte dès qu’on lance un script depuis un shell, une CI ou un orchestrateur.

Quand préférer python -m à l’exécution d’un fichier

Je préfère souvent python -m dès qu’un projet cesse d’être un simple script isolé. L’intérêt est pratique : Python résout le module par son nom dans l’espace des modules, puis exécute son contenu comme environnement principal. C’est plus robuste qu’un chemin de fichier quand le projet grandit, se déplace ou devient installable.

Dans un paquet, un fichier __main__.py sert précisément à définir le comportement lancé par python -m. Je trouve ce pattern très propre pour une application qui expose une interface en ligne de commande. Le plus souvent, ce fichier reste minimal et délègue le travail réel à d’autres modules, ce qui facilite les tests unitaires et les évolutions futures.

mon_paquet/
  __init__.py
  __main__.py
  cli.py

# __main__.py
from .cli import main

raise SystemExit(main())

Quand j’applique cette structure, je sais que le programme peut être lancé proprement, empaqueté plus tard et importé sans surprise. La différence entre fichier exécuté et module importé devient alors une force, pas une source d’ambiguïté. Reste maintenant à repérer les erreurs qui font trébucher même des projets pourtant bien démarrés.

Les erreurs que je vois le plus souvent dans les projets Python

Il y a quelques pièges récurrents que je remarque souvent, y compris dans des bases de code sérieuses. Le premier consiste à laisser du code d’initialisation en haut du fichier : lecture de configuration, connexion à un service, lancement d’un thread, ouverture d’un fichier. Le second est de tout coller dans le bloc if __name__ == "__main__": au lieu d’extraire des fonctions. Le troisième, plus subtil, concerne les imports relatifs quand le module est lancé directement.

• Effets de bord à l’import : un module ne devrait pas démarrer une action lourde dès qu’on le charge.
• Bloc principal trop gros : si le if contient toute la logique, le fichier devient vite difficile à tester.
• Imports relatifs dans un script lancé directement : un module principal n’a pas toujours le contexte de paquet attendu.
• Oubli de protection avec multiprocessing : sur certains modes de démarrage, le module peut être réimporté par des processus enfants.
• Confusion entre __main__ et __main__.py : le nom spécial et le fichier de paquet ne désignent pas exactement la même chose.

Sur les projets qui utilisent du parallélisme, je suis particulièrement vigilant. Si le point d’entrée n’est pas protégé, le processus enfant peut réimporter le module et relancer des actions qu’on ne voulait pas dupliquer. Ce genre de bug est pénible parce qu’il apparaît souvent tard, au moment où l’on teste sur une autre plateforme ou avec un autre mode de lancement. Une fois ces pièges identifiés, la règle de conduite devient très simple.

La règle simple que j’applique sur un backend ou un outil CLI

Dans un backend Python ou un outil en ligne de commande, je garde toujours la même discipline : la logique métier va dans des fonctions ou des modules dédiés, et le point d’entrée reste aussi mince que possible. Le bloc principal doit lancer, pas contenir toute la logique.

• Je garde les imports en haut du fichier, sans exécution cachée.
• Je place l’analyse des arguments dans main(), pas dans le corps global.
• Je fais retourner à main() un code de sortie clair.
• Je choisis python -m dès que le projet ressemble à un paquet ou à une vraie application.

En pratique, cette façon de faire rend les tests plus simples, les imports plus sûrs et l’évolution du projet beaucoup moins fragile. Si tu dois retenir une seule idée, retiens celle-ci : un bon point d’entrée Python est presque invisible, parce qu’il se contente d’orchestrer le reste. C’est précisément ce qui permet ensuite au code de grandir sans perdre sa lisibilité.