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