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.

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

PyObject* PyImport_ImportModuleNoBlock(const char *name)

Return value: New reference.

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

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

Essas funções usam 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. 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.

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

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.

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