"__main__" --- Entorno de código de nivel máximo
************************************************

======================================================================

En Python, el nombre especial "__main__" es utilizado para dos
constructos importantes:

1. el nombre del entorno de máximo nivel del programa, que puede ser
   verificado usando la expresión "__name__=='__main__'"; y

2. el archivo "__main__.py" en paquetes de Python.

Ambos de estos mecanismos están relacionados con módulos de Python;
como los usuarios interactúan con ellos y como ellos interactúan entre
sí.  Están explicados en detalle más abajo.  Si estás empezando con
los módulos de Python, mira la sección tutorial Módulos para una
introducción.


"__name__ == '__main__'"
========================

Cuando un módulo o paquete de Python es importado, "__name__" es
asignado al nombre del módulo.  Normalmente, este es el nombre del
archivo de Python sin la extensión ".py":

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

Si el archivo es parte de un paquete, "__name__" también incluirá la
ruta del paquete padre:

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

Sin embargo, si el módulo es ejecutado en el entorno de código de
máximo nivel, su "__name__" se le asigna el valor del string
"'__main__'".


¿Qué es el "entorno de código de máximo nivel"?
-----------------------------------------------

"__main__" es el nombre del entorno en el cual se ejecuta el código de
máximo nivel. "Código de máximo nivel" es el primer módulo de Python
especificado por el usuario que empieza a ejecutarse. Es "de máximo
nivel" porque importa todos los demás módulos que necesita el
programa. A veces "código de máximo nivel" es llamado un *punto de
entrada* a la aplicación.

El entorno de código de máximo nivel puede ser:

* el ámbito de un intérprete interactivo:

     >>> __name__
     '__main__'

* el módulo de Python pasado al intérprete de Python como un argumento
  de archivo:

     $ python3 helloworld.py
     Hello, world!

* el módulo o paquete de Python pasado al interprete de Python con el
  argumento "-m":

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

* Código de Python leído por el interprete desde input estándar:

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

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

* Código de Python pasado al intérprete Python con el argumento "-c":

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

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

En cada una de estas situaciones, al "__name__" del módulo de máximo
nivel se le asigna el valor "'__main__'".

En consecuencia, un módulo puede descubrir si se está ejecutando o no
en el ámbito principal al verificar su propio "__name__", lo cual
permite un vocablo común para ejecutar código condicionalmente cuando
el módulo no es inicializado desde una declaración de importado:

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

Ver también:

  Para una vista más detallada de como "__name__" es asignado en todas
  las situaciones, ver la sección tutorial Módulos.


Uso idiomático
--------------

Some modules contain code that is intended for script use only, like
parsing command-line arguments or fetching data from standard input.
If a module like this was imported from a different module, for
example to unit test it, the script code would unintentionally execute
as well.

Aquí es donde es útil usar el código de bloque "if
__name__=='__main__'". El código dentro desde bloque no se ejecutará a
menos que el módulo se ejecute en el entorno de máximo nivel.

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

Note que si el módulo no encapsulase el código dentro de la función
"main" pero en vez lo pusiese directo dentro del bloque  "if
__name__=='__main__'", la variable "phrase" sería global al módulo
entero.  Esto está propenso a generar errores ya que otras funciones
dentro del módulo pudiesen estar usando involuntariamente la variable
global en lugar de un nombre local.  Una función "main" resuelve este
problema.

Usar una función "main" tiene el beneficio añadido de que la función
"echo" está aislada y es importable en otros sitios. Cuando "echo.py"
es importado, las funciones "echo" y "main" serán definidas, pero
ninguna de ellas será llamada porque "__name!='__main__'".


Consideraciones de empaquetado
------------------------------

Las funciones "main" se utilizan a menudo para crear líneas de comando
al especificarlas como puntos de entrada para scripts de terminal.
Cuando esto se hace, pip inserta la llamada de la función a un script
plantilla, donde el valor retornado de "main" se pasa a "sys.exit()".
Por ejemplo:

   sys.exit(main())

Dado que la llamada a "main" está dentro de "sys.exit()", la
expectativa es que tu función devolverá un valor aceptable como una
entrada a "sys.exit()"; típicamente, un int o "None" (que se retorna
implícitamente si tu función no tiene una declaración de retorno).

Al seguir pro-activamente esta convención nosotros mismo, nuestro
módulo tendrá el mismo comportamiento cuando se ejecuta directamente
(es decir, "python3 echo.py") que si luego lo empaquetamos como un
punto de entrada de script de terminal en un paquete instalable
mediante pip.

En particular, ten cuidado al devolver cadenas de texto con tu función
"main". "sys.exit()" interpretará un argumento de cadena de texto como
un mensaje de fallo, entonces tu programa tendrá un código de salida
de "1", indicando fallo, y la cadena de texto será escrita a
"sys.stderr".  El ejemplo "echo.py" de antes muestra como usar la
convención "sys.exit(main())".

Ver también:

  Python Packaging User Guide contiene una colección de tutoriales y
  referencias sobre como distribuir e instalar paquetes de Python con
  herramientas modernas.


"__main__.py" en paquetes de Python
===================================

Si no estás familiarizado con paquetes de Python, ver la sección
Paquetes del tutorial.  Comúnmente, el archivo "__main__.py" es
utilizado para proveer una interfaz de línea de comando para un
paquete. Considera el siguiente paquete hipotético, "*bandclass*":

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

"__main__.py" será ejecutado cuando el paquete sea invocado
directamente desde la línea de comandos usando el indicador "-m". Por
ejemplo:

   $ python3 -m bandclass

Este comando causará que "__main__.py" se ejecute. El como se use este
mecanismo dependerá de la naturaleza del paquete que estás
escribiendo, pero en este caso hipotético, puede tener sentido
permitir que el profesor busque estudiantes:

   # 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)}')

Note that "from .student import search_students" is an example of a
relative import.  This import style can be used when referencing
modules within a package.  For more details, see Referencias internas
en paquetes in the Módulos section of the tutorial.


Uso idiomático
--------------

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.

Si se usa, un bloque "if __name__=='__main__'" seguirá funcionando
como se espera para un archivo "__main__.py" dentro de un paquete,
porque su atributo "__name__" incluirá la ruta del paquete si es
importado:

   >>> 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, minimal "__main__.py" like
the "venv" one mentioned below are preferred.

Ver también:

  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]".

  Ver "runpy" para más detalles sobre el indicador "-m" para el
  interprete ejecutable.

  Ver "zipapp" para más información sobre como ejecutar aplicaciones
  empaquetadas como archivos *.zip*. En este caso Python busca un
  archivo "__main__.py" en el directorio raíz del archivo comprimido.


"import __main__"
=================

Independientemente de con cual módulo se ha iniciado un programa de
Python, otros módulos que están siendo ejecutados dentro del mismo
programa pueden importar el ámbito del entorno de máximo nivel
(*namespace*) al importar el módulo "__main__".  Esto no importa un
archivo "__main__.py" pero en su lugar cualquier módulo que recibió el
nombre especial "'__main__'".

Acá hay un módulo ejemplo que consume el nombre de espacio "__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)

Ejemplo del uso de este módulo puede ser:

   # 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())

Si ahora iniciamos nuestro programa el resultado sería así:

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

El código de salida del programa sería 1, indicando un error. Des-
comentando la línea con "my_name = "Dinsdale"" arregla el programa y
ahora sale con un código de estado 0, indicando éxito:

   $ python3 start.py
   Dinsdale found in file /path/to/start.py

Note que importar "__main__" no causa ningún problema de
involuntariamente ejecutar código de máximo nivel que ha sido pensado
para uso por scripts que es puesto en el bloque "if
__name__=="__main__"" del módulo "start". ¿Por qué funciona esto?

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.

El REPL Python es otro ejemplo de un "entorno de máximo nivel", por lo
tanto, cualquier cosa definida en el REPL se hace parte del ámbito
"__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

Note que en este caso el ámbito "__main__" no contiene un atributo
"__file__" ya que es interactivo.

El ámbito "__main__" es utilizado en la implementación de "pdb" y
"rlcompleter".
