# `__main__` --- Top-level code environment

En Python, le nom `__main__` a une fonction particulière. Il intervient dans deux cas :

1. c'est le nom de l'environnement d'exécution principal, ce qui donne lieu au test courant `__name__ == '__main__'` ;

2. c'est aussi le nom du fichier `__main__.py` dans les paquets Python.

Les deux sont liés aux modules Python, à la manière de s'en servir en tant qu'utilisateur et à la manière dont ils interagissent entre eux. Cette page contient des détails sur les modules Python. Si vous ne les avez jamais utilisés, commencez par la section qui leur est consacrée dans le tutoriel : Modules.

## `__name__ == '__main__'`

Lorsqu'un module ou un paquet Python est importé, son attribut `__name__` est défini à son nom, qui est la plupart du temps le nom du fichier qui le contient sans l'extension `.py` :

    >>> import configparser
    >>> configparser.__name__
    'configparser'

Si le fichier fait partie d'un paquet, `__name__` donne tout le chemin d'accès :

    >>> from concurrent.futures import process
    >>> process.__name__
    'concurrent.futures.process'

En revanche, si le module est exécuté dans l'environnement d'exécution principal, la variable `__name__` vaut `'__main__'`.

### Qu'est-ce que l'« environnement d'exécution principal » ?

L'environnement principal a pour nom `__main__`. Il s'agit du premier module Python dont l'exécution a été demandée par l'utilisateur final. On le qualifie de principal car c'est lui qui importe tous les autres modules nécessités par le programme. On l'appelle parfois le point d'entrée de l'application.

L'environnement principal peut prendre diverses formes :

- l'environnement d'une invite de commande interactive :

      >>> __name__
      '__main__'

- le module passé directement en tant que fichier à la commande de l'interpréteur Python :

      $ python helloworld.py
      Hello, world!

- le module ou paquet passé à l'interpréteur avec l'option `-m` :

      $ python -m tarfile
      usage: tarfile.py [-h] [-v] (...)

- le code lu par l'interpréteur depuis l'entrée standard :

      $ echo "import this" | python
      The Zen of Python, by Tim Peters

      Beautiful is better than ugly.
      Explicit is better than implicit.
      ...

- le code passé à l'interpréteur avec l'option `-c` :

      $ python -c "import this"
      The Zen of Python, by Tim Peters

      Beautiful is better than ugly.
      Explicit is better than implicit.
      ...

Dans chacun de ces cas, l'attribut `__name__` du module principal est mis à `'__main__'`.

Un module peut donc savoir s'il est exécuté dans l'environnement principal en vérifiant son `__name__`, ce qui permet typiquement d'exécuter du code lorsque le module est initialisé d'une manière autre que l'importation :

    if __name__ == '__main__':
        # Execute when the module is not initialized from an import statement.
        ...

Voir aussi

Pour plus de détails sur la manière dont `__name__` est défini dans les divers cas, voir la section Modules dans le tutoriel.

### Utilisation idiomatique

Il arrive qu'un module contienne du code qui ne doit s'exécuter que lorsque le module est utilisé comme script. On peut penser à l'analyse des arguments passés en ligne de commande, ou bien à la lecture de l'entrée standard. Il ne faudrait pas que ces opérations soient effectuées lorsque le module est importé depuis un autre module, comme pour les tests.

C'est dans ces situations que sert la construction `if __name__ == '__main__'`. Le code mis à l'intérieur du bloc n'est exécuté que si le module est dans l'environnement principal.

Putting as few statements as possible in the block below `if __name__ == '__main__'` can improve code clarity and correctness. Most often, a function named `main` encapsulates the program's primary behavior:

    # echo.py

    import shlex
    import sys

    def echo(phrase: str) -> None:
       """A dummy wrapper around print."""
       # for demonstration purposes, you can imagine that there is some
       # valuable and reusable logic inside this function
       print(phrase)

    def main() -> int:
        """Echo the input arguments to standard output"""
        phrase = shlex.join(sys.argv)
        echo(phrase)
        return 0

    if __name__ == '__main__':
        sys.exit(main())  # next section explains the use of sys.exit

Si, dans le module ci-dessus, le code de `main` était placé directement dans le `if __name__ == '__main__'`, la variable `phrase` serait globale, et d'autres fonctions pourraient s'en servir par erreur à la place d'une variable locale. Encapsuler le code dans la fonction `main` évite cet ennui.

De plus, la fonction `echo` est elle-même séparée du reste, et on peut l'importer dans un autre module. Le fait d'importer `echo.py` définit les fonctions `main` et `echo`, mais n'en appelle aucune, puisque `__name__ != '__main__'`.

### Considérations liées à l'empaquetage

Les fonctions `main` servent souvent à créer des outils qui s'exécutent en ligne de commande. Les scripts sont ajoutés au système à l'aide de points d'entrée, qui demandent à pip de créer un exécutable. Il le fait en insérant un appel à la fonction à l'intérieur d'un modèle prédéfini où la valeur qu'elle renvoie est passée directement à `sys.exit()` :

    sys.exit(main())

Puisque l'appel de `main` est encapsulé dans `sys.exit()`, `main` doit renvoyer une valeur qui convienne comme argument à `sys.exit()`, par exemple un code de retour sous forme d'entier. La valeur `None` est également acceptée, et c'est d'ailleurs celle que renvoie la fonction si elle se termine sans rencontrer d'instruction `return`.

By proactively following this convention ourselves, our module will have the same behavior when run directly (i.e. `python echo.py`) as it will have if we later package it as a console script entry-point in a pip-installable package.

En particulier, mieux vaut éviter de renvoyer une chaîne de caractères depuis la fonction `main`. En effet, si `sys.exit()` reçoit une chaîne, elle l'interprète comme un message d'erreur, qu'elle affiche sur `sys.stderr` avant de terminer le programme avec le code de retour 1 (erreur). L'exemple de `echo.py` ci-dessus montre la pratique recommandée.

Voir aussi

Le guide de l'empaquetage en Python (en anglais) contient plusieurs tutoriels et documents de référence autour de la distribution et de l'installation de paquets Python avec des outils modernes.

## Le fichier `__main__.py` dans les paquets Python

Si vous n'êtes pas familier des paquets Python, lisez Les paquets dans le tutoriel. Un fichier `__main__.py` permet à un paquet de définir une interface en ligne de commande. Prenons pour exemple un paquet nommé bandclass :

    bandclass
      ├── __init__.py
      ├── __main__.py
      └── student.py

Le fichier `__main__.py` qu'il contient s'exécute lorsque le paquet est appelé depuis la ligne de commande avec l'option `-m` de l'interpréteur, comme ceci :

    $ python -m bandclass

Cette commande lance l'exécution de `__main__.py`. Il vous appartient, en tant que concepteur du paquet, de déterminer ce qu'elle doit faire. Dans notre exemple, elle pourrait rechercher un étudiant dans une base de données :

    # bandclass/__main__.py

    import sys
    from .student import search_students

    student_name = sys.argv[1] if len(sys.argv) >= 2 else ''
    print(f'Found student: {search_students(student_name)}')

Remarquez l'importation `from .student import search_students`. Le point avant `student` sert à rendre le chemin `student` relatif à la position du module qui l'importe. Pour plus d'informations, voir Références internes dans un paquet dans la section Modules du tutoriel.

### Utilisation idiomatique

The content of `__main__.py` typically isn't fenced with an `if __name__ == '__main__'` block. Instead, those files are kept short and import functions to execute from other modules. Those other modules can then be easily unit-tested and are properly reusable.

Cependant, un `if __name__ == '__main__'`, s'il est présent dans le `__main__.py`, fonctionne correctement. En effet, si `__main__.py` est importé depuis autre module, son attribut `__name__` contient, avant `__main__`, le nom du paquet dont il fait partie :

    >>> import asyncio.__main__
    >>> asyncio.__main__.__name__
    'asyncio.__main__'

This won't work for `__main__.py` files in the root directory of a `.zip` file though. Hence, for consistency, a minimal `__main__.py` without a `__name__` check is preferred.

Voir aussi

See `venv` for an example of a package with a minimal `__main__.py` in the standard library. It doesn't contain a `if __name__ == '__main__'` block. You can invoke it with `python -m venv [directory]`.

La documentation du module `runpy` fournit une description complète de l'option `-m` de l'interpréteur.

Le module `zipapp` exécute des applications emballées dans une archive ZIP. Dans ce cas, l'interpréteur recherche un fichier `__main__.py` à la racine de l'archive.

## `import __main__`

Quel que soit le module principal d'un programme, les autres modules peuvent accéder à l'espace de nommage dans lequel il s'exécute en important le module spécial `__main__`. Celui-ci ne correspond pas forcément à un fichier `__main__.py`. Il s'agit simplement du module qui a reçu le nom `'__main__'`.

Voici un exemple d'utilisation du module `__main__` :

    # namely.py

    import __main__

    def did_user_define_their_name():
        return 'my_name' in dir(__main__)

    def print_user_name():
        if not did_user_define_their_name():
            raise ValueError('Define the variable `my_name`!')

        print(__main__.my_name)

Ce code s'utilise comme ceci :

    # start.py

    import sys

    from namely import print_user_name

    # my_name = "Dinsdale"

    def main():
        try:
            print_user_name()
        except ValueError as ve:
            return str(ve)

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

Le programme ci-dessus donne la sortie :

    $ python start.py
    Define the variable `my_name`!

Son code de retour est 1, ce qui signifie une erreur. En supprimant la marque de commentaire en début de ligne `my_name = "Dinsdale"`, le programme est corrigé, et renvoie au système le code 0 car il n'y a plus d'erreur :

    $ python start.py
    Dinsdale

On pourrait s'attendre à un problème au moment de l'importation de `__main__` : cela ne provoque-t-il pas l'exécution anticipée du code de script sous `if __name__ == '__main__'` dans le module principal `start` ?

Python inserts an empty `__main__` module in `sys.modules` at interpreter startup, and populates it by running top-level code. In our example this is the `start` module which runs line by line and imports `namely`. In turn, `namely` imports `__main__` (which is really `start`). That's an import cycle! Fortunately, since the partially populated `__main__` module is present in `sys.modules`, Python passes that to `namely`. See Special considerations for __main__ in the import system's reference for details on how this works.

L'interpréteur interactif est un autre environnement d'exécution principal possible. Toute variable qui y est définie appartient à l'espace de nommage `__main__` :

    >>> import namely
    >>> namely.did_user_define_their_name()
    False
    >>> namely.print_user_name()
    Traceback (most recent call last):
    ...
    ValueError: Define the variable `my_name`!
    >>> my_name = 'Jabberwocky'
    >>> namely.did_user_define_their_name()
    True
    >>> namely.print_user_name()
    Jabberwocky

Le module `__main__` est notamment employé dans les implémentations de `pdb` et `rlcompleter`.