runpy
— Localizando e executando módulos Python¶
Código-fonte: Lib/runpy.py
O módulo runpy
é usado para localizar e executar módulos Python sem importá-los primeiro. Seu principal uso é implementar a opção de linha de comando -m
que permite que os scripts sejam localizados usando o espaço de nomes do módulo Python em vez do sistema de arquivos.
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.
Além disso, quaisquer funções e classes definidas pelo código executado não têm garantia de funcionar corretamente após o retorno de uma função runpy
. Se essa limitação não for aceitável para um determinado caso de uso, importlib
provavelmente será uma escolha mais adequada do que este módulo.
O módulo runpy
fornece duas funções:
-
runpy.
run_module
(mod_name, init_globals=None, run_name=None, alter_sys=False)¶ Execute o código do módulo especificado e retorne o dicionário global 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. O dicionário fornecido não será alterado. Se qualquer uma das variáveis globais especiais abaixo for definida no dicionário fornecido, estas definições serão substituídas por
run_module()
.As variáveis globais especiais
__name__
,__spec__
,__file__
,__cached__
,__loader__
e__package__
são definidas no dicionário global antes que o código do módulo seja executado (Observe que este é um conjunto mínimo de variáveis - outras variáveis podem ser definidas implicitamente como um detalhe de implementação do interpretador).__name__
é definido como run_name se este argumento opcional não forNone
, paramod_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 modo efetivamente importado (isto é,__spec__.name
vai sempre ser mod_name oumod_name + '.__main__
, nunca run_name).__file__
,__cached__
,__loader__
e__package__
são definidos como normal com base no spec de módulo.Se o argumento alter_sys for fornecido e for avaliado como
True
, entãosys.argv[0]
será atualizado com o valor de__file__
esys.modules[__name__]
é atualizado com um objeto de módulo temporário para o módulo que está sendo executado. Ambossys.argv[0]
esys.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ódulosys
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 sub-mó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
.
-
runpy.
run_path
(path_name, init_globals=None, run_name=None)¶ Executa o código no local do sistema de arquivos nomeado e retorna o dicionário global do módulo resultante. Assim como um nome de script fornecido à linha de comando CPython, o caminho fornecido pode se referir a um arquivo de origem Python, um arquivo de bytecode compilado ou uma entrada sys.path válida contendo um módulo
__main__
(por exemplo, um arquivo zip contendo um arquivo de topo de nível__main__.py
).Para um script simples, o código especificado é simplesmente executado em um novo espaço de nomes de módulo. Para uma entrada sys.path válida (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 emsys.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 global do módulo antes do código ser executado. O dicionário fornecido não será alterado. Se qualquer uma das variáveis globais especiais abaixo for definida no dicionário fornecido, estas definições serão substituídas por
run_path()
.As variáveis globais especiais
__name__
,__spec__
,__file__
,__cached__
,__loader__
e__package__
são definidas no dicionário global antes que o código do módulo seja executado (Observe que este é um conjunto mínimo de variáveis - outras variáveis podem ser definidas implicitamente como um detalhe de implementação do interpretador).__name__
é definido como run_name se este argumento opcional não forNone
e como'<run_path>'
caso contrário.Se o caminho fornecido referenciar diretamente um arquivo de script (seja como fonte ou como bytecode pré-compilado), então
__file__
será definido para o caminho fornecido e__spec__
,__cached__
,__loader__
e__package__
serão todos definidos comoNone
.Se o caminho fornecido for uma referência a uma entrada sys.path válida, então
__spec__
será definido apropriadamente para o módulo__main__
importado (ou seja,__spec__.name
sempre será__main__
).__file__
,__cached__
,__loader__
e__package__
serão definidos como normal com base na especificação do módulo.Várias alterações também são feitas no módulo
sys
. Primeiramente,sys.path
pode ser alterado conforme descrito acima.sys.argv[0]
é atualizado com o valor depath_name
esys.modules[__name__]
é atualizado com um objeto de módulo temporário para o módulo que está sendo executado. Todas as modificações em itens emsys
são revertidas antes que a função retorne.Note que, diferentemente de
run_module()
, as alterações feitas emsys
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 encadeamento ainda se aplicam, o uso dessa função no código encadeado deve ser serializado com o bloqueio 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
).Novo na versão 3.2.
Alterado na versão 3.4: Atualizado para aproveitar o recurso de especificação do 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.
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()