Importando Módulos
******************

PyObject* PyImport_ImportModule(const char *name)
    *Return value: New reference.*

   Esta é uma interface simplificada para "PyImport_ImportModuleEx()",
   deixando os argumentos *globals* e *locals* definidos como *NULL* e
   *level* definido para 0. Quando o argumento *name* contém um ponto
   (especificando um submódulo de um pacote), o argumento *fromlist* é
   definido para a lista '"['*']"'  a fim que o retorno seja o módulo
   nomeado ao invés do pacote de nível superior que o contém, como
   seria neste caso.  (Infelizmente, isso tem um efeito colateral
   quando o *name* especifica um subpacote ao invés de um submódulo:
   os submódulos especificados nos pacotes são carregados através da
   variável "__all__"). Retornando uma nova referência para o módulo
   importado, ou *NULL* com uma exceção definida durante a falha. Uma
   falha na importação do módulo não o deixa dentro de "sys.modules".

   Essas funções usam importações absolutas.

PyObject* PyImport_ImportModuleNoBlock(const char *name)

   Esta função tem um alias obsoleto: c: func:
   *PyImport_ImportModule*.

   Alterado na versão 3.3: Essa função falhava em alguns casos, quando
   o bloqueio de importação era mantido por outra thread. No Python
   3.3, no entanto, o esquema de bloqueio mudou passando a ser 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)
    *Return value: New reference.*

   Importar um módulo. Isso é melhor demonstrado através da função
   interna do Python "__import__()".

   O valor retornado é uma nova referência ao módulo importado ou ao
   pacote localizado no nível acima, ou *NULL* através de uma exceção
   definida pela falha.  Como na "__import__()", o valor retornado
   quando um submódulo foi solicitado é o pacote de nível superior, a
   menos que uma *fromlist* tenha sido informada.

   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)
    *Return value: New reference.*

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

   O valor retornado é uma nova referência ao módulo importado ou ao
   pacote localizado no nível acima, ou *NULL* através de uma exceção
   definida pela falha.  Como na "__import__()", o valor retornado
   quando um submódulo foi solicitado é o pacote de nível superior, a
   menos que uma *fromlist* tenha sido informada.

   Novo na versão 3.3.

PyObject* PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
    *Return value: New reference.*

   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)
    *Return value: New reference.*

   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.

   Essas funções usam importações absolutas.

PyObject* PyImport_ReloadModule(PyObject *m)
    *Return value: New reference.*

   Recarregar um módulo. Retorna uma nova referência ao módulo
   recarregado, ou *NULL* com uma exceção definida pela falha (o
   módulo ainda existe nesse caso).

PyObject* PyImport_AddModuleObject(PyObject *name)
    *Return value: Borrowed reference.*

   Retornar o objeto módulo correspondente ao nome do módulo. O
   argumento *name* pode estar no  formato "package.module". Primeiro
   confira no dicionário dos módulos se há um lá, e se não houver,
   crie um novo e insira este dentro do dicionários dos módulos.
   Retorna *NULL* com uma exceção definida pela 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. Utilize
     "PyImport_ImportModule()" ou uma de suas variações para importar
     um módulo.  Estruturas de pacotes implícitos através de um ponto
     no nome 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)
    *Return value: Borrowed reference.*

   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)
    *Return value: New reference.*

   Para um nome de módulo (possivelmente na forma de "package.module")
   e um objeto de código lido a partir de um arquivo bytecode do
   Python ou obtido a partir da função interna "compile()", carrega o
   módulo.  Retorna uma nova referência ao objeto do módulo, ou *NULL*
   com uma exceção definida pela falha. *name* é removido do
   "sys.modules" em casos de erro,  mesmo se o *name* já esteja dentro
   de "sys.modules" na entrada para "PyImport_ExecCodeModule()".
   Deixar módulos inicializados de forma incompleta em "sys.modules" é
   perigoso, como na importação de tais módulos não há como saber que
   o objeto do módulo  tem estado indefinido (e provavelmente com
   problemas com relação às intenções do autor do módulo).

   O módulo "__spec__" e "__loader__" será definido, se não estiver,
   com os valores apropriados. O carregador de especificações definirá
   o módulo "__loader__" (se definido) e uma instância da classe
   "SourceFileLoader" em caso contrário.

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

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

   Se *name*  apontar para um nome com ponto no formato de
   "package.module", qualquer estruturas de pacotes que não tenha sido
   criada não será mais criada.

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

PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
    *Return value: New reference.*

   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)
    *Return value: New reference.*

   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)
    *Return value: New reference.*

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

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

   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()
    *Return value: Borrowed reference.*

   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_GetImporter(PyObject *path)
    *Return value: New reference.*

   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.

void _PyImport_Init()

   Inicia o mecanismo de importação. Apenas para uso interno.

void PyImport_Cleanup()

   Esvazia a tabela do módulo. Apenas para uso interno.

void _PyImport_Fini()

   Finaliza o mecanismo de importação. Apenas para uso interno.

PyObject* _PyImport_FindExtension(char *, char *)

   Apenas para uso interno.

int PyImport_ImportFrozenModuleObject(PyObject *name)
    *Return value: New reference.*

   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)

   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 {
          char *name;
          unsigned char *code;
          int size;
      };

const struct _frozen* PyImport_FrozenModules

   This pointer is initialized to point to an array of "struct
   _frozen" records, terminated by one whose members are all *NULL* or
   zero.  When a frozen module is imported, it is searched in this
   table.  Third-party code could play tricks with this to provide a
   dynamically created collection of frozen modules.

int PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void))

   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 {
          char *name;                 /* ASCII encoded string */
          PyObject* (*initfunc)(void);
      };

int PyImport_ExtendInittab(struct _inittab *newtab)

   Add a collection of modules to the table of built-in modules.  The
   *newtab* array must end with a sentinel entry which contains *NULL*
   for the "name" field; failure to provide the sentinel value can
   result in a memory fault. Returns "0" on success or "-1" if
   insufficient memory could be allocated to extend the internal
   table.  In the event of failure, no modules are added to the
   internal table.  This should be called before "Py_Initialize()".
