"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 :p
   ep:'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(file_path, 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.

   También se realizan una serie de alteraciones en el módulo "sys".
   En primer lugar, "sys.path" puede ser alterado como se describió
   anteriormente. "sys.argv[0]" se actualiza con el valor de
   "file_path" y "sys.modules[__name__]" se actualiza con un objeto de
   módulo temporal para el módulo que se está ejecutando. Todas las
   modificaciones de los elementos de "sys" se revierten antes de que
   se devuelva la función.

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