"runpy" --- Localización y ejecución de módulos *Python*
********************************************************

**Código Fuente:** Lib/runpy.py

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

El modulo  "runpy" es usado para localizar y correr módulos *Python*
sin importarlo primero. Su uso principal es implementar la opción "-m"
cambiando la linea de comando que permite que los scripts se ubiquen
utilizando el espacio de nombres del módulo de Python en lugar del
sistema de archivos.

Tenga en cuenta que este *no* es un módulo de espacio aislado - Todo
el código es ejecutado en el proceso actual, y cualquier efecto
secundario (como las importaciones en cache de otros módulos)
permanecerán en su lugar después de que las funciones hayan retornado.

Además, no se garantiza que las funciones y clases definidas por el
código ejecutado funcionen correctamente después de que se haya
devuelto la función "runpy". Si esa limitación no es aceptable para un
caso de uso determinado, es probable que "importlib" sea una opción
más adecuada que este módulo.

El modulo "runpy" proporciona dos funciones:

runpy.run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)

   Ejecute el código del módulo especificado y devuelva el diccionario
   de globales de módulo resultante. El código del módulo se encuentra
   primero mediante el mecanismo de importación estándar (consulte
   **PEP 302** para obtener más información) y, a continuación, se
   ejecuta en un espacio de nombres de módulo nuevo.

   The *mod_name* argument should be an absolute module name. If the
   module name refers to a package rather than a normal module, then
   that package is imported and the "__main__" submodule within that
   package is then executed and the resulting module globals
   dictionary returned.

   El argumento de diccionario opcional *init_globals* se puede
   utilizar para rellenar previamente el diccionario global del módulo
   antes de ejecutar el código. El diccionario suministrado no se
   modificará. Si alguna de las variables globales especiales
   siguientes se define en el diccionario proporcionado, esas
   definiciones se reemplazan por "run_module()".

   Las variables globales especiales "__name__", "__spec__",
   "__file__", "__cached__", "__loader__" y "__package__" se
   establecen en el diccionario global antes del que el código del
   módulo sea ejecutado (tenga en cuenta que esto es un conjunto
   mínimo de variables - otras variables pueden establecerse
   implícitamente como un detalle de implementación del intérprete).

   "__name__" se establece en *run_name* si el argumento opcional no
   es "None", para "mod_name + ‘.__main__’" si módulo nombrado es un
   paquete y al argumento *mod_name* en caso contrario.

   "__spec__" se configura apropiadamente para el modulo *realmente*
   importado (es decir, "__spec__.name" siempre será un *mod_name* o
   "mod_name + ‘.__main__", jamas *run_name*).

   "__file__", "__cached__", "__loader__" y "__package__" son basados
   en la especificación del modulo set as normal.

   Si el argumento *alter_sys* es proporcionado y evaluado a "True",
   entonces "sys.argv[0]" es actualizado y el valor de "__file__" y
   "sys.modules[__name__]" es actualizado con un objeto de módulo
   temporal para el módulo que se esta ejecutado. Ambas "sys.argv[0]"
   y "sys.modules[__name__]" son restauradas a sus valores originales
   antes del retorno de la función.

   Note that this manipulation of "sys" is not thread-safe. Other
   threads may see the partially initialised module, as well as the
   altered list of arguments. It is recommended that the "sys" module
   be left alone when invoking this function from threaded code.

   Ver también:

     La opción "-m" ofrece una funcionalidad equivalente desde la
     linea de comandos.

   Distinto en la versión 3.1: Added ability to execute packages by
   looking for a "__main__" submodule.

   Distinto en la versión 3.2: Se agrego la variable global
   "__cached__" (consultar **PEP 3147**).

   Distinto en la versión 3.4: Se ha actualizado para aprovechar la
   función de especificación de módulo agregada por **PEP 451**. Esto
   permite que "__cached__" se establezca correctamente para que los
   módulos se ejecuten de esta manera, así como asegurarse de que el
   nombre real del módulo siempre sea accesible como "__spec__.name".

runpy.run_path(path_name, init_globals=None, run_name=None)

   Execute the code at the named filesystem location and return the
   resulting module globals dictionary. As with a script name supplied
   to the CPython command line, the supplied path may refer to a
   Python source file, a compiled bytecode file or a valid "sys.path"
   entry containing a "__main__" module (e.g. a zipfile containing a
   top-level "__main__.py" file).

   For a simple script, the specified code is simply executed in a
   fresh module namespace. For a valid "sys.path" entry (typically a
   zipfile or directory), the entry is first added to the beginning of
   "sys.path". The function then looks for and executes a "__main__"
   module using the updated path. Note that there is no special
   protection against invoking an existing "__main__" entry located
   elsewhere on "sys.path" if there is no such module at the specified
   location.

   El argumento de diccionario opcional *init_globals* se puede
   utilizar para rellenar previamente el diccionario global del módulo
   antes de ejecutar el código. El diccionario suministrado no se
   modificará. Si alguna de las variables globales especiales
   siguientes se define en el diccionario proporcionado, esas
   definiciones se reemplazan por "run_path()".

   Las variables globales especiales "__name__", "__spec__",
   "__file__", "__cached__", "__loader__" y "__package__" se
   establecen en el diccionario global antes del que el código del
   módulo sea ejecutado (tenga en cuenta que esto es un conjunto
   mínimo de variables - otras variables pueden establecerse
   implícitamente como un detalle de implementación del intérprete).

   "__name__" se establece para *run_name* si el argumento opcional no
   es "None" y a "'<run_path>'" de lo contrario.

   Si la ruta proporcionada hace referencia a un archivo *script* (ya
   sea como fuente o un código de *byte* precompilado), entonces
   "__file__" se establecerá en la ruta proporcionada, y "__spec__",
   "__cached__", "__loader__" y "__package__" se establecerán todos en
   "None".

   If the supplied path is a reference to a valid "sys.path" entry,
   then "__spec__" will be set appropriately for the imported
   "__main__" module (that is, "__spec__.name" will always be
   "__main__"). "__file__", "__cached__", "__loader__" and
   "__package__" will be set as normal based on the module spec.

   A number of alterations are also made to the "sys" module. Firstly,
   "sys.path" may be altered as described above. "sys.argv[0]" is
   updated with the value of "path_name" and "sys.modules[__name__]"
   is updated with a temporary module object for the module being
   executed. All modifications to items in "sys" are reverted before
   the function returns.

   Note that, unlike "run_module()", the alterations made to "sys" are
   not optional in this function as these adjustments are essential to
   allowing the execution of "sys.path" entries. As the thread-safety
   limitations still apply, use of this function in threaded code
   should be either serialised with the import lock or delegated to a
   separate process.

   Ver también:

     Opciones de interfaz para una funcionalidad equivalente en la
     linea de comandos ("python path/to/script").

   Nuevo en la versión 3.2.

   Distinto en la versión 3.4: Updated to take advantage of the module
   spec feature added by **PEP 451**. This allows "__cached__" to be
   set correctly in the case where "__main__" is imported from a valid
   "sys.path" entry rather than being executed directly.

Ver también:

  **PEP 338** -- Ejecutando módulos como *scripts*
     *PEP* escrito y implementado por *Nick Coghlan*.

  **PEP 366** -- Importaciones relativas explícitas del módulo
  principal
     *PEP* escrito y implementado por *Nick Coghlan*.

  **PEP 451** — Un tipo *ModuleSpec* para el sistema de Importación
     *PEP* escrito y implementado por *Eric Snow*

  Línea de comandos y entorno - Detalles de la linea de comandos
  *CPython*

  La función "importlib.import_module()"
