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 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)¶
Ejecuta el código del módulo especificado y devuelve el diccionario de globales del módulo resultante. El código del módulo se encuentra primero mediante el mecanismo de importación estándar (consulte PEP 302 para más detalles) y luego 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 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.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. init_globals no se modificará. Si alguna de las variables globales especiales siguientes se define en init_globals, 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 esNone
, paramod_name + ‘.__main__’
si módulo nombrado es un paquete y al argumento mod_name en caso contrario.__spec__
se configura apropiadamente para el módulo realmente importado (es decir,__spec__.name
siempre será un mod_name omod_name + '.__main__'
, nunca 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
, entoncessys.argv[0]
es actualizado y el valor de__file__
ysys.modules[__name__]
es actualizado con un objeto de módulo temporal para el módulo que se esta ejecutado. Ambassys.argv[0]
ysys.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ódulosys
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éaseModuleSpec
para alternativas.
- runpy.run_path(path_name, init_globals=None, run_name=None)¶
Ejecuta el código en la ubicación del sistema de ficheros indicada y devuelve el diccionario global del módulo resultante. Al igual que con un nombre de script suministrado a la línea de comandos de CPython, file_path puede referirse a un archivo fuente de Python, un archivo de código de bytes compilado o una entrada
sys.path
válida que contenga un módulo__main__
(por ejemplo, un archivo zip que contenga un archivo de nivel superior__main__.py
).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 desys.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 desys.path
si no existe 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. init_globals no se modificará. Si alguna de las variables globales especiales siguientes se define en init_globals, 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 esNone
y a'<run_path>'
de lo contrario.Si file_path hace referencia directamente a un archivo script (ya sea como fuente o un código de bytes precompilado), entonces
__file__
se establecerá en file_path, y__spec__
,__cached__
,__loader__
y__package__
se establecerán todos enNone
.Si file_path es una referencia a una entrada válida de
sys.path
, entonces__spec__
se establecerá apropiadamente para el módulo importado__main__
(es decir,__spec__.name
siempre será__main__
).__file__
,__cached__
,__loader__
y__package__
serán set as normal basándose en la especificación del módulo.También se realizan una serie de modificaciones en el módulo
sys
. En primer lugar,sys.path
puede alterarse como se ha descrito anteriormente. Se actualizasys.argv[0]
con el valor de file_path y se actualizasys.modules[__name__]
con un objeto módulo temporal para el módulo que se está ejecutando. Todas las modificaciones a los elementos ensys
son revertidas antes de que la función retorne.Tenga en cuenta que, a diferencia de
run_module()
, las alteraciones realizadas ensys
no son opcionales en esta función, ya que estos ajustes son esenciales para permitir la ejecución de las entradas desys.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 entradasys.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()