importlib
— La implementación de import
¶
Added in version 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:
importlib.metadata
presenta acceso a metadatos de distribuciones de terceros.importlib.resources
provee rutinas para acceder a recursos que no son código 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
ensys.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 (ejemploimport_module('..mod', 'pkg.subpkg')
importarápkg.mod
).La función
import_module()
actúa como un envoltorio simplificador alrededor deimportlib.__import__()
. Esto quiere decir que las semánticas de la función son derivadas deimportlib.__import__()
. La diferencia más importante entre las dos funciones es queimport_module()
retorna el paquete especificado o el módulo (ejemplopkg.mod
), mientras que__import__()
retorna el paquete o módulo del nivel superior (ejemplopkg
).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.invalidate_caches()¶
Invalide los cache internos de ubicadores encontrados en
sys.meta_path
.Si un buscador implementainvalidate_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.Added in version 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 areload()
para el otro módulo no redefine los objetos importados de él — una forma de evitar esto es volver a ejecutar la instrucciónfrom
, otra es usarimport
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.
Added in version 3.4.
Distinto en la versión 3.7:
ModuleNotFoundError
se lanza cuando el módulo que se está recargando carece deModuleSpec
.
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
+-- MetaPathFinder
+-- PathEntryFinder
+-- Loader
+-- ResourceLoader --------+
+-- InspectLoader |
+-- ExecutionLoader --+
+-- FileLoader
+-- SourceLoader
- class importlib.abc.MetaPathFinder¶
Una clase base abstracta que representa meta path finder.
Added in version 3.3.
Distinto en la versión 3.10: No longer a subclass of
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 retornaNone
. 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 implementarMetaPathFinders
concretos.Added in version 3.4.
- 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 ensys.meta_path
.Distinto en la versión 3.4: Returns
None
when called instead ofNotImplemented
.
- 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 porimportlib.machinery.PathFinder
.Added in version 3.3.
Distinto en la versión 3.10: No longer a subclass of
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 implementarPathEntryFinders
concretos.Added in version 3.4.
- 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 porimportlib.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.Added in version 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 definircreate_module()
.Added in version 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.If the requested module already exists in
sys.modules
, that module should be used and reloaded. Otherwise the loader should create a new module and insert it intosys.modules
before any loading begins, to prevent recursion from the import. If the loader inserted a module and the load fails, it must be removed by the loader fromsys.modules
; modules already insys.modules
before the loader began execution should be left alone.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.
__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 assys.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 deNotImplementedError
. Funcionalidad proporcionada cuandoexec_module()
está disponible.Obsoleto desde la versión 3.4: La API recomendada para cargar un módulo es
exec_module()
(ycreate_module()
). Los cargadores deberían implementarlo en lugar deload_module()
. La maquinaria de importación se encarga de todas las demás responsabilidades deload_module()
cuando se implementaexec_module()
.
- 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 deNotImplementedError
.
- 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 unImportError
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
' '
. RetornaNone
si no hay una fuente disponible (por ejemplo, un módulo integrado). LanzaImportError
si el cargador no puede encontrar el módulo especificado.Distinto en la versión 3.4: Lanza
ImportError
en vez deNotImplementedError
.
- 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 deNotImplementedError
.
- 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__)
.Added in version 3.4.
Distinto en la versión 3.5: Hace el método estático.
- exec_module(module)¶
Implementación de
Loader.exec_module()
.Added in version 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 lanzaImportError
.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 deNotImplementedError
.
- class importlib.abc.FileLoader(fullname, path)¶
Una clase base abstracta que hereda de
ResourceLoader
yExecutionLoader
, proporcionando implementaciones concretas deResourceLoader.get_data()
yExecutionLoader.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.
Added in version 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_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 deExecutionLoader
, lo que requiere la implementación de: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
.Added in version 3.3.
Distinto en la versión 3.4: Lanza
OSError
en vez deNotImplementedError
.
- 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. LanzaOSError
si la ruta no se puede manejar.Distinto en la versión 3.4: Lanza
OSError
en vez deNotImplementedError
.
- 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()
.Added in version 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 porExecutionLoader.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.ResourceReader¶
Superseded by TraversableResources
An abstract base class to provide the ability to read resources.
From the perspective of this ABC, a resource is a binary artifact that is shipped within a package. Typically this is something like a data file that lives next to the
__init__.py
file of the package. The purpose of this class is to help abstract out the accessing of such data files so that it does not matter if the package and its data file(s) are stored e.g. in a zip file versus on the file system.For any of methods of this class, a resource argument is expected to be a path-like object which represents conceptually just a file name. This means that no subdirectory paths should be included in the resource argument. This is because the location of the package the reader is for, acts as the «directory». Hence the metaphor for directories and file names is packages and resources, respectively. This is also why instances of this class are expected to directly correlate to a specific package (instead of potentially representing multiple packages or a module).
Loaders that wish to support resource reading are expected to provide a method called
get_resource_reader(fullname)
which returns an object implementing this ABC’s interface. If the module specified by fullname is not a package, this method should returnNone
. An object compatible with this ABC should only be returned when the specified module is a package.Added in version 3.7.
Deprecated since version 3.12, will be removed in version 3.14: Use
importlib.resources.abc.TraversableResources
instead.- abstractmethod open_resource(resource)¶
Returns an opened, file-like object for binary reading of the resource.
If the resource cannot be found,
FileNotFoundError
is raised.
- abstractmethod resource_path(resource)¶
Returns the file system path to the resource.
If the resource does not concretely exist on the file system, raise
FileNotFoundError
.
- abstractmethod is_resource(name)¶
Returns
True
if the named name is considered a resource.FileNotFoundError
is raised if name does not exist.
- abstractmethod contents()¶
Returns an iterable of strings over the contents of the package. Do note that it is not required that all names returned by the iterator be actual resources, e.g. it is acceptable to return names for which
is_resource()
would be false.Allowing non-resource names to be returned is to allow for situations where how a package and its resources are stored are known a priori and the non-resource names would be useful. For instance, returning subdirectory names is allowed so that when it is known that the package and resources are stored on the file system then those subdirectory names can be used directly.
The abstract method returns an iterable of no items.
- class importlib.abc.Traversable¶
An object with a subset of
pathlib.Path
methods suitable for traversing directories and opening files.For a representation of the object on the file-system, use
importlib.resources.as_file()
.Added in version 3.9.
Deprecated since version 3.12, will be removed in version 3.14: Use
importlib.resources.abc.Traversable
instead.- name¶
Abstract. The base name of this object without any parent references.
- abstractmethod iterdir()¶
Yield
Traversable
objects inself
.
- abstractmethod is_dir()¶
Return
True
ifself
is a directory.
- abstractmethod is_file()¶
Return
True
ifself
is a file.
- abstractmethod joinpath(child)¶
Return Traversable child in
self
.
- abstractmethod __truediv__(child)¶
Return
Traversable
child inself
.
- 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¶
An abstract base class for resource readers capable of serving the
importlib.resources.files()
interface. Subclassesimportlib.resources.abc.ResourceReader
and provides concrete implementations of theimportlib.resources.abc.ResourceReader
’s abstract methods. Therefore, any loader supplyingimportlib.abc.TraversableResources
also supplies ResourceReader.Loaders that wish to support resource reading are expected to implement this interface.
Added in version 3.9.
Deprecated since version 3.12, will be removed in version 3.14: Use
importlib.resources.abc.TraversableResources
instead.- abstractmethod files()¶
Returns a
importlib.resources.abc.Traversable
object for the loaded 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.
Added in version 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.
Added in version 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.
Added in version 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).
Added in version 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.
Added in version 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()
).Added in version 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 ABCimportlib.abc.MetaPathFinder
yimportlib.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()
yLoader.exec_module()
- class importlib.machinery.FrozenImporter¶
Un importer para módulos congelados. Esta clase implementa los ABC
importlib.abc.MetaPathFinder
yimportlib.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()
yexec_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.
Added in version 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 elimportlib.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 compruebasys.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 ensys.path_importer_cache
, entoncessys.path_hooks
se busca un buscador para la entrada de ruta y, si se encuentra, se almacena ensys.path_importer_cache
junto con ser consultado sobre el módulo. Si nunca se encuentra ningún buscador, entoncesNone
se almacena en el caché y se retorna.Added in version 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 ensys.path_importer_cache
.
- classmethod invalidate_caches()¶
Llama
importlib.abc.PathEntryFinder.invalidate_caches()
en todos los buscadores almacenados ensys.path_importer_cache
que definen el método. De lo contrario, las entradas ensys.path_importer_cache
establecidas enNone
se eliminan.Distinto en la versión 3.7: Se eliminan las entradas de
None
ensys.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()
.Added in version 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
.Added in version 3.4.
- 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 ofFileFinder
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
subclasificandoimportlib.abc.FileLoader
y proporcionando algunas implementaciones concretas de otros métodos.Added in version 3.3.
- name¶
El nombre del módulo que manejará este cargador.
- path¶
La ruta al archivo de origen.
- 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.
Added in version 3.3.
- name¶
El nombre del módulo que manejará el cargador.
- path¶
La ruta al archivo de código de bytes.
- 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.
Note that, by default, importing an extension module will fail in subinterpreters if it doesn’t implement multi-phase init (see PEP 489), even if it would otherwise import successfully.
Added in version 3.3.
Distinto en la versión 3.12: Multi-phase init is now required for use in subinterpreters.
- 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.
Added in version 3.5.
- exec_module(module)¶
Inicializa el objeto de módulo dado de acuerdo con PEP 489.
Added in version 3.5.
- is_package(fullname)¶
Retorna
True
si la ruta del archivo apunta al módulo__init__
de un paquete basado enEXTENSION_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.
- 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
Added in version 3.11.
- class importlib.machinery.ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)¶
A specification for a module’s import-system-related state. This is typically exposed as the module’s
__spec__
attribute. Many of these attributes are also available directly on a module: for example,module.__spec__.origin == module.__file__
. Note, however, that while the values are usually equivalent, they can differ since there is no synchronization between the two objects. For example, it is possible to update the module’s__file__
at runtime and this will not be automatically reflected in the module’s__spec__.origin
, and vice versa.Added in version 3.4.
- name¶
The module’s fully qualified name (see
__name__
attributes on modules). The finder should always set this attribute to a non-empty string.
- loader¶
The loader used to load the module (see
__loader__
attributes on modules). The finder should always set this attribute.
- origin¶
The location the loader should use to load the module (see
__file__
attributes on modules). For example, for modules loaded from a .py file this is the filename. The finder should always set this attribute to a meaningful value for the loader to use. In the uncommon case that there is not one (like for namespace packages), it should be set toNone
.
- submodule_search_locations¶
The list of locations where the package’s submodules will be found (see
__path__
attributes on modules). Most of the time this is a single directory. The finder should set this attribute to a list, even an empty one, to indicate to the import system that the module is a package. It should be set toNone
for non-package modules. It is set automatically later to a special object for namespace packages.
- 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¶
The filename of a compiled version of the module’s code (see
__cached__
attributes on modules). The finder should always set this attribute but it may beNone
for modules that do not need compiled code stored.
- parent¶
(Read-only) The fully qualified name of the package the module is in (or the empty string for a top-level module). See
__package__
attributes on modules. If the module is a package then this is the same asname
.
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
.Added in version 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 caracterescpython-32
proviene de la etiqueta mágica actual (verget_tag()
; sisys.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 de2
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 lanzaValueError
.El parámetro debug_override está obsoleto y se puede usar para anular el valor del sistema para
__debug__
. Un valorTrue
es el equivalente a establecer optimization en la cadena de caracteres vacía. Un valorFalse
es lo mismo que establecer optimization en1
. Si tanto debug_override como optimization no esNone
, entonces se lanzaTypeError
.Added in version 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 unValueError
. Sisys.implementation.cache_tag
no está definido, se lanzaNotImplementedError
.Added in version 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()
).Added in version 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 lanzaImportError
si un nombre relativo escaparía del paquete que lo contiene (por ejemplo, solicitando..bacon
desde el paquetespam
).Added in version 3.3.
Distinto en la versión 3.9: Para mejorar la coherencia con las declaraciones de importación, aumente
ImportError
en lugar deValueError
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
, thensys.modules[name].__spec__
is returned (unless the spec would beNone
or is not set, in which caseValueError
is raised). Otherwise a search usingsys.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()
.Added in version 3.4.
Distinto en la versión 3.7: Lanza
ModuleNotFoundError
en lugar deAttributeError
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 retornaNone
, 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.Added in version 3.5.
- 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 comoInspectLoader.is_package()
, para completar cualquier información que falte en la especificación.Added in version 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.Added in version 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 incrustasource_hash()
del contenido del archivo fuente correspondiente en su encabezado.Added in version 3.7.
- importlib.util._incompatible_extension_module_restrictions(*, disable_check)¶
A context manager that can temporarily skip the compatibility check for extension modules. By default the check is enabled and will fail when a single-phase init module is imported in a subinterpreter. It will also fail for a multi-phase init module that doesn’t explicitly support a per-interpreter GIL, when imported in an interpreter with its own GIL.
Note that this function is meant to accommodate an unusual case; one which is likely to eventually go away. There’s is a pretty good chance this is not what you were looking for.
You can get the same effect as this function by implementing the basic interface of multi-phase init (PEP 489) and lying about support for multiple interpreters (or per-interpreter GIL).
Advertencia
Using this function to disable the check can lead to unexpected behavior and even crashes. It should only be used during extension module development.
Added in version 3.12.
- 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’screate_module()
method must returnNone
or a type for which its__class__
attribute can be mutated along with not using slots. Finally, modules which substitute the object placed intosys.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.
Added in version 3.5.
Distinto en la versión 3.6: Comenzó a llamar
create_module()
, eliminando la advertencia de compatibilidad paraimportlib.machinery.BuiltinImporter
yimportlib.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