pkgutil — Utilidad de extensión de paquete

Código fuente: Lib/pkgutil.py

Este módulo proporciona utilidades para el sistema de importación, en particular soporte para paquetes.

class pkgutil.ModuleInfo(module_finder, name, ispkg)

Una tupla nombrada que contiene un breve resumen de la información del módulo.

Nuevo en la versión 3.6.

pkgutil.extend_path(path, name)

Extiende la ruta de búsqueda de los módulos que componen un paquete. El uso previsto es colocar el siguiente código en __init__.py: de un paquete:

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

Esto agregará al __path__ del paquete todos los subdirectorios de directorios en sys.path con el nombre del paquete. Esto es útil si se desea distribuir diferentes partes de un único paquete lógico como varios directorios.

También busca archivos *.pkg donde * coincide con el argumento name. Esta característica es similar a archivos *.pth (vea el módulo site para más información) excepto que no incluye líneas de casos especiales que comienzan con ìmport. Un archivo *.pkg es confiable al pie de la letra: además de buscar duplicados, todas las entradas encontradas en un *.pkg se agregan a la ruta, independientemente de si existen en el sistema de archivos. (Esto es una funcionalidad).

Si la ruta de entrada no es una lista (como es el caso de los paquetes congelados), se retorna sin cambios. La ruta de entrada no se modifica; se retorna una copia ampliada. Los elementos solo se adjuntan a la copia al final.

Se supone que sys.path es una secuencia. Los elementos de sys.path que no sean cadenas de caracteres que se refieran a directorios existentes se ignoran. Los elementos Unicode en sys.path que causan errores cuando se utilizan como nombres de archivo pueden hacer que esta función lance una excepción (en línea con el comportamiento de os.path.isdir()).

class pkgutil.ImpImporter(dirname=None)

Buscador PEP 302 que envuelve el algoritmo de importación «clásico» de Python.

Si dirname es una cadena de caracteres, se crea un buscador PEP 302 que busca ese directorio. Si dirname es None, se crea un buscador PEP 302 que busca en el actual sys.path, más cualquier módulo que esté congelado o incorporado.

Tenga en cuenta que ImpImporter no admite actualmente el uso de ubicación sys.meta_path.

Obsoleto desde la versión 3.3: Esta emulación ya no es necesaria, ya que ahora lo es el mecanismo de importación estándar totalmente compatible con PEP 302 y disponible en importlib.

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

Loader that wraps Python’s «classic» import algorithm.

Obsoleto desde la versión 3.3: Esta emulación ya no es necesaria, ya que ahora lo es el mecanismo de importación estándar totalmente compatible con PEP 302 y disponible en importlib.

pkgutil.find_loader(fullname)

Recupera un módulo loader para un fullname dado.

Este es un contenedor de compatibilidad con versiones anteriores de importlib.util.find_spec() que convierte la mayoría de los errores en ImportError y solo retorna el cargador en lugar del completo ModuleSpec.

Distinto en la versión 3.3: Actualizado para basarse directamente en importlib en lugar de depender del paquete interno PEP 302 emulación de importación.

Distinto en la versión 3.4: Actualizado basado en PEP 451

pkgutil.get_importer(path_item)

Recupera un finder para el path_item.

El buscador retornado se almacena en caché en sys.path_importer_cache si fue creado recientemente por un enlace de ruta.

La caché (o parte de ella) puede ser borrada manualmente si el escaneo de sys.path_hooks es necesario.

Distinto en la versión 3.3: Actualizado para basarse directamente en importlib en lugar de depender del paquete interno PEP 302 emulación de importación.

pkgutil.get_loader(module_or_name)

Obtiene un objeto loader para module_or_name.

Si se puede acceder al módulo o paquete a través del mecanismo de importación normal, se devuelve un contenedor alrededor de la parte relevante de esa maquinaria. Retorna None si el módulo no se puede encontrar o importar. Si el módulo nombrado aún no se ha importado, se importa el paquete que lo contiene (si lo hay), para establecer el paquete __path__.

Distinto en la versión 3.3: Actualizado para basarse directamente en importlib en lugar de depender del paquete interno PEP 302 emulación de importación.

Distinto en la versión 3.4: Actualizado basado en PEP 451

pkgutil.iter_importers(fullname='')

Cede (yield) objectos finder para el nombre de módulo dado.

Si el nombre completo contiene un “.”, los buscadores serán para el paquete que contiene el nombre completo; de lo contrario, serán todos los buscadores de nivel superior registrados (es decir, los de sys.meta_path y sys.path_hooks).

Si el módulo nombrado está en un paquete, ese paquete se importa como un efecto secundario de invocar esta función.

Si no se especifica ningún nombre de módulo, se generan todos los buscadores de nivel superior.

Distinto en la versión 3.3: Actualizado para basarse directamente en importlib en lugar de depender del paquete interno PEP 302 emulación de importación.

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

Cede (yield) ModuleInfo para todos los submódulos en path, o, si path es None, todos los módulos de nivel superior en sys.path.

path tendría que ser None o una list de rutas en las que buscar módulos.

prefix es una cadena para mostrar delante de cada nombre de módulo en la salida.

Nota

Sólo funciona para un finder que define un método iter_modules(). Esta interfaz no es estándar, por lo que el módulo también proporciona implementaciones para importlib.machinery.FileFinder y zipimport.zipimporter.

Distinto en la versión 3.3: Actualizado para basarse directamente en importlib en lugar de depender del paquete interno PEP 302 emulación de importación.

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

Cede (yield) ModuleInfo para todos los módulos de forma recursiva en path, o, si path es None, todos los módulos accesibles.

path tendría que ser None o una list de rutas en las que buscar módulos.

prefix es una cadena para mostrar delante de cada nombre de módulo en la salida.

Note que esta función debe importar todos los packages (¡no todos los módulos!) en el path especificado, para acceder al atributo __path__ para encontrar submódulos.

onerror es una función que se llama con un argumento (el nombre del paquete que se estaba importando) si se produce alguna excepción al intentar importar un paquete. Si no se proporciona ninguna función onerror, los ImportError se capturan e ignoran, mientras que todas las demás excepciones se propagan, terminando la búsqueda.

Ejemplos:

# list all modules python can access
walk_packages()

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

Nota

Sólo funciona para un finder que define un método iter_modules(). Esta interfaz no es estándar, por lo que el módulo también proporciona implementaciones para importlib.machinery.FileFinder y zipimport.zipimporter.

Distinto en la versión 3.3: Actualizado para basarse directamente en importlib en lugar de depender del paquete interno PEP 302 emulación de importación.

pkgutil.get_data(package, resource)

Obtiene un recurso de un paquete.

Esto es un contenedor para la API loader get_data. El argumento package debe ser el nombre de un paquete, en formato de módulo estándar (foo.bar).El argumento resource debe tener la forma de un nombre de archivo relativo, utilizando / como separador de ruta.El nombre del directorio principal .. no está permitido, ni tampoco un nombre raíz (empezando por /).

La función retorna una cadena de caracteres binaria que es el contenido del recurso especificado.

Para los paquetes ubicados en el sistema de archivos, que ya se han importado, este es el equivalente aproximado de:

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

Si el paquete no puede ser localizado o cargado, o usa un loader el cuál no soporta get_data, entonces retorna None. En particular, el: término loader para namespace packages no soporta get_data.