Importando módulos
******************

PyObject *PyImport_ImportModule(const char *name)
    *Retorna valor: Nova referência.** Part of the Stable ABI.*

   Esta é uma interface simplificada para "PyImport_ImportModuleEx()"
   abaixo, deixando os argumentos *globals* e *locals* definidos como
   "NULL" e *level* definido como 0. Quando o argumento *name* contém
   um caractere de ponto (quando especifica um submódulo de um
   pacote), o argumento *fromlist* é definido para a lista "['*']" de
   modo que o valor de retorno é o módulo nomeado em vez do pacote de
   nível superior que o contém como faria caso contrário, seja o caso.
   (Infelizmente, isso tem um efeito colateral adicional quando *name*
   de fato especifica um subpacote em vez de um submódulo: os
   submódulos especificados na variável "__all__" do pacote são
   carregados.) Retorna uma nova referência ao módulo importado, ou
   "NULL" com uma exceção definida em caso de falha. Uma importação
   com falha de um módulo não deixa o módulo em "sys.modules".

   Esta função sempre usa importações absolutas.

PyObject *PyImport_ImportModuleNoBlock(const char *name)
    *Retorna valor: Nova referência.** Part of the Stable ABI.*

   Esta função é um alias descontinuado de "PyImport_ImportModule()".

   Alterado na versão 3.3: Essa função falhava em alguns casos, quando
   a trava de importação era mantida por outra thread. No Python 3.3,
   no entanto, o esquema de trava mudou passando a ser de travas por
   módulo na maior parte, dessa forma, o comportamento especial dessa
   função não é mais necessário.

PyObject *PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
    *Retorna valor: Nova referência.*

   Importa um módulo. Isso é melhor descrito referindo-se à função
   embutida do Python "__import__()".

   O valor de retorno é uma nova referência ao módulo importado ou
   pacote de nível superior, ou "NULL" com uma exceção definida em
   caso de falha. Como para "__import__()", o valor de retorno quando
   um submódulo de um pacote é solicitado é normalmente o pacote de
   nível superior, a menos que um *fromlist* não vazio seja fornecido.

   As importações com falhas removem objetos incompletos do módulo,
   como em "PyImport_ImportModule()".

PyObject *PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
    *Retorna valor: Nova referência.** Part of the Stable ABI since
   version 3.7.*

   Importa um módulo. Isso é melhor descrito referindo-se à função
   embutida do Python "__import__()", já que a função padrão
   "__import__()" chama essa função diretamente.

   O valor de retorno é uma nova referência ao módulo importado ou
   pacote de nível superior, ou "NULL" com uma exceção definida em
   caso de falha. Como para "__import__()", o valor de retorno quando
   um submódulo de um pacote é solicitado é normalmente o pacote de
   nível superior, a menos que um *fromlist* não vazio seja fornecido.

   Novo na versão 3.3.

PyObject *PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
    *Retorna valor: Nova referência.** Part of the Stable ABI.*

   Semelhante para "PyImport_ImportModuleLevelObject()", mas o nome é
   uma string codificada em UTF-8 de um objeto Unicode.

   Alterado na versão 3.3: Valores negativos para *level* não são mais
   aceitos.

PyObject *PyImport_Import(PyObject *name)
    *Retorna valor: Nova referência.** Part of the Stable ABI.*

   Essa é uma interface de alto nível que chama a atual "função
   auxiliar de importação" (com um *level* explícito de 0,
   significando importação absoluta). Invoca a função "__import__()" a
   partir de "__builtins__" da global atual. Isso significa que a
   importação é feita usando quaisquer extras de importação instalados
   no ambiente atual.

   Esta função sempre usa importações absolutas.

PyObject *PyImport_ReloadModule(PyObject *m)
    *Retorna valor: Nova referência.** Part of the Stable ABI.*

   Recarrega um módulo. Retorna uma nova referência para o módulo
   recarregado, ou "NULL" com uma exceção definida em caso de falha (o
   módulo ainda existe neste caso).

PyObject *PyImport_AddModuleObject(PyObject *name)
    *Retorna valor: Referência emprestada.** Part of the Stable ABI
   since version 3.7.*

   Retorna o objeto módulo correspondente a um nome de módulo. O
   argumento *name* pode ter a forma "package.module". Primeiro
   verifica o dicionário de módulos se houver algum, caso contrário,
   cria um novo e insere-o no dicionário de módulos. Retorna "NULL"
   com uma exceção definida em caso de falha.

   Nota:

     Esta função não carrega ou importa o módulo; se o módulo não foi
     carregado, você receberá um objeto de módulo vazio. Use
     "PyImport_ImportModule()" ou uma de suas variações para importar
     um módulo. Estruturas de pacotes implícitos por um nome
     pontilhado para a *name* não são criados se não estiverem
     presentes.

   Novo na versão 3.3.

PyObject *PyImport_AddModule(const char *name)
    *Retorna valor: Referência emprestada.** Part of the Stable ABI.*

   Semelhante para "PyImport_AddModuleObject()", mas o nome é uma
   string codifica em UTF-8 em vez de um objeto Unicode.

PyObject *PyImport_ExecCodeModule(const char *name, PyObject *co)
    *Retorna valor: Nova referência.** Part of the Stable ABI.*

   Dado um nome de módulo (possivelmente na forma "package.module") e
   um objeto código lido de um arquivo de bytecode Python ou obtido da
   função embutida "compile()", carrega o módulo. Retorna uma nova
   referência ao objeto do módulo, ou "NULL" com uma exceção definida
   se ocorrer um erro. *name* é removido de "sys.modules" em casos de
   erro, mesmo se *name* já estivesse em "sys.modules" na entrada para
   "PyImport_ExecCodeModule()". Deixar módulos incompletamente
   inicializados em "sys.modules" é perigoso, pois as importações de
   tais módulos não têm como saber se o objeto módulo é um estado
   desconhecido (e provavelmente danificado em relação às intenções do
   autor do módulo).

   O "__spec__" e o "__loader__" do módulo serão definidos, se não
   estiverem, com os valores apropriados. O carregador do spec será
   definido para o "__loader__" do módulo (se definido) e para uma
   instância da classe "SourceFileLoader" em caso contrário.

   O atributo "__file__" do módulo será definido para o "co_filename"
   do objeto código. Se aplicável, "__cached__" também será definido.

   Esta função recarregará o módulo se este já tiver sido importado.
   Veja "PyImport_ReloadModule()" para forma desejada de recarregar um
   módulo.

   Se *name* apontar para um nome pontilhado no formato de
   "package.module", quaisquer estruturas de pacote ainda não criadas
   ainda não serão criadas.

   Veja também "PyImport_ExecCodeModuleEx()" e
   "PyImport_ExecCodeModuleWithPathnames()".

PyObject *PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
    *Retorna valor: Nova referência.** Part of the Stable ABI.*

   Como "PyImport_ExecCodeModule()", mas o atributo "__file__"  do
   objeto módulo é definido como *pathname*  se não for "NULL".

   Veja também "PyImport_ExecCodeModuleWithPathnames()".

PyObject *PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
    *Retorna valor: Nova referência.** Part of the Stable ABI since
   version 3.7.*

   Como "PyImport_ExecCodeModuleEx()", mas o atributo "__cached__"  do
   objeto módulo é definido como *cpathname*  se não for "NULL". Das
   três funções, esta é a preferida para usar.

   Novo na versão 3.3.

PyObject *PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)
    *Retorna valor: Nova referência.** Part of the Stable ABI.*

   Como "PyImport_ExecCodeModuleObject()", mas *name*, *pathname* e
   *cpathname* são strings codificadas em UTF-8. Também são feitas
   tentativas para descobrir qual valor para *pathname* deve ser de
   *cpathname* se o primeiro estiver definido como "NULL".

   Novo na versão 3.2.

   Alterado na versão 3.3: Usa "imp.source_from_cache()" no cálculo do
   caminho de origem se apenas o caminho do bytecode for fornecido.

long PyImport_GetMagicNumber()
    * Part of the Stable ABI.*

   Retorna o número mágico para arquivos de bytecode Python (também
   conhecido como arquivo ".pyc"). O número mágico deve estar presente
   nos primeiros quatro bytes do arquivo bytecode, na ordem de bytes
   little-endian. Retorna "-1" em caso de erro.

   Alterado na versão 3.3: Retorna o valor de "-1" no caso de falha.

const char *PyImport_GetMagicTag()
    * Part of the Stable ABI.*

   Retorna a string de tag mágica para nomes de arquivo de bytecode
   Python no formato de **PEP 3147**. Tenha em mente que o valor em
   "sys.implementation.cache_tag" é autoritativo e deve ser usado no
   lugar desta função.

   Novo na versão 3.2.

PyObject *PyImport_GetModuleDict()
    *Retorna valor: Referência emprestada.** Part of the Stable ABI.*

   Retorna o dicionário usado para a administração do módulo (também
   conhecido como "sys.modules"). Observe que esta é uma variável por
   interpretador.

PyObject *PyImport_GetModule(PyObject *name)
    *Retorna valor: Nova referência.** Part of the Stable ABI since
   version 3.8.*

   Retorna o módulo já importado com o nome fornecido. Se o módulo
   ainda não foi importado, retorna "NULL", mas não define um erro.
   Retorna "NULL" e define um erro se a pesquisa falhar.

   Novo na versão 3.7.

PyObject *PyImport_GetImporter(PyObject *path)
    *Retorna valor: Nova referência.** Part of the Stable ABI.*

   Retorna um objeto localizador para o item *path* de
   "sys.path"/"pkg.__path__", possivelmente obtendo-o do dicionário
   "sys.path_importer_cache". Se ainda não foi armazenado em cache,
   atravessa "sys.path_hooks" até que um gancho seja encontrado que
   possa lidar com o item de caminho. Retorna "None" se nenhum gancho
   puder; isso diz ao nosso chamador que o *localizador baseado no
   caminho* não conseguiu encontrar um localizador para este item de
   caminho. Armazena o resultado em "sys.path_importer_cache". Retorna
   uma nova referência ao objeto localizador.

int PyImport_ImportFrozenModuleObject(PyObject *name)
    * Part of the Stable ABI since version 3.7.*

   Carrega um módulo congelado chamado *name*. Retorna "1" para
   sucesso, "0" se o módulo não for encontrado e "-1" com uma exceção
   definida se a inicialização falhar. Para acessar o módulo importado
   em um carregamento bem-sucedido, use "PyImport_ImportModule()".
   (Observe o nome incorreto --- esta função recarregaria o módulo se
   ele já tivesse sido importado.)

   Novo na versão 3.3.

   Alterado na versão 3.4: O atributo "__file__" não está mais
   definido no módulo.

int PyImport_ImportFrozenModule(const char *name)
    * Part of the Stable ABI.*

   Semelhante a "PyImport_ImportFrozenModuleObject()", mas o nome é
   uma string codificada em UTF-8 em vez de um objeto Unicode.

struct _frozen

   Esta é a definição do tipo de estrutura para descritores de módulo
   congelados, conforme gerado pelo utilitário **freeze** (veja
   "Tools/freeze/" na distribuição fonte do Python). Sua definição,
   encontrada em "Include/import.h", é:

      struct _frozen {
          const char *name;
          const unsigned char *code;
          int size;
      };

const struct _frozen *PyImport_FrozenModules

   Este ponteiro é inicializado para apontar para um vetor de
   registros de "_frozen", terminado por um cujos membros são todos
   "NULL" ou zero. Quando um módulo congelado é importado, ele é
   pesquisado nesta tabela. O código de terceiros pode fazer truques
   com isso para fornecer uma coleção criada dinamicamente de módulos
   congelados.

int PyImport_AppendInittab(const char *name, PyObject *(*initfunc)(void))
    * Part of the Stable ABI.*

   Adiciona um único módulo à tabela existente de módulos embutidos.
   Este é um invólucro prático em torno de "PyImport_ExtendInittab()",
   retornando "-1" se a tabela não puder ser estendida. O novo módulo
   pode ser importado pelo nome *name* e usa a função *initfunc* como
   a função de inicialização chamada na primeira tentativa de
   importação. Deve ser chamado antes de "Py_Initialize()".

struct _inittab

   Estrutura que descreve uma única entrada na lista de módulos
   embutidos. Cada uma dessas estruturas fornece o nome e a função de
   inicialização para um módulo embutido ao interpretador. O nome é
   uma string codificada em ASCII. Os programas que embutem Python
   podem usar um vetor dessas estruturas em conjunto com
   "PyImport_ExtendInittab()" para fornecer módulos embutidos
   adicionais. A estrutura é definida em "Include/import.h" como:

      struct _inittab {
          const char *name;           /* ASCII encoded string */
          PyObject* (*initfunc)(void);
      };

int PyImport_ExtendInittab(struct _inittab *newtab)

   Adiciona uma coleção de módulos à tabela de módulos embutidos. O
   vetor *newtab* deve terminar com uma entrada sentinela que contém
   "NULL" para o campo "name"; a falha em fornecer o valor sentinela
   pode resultar em uma falha de memória. Retorna "0" em caso de
   sucesso ou "-1" se memória insuficiente puder ser alocada para
   estender a tabela interna. Em caso de falha, nenhum módulo é
   adicionado à tabela interna. Deve ser chamado antes de
   "Py_Initialize()".

   Se Python é inicializado várias vezes, "PyImport_AppendInittab()"
   ou "PyImport_ExtendInittab()" devem ser chamados antes de cada
   inicialização do Python.
