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