"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 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 modo *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 na especificação do 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 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
   especificação do 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(file_path, 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 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 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 for "None" 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 como "None".

   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.

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