"importlib" --- La implementación de "import"
*********************************************

Nuevo en la versión 3.1.

**Código fuente:** Lib/importlib/__init__.py

======================================================================


Introducción
============

El propósito del paquete "importlib" es doble. Uno es proveer la
implementación de la declaración de "import", (y así, por extensión,
el método "__import__()" ) en el código fuente de Python. Esto provee
una implementación de la "import" la cual es compatible con cualquier
interprete de Python. También provee una implementación que es más
fácil de comprender que otras implementaciones, en lenguajes
diferentes a Python.

Dos, los componentes incluidos para implementar "import"  están
expuestos en este paquete para que sea más fácil para los usuarios
crear sus propios objetos (conocidos de forma genérica como
*importer*) para participar en el proceso de importación.

Ver también:

  La declaración import
     La referencia en el lenguaje para la declaración de "import".

  Especificaciones de paquetes
     Especificaciones originales de los paquetes. Algunas semánticas
     han cambiado desde que este documento fue escrito (ejemplo,
     redirección de acuerdo a "None" en "sys.modules").

  La función "__import__()"
     La declaración de "import" es una decoración sintáctica para esta
     función.

  **PEP 235**
     Importar en sistemas que no distinguen entre mayúsculas y
     minúsculas

  **PEP 263**
     Definiendo las codificaciones del código fuente de Python

  **PEP 302**
     Nuevos ganchos de importación

  pep:*328*
     Importaciones: Multilíneas, y absolutos/relativos

  **PEP 366**
     Importaciones relativas, explicitas, del módulo principal

  **PEP 420**
     Paquetes implícitos en el espacio de nombres

  **PEP 451**
     Un tipo de ModuleSpec para el sistema de importación

  **PEP 488**
     Eliminación de archivos PYO

  **PEP 489**
     Inicialización de extensión de módulo en múltiples fases

  **PEP 552**
     Pycs determinísticos

  **PEP 3120**
     Usando UTF-8 como la codificación fuente por defecto

  **PEP 3147**
     Repositorio de directorios PYC


Funciones
=========

importlib.__import__(name, globals=None, locals=None, fromlist=(), level=0)

   Una implementación de la función "__import__()" incorporada.

   Nota:

     La importación programática los módulos debe usar
     "import_module()" en lugar de esta función.

importlib.import_module(name, package=None)

   Importar un módulo. El argumento llamado *name* especifica qué
   módulo importar en términos absolutos o relativos (ejemplo, puede
   ser "pkg.mod" o "..mod"). Si el nombre fuera especificado en
   términos relativos, entonces el argumento llamado *package* debe
   ser igual al nombre del paquete que será el ancla para resolver el
   nombre del paquete (ejemplo "import_module('..mod', 'pkg.subpkg')"
   importará "pkg.mod").

   La función "import_module()" actúa como un envoltorio simplificador
   alrededor de "importlib.__import__()".  Esto quiere decir que las
   semánticas de la función son derivadas de "importlib.__import__()".
   La diferencia más importante entre las dos funciones es que
   "import_module()" retorna el paquete especificado o el módulo
   (ejemplo "pkg.mod"), mientras que "__import__()" retorna el paquete
   o módulo del nivel superior (ejemplo "pkg").

   Si está importando dinámicamente un módulo que se creó desde que el
   intérprete comenzó la ejecución (por ejemplo, creó un archivo
   fuente de Python), es posible que deba llamar a
   "invalidate_caches()" para que el nuevo módulo sea detectado por el
   sistema de importación.

   Distinto en la versión 3.3: Paquetes padres son importados
   automáticamente.

importlib.find_loader(name, path=None)

   Encuentra el cargador de un módulo, opcionalmente con el
   especificado en *path*.Si el módulo esta en "sys.modules", entonces
   retorna el *sys.modules[name].__loader__`* (a menos que el cargador
   sea "None" o no haya uno especificado, en tal caso se eleva un
   "ValueError").Si no se encuentra ahí, se hace una búsqueda usando
   "sys.meta_path". Se retorna "None" si no se encuentra un cargador.

   Un nombre con puntos no tiene sus ascendientes importados
   implícitamente, ya que eso requeriría cargarlo y eso podría no ser
   deseado. Para importar un sub-módulo correctamente debes importar
   todos los paquetes ascendientes del sub-módulo y pase el argumento
   correcto a *path*.

   Nuevo en la versión 3.3.

   Distinto en la versión 3.4: Si el "__loader__" no está configurado,
   eleva un "ValueError", igual a si el atributo fuera "None".

   Obsoleto desde la versión 3.4: Utilice "importlib.util.find_spec()"
   en su lugar.

importlib.invalidate_caches()

   Invalide los cache internos de ubicadores encontrados en
   "sys.meta_path".Si un buscador implementa "invalidate_caches()"
   entonces será llamado para realizar la invalidación.Esta función
   debe ser llamada si cualquier módulo ha sido creado/instalado
   mientras tu programa esta siendo ejecutado para garantizar que
   todos los buscadores noten la existencia del nuevo módulo.

   Nuevo en la versión 3.3.

importlib.reload(module)

   Recarga un *modulo* previamente importado. El argumento debe ser un
   objeto módulo, por lo que debe haber sido importado exitosamente.
   Esto es útil cuando has editado el código fuente de un archivo
   usando un editor externo y deseas probar la nueva versión sin
   abandonar el interprete de Python. El valor retornado es el objeto
   módulo (que puede ser diferente si la reimportación crea un nuevo
   objeto en "sys.modules").

   Cuando "reload()" es ejecutada:

   * El código de un módulo de Python es recompilado y el código del
     módulo reejecutado, definiendo un nuevo conjunto de objetos que
     son asignados a los nombres de los módulos en el diccionario,
     reusando el *loader* que originalmente carga los módulos. El
     método "init" de los módulos de extension no es llamado de nuevo.

   * Al igual que con todos los demás objetos en Python, los objetos
     antiguos solo se recuperan después de que sus recuentos de
     referencias caen a cero.

   * Los nombres en el espacio de nombres del módulo se actualizan
     para señalar cualquier objeto nuevo o modificado.

   * Otras referencias a los objetos antiguos (como los nombres
     externos al módulo) no se vuelven a vincular para hacer
     referencia a los nuevos objetos y deben actualizarse en cada
     espacio de nombres donde se produzcan si se desea.

   Hay una serie de otras advertencias:

   Cuando se vuelve a cargar un módulo, se conserva su diccionario
   (que contiene las variables globales del módulo). Las
   redefiniciones de nombres anularán las antiguas definiciones, por
   lo que generalmente esto no es un problema. Si la nueva versión de
   un módulo no define un nombre que fue definido por la versión
   anterior, la definición anterior permanece. Esta característica se
   puede utilizar en beneficio del módulo si mantiene una tabla global
   o caché de objetos --- con una declaración "try" puede probar la
   presencia de la tabla y omitir su inicialización si lo desea:

      try:
          cache
      except NameError:
          cache = {}

   Por lo general, no es muy útil recargar módulos integrados o
   cargados dinámicamente. No se recomienda recargar "sys",
   "__main__", "builtins" y otros módulos clave. En muchos casos, los
   módulos de extensión no están diseñados para inicializarse más de
   una vez y pueden fallar de manera arbitraria cuando se vuelven a
   cargar.

   Si un módulo importa objetos de otro módulo usando "from" ...
   "import" ..., al llamar a "reload()" para el otro módulo no
   redefine los objetos importados de él --- una forma de evitar esto
   es volver a ejecutar la instrucción "from", otra es usar "import" y
   nombres calificados (*module.name*) en su lugar.

   Si un módulo crea instancias de una clase, volver a cargar el
   módulo que define la clase no afecta las definiciones de método de
   las instancias --- continúan usando la definición de clase
   anterior. Lo mismo ocurre con las clases derivadas.

   Nuevo en la versión 3.4.

   Distinto en la versión 3.7: "ModuleNotFoundError" se lanza cuando
   el módulo que se está recargando carece de "ModuleSpec".


"importlib.abc" -- Clases base abstractas relacionadas con la importación
=========================================================================

**Código fuente:** Lib/importlib/abc.py

======================================================================

El módulo "importlib.abc" contiene todas las clases base abstractas
principales utilizadas por "import". También se proporcionan algunas
subclases de las clases base abstractas centrales para ayudar a
implementar los ABC centrales.

Jerarquía ABC:

   object
    +-- Finder (deprecated)
    |    +-- MetaPathFinder
    |    +-- PathEntryFinder
    +-- Loader
         +-- ResourceLoader --------+
         +-- InspectLoader          |
              +-- ExecutionLoader --+
                                    +-- FileLoader
                                    +-- SourceLoader

class importlib.abc.Finder

   Una clase base abstracta que representa *finder*.

   Obsoleto desde la versión 3.3: Utilice "MetaPathFinder" o
   "PathEntryFinder" en su lugar.

   abstractmethod find_module(fullname, path=None)

      Un método abstracto para encontrar un *loader* para el módulo
      especificado. Originalmente especificado en **PEP 302**, este
      método estaba destinado a ser utilizado en "sys.meta_path" y en
      el subsistema de importación basado en rutas.

      Distinto en la versión 3.4: Retorna "None" cuando se llama en
      lugar de generar "NotImplementedError".

class importlib.abc.MetaPathFinder

   Una clase base abstracta que representa un *meta path finder*. Por
   compatibilidad, esta es una subclase de "Finder".

   Nuevo en la versión 3.3.

   find_spec(fullname, path, target=None)

      Un método abstracto para encontrar un *spec* para el módulo
      especificado. Si se trata de una importación de nivel superior,
      el *path* será "None". De lo contrario, esta es una búsqueda de
      un subpaquete o módulo y *path* será el valor de "__path__" del
      paquete principal. Si no se puede encontrar una especificación,
      se retorna "None". Cuando se pasa, "target" es un objeto de
      módulo que el buscador puede usar para hacer una suposición más
      informada sobre qué especificación retornar.
      "importlib.util.spec_from_loader()" puede ser útil para
      implementar "MetaPathFinders" concretos.

      Nuevo en la versión 3.4.

   find_module(fullname, path)

      Un método heredado para encontrar un *loader* para el módulo
      especificado. Si se trata de una importación de nivel superior,
      el *path* será "None". De lo contrario, esta es una búsqueda de
      un subpaquete o módulo y *path* será el valor de "__path__" del
      paquete principal. Si no se puede encontrar un cargador, se
      retorna "None".

      Si se define "find_spec()", se proporciona una funcionalidad
      compatible con versiones anteriores.

      Distinto en la versión 3.4: Retorna "None" cuando se llama en
      lugar de generar "NotImplementedError". Puede usar "find_spec()"
      para proporcionar funcionalidad.

      Obsoleto desde la versión 3.4: Use "find_spec()" en su lugar.

   invalidate_caches()

      Un método opcional que, cuando se llama, debería invalidar
      cualquier caché interno utilizado por el buscador. Utilizado por
      "importlib.invalidate_caches()" al invalidar los cachés de todos
      los buscadores en "sys.meta_path".

      Distinto en la versión 3.4: Retorna "None" cuando se llama en
      lugar de "NotImplemented".

class importlib.abc.PathEntryFinder

   Una clase base abstracta que representa un *path entry finder*.
   Aunque tiene algunas similitudes con "MetaPathFinder",
   "PathEntryFinder" está diseñado para usarse solo dentro del
   subsistema de importación basado en rutas proporcionado por
   "PathFinder". Este ABC es una subclase de "Finder" solo por razones
   de compatibilidad.

   Nuevo en la versión 3.3.

   find_spec(fullname, target=None)

      Un método abstracto para encontrar un *spec* para el módulo
      especificado. El buscador buscará el módulo solo dentro del
      *path entry* a la que está asignado. Si no se puede encontrar
      una especificación, se retorna "None". Cuando se pasa, "target"
      es un objeto de módulo que el buscador puede usar para hacer una
      suposición más informada sobre qué especificación retornar.
      "importlib.util.spec_from_loader()" puede ser útil para
      implementar "PathEntryFinders" concretos.

      Nuevo en la versión 3.4.

   find_loader(fullname)

      Un método heredado para encontrar un *loader* para el módulo
      especificado. Retorna una tupla de 2 de "(loader, portion)"
      donde "portion" es una secuencia de ubicaciones del sistema de
      archivos que contribuyen a parte de un paquete de espacio de
      nombres. El cargador puede ser "None" mientras se especifica
      "portion" para indicar la contribución de las ubicaciones del
      sistema de archivos a un paquete de espacio de nombres. Se puede
      usar una lista vacía para "portion" para indicar que el cargador
      no es parte de un paquete de espacio de nombres. Si "loader" es
      "None" y "portion" es la lista vacía, entonces no se encontró
      ningún cargador o ubicación para un paquete de espacio de
      nombres (es decir, no se pudo encontrar nada para el módulo).

      Si se define "find_spec()", se proporciona una funcionalidad
      compatible con versiones anteriores.

      Distinto en la versión 3.4: Retorna "(None, [])" en lugar de
      lanzar "NotImplementedError". Usa "find_spec()" cuando está
      disponible para proporcionar funcionalidad.

      Obsoleto desde la versión 3.4: Use "find_spec()" en su lugar.

   find_module(fullname)

      Una implementación concreta de "Finder.find_module()" que es
      equivalente a "self.find_loader(fullname)[0]".

      Obsoleto desde la versión 3.4: Use "find_spec()" en su lugar.

   invalidate_caches()

      Un método opcional que, cuando se llama, debería invalidar
      cualquier caché interno utilizado por el buscador. Usado por
      "PathFinder.invalidate_caches()" al invalidar las cachés de
      todos los buscadores en caché.

class importlib.abc.Loader

   Una clase base abstracta para un *loader*. Consulte **PEP 302**
   para obtener la definición exacta de cargador.

   Los cargadores que deseen admitir la lectura de recursos deben
   implementar un método "get_resource_reader(fullname)" según lo
   especificado por "importlib.abc.ResourceReader".

   Distinto en la versión 3.7: Introdujo el método opcional
   "get_resource_reader()".

   create_module(spec)

      Un método que retorna el objeto de módulo que se utilizará al
      importar un módulo. Este método puede retornar "None", lo que
      indica que se debe llevar a cabo la semántica de creación de
      módulos predeterminada.

      Nuevo en la versión 3.4.

      Distinto en la versión 3.5: A partir de Python 3.6, este método
      no será opcional cuando se defina "exec_module()".

   exec_module(module)

      Un método abstracto que ejecuta el módulo en su propio espacio
      de nombres cuando se importa o se vuelve a cargar un módulo. El
      módulo ya debería estar inicializado cuando se llama a
      "exec_module()". Cuando existe este método, se debe definir
      "create_module()".

      Nuevo en la versión 3.4.

      Distinto en la versión 3.6: "create_module()" también debe
      definirse.

   load_module(fullname)

      Un método heredado para cargar un módulo. Si el módulo no se
      puede cargar, se lanza "ImportError"; de lo contrario, se
      retorna el módulo cargado.

      Si el módulo solicitado ya existe en "sys.modules", ese módulo
      debe usarse y recargarse. De lo contrario, el cargador debe
      crear un nuevo módulo e insertarlo en "sys.modules" antes de que
      comience la carga, para evitar la recursividad de la
      importación. Si el cargador insertó un módulo y la carga falla,
      el cargador debe eliminarlo de "sys.modules"; los módulos que ya
      están en "sys.modules" antes de que el cargador comenzara a
      ejecutarse deben dejarse en paz (ver
      "importlib.util.module_for_loader()").

      El cargador debe establecer varios atributos en el módulo.
      (Tenga en cuenta que algunos de estos atributos pueden cambiar
      cuando se recarga un módulo):

      * "__name__"
           El nombre del módulo.

      * "__file__"
           La ruta hacia donde se almacenan los datos del módulo (no
           configurada para módulos integrados).

      * "__cached__"
           La ruta a la que se debe almacenar una versión compilada
           del módulo (no se establece cuando el atributo sería
           inapropiado).

      * "__path__"
           Una lista de cadenas de caracteres que especifican la ruta
           de búsqueda dentro de un paquete. Este atributo no se
           establece en módulos.

      * "__package__"
           El nombre completo del paquete bajo el cual se cargó el
           módulo como submódulo (o la cadena de caracteres vacía para
           los módulos de nivel superior). Para los paquetes, es lo
           mismo que "__name__". El decorador
           "importlib.util.module_for_loader()" puede manejar los
           detalles de "__package__".

      * "__loader__"
           El cargador utilizado para cargar el módulo. El decorador
           "importlib.util.module_for_loader()" puede manejar los
           detalles de "__package__".

      Cuando "exec_module()" está disponible, se proporciona una
      funcionalidad compatible con versiones anteriores.

      Distinto en la versión 3.4: Lanza "ImportError" cuando se llama
      en lugar de "NotImplementedError". Funcionalidad proporcionada
      cuando "exec_module()" está disponible.

      Obsoleto desde la versión 3.4: La API recomendada para cargar un
      módulo es "exec_module()" (y "create_module()"). Los cargadores
      deberían implementarlo en lugar de load_module(). La maquinaria
      de importación se encarga de todas las demás responsabilidades
      de load_module() cuando se implementa exec_module().

   module_repr(module)

      Un método heredado que, cuando se implementa, calcula y retorna
      la repr del módulo dado, como una cadena. El repr()
      predeterminado del tipo de módulo utilizará el resultado de este
      método según corresponda.

      Nuevo en la versión 3.3.

      Distinto en la versión 3.4: Hecho opcional en vez de un método
      abstracto (*abstractmethod*)

      Obsoleto desde la versión 3.4: La maquinaria de importación
      ahora se encarga de esto automáticamente.

class importlib.abc.ResourceReader

   *Superseded by TraversableResources*

   Un *abstract base class* para proporcionar la capacidad de leer
   *resources*.

   Desde la perspectiva de este ABC, un *resource* es un artefacto
   binario que se envía dentro de un paquete. Por lo general, esto es
   algo así como un archivo de datos que se encuentra junto al archivo
   "__init__.py" del paquete. El propósito de esta clase es ayudar a
   abstraer el acceso a dichos archivos de datos de modo que no
   importe si el paquete y sus archivos de datos se almacenan en un,
   por ejemplo, zip en comparación con el sistema de archivos.

   Para cualquiera de los métodos de esta clase, se espera que un
   argumento *resource* sea un *path-like object* que representa
   conceptualmente solo un nombre de archivo. Esto significa que no se
   deben incluir rutas de subdirectorio en el argumento *resource*.
   Esto se debe a que la ubicación del paquete para el que está
   ubicado el lector actúa como el "directorio". Por lo tanto, la
   metáfora de los directorios y los nombres de los archivos son los
   paquetes y los recursos, respectivamente. Esta es también la razón
   por la que se espera que las instancias de esta clase se
   correlacionen directamente con un paquete específico (en lugar de
   representar potencialmente varios paquetes o un módulo).

   Se espera que los cargadores que deseen admitir la lectura de
   recursos proporcionen un método llamado
   "get_resource_reader(fullname)" que retorna un objeto que
   implementa la interfaz de este ABC. Si el módulo especificado por
   fullname no es un paquete, este método debería devolver "None". Un
   objeto compatible con este ABC solo debe retornarse cuando el
   módulo especificado es un paquete.

   Nuevo en la versión 3.7.

   abstractmethod open_resource(resource)

      Retorna un, *file-like object* abierto para la lectura binaria
      del *resource*.

      Si no se puede encontrar el recurso, se lanza
      "FileNotFoundError".

   abstractmethod resource_path(resource)

      Retorna la ruta del sistema de archivos al *resource*.

      Si el recurso no existe concretamente en el sistema de archivos,
      lanza "FileNotFoundError".

   abstractmethod is_resource(name)

      Retorna "True" si el *name* nombrado se considera un recurso.
      "FileNotFoundError" se lanza si *name* no existe.

   abstractmethod contents()

      Retorna un *iterable* de cadenas de caracteres sobre el
      contenido del paquete. Tenga en cuenta que no es necesario que
      todos los nombres retornados por el iterador sean recursos
      reales, por ejemplo, es aceptable retornar nombres para los que
      "is_resource()" sería falso.

      Al permitir que se retornen nombres que no son de recursos es
      para permitir situaciones en las que se conoce a priori cómo se
      almacenan un paquete y sus recursos y los nombres que no son de
      recursos serían útiles. Por ejemplo, se permite el retorno de
      nombres de subdirectorios para que cuando se sepa que el paquete
      y los recursos están almacenados en el sistema de archivos, esos
      nombres de subdirectorios se puedan usar directamente.

      El método abstracto retorna un iterable de ningún elemento.

class importlib.abc.ResourceLoader

   Una clase base abstracta para un *loader* que implementa el
   protocolo opcional **PEP 302** para cargar recursos arbitrarios
   desde el back-end de almacenamiento.

   Obsoleto desde la versión 3.7: Este ABC está en desuso a favor de
   admitir la carga de recursos a través de
   "importlib.abc.ResourceReader".

   abstractmethod get_data(path)

      Un método abstracto para devolver los bytes de los datos
      ubicados en *path*. Los cargadores que tienen un back-end de
      almacenamiento similar a un archivo que permite almacenar datos
      arbitrarios pueden implementar este método abstracto para dar
      acceso directo a los datos almacenados. "OSError" se lanza si no
      se puede encontrar el *path*. Se espera que la *path* se
      construya utilizando el atributo "__file__" de un módulo o un
      elemento de un paquete "__path__".

      Distinto en la versión 3.4: Lanza "OSError" en vez de
      "NotImplementedError".

class importlib.abc.InspectLoader

   Una clase base abstracta para un *loader* que implementa el
   protocolo opcional **PEP 302** para cargadores que inspeccionan
   módulos.

   get_code(fullname)

      Retorna el objeto código para un módulo, o "None" si el módulo
      no tiene un objeto código (como sería el caso, por ejemplo, para
      un módulo integrado). Lanza un "ImportError" si el cargador no
      puede encontrar el módulo solicitado.

      Nota:

        Si bien el método tiene una implementación predeterminada, se
        sugiere que se anule si es posible para mejorar el
        rendimiento.

      Distinto en la versión 3.4: Ya no es un método abstracto y se
      proporciona una implementación concreta.

   abstractmethod get_source(fullname)

      Un método abstracto para retornar la fuente de un módulo. Se
      retorna como una cadena de caracteres de texto usando *universal
      newlines*, traduciendo todos los separadores de línea
      reconocidos en caracteres "' '". Retorna "None" si no hay una
      fuente disponible (por ejemplo, un módulo integrado). Lanza
      "ImportError" si el cargador no puede encontrar el módulo
      especificado.

      Distinto en la versión 3.4: Lanza "ImportError" en vez de
      "NotImplementedError".

   is_package(fullname)

      An optional method to return a true value if the module is a
      package, a false value otherwise. "ImportError" is raised if the
      *loader* cannot find the module.

      Distinto en la versión 3.4: Lanza "ImportError" en vez de
      "NotImplementedError".

   static source_to_code(data, path='<string>')

      Cree un objeto de código a partir de la fuente de Python.

      El argumento *data* puede ser cualquier cosa que admita la
      función "compile()" (es decir, cadena de caracteres o bytes). El
      argumento *path* debe ser la "ruta" de donde se originó el
      código fuente, que puede ser un concepto abstracto (por ejemplo,
      ubicación en un archivo zip).

      Con el objeto de código subsiguiente, uno puede ejecutarlo en un
      módulo ejecutando "exec(code, module.__dict__)".

      Nuevo en la versión 3.4.

      Distinto en la versión 3.5: Hace el método estático.

   exec_module(module)

      Implementación de "Loader.exec_module()".

      Nuevo en la versión 3.4.

   load_module(fullname)

      Implementación de "Loader.load_module()".

      Obsoleto desde la versión 3.4: use "exec_module()" en su lugar.

class importlib.abc.ExecutionLoader

   Una clase base abstracta que hereda de "InspectLoader" que, cuando
   se implementa, ayuda a que un módulo se ejecute como un script. El
   ABC representa un protocolo opcional **PEP 302**.

   abstractmethod get_filename(fullname)

      Un método abstracto que retorna el valor de "__file__" para el
      módulo especificado. Si no hay una ruta disponible, se lanza
      "ImportError".

      Si el código fuente está disponible, entonces el método debe
      devolver la ruta al archivo fuente, independientemente de si se
      utilizó un código de bytes para cargar el módulo.

      Distinto en la versión 3.4: Lanza "ImportError" en vez de
      "NotImplementedError".

class importlib.abc.FileLoader(fullname, path)

   Una clase base abstracta que hereda de "ResourceLoader" y
   "ExecutionLoader", proporcionando implementaciones concretas de
   "ResourceLoader.get_data()" y "ExecutionLoader.get_filename()".

   El argumento *fullname* es un nombre completamente resuelto del
   módulo que el cargador debe manejar. El argumento *path* es la ruta
   al archivo del módulo.

   Nuevo en la versión 3.3.

   name

      El nombre del módulo que puede manejar el cargador.

   path

      Ruta al archivo del módulo.

   load_module(fullname)

      Llama a super's "load_module()".

      Obsoleto desde la versión 3.4: Utilice "Loader.exec_module()" en
      su lugar.

   abstractmethod get_filename(fullname)

      Retorna "path".

   abstractmethod get_data(path)

      Lee *path* como un archivo binario y devuelve los bytes de él.

class importlib.abc.SourceLoader

   Una clase base abstracta para implementar la carga de archivos
   fuente (y opcionalmente bytecode). La clase hereda tanto de
   "ResourceLoader" como de "ExecutionLoader", lo que requiere la
   implementación de:

   * "ResourceLoader.get_data()"

   * "ExecutionLoader.get_filename()"
        Solo debe devolver la ruta al archivo de origen; la carga sin
        fuente no es compatible.

   Los métodos abstractos definidos por esta clase son para agregar
   soporte de archivo de código de bytes opcional. No implementar
   estos métodos opcionales (o hacer que se lance
   "NotImplementedError") hace que el cargador solo funcione con el
   código fuente. La implementación de los métodos permite que el
   cargador trabaje con archivos fuente *y* código de bytes; no
   permite la carga *sin fuente* donde solo se proporciona un código
   de bytes. Los archivos de código de bytes son una optimización para
   acelerar la carga al eliminar el paso de análisis del compilador de
   Python, por lo que no se expone ninguna API específica de código de
   bytes.

   path_stats(path)

      Método abstracto opcional que devuelve un "dict" que contiene
      metadatos sobre la ruta especificada. Las claves de diccionario
      admitidas son:

      * "'mtime'" (obligatorio): un número entero o de punto flotante
        que representa la hora de modificación del código fuente;

      * "'size'" (opcional): el tamaño en bytes del código fuente.

      Cualquier otra clave del diccionario se ignora para permitir
      futuras extensiones. Si no se puede manejar la ruta, se genera
      "OSError".

      Nuevo en la versión 3.3.

      Distinto en la versión 3.4: Lanza "OSError" en vez de
      "NotImplementedError".

   path_mtime(path)

      Método abstracto opcional que retorna la hora de modificación de
      la ruta especificada.

      Obsoleto desde la versión 3.3: Este método está obsoleto en
      favor de "path_stats()". No tiene que implementarlo, pero aún
      está disponible para fines de compatibilidad. Lanza "OSError" si
      la ruta no se puede manejar.

      Distinto en la versión 3.4: Lanza "OSError" en vez de
      "NotImplementedError".

   set_data(path, data)

      Método abstracto opcional que escribe los bytes especificados en
      una ruta de archivo. Los directorios intermedios que no existan
      se crearán automáticamente.

      Cuando la escritura en la ruta falla porque la ruta es de solo
      lectura ("errno.EACCES"/"PermissionError"), no propague la
      excepción.

      Distinto en la versión 3.4: Ya no lanza "NotImplementedError"
      cuando se llama.

   get_code(fullname)

      Implementación concreta de "InspectLoader.get_code()".

   exec_module(module)

      Implementación concreta de "Loader.exec_module()".

      Nuevo en la versión 3.4.

   load_module(fullname)

      Implementación concreta de "Loader.load_module()".

      Obsoleto desde la versión 3.4: Utilice "exec_module()" en su
      lugar.

   get_source(fullname)

      Implementación concreta de "InspectLoader.get_source()".

   is_package(fullname)

      Implementación concreta de "InspectLoader.is_package()". Se
      determina que un módulo es un paquete si su ruta de archivo
      (proporcionada por "ExecutionLoader.get_filename()") es un
      archivo llamado "__init__" cuando se elimina la extensión del
      archivo **y** el nombre del módulo sí lo hace no termina en
      "__init__".

class importlib.abc.Traversable

   Un objeto con un subconjunto de métodos pathlib.Path adecuados para
   recorrer directorios y abrir archivos.

   Nuevo en la versión 3.9.

   abstractmethod name()

      The base name of this object without any parent references.

   abstractmethod iterdir()

      Yield Traversable objects in self.

   abstractmethod is_dir()

      Return True if self is a directory.

   abstractmethod is_file()

      Return True if self is a file.

   abstractmethod joinpath(child)

      Return Traversable child in self.

   abstractmethod __truediv__(child)

      Return Traversable child in self.

   abstractmethod open(mode='r', *args, **kwargs)

      *mode* may be 'r' or 'rb' to open as text or binary. Return a
      handle suitable for reading (same as "pathlib.Path.open").

      When opening as text, accepts encoding parameters such as those
      accepted by "io.TextIOWrapper".

   read_bytes()

      Read contents of self as bytes.

   read_text(encoding=None)

      Read contents of self as text.

   Note: In Python 3.11 and later, this class is found in
   "importlib.resources.abc".

class importlib.abc.TraversableResources

   Una clase base abstracta para lectores de recursos capaz de servir
   la interfaz de "files". Subclases ResourceReader y proporciona
   implementaciones concretas de los métodos abstractos de
   ResourceReader. Por lo tanto, cualquier cargador que suministre
   TraversableReader también suministra ResourceReader.

   Nuevo en la versión 3.9.

   Note: In Python 3.11 and later, this class is found in
   "importlib.resources.abc".


"importlib.resources" -- Recursos
=================================

**Código fuente:** Lib/importlib/resources.py

======================================================================

Nuevo en la versión 3.7.

Este módulo aprovecha el sistema de importación de Python para
proporcionar acceso a *resources* dentro de *packages*. Si puede
importar un paquete, puede acceder a los recursos dentro de ese
paquete. Los recursos se pueden abrir o leer, ya sea en modo binario o
texto.

Los recursos son similares a los archivos dentro de los directorios,
aunque es importante tener en cuenta que esto es solo una metáfora.
Los recursos y paquetes **no** tienen que existir como archivos y
directorios físicos en el sistema de archivos.

Nota:

  Este módulo proporciona una funcionalidad similar a pkg_resources
  Acceso Básico a Recursos sin la sobrecarga de rendimiento de ese
  paquete. Esto facilita la lectura de los recursos incluidos en los
  paquetes, con una semántica más estable y coherente.El backport
  independiente de este módulo proporciona más información sobre usar
  importlib.resources y migrar desde pkg_resources a
  importlib.resources.

Los cargadores que deseen admitir la lectura de recursos deben
implementar un método "get_resource_reader(fullname)" según lo
especificado por "importlib.abc.ResourceReader".

Se definen los siguientes tipos.

importlib.resources.Package

   El tipo "Package" se define como "Union[str, ModuleType]". Esto
   significa que cuando la función describe la aceptación de un
   "Package", puede pasar una cadena de caracteres o un módulo. Los
   objetos de módulo deben tener un
   "__spec__.submodule_search_locations" que se pueda resolver que no
   sea "None".

importlib.resources.Resource

   Este tipo describe los nombres de los recursos que se pasan a las
   distintas funciones de este paquete. Esto se define como
   "Union[str, os.PathLike]".

Están disponibles las siguientes funciones.

importlib.resources.files(package)

   Returns an "importlib.abc.Traversable" object representing the
   resource container for the package (think directory) and its
   resources (think files). A Traversable may contain other containers
   (think subdirectories).

   *package* es un nombre o un objeto de módulo que cumple con los
   requisitos de "Package".

   Nuevo en la versión 3.9.

importlib.resources.as_file(traversable)

   Given a "importlib.abc.Traversable" object representing a file,
   typically from "importlib.resources.files()", return a context
   manager for use in a "with" statement. The context manager provides
   a "pathlib.Path" object.

   Exiting the context manager cleans up any temporary file created
   when the resource was extracted from e.g. a zip file.

   Use "as_file" when the Traversable methods ("read_text", etc) are
   insufficient and an actual file on the file system is required.

   Nuevo en la versión 3.9.

importlib.resources.open_binary(package, resource)

   Abra para lectura binaria el *resource* dentro del *package*.

   *package* es un nombre o un objeto de módulo que cumple con los
   requisitos de "Package". *resource* es el nombre del recurso a
   abrir dentro de *package*; puede que no contenga separadores de
   ruta y puede que no tenga sub-recursos (es decir, no puede ser un
   directorio). Esta función retorna una instancia de
   "typing.BinaryIO", un flujo de E/S binario abierto para lectura.

importlib.resources.open_text(package, resource, encoding='utf-8', errors='strict')

   Se abre para leer el texto del *resource* dentro del *package*. De
   forma predeterminada, el recurso está abierto para lectura como
   UTF-8.

   *package* es un nombre o un objeto de módulo que cumple con los
   requisitos de "Package". *resource* es el nombre del recurso a
   abrir dentro de *package*; puede que no contenga separadores de
   ruta y puede que no tenga sub-recursos (es decir, no puede ser un
   directorio). *encoding* y *errors* tienen el mismo significado que
   con la función integrada "open()".

   Esta función retorna una instancia de "typing.TextIO", un flujo de
   E/S de texto abierto para lectura.

importlib.resources.read_binary(package, resource)

   Lee y retorna el contenido del *resource* dentro del *package* como
   "bytes".

   *package* es un nombre o un objeto de módulo que cumple con los
   requisitos de "Package". *resource* es el nombre del recurso a
   abrir dentro de *package*; puede que no contenga separadores de
   ruta y puede que no tenga sub-recursos (es decir, no puede ser un
   directorio). Esta función retorna el contenido del recurso como
   "bytes".

importlib.resources.read_text(package, resource, encoding='utf-8', errors='strict')

   Lee y retorna el contenido de *resource* dentro de *package* como
   un "str". De forma predeterminada, los contenidos se leen como
   UTF-8 estricto.

   *package* es un nombre o un objeto de módulo que cumple con los
   requisitos de "Package". *resource* es el nombre del recurso a
   abrir dentro de *package*; puede que no contenga separadores de
   ruta y puede que no tenga sub-recursos (es decir, no puede ser un
   directorio). *encoding* y *errors* tienen el mismo significado que
   con la función integrada "open()". Esta función retorna el
   contenido del recurso como "str".

importlib.resources.path(package, resource)

   Retorna la ruta al *resource* como una ruta real del sistema de
   archivos. Esta función retorna un administrador de contexto para
   usar en una declaración "with". El administrador de contexto
   proporciona un objeto "pathlib.Path".

   Salir del administrador de contexto limpia cualquier archivo
   temporal creado cuando el recurso necesita ser extraído, por
   ejemplo, un archivo zip.

   *package* es un nombre o un objeto de módulo que cumple con los
   requisitos de "Package". *resource* es el nombre del recurso a
   abrir dentro de *package*; puede que no contenga separadores de
   ruta y puede que no tenga sub-recursos (es decir, no puede ser un
   directorio).

importlib.resources.is_resource(package, name)

   Retorna "True" si hay un recurso llamado *name* en el paquete; de
   lo contrario, "False". ¡Recuerde que los directorios *no* son
   recursos! *package* es un nombre o un objeto de módulo que cumple
   con los requisitos de "Package".

importlib.resources.contents(package)

   Retorna un iterable sobre los elementos nombrados dentro del
   paquete. El iterable retorna recursos "str" (por ejemplo, archivos)
   y no-recursos (por ejemplo, directorios). El iterable no recurre a
   subdirectorios.

   *package* es un nombre o un objeto de módulo que cumple con los
   requisitos de "Package".


"importlib.machinery" -- Importadores y enlaces de ruta
=======================================================

**Código fuente:** Lib/importlib/machinery.py

======================================================================

Este módulo contiene varios objetos que ayudan "import" buscar y
cargar módulos.

importlib.machinery.SOURCE_SUFFIXES

   Una lista de cadenas de caracteres que representan los sufijos de
   archivo reconocidos para los módulos de origen.

   Nuevo en la versión 3.3.

importlib.machinery.DEBUG_BYTECODE_SUFFIXES

   Una lista de cadenas que representan los sufijos de archivo para
   módulos de código de bytes no optimizados.

   Nuevo en la versión 3.3.

   Obsoleto desde la versión 3.5: Utilice "BYTECODE_SUFFIXES" en su
   lugar.

importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES

   Una lista de cadenas de caracteres que representan los sufijos de
   archivo para módulos de código de bytes optimizados.

   Nuevo en la versión 3.3.

   Obsoleto desde la versión 3.5: Utilice "BYTECODE_SUFFIXES" en su
   lugar.

importlib.machinery.BYTECODE_SUFFIXES

   Una lista de cadenas de caracteres que representan los sufijos de
   archivo reconocidos para los módulos de código de bytes (incluido
   el punto inicial).

   Nuevo en la versión 3.3.

   Distinto en la versión 3.5: El valor ya no depende de "__debug__".

importlib.machinery.EXTENSION_SUFFIXES

   Una lista de cadenas de caracteres que representan los sufijos de
   archivo reconocidos para los módulos de extensión.

   Nuevo en la versión 3.3.

importlib.machinery.all_suffixes()

   Retorna una lista combinada de cadenas de caracteres que
   representan todos los sufijos de archivo para módulos reconocidos
   por la maquinaria de importación estándar. Este es un ayudante para
   el código que simplemente necesita saber si una ruta del sistema de
   archivos potencialmente se refiere a un módulo sin necesidad de
   detalles sobre el tipo de módulo (por ejemplo,
   "inspect.getmodulename()").

   Nuevo en la versión 3.3.

class importlib.machinery.BuiltinImporter

   Un *importer* para módulos integrados. Todos los módulos integrados
   conocidos se enumeran en "sys.builtin_module_names". Esta clase
   implementa los ABC "importlib.abc.MetaPathFinder" y
   "importlib.abc.InspectLoader".

   Esta clase solo define los métodos de clase para aliviar la
   necesidad de instanciación.

   Distinto en la versión 3.5: Como parte de **PEP 489**, el
   importador integrado ahora implementa "Loader.create_module()" y
   "Loader.exec_module()"

class importlib.machinery.FrozenImporter

   Un *importer* para módulos congelados. Esta clase implementa los
   ABC "importlib.abc.MetaPathFinder" y "importlib.abc.InspectLoader".

   Esta clase solo define los métodos de clase para aliviar la
   necesidad de instanciación.

   Distinto en la versión 3.4: Métodos obtenidos "create_module()" y
   "exec_module()".

class importlib.machinery.WindowsRegistryFinder

   *Finder* para los módulos declarados en el registro de Windows.
   Esta clase implementa el "importlib.abc.MetaPathFinder" ABC.

   Esta clase solo define los métodos de clase para aliviar la
   necesidad de instanciación.

   Nuevo en la versión 3.3.

   Obsoleto desde la versión 3.6: Utilice la configuración de "site"
   en su lugar. Es posible que las versiones futuras de Python no
   habiliten este buscador de forma predeterminada.

class importlib.machinery.PathFinder

   Un *Finder* para "sys.path" y atributos del paquete "__path__".
   Esta clase implementa el "importlib.abc.MetaPathFinder" ABC.

   Esta clase solo define los métodos de clase para aliviar la
   necesidad de instanciación.

   classmethod find_spec(fullname, path=None, target=None)

      Método de clase que intenta encontrar un *spec* para el módulo
      especificado por *fullname* en "sys.path" o, si está definido,
      en *path*. Para cada entrada de ruta que se busca, se comprueba
      "sys.path_importer_cache". Si se encuentra un objeto que no es
      falso, se utiliza como *path entry finder* para buscar el módulo
      que se está buscando. Si no se encuentra ninguna entrada en
      "sys.path_importer_cache", entonces "sys.path_hooks" se busca un
      buscador para la entrada de ruta y, si se encuentra, se almacena
      en "sys.path_importer_cache" junto con ser consultado sobre el
      módulo. Si nunca se encuentra ningún buscador, entonces "None"
      se almacena en el caché y se retorna.

      Nuevo en la versión 3.4.

      Distinto en la versión 3.5: Si el directorio de trabajo actual,
      representado por una cadena de caracteres vacía, ya no es
      válido, se retorna``None`` pero no se almacena ningún valor en
      "sys.path_importer_cache".

   classmethod find_module(fullname, path=None)

      Una envoltura heredada alrededor de "find_spec()".

      Obsoleto desde la versión 3.4: Use "find_spec()" en su lugar.

   classmethod invalidate_caches()

      Llama "importlib.abc.PathEntryFinder.invalidate_caches()" en
      todos los buscadores almacenados en "sys.path_importer_cache"
      que definen el método. De lo contrario, las entradas en
      "sys.path_importer_cache" establecidas en "None" se eliminan.

      Distinto en la versión 3.7: Se eliminan las entradas de "None"
      en "sys.path_importer_cache".

   Distinto en la versión 3.4: Llama a objetos en "sys.path_hooks" con
   el directorio de trabajo actual para "''" (es decir, la cadena de
   caracteres vacía).

class importlib.machinery.FileFinder(path, *loader_details)

   Una implementación concreta de "importlib.abc.PathEntryFinder" que
   almacena en caché los resultados del sistema de archivos.

   El argumento *path* es el directorio que el buscador se encarga de
   buscar.

   El argumento *loader_details* es un número variable de tuplas de 2
   elementos, cada una de las cuales contiene un cargador y una
   secuencia de sufijos de archivo que el cargador reconoce. Se espera
   que los cargadores sean invocables que acepten dos argumentos del
   nombre del módulo y la ruta al archivo encontrado.

   El buscador almacenará en caché el contenido del directorio según
   sea necesario, haciendo llamadas estadísticas para cada búsqueda de
   módulo para verificar que la caché no esté desactualizada. Debido a
   que la obsolescencia de la caché se basa en la granularidad de la
   información de estado del sistema operativo del sistema de
   archivos, existe una condición de carrera potencial de buscar un
   módulo, crear un nuevo archivo y luego buscar el módulo que
   representa el nuevo archivo. Si las operaciones ocurren lo
   suficientemente rápido como para ajustarse a la granularidad de las
   llamadas estadísticas, la búsqueda del módulo fallará. Para evitar
   que esto suceda, cuando cree un módulo dinámicamente, asegúrese de
   llamar a "importlib.invalidate_caches()".

   Nuevo en la versión 3.3.

   path

      La ruta en la que buscará el buscador.

   find_spec(fullname, target=None)

      Intente encontrar la especificación para manejar *fullname*
      dentro de "path".

      Nuevo en la versión 3.4.

   find_loader(fullname)

      Intente encontrar el cargador para manejar *fullname* dentro de
      "path".

   invalidate_caches()

      Borrar el caché interno.

   classmethod path_hook(*loader_details)

      Un método de clase que devuelve un cierre para su uso en
      "sys.path_hooks". Una instancia de "FileFinder" es retornada por
      el cierre usando el argumento de ruta dado al cierre
      directamente y *loader_details* indirectamente.

      Si el argumento del cierre no es un directorio existente, se
      lanza "ImportError".

class importlib.machinery.SourceFileLoader(fullname, path)

   Una implementación concreta de "importlib.abc.SourceLoader"
   subclasificando "importlib.abc.FileLoader" y proporcionando algunas
   implementaciones concretas de otros métodos.

   Nuevo en la versión 3.3.

   name

      El nombre del módulo que manejará este cargador.

   path

      La ruta al archivo de origen.

   is_package(fullname)

      Devuelve "True" si "path" parece ser para un paquete.

   path_stats(path)

      Implementación concreta de
      "importlib.abc.SourceLoader.path_stats()".

   set_data(path, data)

      Implementación concreta de
      "importlib.abc.SourceLoader.set_data()".

   load_module(name=None)

      Implementación concreta de "importlib.abc.Loader.load_module()"
      donde especificar el nombre del módulo a cargar es opcional.

      Obsoleto desde la versión 3.6: Utilice
      "importlib.abc.Loader.exec_module()" en su lugar.

class importlib.machinery.SourcelessFileLoader(fullname, path)

   Una implementación concreta de "importlib.abc.FileLoader" que puede
   importar archivos de código de bytes (es decir, no existen archivos
   de código fuente).

   Tenga en cuenta que el uso directo de archivos de código de bytes
   (y, por lo tanto, no de archivos de código fuente) impide que sus
   módulos sean utilizables por todas las implementaciones de Python o
   las nuevas versiones de Python que cambian el formato de código de
   bytes.

   Nuevo en la versión 3.3.

   name

      El nombre del módulo que manejará el cargador.

   path

      La ruta al archivo de código de bytes.

   is_package(fullname)

      Determina si el módulo es un paquete basado en "path".

   get_code(fullname)

      Retorna el objeto de código para "name" creado a partir de
      "path".

   get_source(fullname)

      Devuelve "None" ya que los archivos de código de bytes no tienen
      fuente cuando se usa este cargador.

   load_module(name=None)

   Implementación concreta de "importlib.abc.Loader.load_module()"
   donde especificar el nombre del módulo a cargar es opcional.

   Obsoleto desde la versión 3.6: Utilice
   "importlib.abc.Loader.exec_module()" en su lugar.

class importlib.machinery.ExtensionFileLoader(fullname, path)

   Una implementación concreta de "importlib.abc.ExecutionLoader" para
   módulos de extensión.

   El argumento *fullname* especifica el nombre del módulo que el
   cargador debe admitir. El argumento *path* es la ruta al archivo
   del módulo de extensión.

   Nuevo en la versión 3.3.

   name

      Nombre del módulo que admite el cargador.

   path

      Ruta al módulo de extensión.

   create_module(spec)

      Crea el objeto de módulo a partir de la especificación dada de
      acuerdo con **PEP 489**.

      Nuevo en la versión 3.5.

   exec_module(module)

      Inicializa el objeto de módulo dado de acuerdo con **PEP 489**.

      Nuevo en la versión 3.5.

   is_package(fullname)

      Retorna "True" si la ruta del archivo apunta al módulo
      "__init__" de un paquete basado en "EXTENSION_SUFFIXES".

   get_code(fullname)

      Retorna "None" ya que los módulos de extensión carecen de un
      objeto de código.

   get_source(fullname)

      Retorna "None" ya que los módulos de extensión no tienen código
      fuente.

   get_filename(fullname)

      Retorna "path".

      Nuevo en la versión 3.4.

class importlib.machinery.ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)

   Una especificación para el estado relacionado con el sistema de
   importación de un módulo. Esto generalmente se expone como el
   atributo "__spec__" del módulo. En las descripciones siguientes,
   los nombres entre paréntesis dan el atributo correspondiente
   disponible directamente en el objeto del módulo, por ejemplo,
   "module.__spec__.origin == module.__file__". Sin embargo, tenga en
   cuenta que, si bien los *values* suelen ser equivalentes, pueden
   diferir ya que no hay sincronización entre los dos objetos. Por lo
   tanto, es posible actualizar el "__path__" del módulo en tiempo de
   ejecución, y esto no se reflejará automáticamente en
   "__spec__.submodule_search_locations".

   Nuevo en la versión 3.4.

   name

   ("__name__")

   Una cadena de caracteres para el nombre completo del módulo.

   loader

   ("__loader__")

   El *Loader* que debe usarse al cargar el módulo. *Finders* siempre
   debe establecer esto.

   origin

   ("__file__")

   Nombre del lugar desde el que se carga el módulo, por ejemplo
   "incorporado" (*builtin*) para los módulos incorporados y el nombre
   de archivo para los módulos cargados desde la fuente. Normalmente
   se debe establecer "origen", pero puede ser "None" (el valor
   predeterminado), lo que indica que no está especificado (por
   ejemplo, para paquetes de espacio de nombres).

   submodule_search_locations

   ("__path__")

   Lista de cadenas de caracteres de dónde encontrar submódulos, si es
   un paquete ("None" de lo contrario).

   loader_state

   Contenedor de datos adicionales específicos del módulo para usar
   durante la carga (o "None").

   cached

   ("__cached__")

   Cadena de caracteres para el lugar donde se debe almacenar el
   módulo compilado (o "None").

   parent

   ("__package__")

   (Solo lectura) El nombre completo del paquete bajo el cual se debe
   cargar el módulo como submódulo (o la cadena de caracteres vacía
   para los módulos de nivel superior). Para los paquetes, es lo mismo
   que "__name__".

   has_location

   Booleano que indica si el atributo "origen" del módulo se refiere a
   una ubicación cargable.


"importlib.util" -- Código de utilidad para importadores
========================================================

**Código fuente:** Lib/importlib/util.py

======================================================================

Este módulo contiene los diversos objetos que ayudan en la
construcción de un *importer*.

importlib.util.MAGIC_NUMBER

   Los bytes que representan el número de versión del código de bytes.
   Si necesita ayuda para cargar/escribir código de bytes, considere
   "importlib.abc.SourceLoader".

   Nuevo en la versión 3.4.

importlib.util.cache_from_source(path, debug_override=None, *, optimization=None)

   Retorna la ruta **PEP 3147**/**PEP 488** al archivo compilado por
   bytes asociado con la *path* de origen. Por ejemplo, si *path* es
   "/foo/bar/baz.py", el valor de retorno sería
   "/foo/bar/__pycache__/baz.cpython-32.pyc" para Python 3.2. La
   cadena de caracteres "cpython-32" proviene de la etiqueta mágica
   actual (ver "get_tag()"; si "sys.implementation.cache_tag" no está
   definido, se lanzará "NotImplementedError").

   El parámetro *optimization* se utiliza para especificar el nivel de
   optimización del archivo de código de bytes. Una cadena de
   caracteres vacía no representa optimización, por lo que
   "/foo/bar/baz.py" con una *optimization* de "''" dará como
   resultado una ruta de código de bytes de
   "/foo/bar/__pycache__/baz.cpython-32.pyc". "None" hace que se
   utilice el nivel de optimización del intérprete. Se usa la
   representación de cadena de caracteres de cualquier otro valor, por
   lo que "/foo/bar/baz.py" con una *optimization* de "2" conducirá a
   la ruta del código de bytes de
   "/foo/bar/__pycache__/baz.cpython-32.opt-2.pyc". La representación
   de cadena de caracteres *optimization* solo puede ser alfanumérica,
   de lo contrario se lanza "ValueError".

   El parámetro *debug_override* está obsoleto y se puede usar para
   anular el valor del sistema para "__debug__". Un valor "True" es el
   equivalente a establecer *optimization* en la cadena de caracteres
   vacía. Un valor "False" es lo mismo que establecer *optimization*
   en "1". Si tanto *debug_override* como *optimization* no es "None",
   entonces se lanza "TypeError".

   Nuevo en la versión 3.4.

   Distinto en la versión 3.5: Se agregó el parámetro *optimization* y
   el parámetro *debug_override* quedó obsoleto.

   Distinto en la versión 3.6: Acepta un *path-like object*.

importlib.util.source_from_cache(path)

   Dado el *path* a un nombre de archivo **PEP 3147**, retorna la ruta
   del archivo del código fuente asociado. Por ejemplo, si *path* es
   "/foo/bar/__pycache__/baz.cpython-32.pyc", la ruta retornada sería
   "/foo/bar/baz.py". *path* no necesita existir, sin embargo, si no
   se ajusta al formato **PEP 3147** o **PEP 488**, se lanza un
   "ValueError". Si "sys.implementation.cache_tag" no está definido,
   se lanza "NotImplementedError".

   Nuevo en la versión 3.4.

   Distinto en la versión 3.6: Acepta un *path-like object*.

importlib.util.decode_source(source_bytes)

   Decodifica los bytes dados que representan el código fuente y los
   retorna como una cadena de caracteres con nuevas líneas universales
   (como lo requiere "importlib.abc.InspectLoader.get_source()").

   Nuevo en la versión 3.4.

importlib.util.resolve_name(name, package)

   Resuelve un nombre de módulo relativo a uno absoluto.

   Si **name** no tiene puntos iniciales, entonces **name**
   simplemente se retorna. Esto permite el uso como
   "importlib.util.resolve_name('sys', __spec__.parent)" sin hacer una
   verificación para ver si se necesita el argumento **package**.

   "ImportError" se lanza si **name** es un nombre de módulo relativo
   pero **package** es un valor falso (por ejemplo, "None" o la cadena
   de caracteres vacía). También se lanza "ImportError" un nombre
   relativo que escaparía del paquete que lo contiene (por ejemplo,
   solicitando "..bacon" desde el paquete "spam").

   Nuevo en la versión 3.3.

   Distinto en la versión 3.9: Para mejorar la coherencia con las
   declaraciones de importación, aumente "ImportError" en lugar de
   "ValueError" para intentos de importación relativa no válidos.

importlib.util.find_spec(name, package=None)

   Busca el *spec* para un módulo, opcionalmente relativo al nombre
   del **package** especificado. Si el módulo está en "sys.modules",
   se retorna "sys.modules[name].__spec__" (a menos que la
   especificación sea "None" o no esté establecida, en cuyo caso se
   lanza "ValueError"). De lo contrario, se realiza una búsqueda
   utilizando "sys.meta_path". Se retorna "None" si no se encuentra
   ninguna especificación.

   Si **name** es para un submódulo (contiene un punto), el módulo
   principal se importa automáticamente.

   **name** y **package** funcionan igual que para "import_module()".

   Nuevo en la versión 3.4.

   Distinto en la versión 3.7: Lanza "ModuleNotFoundError" en lugar de
   "AttributeError" si **package** no es de hecho un paquete (es
   decir, carece de un atributo "__path__").

importlib.util.module_from_spec(spec)

   Cree un nuevo módulo basado en **spec** y
   "spec.loader.create_module".

   Si "spec.loader.create_module" no retorna "None", no se
   restablecerán los atributos preexistentes. Además, no se lanzará
   "AttributeError" si se activa mientras se accede a **spec** o se
   establece un atributo en el módulo.

   Esta función es preferible a usar "types.ModuleType" para crear un
   nuevo módulo ya que **spec** se usa para establecer tantos
   atributos de importación controlados en el módulo como sea posible.

   Nuevo en la versión 3.5.

@importlib.util.module_for_loader

   Un *decorator* para "importlib.abc.Loader.load_module()" para
   manejar la selección del objeto de módulo adecuado para cargar. Se
   espera que el método decorado tenga una firma de llamada que tome
   dos argumentos posicionales (por ejemplo, "load_module(self,
   module)") para los cuales el segundo argumento será el módulo
   **object** que usará el cargador. Tenga en cuenta que el decorador
   no funcionará con métodos estáticos debido a la suposición de dos
   argumentos.

   El método decorado tomará el **name** del módulo que se cargará
   como se esperaba para un *loader*. Si el módulo no se encuentra en
   "sys.modules", se construye uno nuevo. Independientemente de la
   procedencia del módulo, "__loader__" se establece en **self** y
   "__package__" se establece en función de lo que retorna
   "importlib.abc.InspectLoader.is_package()" (si está disponible) .
   Estos atributos se establecen incondicionalmente para admitir la
   recarga.

   Si el método decorado lanza una excepción y se agrega un módulo a
   "sys.modules", entonces el módulo se eliminará para evitar que un
   módulo parcialmente inicializado quede en "sys.modules". Si el
   módulo ya estaba en "sys.modules" entonces se deja solo.

   Distinto en la versión 3.3: "__loader__" y "__package__" se
   configuran automáticamente (cuando es posible).

   Distinto en la versión 3.4: Establece "__name__", "__loader__"
   "__package__" incondicionalmente para apoyar la recarga.

   Obsoleto desde la versión 3.4: La maquinaria de importación ahora
   realiza directamente toda la funcionalidad proporcionada por esta
   función.

@importlib.util.set_loader

   Un *decorator* para "importlib.abc.Loader.load_module()" para
   establecer el atributo "__loader__" en el módulo retornado. Si el
   atributo ya está configurado, el decorador no hace nada. Se asume
   que el primer argumento posicional del método envuelto (es decir,
   "self") es lo que se debe establecer en "__loader__".

   Distinto en la versión 3.4: Establece "__loader__" si está
   configurado como "None", como si el atributo no existiera.

   Obsoleto desde la versión 3.4: La maquinaria de importación se
   encarga de esto automáticamente.

@importlib.util.set_package

   Un *decorator* para "importlib.abc.Loader.load_module()" para
   establecer el atributo "__package__" en el módulo retornado. Si
   "__package__" está configurado y tiene un valor diferente a "None",
   no se cambiará.

   Obsoleto desde la versión 3.4: La maquinaria de importación se
   encarga de esto automáticamente.

importlib.util.spec_from_loader(name, loader, *, origin=None, is_package=None)

   Una función de fábrica para crear una instancia "ModuleSpec" basada
   en un cargador. Los parámetros tienen el mismo significado que para
   ModuleSpec. La función utiliza APIs disponibles *loader*, como
   "InspectLoader.is_package()", para completar cualquier información
   que falte en la especificación.

   Nuevo en la versión 3.4.

importlib.util.spec_from_file_location(name, location, *, loader=None, submodule_search_locations=None)

   Una función de fábrica para crear una instancia "ModuleSpec" basada
   en la ruta a un archivo. La información que falte se completará en
   la especificación mediante el uso de las API de carga y la
   implicación de que el módulo estará basado en archivos.

   Nuevo en la versión 3.4.

   Distinto en la versión 3.6: Acepta un *path-like object*.

importlib.util.source_hash(source_bytes)

   Retorna el hash de *source_bytes* como bytes. Un archivo ".pyc"
   basado en hash incrusta "source_hash()" del contenido del archivo
   fuente correspondiente en su encabezado.

   Nuevo en la versión 3.7.

class importlib.util.LazyLoader(loader)

   Una clase que pospone la ejecución del cargador de un módulo hasta
   que el módulo tiene acceso a un atributo.

   Esta clase **solo** funciona con cargadores que definen
   "exec_module()" ya que se requiere control sobre qué tipo de módulo
   se usa para el módulo. Por esas mismas razones, el método del
   cargador "create_module()" debe retornar "None" o un tipo para el
   cual su atributo "__class__" se puede mutar junto con no usar
   *slots*. Finalmente, los módulos que sustituyen el objeto colocado
   en "sys.modules" no funcionarán ya que no hay forma de reemplazar
   correctamente las referencias del módulo en todo el intérprete de
   forma segura; "ValueError" se genera si se detecta tal sustitución.

   Nota:

     Para proyectos donde el tiempo de inicio es crítico, esta clase
     permite minimizar potencialmente el costo de cargar un módulo si
     nunca se usa. Para proyectos en los que el tiempo de inicio no es
     esencial, el uso de esta clase se desaconseja **en gran medida**
     debido a que los mensajes de error creados durante la carga se
     posponen y, por lo tanto, ocurren fuera de contexto.

   Nuevo en la versión 3.5.

   Distinto en la versión 3.6: Comenzó a llamar "create_module()",
   eliminando la advertencia de compatibilidad para
   "importlib.machinery.BuiltinImporter" y
   "importlib.machinery.ExtensionFileLoader".

   classmethod factory(loader)

      Un método estático que devuelve un invocable que crea un
      cargador diferido. Esto está destinado a utilizarse en
      situaciones en las que el cargador se pasa por clase en lugar de
      por instancia.

         suffixes = importlib.machinery.SOURCE_SUFFIXES
         loader = importlib.machinery.SourceFileLoader
         lazy_loader = importlib.util.LazyLoader.factory(loader)
         finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes))


Ejemplos
========


Importar programáticamente
--------------------------

Para importar un módulo mediante programación, use
"importlib.import_module()".

   import importlib

   itertools = importlib.import_module('itertools')


Comprobando si se puede importar un módulo
------------------------------------------

Si necesita averiguar si un módulo se puede importar sin realmente
realizar la importación, entonces debe usar
"importlib.util.find_spec()".

   import importlib.util
   import sys

   # For illustrative purposes.
   name = 'itertools'

   if name in sys.modules:
       print(f"{name!r} already in sys.modules")
   elif (spec := importlib.util.find_spec(name)) is not None:
       # If you chose to perform the actual import ...
       module = importlib.util.module_from_spec(spec)
       sys.modules[name] = module
       spec.loader.exec_module(module)
       print(f"{name!r} has been imported")
   else:
       print(f"can't find the {name!r} module")


Importar un archivo fuente directamente
---------------------------------------

Para importar un archivo fuente de Python directamente, use la
siguiente receta (solo Python 3.5 y más reciente):

   import importlib.util
   import sys

   # For illustrative purposes.
   import tokenize
   file_path = tokenize.__file__
   module_name = tokenize.__name__

   spec = importlib.util.spec_from_file_location(module_name, file_path)
   module = importlib.util.module_from_spec(spec)
   sys.modules[module_name] = module
   spec.loader.exec_module(module)


Configurar un importador
------------------------

Para personalizaciones profundas de la importación, normalmente desea
implementar un *importador*. Esto significa administrar tanto el lado
*finder* como *loader* de las cosas. Para los buscadores, hay dos
sabores para elegir según sus necesidades: un *meta path finder* o un
*path entry finder*. El primero es lo que pondrías en "sys.meta_path"
mientras que el segundo es lo que creas usando un *path entry hook* en
"sys.path_hooks" que funciona con "sys .path" entradas para crear
potencialmente un buscador. Este ejemplo le mostrará cómo registrar
sus propios importadores para que import los utilice (para crear un
importador para usted, lea la documentación de las clases apropiadas
definidas dentro de este paquete):

   import importlib.machinery
   import sys

   # For illustrative purposes only.
   SpamMetaPathFinder = importlib.machinery.PathFinder
   SpamPathEntryFinder = importlib.machinery.FileFinder
   loader_details = (importlib.machinery.SourceFileLoader,
                     importlib.machinery.SOURCE_SUFFIXES)

   # Setting up a meta path finder.
   # Make sure to put the finder in the proper location in the list in terms of
   # priority.
   sys.meta_path.append(SpamMetaPathFinder)

   # Setting up a path entry finder.
   # Make sure to put the path hook in the proper location in the list in terms
   # of priority.
   sys.path_hooks.append(SpamPathEntryFinder.path_hook(loader_details))


Aproximando "importlib.import_module()"
---------------------------------------

La importación en sí está implementada en código Python, lo que
permite exponer la mayor parte de la maquinaria de importación a
través de importlib. Lo siguiente ayuda a ilustrar las diversas API
que importlib expone al proporcionar una implementación aproximada de
"importlib.import_module()" (Python 3.4 y más reciente para el uso de
importlib, Python 3.6 y más reciente para otras partes del código).

   import importlib.util
   import sys

   def import_module(name, package=None):
       """An approximate implementation of import."""
       absolute_name = importlib.util.resolve_name(name, package)
       try:
           return sys.modules[absolute_name]
       except KeyError:
           pass

       path = None
       if '.' in absolute_name:
           parent_name, _, child_name = absolute_name.rpartition('.')
           parent_module = import_module(parent_name)
           path = parent_module.__spec__.submodule_search_locations
       for finder in sys.meta_path:
           spec = finder.find_spec(absolute_name, path)
           if spec is not None:
               break
       else:
           msg = f'No module named {absolute_name!r}'
           raise ModuleNotFoundError(msg, name=absolute_name)
       module = importlib.util.module_from_spec(spec)
       sys.modules[absolute_name] = module
       spec.loader.exec_module(module)
       if path is not None:
           setattr(parent_module, child_name, module)
       return module
