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 triple:

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 intérprete de Python. También provee una implementación que es más fácil de comprender que una implementada en un lenguajes que no es 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.

Tres, el paquete contiene módulos exponiendo funcionalidad adicional para administrar aspectos de paquetes de Python:

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.

La inicialización de la ruta de búsqueda de módulo de sys.path

La inicialización de sys.path.

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.

Distinto en la versión 3.10: Paquetes de espacio de nombres creados/instalados en una ubicación sys.path distinta después de que el mismo espacio de nombres fue importado son notados.

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

Una clase base abstracta que representa 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: Returns None when called instead of 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() según lo especificado por importlib.abc.ResourceReader.

Distinto en la versión 3.7: Introducido 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.6: Este método ya no es 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 completo del módulo. Es '__main__' para un módulo ejecutado.

  • __file__

    La ubicación que el cargador usó para cargar el módulo. Por ejemplo, para módulos cargados desde un archivo .py, éste es el nombre del archivo. No está establecido para todos los módulos (por ejemplo. módulos integrados).

  • __cached__

    El nombre de archivo de una versión compilada del código del módulo. No está establecido para todos los módulos (por ejemplo, módulos integrados).

  • __path__

    The list of locations where the package’s submodules will be found. Most of the time this is a single directory. The import system passes this attribute to __import__() and to finders in the same way as sys.path but just for the package. It is not set on non-package modules so it can be used as an indicator that the module is a package.

  • __package__

    El nombre completo del paquete bajo el cual está el módulo (o la cadena de caracteres vacía para los módulos de nivel superior). Si el módulo es un paquete es lo mismo que __name__.

  • __loader__

    El cargador usado para cargar el módulo.

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 representación del módulo dado, como una cadena. El método __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.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.resources.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:

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.

When writing to the path fails because the path is read-only (errno.EACCES/PermissionError), do not propagate the exception.

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

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)

A class method which returns a closure for use on sys.path_hooks. An instance of FileFinder is returned by the closure using the path argument given to the closure directly and loader_details indirectly.

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.NamespaceLoader(name, path, path_finder)

Una implementación concreta de importlib.abc.InspectLoader para paquetes de espacio de nombres. Ésta es un alias para una clase privada y sólo se hace pública para introspeccionar el atributo __loader__ en paquetes de espacio de nombres:

>>> from importlib.machinery import NamespaceLoader
>>> import my_namespace
>>> isinstance(my_namespace.__loader__, NamespaceLoader)
True
>>> import importlib.abc
>>> isinstance(my_namespace.__loader__, importlib.abc.Loader)
True

Nuevo en la versión 3.11.

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 valores suelen ser equivalentes, pueden diferir ya que no hay sincronización entre los dos objetos. Por ejemplo, es posible actualizar el __path__ del módulo en tiempo de ejecución, y esto no se reflejará automáticamente en el __spec__.origin del módulo, y viceversa.

Nuevo en la versión 3.4.

name

(__name__)

El nombre completo del módulo. El buscador debe siempre establecer este atributo a una cadena de caracteres no vacía.

loader

(__loader__)

El Cargador que debe usarse para cargar el módulo. El Buscador siempre debe establecer este atributo.

origin

(__file__)

La ubicación que el cargador debe usar para cargar el módulo. Por ejemplo, para módulos cargados de archivos .py éste es el nombre del archivo. El buscador debe siempre establecer este atributo a un valor significativo para que el cargador lo use. El en caso poco común de que no hay uno (como para paquetes de nombre de espacio), debe estar establecido en None.

submodule_search_locations

(__path__)

La lista de ubicaciones donde los sub-módulos del paquete serán encontrados. La mayoría de las veces es un solo directorio. El buscador debe establecer este atributo a una lista, incluso una vacía, para indicar al sistema de importación que el módulo es un paquete. Debe ser establecido en None para módulos que no son paquetes. Es establecido automáticamente más tarde a un objeto especial para paquetes de espacio de nombres.

loader_state

El buscador podría establecer este atributo a un objeto conteniendo datos adicionales y específicos al módulo para usar cuando se carga el módulo.. De lo contrario, debe establecerse en None.

cached

(__cached__)

El nombre de archivo de una versión compilada del código de el módulo. El buscador siempre debe establecer este atributo pero puede ser None para módulos que no necesitan guardar código compilado.

parent

(__package__)

(Solo lectura) El nombre completo del paquete bajo el cual está este módulo (o la cadena de caracteres vacía para los módulos de nivel superior). Si el módulo es un paquete es lo mismo que __name__.

has_location
True si el origin de la especificación se refiere a una ubicación cargable,

False en caso contrario. Este valor impacta en cómo origin es interpretado y cómo el atributo __file__ del módulo es poblado.

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 si un nombre relativo 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)

Find the spec for a module, optionally relative to the specified package name. If the module is in sys.modules, then sys.modules[name].__spec__ is returned (unless the spec would be None or is not set, in which case ValueError is raised). Otherwise a search using sys.meta_path is done. None is returned if no spec is found.

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.

This class only works with loaders that define exec_module() as control over what module type is used for the module is required. For those same reasons, the loader’s create_module() method must return None or a type for which its __class__ attribute can be mutated along with not using slots. Finally, modules which substitute the object placed into sys.modules will not work as there is no way to properly replace the module references throughout the interpreter safely; ValueError is raised if such a substitution is detected.

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)

A class method which returns a callable that creates a lazy loader. This is meant to be used in situations where the loader is passed by class instead of by instance.

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().

Note que si name es un sub-módulo (contiene sólo un punto), importlib.util.find_spec() importará el módulo padre.

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:

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

For deep customizations of import, you typically want to implement an importer. This means managing both the finder and loader side of things. For finders there are two flavours to choose from depending on your needs: a meta path finder or a path entry finder. The former is what you would put on sys.meta_path while the latter is what you create using a path entry hook on sys.path_hooks which works with sys.path entries to potentially create a finder. This example will show you how to register your own importers so that import will use them (for creating an importer for yourself, read the documentation for the appropriate classes defined within this package):

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():

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