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