"__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`!')

       if '__file__' in dir(__main__):
           print(__main__.my_name, "found in file", __main__.__file__)
       else:
           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 found in file /path/to/start.py

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

Dans ce cas, il n'y a pas de variable "__file__", puisque cela n'a pas
de sens dans le mode interactif.

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