# `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 lanza 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, lanza 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`.

    Obsoleto desde la versión 3.10: Implemente `MetaPathFinder.find_spec()` o `PathEntryFinder.find_spec()` en su lugar.

class `importlib.abc.``MetaPathFinder`

  An abstract base class representing a meta path finder.

  Nuevo en la versión 3.3.

  Distinto en la versión 3.10: Ya no hereda de `Finder`.

  `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 buscador de entradas de ruta. Aunque tiene algunas similitudes con `MetaPathFinder`, `PathEntryFinder` está diseñado para usarse solo dentro del subsistema de importación basado en rutas proporcionado por `importlib.machinery.PathFinder`.

  Nuevo en la versión 3.3.

  Distinto en la versión 3.10: Ya no hereda de `Finder`.

  `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 `importlib.machinery.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__`

        The fully qualified name of the package under which the module was loaded as a submodule (or the empty string for top-level modules). For packages, it is the same as `__name__`. The `importlib.util.module_for_loader()` decorator can handle the details for `__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`

  Reemplazada por 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)

    Un método opcional para retornar un valor verdadero si el módulo es un paquete, un valor falso en caso contrario. Se lanza `ImportError` si el cargador no puede encontrar el módulo.

    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.

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.

  Se espera que los cargadores que deseen admitir la lectura de recursos implementen esta interfaz.

  Nuevo en la versión 3.9.

## `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)

  Retorna un objeto `importlib.resources.abc.Traversable` que representa el contenedor de recursos para el paquete (directorio think) y sus recursos (archivos think). Un Traversable puede contener otros contenedores (subdirectorios think).

  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)

  Dado un objeto `importlib.resources.abc.Traversable` que representa un archivo, típicamente de `importlib.resources.files()`, retorna un gestor de contexto para su uso en una sentencia `with`. El gestor de contexto proporciona un objeto `pathlib.Path`.

  Salir del gestor de contexto limpia cualquier archivo temporal creado cuando se extrajo el recurso de, por ejemplo, un archivo zip.

  Use `as_file` cuando los métodos Traversable (``read_text`, etc) sean insuficientes y se requiera un archivo real en el sistema de archivos.

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

    Obsoleto desde la versión 3.10: Use `find_spec()` en su lugar.

  `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__`)

  A string for the fully qualified name of the module.

  `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__`)

  (Read-only) The fully qualified name of the package under which the module should be loaded as a submodule (or the empty string for top-level modules). For packages, it is the same as `__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 de `ModuleSpec` basada en un cargador. Los parámetros tienen el mismo significado que para ModuleSpec. La función utiliza APIs disponibles de loader, tal 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 de `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 loader 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

If you need to find out if a module can be imported without actually doing the import, then you should use `importlib.util.find_spec()`.

Note that if `name` is a submodule (contains a dot), `importlib.util.find_spec()` will import the parent module.

    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)

### Implementar importaciones diferidas

El ejemplo de abajo muestra cómo implementar importaciones diferidas:

    >>> import importlib.util
    >>> import sys
    >>> def lazy_import(name):
    ...     spec = importlib.util.find_spec(name)
    ...     loader = importlib.util.LazyLoader(spec.loader)
    ...     spec.loader = loader
    ...     module = importlib.util.module_from_spec(spec)
    ...     sys.modules[name] = module
    ...     loader.exec_module(module)
    ...     return module
    ...
    >>> lazy_typing = lazy_import("typing")
    >>> #lazy_typing is a real module object,
    >>> #but it is not loaded in memory yet.
    >>> lazy_typing.TYPE_CHECKING
    False

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