# `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.

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

  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.

  Tenga en cuenta que esta manipulación de `sys` no es segura para subprocesos. Otros subprocesos pueden ver el módulo parcialmente inicializado, así como la lista alterada de argumentos. Se recomienda que el módulo `sys` se deje solo al invocar esta función desde código roscado.

  Ver también

  La opción `-m` ofrece una funcionalidad equivalente desde la linea 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ó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)

  Ejecute el código en la ubicación del sistema de archivos con nombre y devuelva el diccionario de globales de módulo resultante. Al igual que con un nombre de script proporcionado a la línea de comandos de CPython, la ruta de acceso proporcionada puede hacer referencia a un archivo de origen de Python, un archivo de código de bytes compilado o una entrada sys.path válida que contiene un módulo `__main__` (por ejemplo, un archivo zip que contiene un archivo `__main__.py` de nivel superior).

  Para un script simple, el código especificado se ejecuta simplemente en un espacio de nombres de un módulo nuevo. Para un entrada sys.path valida (comúnmente es un archivo zip o un directorio), la entrada se agrega primero al comienzo de `sys.path`. La función busca y ejecuta un modulo `__main__` usando la ruta actualizada. Tenga en cuenta que no existe una protección especial contra la invocación de una entrada existente `__main__` ubicada en otro lugar en `sys.path` si no hay tal módulo en la ubicación especificada.

  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`.

  Si la ruta proporciona es una referencia a una entrada sys.path valida, entonces `__spec__` se establece apropiadamente para la importación del modulo `__main__``(es decir, ``__spec__.name` siempre deberá ser `__main__`). `__file__`, `__cached__`, `__loader__` y `__package__` estarán basadas en la especificación del modulo establecidas como normal.

  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.

  Tenga en cuenta que, diferente a `run_module()`, las alteraciones hecha a `sys` no son opcionales en esta función ya que estos ajustes son esenciales para permitir la ejecución de entradas sys.path. Como aún se aplican las limitaciones de seguridad de los subprocesos, el uso de esta función en un código procesado debe serializarse con el bloqueo de importación o delegarse a un proceso separado.

  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: Actualizado para aprovechar la función de especificación del módulo agregada por PEP 451. Esto permite que `__cached__` se configure correctamente en el caso de que `__main__` se importe de una entrada sys.path valida en lugar de ejecutarse directamente.

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