# `runpy` — Locating and executing Python modules

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 línea 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)

  Execute the code of the specified module and return the resulting module’s globals dictionary. The module’s code is first located using the standard import mechanism (refer to PEP 302 for details) and then executed in a fresh module namespace.

  El argumento mod_name debe ser un nombre de módulo absoluto. Si el nombre del módulo se refiere a un paquete en lugar de a un módulo normal, entonces ese paquete se importa y el submódulo `__main__` dentro de ese paquete se ejecuta y se devuelve el diccionario de globales del módulo resultante.

  The optional dictionary argument init_globals may be used to pre-populate the module’s globals dictionary before the code is executed. init_globals will not be modified. If any of the special global variables below are defined in init_globals, those definitions are overridden by `run_module()`.

  The special global variables `__name__`, `__spec__`, `__file__`, `__cached__`, `__loader__` and `__package__` are set in the globals dictionary before the module code is executed. (Note that this is a minimal set of variables - other variables may be set implicitly as an interpreter implementation detail.)

  `__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__` will be set appropriately for the actually imported module (that is, `__spec__.name` will always be mod_name or `mod_name + '.__main__'`, never run_name).

  `__file__`, `__cached__`, `__loader__` y `__package__` son establecidos de forma normal basados en la especificación del módulo.

  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.

  Tenga en cuenta que esta manipulación de `sys` no es segura para los hilos. Otros hilos pueden ver el módulo parcialmente inicializado, así como la lista de argumentos alterada. Se recomienda no utilizar el módulo `sys` cuando se invoque a esta función desde código con hilos.

  Ver también

  La opción `-m` ofrece una funcionalidad equivalente desde la línea de comandos.

  Distinto en la versión 3.1: Se agrego la capacidad de ejecutar paquetes buscando un submódulo `__main__`.

  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ódulos añadida por PEP 451. Esto permite que `__cached__` se establezca correctamente para que los módulos se ejecuten de esta manera, así como asegurar que el nombre real del módulo siempre sea accesible como `__spec__.name`.

  Distinto en la versión 3.12: El establecimiento de `__cached__`, `__loader__`, y `__package__` están obsoletos. Véase `ModuleSpec` para alternativas.

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

  Execute the code at the named filesystem location and return the resulting module’s globals dictionary. As with a script name supplied to the CPython command line, file_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).

  Para un script simple, el código especificado simplemente se ejecuta en un espacio de nombres de módulo nuevo. Para una entrada `sys.path` válida (normalmente un archivo zip o directorio), la entrada se añade primero al principio de `sys.path`. A continuación, la función busca y ejecuta un módulo `__main__` utilizando la ruta actualizada. Tenga en cuenta que no hay ninguna protección especial contra la invocación de una entrada `__main__` existente ubicada en otro lugar de `sys.path` si no existe tal módulo en la ubicación especificada.

  The optional dictionary argument init_globals may be used to pre-populate the module’s globals dictionary before the code is executed. init_globals will not be modified. If any of the special global variables below are defined in init_globals, those definitions are overridden by `run_path()`.

  The special global variables `__name__`, `__spec__`, `__file__`, `__cached__`, `__loader__` and `__package__` are set in the globals dictionary before the module code is executed. (Note that this is a minimal set of variables - other variables may be set implicitly as an interpreter implementation detail.)

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

  If file_path directly references a script file (whether as source or as precompiled byte code), then `__file__` will be set to file_path, and `__spec__`, `__cached__`, `__loader__` and `__package__` will all be set to `None`.

  If file_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 file_path 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.

  Tenga en cuenta que, a diferencia de `run_module()`, las alteraciones realizadas en `sys` no son opcionales en esta función, ya que estos ajustes son esenciales para permitir la ejecución de las entradas de `sys.path`. Como las limitaciones de seguridad de hilos aún se aplican, el uso de esta función en código con hilos debe ser serializado con el bloqueo de importación o delegado a un proceso separado.

  Ver también

  Opciones de interfaz para una funcionalidad equivalente en la línea de comandos (`python path/to/script`).

  Added in version 3.2.

  Distinto en la versión 3.4: Se ha actualizado para aprovechar la función de especificación de módulos añadida por PEP 451. Esto permite que `__cached__` se establezca correctamente en el caso de que `__main__` se importe desde una entrada `sys.path` válida en lugar de ejecutarse directamente.

  Distinto en la versión 3.12: El establecimiento de `__cached__`, `__loader__` y `__package__` están en desuso.

Ver también

PEP 338 – Ejecutando módulos como scripts

  PEP escrito e implementado por Nick Coghlan.

PEP 366 – Importaciones relativas explícitas del módulo principal

  PEP escrito e implementado por Nick Coghlan.

PEP 451 — Un tipo ModuleSpec para el sistema de Importación

  PEP escrito e implementado por Eric Snow

Línea de comandos y entorno - Detalles de la línea de comandos CPython

La función `importlib.import_module()`