pkgutil — Utilitário de extensão de pacote

Código-fonte: Lib/pkgutil.py

---

Este módulo fornece utilitários para o sistema de importação, em particular suporte a pacotes.

class pkgutil.ModuleInfo(module_finder, name, ispkg)

Um namedtuple que contém um breve resumo das informações de um módulo.

Novo na versão 3.6.

pkgutil.extend_path(path, name)

Estende o caminho de pesquisa para os módulos que compõem um pacote. O uso pretendido é colocar o seguinte código no __init__.py de um pacote:

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

This will add to the package’s __path__ all subdirectories of directories on sys.path named after the package. This is useful if one wants to distribute different parts of a single logical package as multiple directories.

It also looks for *.pkg files beginning where * matches the name argument. This feature is similar to *.pth files (see the site module for more information), except that it doesn’t special-case lines starting with import. A *.pkg file is trusted at face value: apart from checking for duplicates, all entries found in a *.pkg file are added to the path, regardless of whether they exist on the filesystem. (This is a feature.)

Se o caminho de entrada não for uma lista (como é o caso de pacotes congelados), ele será retornado inalterado. O caminho de entrada não é modificado; uma cópia estendida é retornada. Os itens são anexados à cópia apenas no final.

Presume-se que sys.path seja uma sequência. Itens de sys.path que não sejam strings referentes a diretórios existentes são ignorados. Itens Unicode em sys.path que causam erros quando usados como nomes de arquivo podem fazer com que esta função levante uma exceção (em linha com o comportamento de os.path.isdir()).

class pkgutil.ImpImporter(dirname=None)

PEP 302 Finder that wraps Python’s “classic” import algorithm.

If dirname is a string, a PEP 302 finder is created that searches that directory. If dirname is None, a PEP 302 finder is created that searches the current sys.path, plus any modules that are frozen or built-in.

Note that ImpImporter does not currently support being used by placement on sys.meta_path.

Obsoleto desde a versão 3.3: This emulation is no longer needed, as the standard import mechanism is now fully PEP 302 compliant and available in importlib.

class pkgutil.ImpLoader(fullname, file, filename, etc)

Loader that wraps Python’s “classic” import algorithm.

Obsoleto desde a versão 3.3: This emulation is no longer needed, as the standard import mechanism is now fully PEP 302 compliant and available in importlib.

pkgutil.find_loader(fullname)

Retrieve a module loader for the given fullname.

This is a backwards compatibility wrapper around importlib.util.find_spec() that converts most failures to ImportError and only returns the loader rather than the full ModuleSpec.

Alterado na versão 3.3: Atualizado para ser baseado diretamente em importlib em vez de depender da emulação de importação interna do pacote da PEP 302.

Alterado na versão 3.4: Updated to be based on PEP 451

pkgutil.get_importer(path_item)

Recupera um localizador para o path_item fornecido.

O localizador retornado é armazenado em cache em sys.path_importer_cache se ele foi criado recentemente por um gancho de caminho.

O cache (ou parte dele) pode ser limpo manualmente se uma nova varredura de sys.path_hooks for necessária.

Alterado na versão 3.3: Atualizado para ser baseado diretamente em importlib em vez de depender da emulação de importação interna do pacote da PEP 302.

pkgutil.get_loader(module_or_name)

Get a loader object for module_or_name.

If the module or package is accessible via the normal import mechanism, a wrapper around the relevant part of that machinery is returned. Returns None if the module cannot be found or imported. If the named module is not already imported, its containing package (if any) is imported, in order to establish the package __path__.

Alterado na versão 3.3: Atualizado para ser baseado diretamente em importlib em vez de depender da emulação de importação interna do pacote da PEP 302.

Alterado na versão 3.4: Updated to be based on PEP 451

pkgutil.iter_importers(fullname='')

Produz objetos localizador para o nome do módulo fornecido.

Se fullname contiver '.', os localizadores serão para o pacote que contém fullname, caso contrário, serão todos os localizadores de nível superior registrados (ou seja, aqueles em sys.meta_path e sys.path_hooks).

Se o módulo nomeado estiver em um pacote, esse pacote será importado como um efeito colateral da invocação desta função.

Se nenhum nome de módulo for especificado, todos os localizadores de nível superior serão produzidos.

Alterado na versão 3.3: Atualizado para ser baseado diretamente em importlib em vez de depender da emulação de importação interna do pacote da PEP 302.

pkgutil.iter_modules(path=None, prefix='')

Levanta ModuleInfo para todos os submódulos em path ou, se path for None, todos os módulos de nível superior em sys.path.

path deve ser None ou uma lista de caminhos para procurar módulos.

prefix é uma string a ser exibida na frente de cada nome de módulo na saída.

Nota

Funciona apenas para um localizador que define um método iter_modules(). Esta interface não é padrão, portanto, o módulo também fornece implementações para importlib.machinery.FileFinder e zipimport.zipimporter.

Alterado na versão 3.3: Atualizado para ser baseado diretamente em importlib em vez de depender da emulação de importação interna do pacote da PEP 302.

pkgutil.walk_packages(path=None, prefix='', onerror=None)

Levanta ModuleInfo para todos os módulos recursivamente em path, ou, se path for None, todos os módulos acessíveis.

path deve ser None ou uma lista de caminhos para procurar módulos.

prefix é uma string a ser exibida na frente de cada nome de módulo na saída.

Observe que esta função deve importar todos os pacotes (não todos os módulos!) no caminho path fornecido, para acessar o atributo __path__ para encontrar submódulos.

onerror é uma função que é chamada com um argumento (o nome do pacote que estava sendo importado) caso ocorra alguma exceção durante a tentativa de importação de um pacote. Se nenhuma função onerror for fornecida, ImportErrors são capturadas e ignoradas, enquanto todas as outras exceções são propagadas, encerrando a busca.

Exemplos:

# list all modules python can access
walk_packages()

# list all submodules of ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')

Nota

Funciona apenas para um localizador que define um método iter_modules(). Esta interface não é padrão, portanto, o módulo também fornece implementações para importlib.machinery.FileFinder e zipimport.zipimporter.

Alterado na versão 3.3: Atualizado para ser baseado diretamente em importlib em vez de depender da emulação de importação interna do pacote da PEP 302.

pkgutil.get_data(package, resource)

Obtém um recurso de um pacote.

Este é um invólucro para a API get_data do carregador. O argumento package deve ser o nome de um pacote, no formato de módulo padrão (foo.bar). O argumento resource deve estar no formato de um nome de arquivo relativo, usando / como separador de caminho. O nome do diretório pai .. não é permitido, nem um nome raiz (começando com /).

A função retorna uma string binária que é o conteúdo do recurso especificado.

Para pacotes localizados no sistema de arquivos, que já foram importados, isso é o equivalente aproximado de:

d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()

Se o pacote não puder ser localizado ou carregado, ou se usar um carregador que não oferece suporte a get_data, None será retornado. Em particular, o carregador para pacotes de espaço de nomes não oferece suporte a get_data.

pkgutil.resolve_name(name)

Resolve um nome a um objeto.

Essa funcionalidade é usada em vários lugares na biblioteca padrão (veja bpo-12915) - e funcionalidades equivalentes também estão amplamente utilizadas em pacotes de terceiros, como setuptools, Django e Pyramid.

Espera-se que name seja uma string em um dos seguintes formatos, onde W é uma abreviação para um identificador Python válido e ponto representa um ponto literal nessas pseudo-regexes:

• W(.W)*

• W(.W)*:(W(.W)*)?

A primeira forma destina-se apenas à retrocompatibilidade. Ela presume que parte do nome pontilhado seja um pacote e o restante seja um objeto em algum lugar dentro desse pacote, possivelmente aninhado dentro de outros objetos. Como o ponto onde o pacote termina e a hierarquia de objetos começa não pode ser inferido por inspeção, tentativas repetidas de importação devem ser feitas com esta forma.

Na segunda forma, o chamador deixa claro o ponto de divisão por meio de um caractere de dois pontos: o nome pontilhado à esquerda do caractere de dois pontos representa um pacote a ser importado, e o nome pontilhado à direita representa a hierarquia de objetos dentro desse pacote. Apenas uma importação é necessária nesta forma. Se terminar com caractere de dois pontos, um objeto de módulo será retornado.

A função retornará um objeto (que pode ser um módulo) ou levantará uma das seguintes exceções:

ValueError – se name não estiver em um formato reconhecido.

ImportError – se uma importação falhou quando não deveria.

AttributeError – Se ocorrer uma falha ao percorrer a hierarquia de objetos dentro do pacote importado para chegar ao objeto desejado.

Novo na versão 3.9.