runpy — Localizando e executando módulos Python

Código-fonte: Lib/runpy.py

The runpy module is used to locate and run Python modules without importing them first. Its main use is to implement the -m command line switch that allows scripts to be located using the Python module namespace rather than the filesystem.

Observe que este não é um módulo isolado - todo o código é executado no processo atual, e quaisquer efeitos colaterais (como importações em cache de outros módulos) irão permanecer em vigor após o retorno da função.

Furthermore, any functions and classes defined by the executed code are not guaranteed to work correctly after a runpy function has returned. If that limitation is not acceptable for a given use case, importlib is likely to be a more suitable choice than this module.

The runpy module provides two functions:

runpy.run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)

Executa o código do módulo especificado e retorna o dicionário de globals do módulo resultante. O código do módulo é localizado primeiro usando o mecanismo de importação padrão (consulte PEP 302 para detalhes) e então executado em um novo espaço de nomes de módulo.

O argumento mod_name deve ser um nome de módulo absoluto. Se o nome do módulo se referir a um pacote ao invés de um módulo normal, então esse pacote é importado e o submódulo __main__ dentro desse pacote é então executado e o dicionário global do módulo resultante retornado.

O argumento opcional de dicionário init_globals pode ser usado para preencher previamente o dicionário global do módulo antes do código ser executado. init_globals não será modificado. Se qualquer uma das variáveis globais especiais abaixo for definida em init_globals, estas definições serão substituídas por run_module().

The special global variables __name__, __spec__, __file__, __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__ é definido como run_name se este argumento opcional não for None, para mod_name + '.__main__' se o módulo nomeado for um pacote e para o argumento mod_name caso contrário .

__spec__ será definido adequadamente para o módulo efetivamente importado (isto é, __spec__.name vai sempre ser mod_name ou mod_name + '.__main__', nunca run_name).

__file__, __loader__ and __package__ are set as normal based on the module spec.

Se o argumento alter_sys for fornecido e for avaliado como True, então sys.argv[0] será atualizado com o valor de __file__ e sys.modules[__name__] é atualizado com um objeto de módulo temporário para o módulo que está sendo executado. Ambos sys.argv[0] e sys.modules[__name__] são restaurados para seus valores originais antes que a função retorne.

Note que esta manipulação de sys não é segura para thread. Outras threads podem ver o módulo parcialmente inicializado, bem como a lista alterada de argumentos. É recomendado que o módulo sys seja deixado sozinho ao invocar esta função a partir do código encadeado.

Ver também

A opção -m oferece funcionalidade equivalente na linha de comando.

Alterado na versão 3.1: Adicionada capacidade de executar pacotes procurando por um submódulo __main__.

Alterado na versão 3.2: Adicionada a variável global __cached__ (veja PEP 3147).

Alterado na versão 3.4: Atualizado para aproveitar o recurso de spec de módulo adicionado por PEP 451. Isso permite que __cached__ seja configurado corretamente para módulos executados desta forma, assim como garante que o nome real do módulo esteja sempre acessível como __spec__.name.

Alterado na versão 3.12: A definição de __cached__, __loader__ e __package__ foi descontinuada. Veja ModuleSpec para alternativas.

Alterado na versão 3.15: __cached__ is no longer set.

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, path_name 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 um script simples, o código especificado é simplesmente executado em um novo espaço de nomes de módulo. Para uma entrada válida sys.path (normalmente um arquivo zip ou diretório), a entrada é primeiro adicionada ao início de sys.path. A função então procura e executa um módulo __main__ usando o caminho atualizado. Observe que não há proteção especial contra invocar uma entrada __main__ existente localizada em outro lugar em sys.path se não houver tal módulo no local especificado.

O argumento opcional de dicionário init_globals pode ser usado para preencher previamente o dicionário de globals do módulo antes do código ser executado. init_globals não será modificado. Se qualquer uma das variáveis globais especiais abaixo for definida em init_globals, estas definições serão substituídas por run_path().

The special global variables __name__, __spec__, __file__, __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__ é definido como run_name se este argumento opcional não for None e como '<run_path>' caso contrário.

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

If path_name 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__, __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 que, diferentemente de run_module(), as alterações feitas em sys não são opcionais nesta função, pois esses ajustes são essenciais para permitir a execução das entradas do sys.path. Como as limitações de segurança de threads ainda se aplicam, o uso dessa função no código encadeado deve ser serializado com a trava de importação ou delegado a um processo separado.

Ver também

Opções de interface para funcionalidade equivalente na linha de comando (python path/to/script).

Adicionado na versão 3.2.

Alterado na versão 3.4: Atualizado para aproveitar o recurso de spec de módulo adicionado por PEP 451. Isso permite que __cached__ seja definido corretamente no caso em que __main__ é importado de uma entrada sys.path válida em vez de ser executado diretamente.

Alterado na versão 3.12: A definição de __cached__, __loader__ e __package__ foi descontinuada.

Alterado na versão 3.15: __cached__ is no longer set.

Ver também

PEP 338 – Executando módulos como scripts

PEP escrita e implementada por Nick Coghlan.

PEP 366 – Importações relativas explícitas do módulo principal

PEP escrita e implementada por Nick Coghlan.

PEP 451 – Um tipo ModuleSpec para o sistema de importação

PEP escrita e implementada por Eric Snow

Linha de comando e ambiente - Detalhes da linha de comando do CPython

A função importlib.import_module()