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