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)

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

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 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__, __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ã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.

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 de globals do módulo resultante. Assim como um nome de script fornecido à linha de comando CPython, file_path pode se referir a um arquivo fonte Python, um arquivo compilado em bytecode ou uma entrada válida de sys.path contendo um módulo __main__ (por exemplo, um arquivo zip contendo um arquivo de nível superior __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 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().

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 for None e como '<run_path>' caso contrário.

Se file_path fizer referência diretamente a um arquivo de script (seja como fonte ou como bytecode pré-compilado), então __file__ será definido para file_path e __spec__, __cached__, __loader__ e __package__ serão todos definidos como None.

Se file_path for uma referência a uma entrada válida de sys.path, 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 no spec de 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 de file_path e sys.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 em sys são revertidas antes que a função retorne.

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.

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