Esta documentação é de uma versão antiga do Python que não é mais atualizada. Você deveria atualizar e ler a Documentação do Python para versão estável atual.

# Importando módulos

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

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

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

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

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

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

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

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

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

  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)
  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_GetModule`(PyObject *name)
  Return value: New reference.

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

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 {
          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 `struct_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))

  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.