`importlib` — Die Implementierung von `import`¶

Hinzugefügt in Version 3.1.

Quellcode: Lib/importlib/__init__.py

Einleitung¶

Der Zweck des Pakets importlib ist dreifach.

Erstens soll es die Implementierung der import-Anweisung (und damit, erweitert, die __import__()-Funktion) in Python-Quellcode bereitstellen. Dies liefert eine Implementierung von import, die auf jeden Python-Interpreter portierbar ist. Dies liefert auch eine Implementierung, die leichter zu verstehen ist als eine, die in einer anderen Programmiersprache als Python implementiert ist.

Zweitens werden die Komponenten zur Implementierung von import in diesem Paket freigelegt, wodurch es für Benutzer einfacher wird, ihre eigenen benutzerdefinierten Objekte (generisch als Importer bekannt) zu erstellen, die am Importprozess teilnehmen können.

Drittens enthält das Paket Module, die zusätzliche Funktionalität zum Verwalten von Aspekten von Python-Paketen bereitstellen.

importlib.metadata bietet Zugriff auf Metadaten von Drittanbieter-Distributionen.
importlib.resources bietet Routinen zum Zugreifen auf Nicht-Code-„Ressourcen“ aus Python-Paketen.

Siehe auch

Die Import-Anweisung: Die Sprachreferenz für die import-Anweisung.
Paketspezifikation: Ursprüngliche Spezifikation von Paketen. Einige Semantiken haben sich seit dem Schreiben dieses Dokuments geändert (z. B. Umleitungen basierend auf None in sys.modules).
Die Funktion __import__(): Die import-Anweisung ist syntaktischer Zucker für diese Funktion.
Die Initialisierung des Modul-Suchpfads sys.path: Die Initialisierung von sys.path.
PEP 235: Import auf plattformen mit nicht-fallbasierter Groß-/Kleinschreibung
PEP 263: Definition von Python-Quellcode-Kodierungen
PEP 302: Neue Import-Hooks
PEP 328: Imports: Mehrzeilig und Absolut/Relativ
PEP 366: Explizite relative Imports des Hauptmoduls
PEP 420: Implizite Namensraum-Pakete
PEP 451: Ein ModuleSpec-Typ für das Importsystem
PEP 488: Entfernung von PYO-Dateien
PEP 489: Mehrphasige Initialisierung von Erweiterungsmodulen
PEP 552: Deterministische pycs
PEP 3120: UTF-8 als Standard-Quellkodierung verwenden
PEP 3147: PYC-Repository-Verzeichnisse

Funktionen¶

importlib.__import__(name, globals=None, locals=None, fromlist=(), level=0)¶: Eine Implementierung der integrierten Funktion __import__().

Hinweis

Programmatisches Importieren von Modulen sollte import_module() anstelle dieser Funktion verwenden.

importlib.import_module(name, package=None)¶

Importiert ein Modul. Das Argument name gibt an, welches Modul absolut oder relativ importiert werden soll (z. B. entweder pkg.mod oder ..mod). Wenn der Name relativ angegeben ist, muss das Argument package auf den Namen des Pakets gesetzt werden, das als Anker für die Auflösung des Paketnamens dient (z. B. importiert import_module('..mod', 'pkg.subpkg') pkg.mod).

Die Funktion import_module() fungiert als vereinfachender Wrapper um importlib.__import__(). Das bedeutet, dass alle Semantiken der Funktion von importlib.__import__() abgeleitet werden. Der wichtigste Unterschied zwischen diesen beiden Funktionen ist, dass import_module() das angegebene Paket oder Modul (z. B. pkg.mod) zurückgibt, während __import__() das Top-Level-Paket oder Modul (z. B. pkg) zurückgibt.

Wenn Sie ein Modul dynamisch importieren, das seit Beginn der Ausführung des Interpreters erstellt wurde (z. B. eine Python-Quelldatei erstellt haben), müssen Sie möglicherweise invalidate_caches() aufrufen, damit das neue Modul vom Importssystem bemerkt wird.

Geändert in Version 3.3: Übergeordnete Pakete werden automatisch importiert.

importlib.invalidate_caches()¶: Invalidiert die internen Caches von Findern, die unter sys.meta_path gespeichert sind. Wenn ein Finder invalidate_caches() implementiert, wird er aufgerufen, um die Invalidierung durchzuführen. Diese Funktion sollte aufgerufen werden, wenn während der Ausführung Ihres Programms Module erstellt/installiert werden, um sicherzustellen, dass alle Finder die Existenz des neuen Moduls bemerken.

Hinzugefügt in Version 3.3.

Geändert in Version 3.10: Namensraum-Pakete, die nach dem bereits erfolgten Import desselben Namensraums an einem anderen sys.path-Ort erstellt/installiert werden, werden bemerkt.

importlib.reload(module)¶

Lädt ein zuvor importiertes Modul neu. Das Argument muss ein Modulobjekt sein, daher muss es zuvor erfolgreich importiert worden sein. Dies ist nützlich, wenn Sie die Modulquelldatei mit einem externen Editor bearbeitet haben und die neue Version ausprobieren möchten, ohne den Python-Interpreter zu verlassen. Der Rückgabewert ist das Modulobjekt (das sich unterscheiden kann, wenn ein erneuter Import dazu führt, dass ein anderes Objekt in sys.modules platziert wird).

Wenn reload() ausgeführt wird

Der Code eines Python-Moduls wird neu kompiliert und der Code auf Modulebene wird erneut ausgeführt, wobei ein neuer Satz von Objekten definiert wird, die mit Namen im Wörterbuch des Moduls durch Wiederverwendung des Loaders, der das Modul ursprünglich geladen hat, verbunden werden. Die init-Funktion von Erweiterungsmodulen wird nicht ein zweites Mal aufgerufen.
Wie bei allen anderen Objekten in Python werden die alten Objekte erst dann wieder freigegeben, wenn ihre Referenzzähler auf Null fallen.
Die Namen im Modulnamensraum werden aktualisiert, um auf neue oder geänderte Objekte zu verweisen.
Andere Referenzen auf die alten Objekte (wie externe Namen des Moduls) werden nicht an die neuen Objekte gebunden und müssen in jedem Namensraum, in dem sie auftreten, aktualisiert werden, wenn dies gewünscht wird.

Es gibt eine Reihe weiterer Vorbehalte

Wenn ein Modul neu geladen wird, wird sein Wörterbuch (das die globalen Variablen des Moduls enthält) beibehalten. Neudefinitionen von Namen überschreiben die alten Definitionen, daher ist dies im Allgemeinen kein Problem. Wenn die neue Version eines Moduls keinen Namen definiert, der von der alten Version definiert wurde, bleibt die alte Definition bestehen. Dieses Feature kann zum Vorteil des Moduls genutzt werden, wenn es eine globale Tabelle oder einen Cache von Objekten pflegt – mit einer try-Anweisung kann es auf die Existenz der Tabelle prüfen und deren Initialisierung überspringen, wenn gewünscht.

try:
    cache
except NameError:
    cache = {}

Das erneute Laden von integrierten oder dynamisch geladenen Modulen ist im Allgemeinen nicht sehr nützlich. Das erneute Laden von sys, __main__, builtins und anderen wichtigen Modulen wird nicht empfohlen. In vielen Fällen sind Erweiterungsmodule nicht dafür ausgelegt, mehr als einmal initialisiert zu werden, und können bei erneutem Laden auf beliebige Weise fehlschlagen.

Wenn ein Modul Objekte aus einem anderen Modul mit from ... import … importiert, definiert das erneute Laden des anderen Moduls die daraus importierten Objekte nicht neu – eine Möglichkeit, dies zu umgehen, ist die erneute Ausführung der from-Anweisung, eine andere ist die Verwendung von import und qualifizierten Namen (module.name) anstelle.

Wenn ein Modul Instanzen einer Klasse instanziiert, hat das erneute Laden des Moduls, das die Klasse definiert, keine Auswirkungen auf die Methodendefinitionen der Instanzen – sie verwenden weiterhin die alte Klassendefinition. Dasselbe gilt für abgeleitete Klassen.

Hinzugefügt in Version 3.4.

Geändert in Version 3.7: ModuleNotFoundError wird ausgelöst, wenn dem neu zu ladenden Modul ein ModuleSpec fehlt.

Warnung

Diese Funktion ist nicht threadsicher. Der Aufruf von mehreren Threads kann zu unerwartetem Verhalten führen. Es wird empfohlen, threading.Lock oder andere Synchronisationsprimitive für threadsicheres Modul-Neuladen zu verwenden.

`importlib.abc` – Abstrakte Basisklassen im Zusammenhang mit dem Import¶

Quellcode: Lib/importlib/abc.py

Das Modul importlib.abc enthält alle Kern-Abstrakten Basisklassen, die von import verwendet werden. Einige Unterklassen der Kern-Abstrakten Basisklassen werden ebenfalls bereitgestellt, um bei der Implementierung der Kern-ABCs zu helfen.

ABC-Hierarchie

object
 +-- MetaPathFinder
 +-- PathEntryFinder
 +-- Loader
      +-- ResourceLoader --------+
      +-- InspectLoader          |
           +-- ExecutionLoader --+
                                 +-- FileLoader
                                 +-- SourceLoader

class importlib.abc.MetaPathFinder¶

Eine abstrakte Basisklasse, die einen Meta-Path-Finder darstellt.

Hinzugefügt in Version 3.3.

Geändert in Version 3.10: Keine Unterklasse mehr von Finder.

find_spec(fullname, path, target=None)¶: Eine abstrakte Methode zum Finden eines Spec für das angegebene Modul. Wenn dies ein Top-Level-Import ist, ist path None. Andernfalls ist dies eine Suche nach einem Subpaket oder Modul und path ist der Wert von __path__ des übergeordneten Pakets. Wenn kein Spec gefunden werden kann, wird None zurückgegeben. Wenn es übergeben wird, ist target ein Modulobjekt, das der Finder verwenden kann, um eine fundiertere Vermutung darüber anzustellen, welchen Spec er zurückgeben soll. importlib.util.spec_from_loader() kann bei der Implementierung konkreter MetaPathFinders nützlich sein.

Hinzugefügt in Version 3.4.

invalidate_caches()¶: Eine optionale Methode, die bei Aufruf jeden internen Cache, der vom Finder verwendet wird, invalidieren sollte. Wird von importlib.invalidate_caches() beim Invalidieren der Caches aller Finder unter sys.meta_path verwendet.

Geändert in Version 3.4: Gibt None zurück, wenn sie aufgerufen wird, anstelle von NotImplemented.

class importlib.abc.PathEntryFinder¶

Eine abstrakte Basisklasse, die einen Pfad-Eintrag-Finder darstellt. Obwohl sie einige Ähnlichkeiten mit MetaPathFinder aufweist, ist PathEntryFinder nur für die Verwendung innerhalb des Pfad-basierten Import-Subsystems vorgesehen, das von importlib.machinery.PathFinder bereitgestellt wird.

Hinzugefügt in Version 3.3.

Geändert in Version 3.10: Keine Unterklasse mehr von Finder.

find_spec(fullname, target=None)¶: Eine abstrakte Methode zum Finden eines Spec für das angegebene Modul. Der Finder sucht das Modul nur innerhalb des Pfad-Eintrags, dem er zugeordnet ist. Wenn kein Spec gefunden werden kann, wird None zurückgegeben. Wenn es übergeben wird, ist target ein Modulobjekt, das der Finder verwenden kann, um eine fundiertere Vermutung darüber anzustellen, welchen Spec er zurückgeben soll. importlib.util.spec_from_loader() kann bei der Implementierung konkreter PathEntryFinders nützlich sein.

Hinzugefügt in Version 3.4.

invalidate_caches()¶: Eine optionale Methode, die bei Aufruf jeden internen Cache, der vom Finder verwendet wird, invalidieren sollte. Wird von importlib.machinery.PathFinder.invalidate_caches() beim Invalidieren der Caches aller gecachten Finder verwendet.

class importlib.abc.Loader¶

Eine abstrakte Basisklasse für einen Loader. Siehe PEP 302 für die genaue Definition eines Loaders.

Loader, die Ressourcenlesung unterstützen möchten, sollten eine Methode get_resource_reader() implementieren, wie von importlib.resources.abc.ResourceReader spezifiziert.

Geändert in Version 3.7: Einführung der optionalen Methode get_resource_reader().

create_module(spec)¶: Eine Methode, die das Modulobjekt zurückgibt, das beim Importieren eines Moduls verwendet werden soll. Diese Methode kann None zurückgeben, was bedeutet, dass die Standardsemantiken zur Modulerstellung angewendet werden sollen.

Hinzugefügt in Version 3.4.

Geändert in Version 3.6: Diese Methode ist nicht mehr optional, wenn exec_module() definiert ist.

exec_module(module)¶: Eine abstrakte Methode, die das Modul in seinem eigenen Namensraum ausführt, wenn ein Modul importiert oder neu geladen wird. Das Modul sollte beim Aufruf von exec_module() bereits initialisiert sein. Wenn diese Methode existiert, muss create_module() ebenfalls definiert sein.

Hinzugefügt in Version 3.4.

Geändert in Version 3.6: create_module() muss ebenfalls definiert sein.

load_module(fullname)¶

Eine Legacy-Methode zum Laden eines Moduls. Wenn das Modul nicht geladen werden kann, wird ImportError ausgelöst, andernfalls wird das geladene Modul zurückgegeben.

Wenn das angeforderte Modul bereits in sys.modules existiert, sollte dieses Modul verwendet und neu geladen werden. Andernfalls sollte der Loader ein neues Modul erstellen und es in sys.modules einfügen, bevor das Laden beginnt, um Rekursionen durch den Import zu verhindern. Wenn der Loader ein Modul eingefügt hat und das Laden fehlschlägt, muss es vom Loader aus sys.modules entfernt werden; Module, die bereits vor Beginn der Ausführung des Loaders in sys.modules waren, sollten unverändert bleiben.

Der Loader sollte mehrere Attribute für das Modul setzen (beachten Sie, dass einige dieser Attribute sich ändern können, wenn ein Modul neu geladen wird)

Wenn exec_module() verfügbar ist, wird abwärtskompatible Funktionalität bereitgestellt.

Geändert in Version 3.4: Wirft ImportError beim Aufruf anstelle von NotImplementedError. Funktionalität wird bereitgestellt, wenn exec_module() verfügbar ist.

Veraltet seit Version 3.4, wird in Version 3.15 entfernt: Die empfohlene API zum Laden eines Moduls ist exec_module() (und create_module()). Loader sollten diese anstelle von load_module() implementieren. Die Import-Maschinerie übernimmt alle anderen Verantwortlichkeiten von load_module(), wenn exec_module() implementiert ist.

class importlib.abc.ResourceLoader¶

Ersetzt durch TraversableResources

Eine abstrakte Basisklasse für einen Loader, der das optionale PEP 302-Protokoll für das Laden beliebiger Ressourcen aus dem Speicher-Backend implementiert.

Veraltet seit Version 3.7: Diese ABC ist zugunsten der Unterstützung des Ressourcenladens über importlib.resources.abc.TraversableResources veraltet. Diese Klasse existiert nur für Abwärtskompatibilität mit anderen ABCs in diesem Modul.

abstractmethod get_data(path)¶

Eine abstrakte Methode, um die Bytes für die Daten zurückzugeben, die sich unter path befinden. Loader, die ein dateiähnliches Speicher-Backend haben, das das Speichern beliebiger Daten ermöglicht, können diese abstrakte Methode implementieren, um direkten Zugriff auf die gespeicherten Daten zu gewähren. OSError muss ausgelöst werden, wenn der path nicht gefunden werden kann. Der path wird erwartet, dass er mit dem __file__-Attribut eines Moduls oder einem Element aus dem __path__ eines Pakets konstruiert wird.

Geändert in Version 3.4: Löst OSError anstelle von NotImplementedError aus.

class importlib.abc.InspectLoader¶

Eine abstrakte Basisklasse für einen loader, der das optionale PEP 302-Protokoll für Loader implementiert, die Module inspizieren.

get_code(fullname)¶: Gibt das Code-Objekt für ein Modul zurück, oder None, wenn das Modul kein Code-Objekt hat (wie es z.B. bei einem eingebauten Modul der Fall wäre). Löst einen ImportError aus, wenn der Loader das angeforderte Modul nicht finden kann.

Hinweis

Obwohl die Methode eine Standardimplementierung hat, wird empfohlen, sie nach Möglichkeit zur Leistungssteigerung zu überschreiben.

Geändert in Version 3.4: Nicht mehr abstrakt und eine konkrete Implementierung wird bereitgestellt.

abstractmethod get_source(fullname)¶: Eine abstrakte Methode, um den Quellcode eines Moduls zurückzugeben. Er wird als Textzeichenkette zurückgegeben, die universelle Zeilenumbrüche verwendet und alle erkannten Zeilentrenner in '\n'-Zeichen übersetzt. Gibt None zurück, wenn kein Quellcode verfügbar ist (z.B. bei einem eingebauten Modul). Löst ImportError aus, wenn der Loader das angegebene Modul nicht finden kann.

Geändert in Version 3.4: Löst ImportError anstelle von NotImplementedError aus.

is_package(fullname)¶: Eine optionale Methode, die einen wahren Wert zurückgibt, wenn das Modul ein Paket ist, andernfalls einen falschen Wert. ImportError wird ausgelöst, wenn der loader das Modul nicht finden kann.

Geändert in Version 3.4: Löst ImportError anstelle von NotImplementedError aus.

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

Erzeugt ein Code-Objekt aus Python-Quelltext.

Das Argument data kann alles sein, was die Funktion compile() unterstützt (d.h. Zeichenkette oder Bytes). Das Argument path sollte der "Pfad" sein, von dem der Quellcode stammt, was ein abstraktes Konzept sein kann (z.B. Speicherort in einer Zip-Datei).

Mit dem anschließenden Code-Objekt kann es in einem Modul ausgeführt werden, indem exec(code, module.__dict__) ausgeführt wird.

Hinzugefügt in Version 3.4.

Geändert in Version 3.5: Die Methode wurde statisch gemacht.

exec_module(module)¶: Implementierung von Loader.exec_module().

Hinzugefügt in Version 3.4.

load_module(fullname)¶: Implementierung von Loader.load_module().

Veraltet seit Version 3.4, wird in Version 3.15 entfernt: Verwenden Sie stattdessen exec_module().

class importlib.abc.ExecutionLoader¶

Eine abstrakte Basisklasse, die von InspectLoader erbt und, wenn sie implementiert wird, einem Modul hilft, als Skript ausgeführt zu werden. Die ABC stellt ein optionales PEP 302-Protokoll dar.

abstractmethod get_filename(fullname)¶: Eine abstrakte Methode, die den Wert von __file__ für das angegebene Modul zurückgeben soll. Wenn kein Pfad verfügbar ist, wird ImportError ausgelöst.

Wenn Quellcode verfügbar ist, sollte die Methode den Pfad zur Quelldatei zurückgeben, unabhängig davon, ob Bytecode zum Laden des Moduls verwendet wurde.

Geändert in Version 3.4: Löst ImportError anstelle von NotImplementedError aus.

class importlib.abc.FileLoader(fullname, path)¶

Eine abstrakte Basisklasse, die von ResourceLoader und ExecutionLoader erbt und konkrete Implementierungen von ResourceLoader.get_data() und ExecutionLoader.get_filename() bereitstellt.

Das Argument fullname ist der vollständig aufgelöste Name des Moduls, das der Loader behandeln soll. Das Argument path ist der Pfad zur Datei für das Modul.

Hinzugefügt in Version 3.3.

name¶: Der Name des Moduls, das der Loader behandeln kann.

path¶: Pfad zur Datei des Moduls.

load_module(fullname)¶: Ruft die load_module() des Super-Objekts auf.

Veraltet seit Version 3.4, wird in Version 3.15 entfernt: Verwenden Sie stattdessen Loader.exec_module().

abstractmethod get_filename(fullname)¶: Gibt path zurück.

abstractmethod get_data(path)¶: Liest path als Binärdatei und gibt die Bytes daraus zurück.

class importlib.abc.SourceLoader¶

Eine abstrakte Basisklasse zur Implementierung des Ladens von Quellcode- (und optional Bytecode-) Dateien. Die Klasse erbt sowohl von ResourceLoader als auch von ExecutionLoader und erfordert die Implementierung von

ResourceLoader.get_data()
ExecutionLoader.get_filename()
Sollte nur den Pfad zur Quelldatei zurückgeben; Quellcodefreies Laden wird nicht unterstützt.

Die von dieser Klasse definierten abstrakten Methoden dienen zur Unterstützung der optionalen Bytecode-Datei-Unterstützung. Wenn diese optionalen Methoden nicht implementiert werden (oder dazu gebracht werden, NotImplementedError auszulösen), funktioniert der Loader nur mit Quellcode. Die Implementierung der Methoden ermöglicht dem Loader die Arbeit mit Quellcode- *und* Bytecode-Dateien; sie erlaubt kein *quellfreies* Laden, bei dem nur Bytecode bereitgestellt wird. Bytecode-Dateien sind eine Optimierung zur Beschleunigung des Ladens, indem der Parsingschritt des Python-Compilers entfernt wird, und daher wird keine Bytecode-spezifische API verfügbar gemacht.

path_stats(path)¶

Optionale abstrakte Methode, die ein dict mit Metadaten zum angegebenen Pfad zurückgibt. Unterstützte Wörterbuchschlüssel sind

'mtime' (obligatorisch): eine ganze Zahl oder Gleitkommazahl, die die Änderungszeit des Quellcodes darstellt;
'size' (optional): die Größe des Quellcodes in Bytes.

Alle anderen Schlüssel im Wörterbuch werden ignoriert, um zukünftige Erweiterungen zu ermöglichen. Wenn der Pfad nicht behandelt werden kann, wird OSError ausgelöst.

Hinzugefügt in Version 3.3.

Geändert in Version 3.4: Löst OSError anstelle von NotImplementedError aus.

path_mtime(path)¶: Optionale abstrakte Methode, die die Änderungszeit für den angegebenen Pfad zurückgibt.

Veraltet seit Version 3.3: Diese Methode ist zugunsten von path_stats() veraltet. Sie müssen sie nicht implementieren, aber sie ist noch zur Kompatibilität verfügbar. Lösen Sie OSError aus, wenn der Pfad nicht behandelt werden kann.

Geändert in Version 3.4: Löst OSError anstelle von NotImplementedError aus.

set_data(path, data)¶

Optionale abstrakte Methode, die die angegebenen Bytes in einen Dateipfad schreibt. Alle nicht vorhandenen Zwischenverzeichnisse müssen automatisch erstellt werden.

Beim Schreiben auf den Pfad, wenn dies fehlschlägt, weil der Pfad schreibgeschützt ist (errno.EACCES/PermissionError), darf die Ausnahme nicht weitergegeben werden.

Geändert in Version 3.4: Löst beim Aufruf keine NotImplementedError mehr aus.

get_code(fullname)¶: Konkrete Implementierung von InspectLoader.get_code().

exec_module(module)¶: Konkrete Implementierung von Loader.exec_module().

Hinzugefügt in Version 3.4.

load_module(fullname)¶: Konkrete Implementierung von Loader.load_module().

Veraltet seit Version 3.4, wird in Version 3.15 entfernt: Verwenden Sie stattdessen exec_module().

get_source(fullname)¶: Konkrete Implementierung von InspectLoader.get_source().

is_package(fullname)¶: Konkrete Implementierung von InspectLoader.is_package(). Ein Modul wird als Paket bestimmt, wenn sein Dateipfad (wie von ExecutionLoader.get_filename() bereitgestellt) eine Datei namens __init__ ist, wenn die Dateierweiterung entfernt wird, *und* der Modulname selbst nicht auf __init__ endet.

class importlib.abc.ResourceReader¶

Ersetzt durch TraversableResources

Eine abstrakte Basisklasse, um die Möglichkeit des Lesens von Ressourcen bereitzustellen.

Aus Sicht dieser ABC ist eine Ressource ein binäres Artefakt, das innerhalb eines Pakets mitgeliefert wird. Typischerweise handelt es sich dabei um etwas wie eine Datendatei, die sich neben der __init__.py-Datei des Pakets befindet. Der Zweck dieser Klasse ist es, den Zugriff auf solche Datendateien zu abstrahieren, damit es keine Rolle spielt, ob das Paket und seine Datendatei(en) z.B. in einer Zip-Datei oder auf dem Dateisystem gespeichert sind.

Für jede Methode dieser Klasse wird erwartet, dass ein resource-Argument ein pfadähnliches Objekt ist, das konzeptionell nur einen Dateinamen darstellt. Das bedeutet, dass keine Unterverzeichnispfade im resource-Argument enthalten sein sollten. Das liegt daran, dass der Speicherort des Pakets, für das der Reader zuständig ist, als "Verzeichnis" fungiert. Daher ist die Metapher für Verzeichnisse und Dateinamen Pakete und Ressourcen. Dies ist auch der Grund, warum Instanzen dieser Klasse direkt mit einem bestimmten Paket korreliert werden sollen (anstatt potenziell mehrere Pakete oder ein Modul darzustellen).

Loader, die das Lesen von Ressourcen unterstützen möchten, sollen eine Methode namens get_resource_reader(fullname) bereitstellen, die ein Objekt zurückgibt, das die Schnittstelle dieser ABC implementiert. Wenn das durch fullname angegebene Modul kein Paket ist, sollte diese Methode None zurückgeben. Ein mit dieser ABC kompatibles Objekt sollte nur zurückgegeben werden, wenn das angegebene Modul ein Paket ist.

Hinzugefügt in Version 3.7.

Veraltet seit Version 3.12, entfernt in Version 3.14: Verwenden Sie stattdessen importlib.resources.abc.TraversableResources.

abstractmethod open_resource(resource)¶: Gibt ein geöffnetes, dateiähnliches Objekt für das Binärlesen der Ressource zurück.

Wenn die Ressource nicht gefunden werden kann, wird FileNotFoundError ausgelöst.

abstractmethod resource_path(resource)¶: Gibt den Dateisystempfad zur Ressource zurück.

Wenn die Ressource nicht konkret auf dem Dateisystem existiert, lösen Sie FileNotFoundError aus.

abstractmethod is_resource(name)¶: Gibt True zurück, wenn der benannte name als Ressource betrachtet wird. FileNotFoundError wird ausgelöst, wenn name nicht existiert.

abstractmethod contents()¶: Gibt ein Iterable von Zeichenketten über den Inhalt des Pakets zurück. Beachten Sie, dass es nicht erforderlich ist, dass alle vom Iterator zurückgegebenen Namen tatsächliche Ressourcen sind. Es ist beispielsweise akzeptabel, Namen zurückzugeben, für die is_resource() falsch wäre.

Das Zurückgeben von Nicht-Ressourcen-Namen ist zulässig, um Situationen zu ermöglichen, in denen bekannt ist, wie ein Paket und seine Ressourcen gespeichert sind, und die Nicht-Ressourcen-Namen nützlich wären. Beispielsweise ist das Zurückgeben von Unterverzeichnisnamen zulässig, damit, wenn bekannt ist, dass das Paket und die Ressourcen auf dem Dateisystem gespeichert sind, diese Unterverzeichnisnamen direkt verwendet werden können.

Die abstrakte Methode gibt ein Iterable von keinen Elementen zurück.

class importlib.abc.Traversable¶

Ein Objekt mit einer Teilmenge von pathlib.Path-Methoden, die für die Traversierung von Verzeichnissen und das Öffnen von Dateien geeignet sind.

Für eine Darstellung des Objekts auf dem Dateisystem verwenden Sie importlib.resources.as_file().

Hinzugefügt in Version 3.9.

Veraltet seit Version 3.12, entfernt in Version 3.14: Verwenden Sie stattdessen importlib.resources.abc.Traversable.

name¶: Abstrakt. Der Basisname dieses Objekts ohne übergeordnete Verweise.

abstractmethod iterdir()¶: Gibt Traversable-Objekte in self zurück.

abstractmethod is_dir()¶: Gibt True zurück, wenn self ein Verzeichnis ist.

abstractmethod is_file()¶: Gibt True zurück, wenn self eine Datei ist.

abstractmethod joinpath(child)¶: Gibt das Traversable-Kind in self zurück.

abstractmethod __truediv__(child)¶: Gibt das Traversable-Kind in self zurück.

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

mode kann 'r' oder 'rb' sein, um als Text oder Binärdatei zu öffnen. Gibt ein Handle zurück, das zum Lesen geeignet ist (wie bei pathlib.Path.open).

Beim Öffnen als Text werden Kodierungsparameter akzeptiert, wie sie von io.TextIOWrapper akzeptiert werden.

read_bytes()¶: Liest den Inhalt von self als Bytes.

read_text(encoding=None)¶: Liest den Inhalt von self als Text.

class importlib.abc.TraversableResources¶

Eine abstrakte Basisklasse für Ressourcennleser, die die importlib.resources.files()-Schnittstelle bedienen können. Unterklassen von importlib.resources.abc.ResourceReader und stellen konkrete Implementierungen der abstrakten Methoden von importlib.resources.abc.ResourceReader bereit. Daher stellt jeder Loader, der importlib.abc.TraversableResources bereitstellt, auch ResourceReader bereit.

Loader, die das Lesen von Ressourcen unterstützen möchten, sollen diese Schnittstelle implementieren.

Hinzugefügt in Version 3.9.

Veraltet seit Version 3.12, entfernt in Version 3.14: Verwenden Sie stattdessen importlib.resources.abc.TraversableResources.

abstractmethod files()¶: Gibt ein importlib.resources.abc.Traversable-Objekt für das geladene Paket zurück.

`importlib.machinery` – Importer und Pfadhaken¶

Quellcode: Lib/importlib/machinery.py

Dieses Modul enthält die verschiedenen Objekte, die import beim Finden und Laden von Modulen helfen.

importlib.machinery.SOURCE_SUFFIXES¶: Eine Liste von Zeichenketten, die die erkannten Dateisuffixe für Quellmodule darstellen.

Hinzugefügt in Version 3.3.

importlib.machinery.DEBUG_BYTECODE_SUFFIXES¶: Eine Liste von Zeichenketten, die die Dateisuffixe für nicht optimierte Bytecodemodule darstellen.

Hinzugefügt in Version 3.3.

Veraltet seit Version 3.5: Verwenden Sie stattdessen BYTECODE_SUFFIXES.

importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES¶: Eine Liste von Zeichenketten, die die Dateisuffixe für optimierte Bytecodemodule darstellen.

Hinzugefügt in Version 3.3.

Veraltet seit Version 3.5: Verwenden Sie stattdessen BYTECODE_SUFFIXES.

importlib.machinery.BYTECODE_SUFFIXES¶: Eine Liste von Zeichenketten, die die erkannten Dateisuffixe für Bytecodemodule darstellen (einschließlich des führenden Punkts).

Hinzugefügt in Version 3.3.

Geändert in Version 3.5: Der Wert ist nicht mehr abhängig von __debug__.

importlib.machinery.EXTENSION_SUFFIXES¶: Eine Liste von Zeichenketten, die die erkannten Dateisuffixe für Erweiterungsmodule darstellen.

Hinzugefügt in Version 3.3.

importlib.machinery.all_suffixes()¶: Gibt eine kombinierte Liste von Zeichenketten zurück, die alle Dateiendungen für Module darstellen, die von der Standard-Importmaschine erkannt werden. Dies ist eine Hilfe für Code, der einfach nur wissen muss, ob ein Dateisystempfad potenziell auf ein Modul verweist, ohne Details über die Art des Moduls zu benötigen (z. B. für inspect.getmodulename()).

Hinzugefügt in Version 3.3.

class importlib.machinery.BuiltinImporter¶

Ein Importer für eingebaute Module. Alle bekannten eingebauten Module sind in sys.builtin_module_names aufgeführt. Diese Klasse implementiert die ABCs importlib.abc.MetaPathFinder und importlib.abc.InspectLoader.

Nur Klassenmethoden werden von dieser Klasse definiert, um die Notwendigkeit der Instanziierung zu vermeiden.

Geändert in Version 3.5: Als Teil von PEP 489 implementiert der eingebaute Importer nun Loader.create_module() und Loader.exec_module()

class importlib.machinery.FrozenImporter¶

Ein Importer für gefrorene Module. Diese Klasse implementiert die ABCs importlib.abc.MetaPathFinder und importlib.abc.InspectLoader.

Nur Klassenmethoden werden von dieser Klasse definiert, um die Notwendigkeit der Instanziierung zu vermeiden.

Geändert in Version 3.4: Methoden create_module() und exec_module() hinzugefügt.

class importlib.machinery.WindowsRegistryFinder¶

Ein Finder für Module, die in der Windows-Registrierung deklariert sind. Diese Klasse implementiert die ABC importlib.abc.MetaPathFinder.

Nur Klassenmethoden werden von dieser Klasse definiert, um die Notwendigkeit der Instanziierung zu vermeiden.

Hinzugefügt in Version 3.3.

Veraltet seit Version 3.6: Verwenden Sie stattdessen die Konfiguration von site. Zukünftige Versionen von Python werden diesen Finder möglicherweise nicht mehr standardmäßig aktivieren.

class importlib.machinery.PathFinder¶

Ein Finder für sys.path und Paket-Attribute __path__. Diese Klasse implementiert die ABC importlib.abc.MetaPathFinder.

Nur Klassenmethoden werden von dieser Klasse definiert, um die Notwendigkeit der Instanziierung zu vermeiden.

classmethod find_spec(fullname, path=None, target=None)¶: Klassenmethode, die versucht, ein Spec für das durch *fullname* angegebene Modul in sys.path oder, falls definiert, in *path* zu finden. Für jeden durchsuchten Pfadeintrag wird sys.path_importer_cache überprüft. Wenn ein nicht-falsches Objekt gefunden wird, wird es als Pfad-Eintrags-Finder verwendet, um nach dem gesuchten Modul zu suchen. Wenn kein Eintrag in sys.path_importer_cache gefunden wird, wird sys.path_hooks nach einem Finder für den Pfadeintrag durchsucht. Wenn einer gefunden wird, wird er zusammen mit der Abfrage nach dem Modul in sys.path_importer_cache gespeichert. Wenn nie ein Finder gefunden wird, wird None sowohl im Cache gespeichert als auch zurückgegeben.

Hinzugefügt in Version 3.4.

Geändert in Version 3.5: Wenn das aktuelle Arbeitsverzeichnis – dargestellt durch einen leeren String – nicht mehr gültig ist, wird None zurückgegeben, aber kein Wert in sys.path_importer_cache gespeichert.

classmethod invalidate_caches()¶: Ruft importlib.abc.PathEntryFinder.invalidate_caches() für alle in sys.path_importer_cache gespeicherten Finder auf, die die Methode definieren. Andernfalls werden Einträge in sys.path_importer_cache, die auf None gesetzt sind, gelöscht.

Geändert in Version 3.7: Einträge von None in sys.path_importer_cache werden gelöscht.

Geändert in Version 3.4: Ruft Objekte in sys.path_hooks mit dem aktuellen Arbeitsverzeichnis für '' (d.h. dem leeren String) auf.

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

Eine konkrete Implementierung von importlib.abc.PathEntryFinder, die Ergebnisse vom Dateisystem zwischenspeichert.

Das Argument *path* ist das Verzeichnis, für das der Finder zuständig ist.

Das Argument *loader_details* ist eine variable Anzahl von 2-Element-Tupeln, die jeweils einen Loader und eine Liste von Dateiendungen enthalten, die der Loader erkennt. Die Loader sollen aufrufbare Objekte sein, die zwei Argumente akzeptieren: den Namen des Moduls und den Pfad zur gefundenen Datei.

Der Finder speichert den Verzeichnisinhalt bei Bedarf zwischen und führt stat-Aufrufe für jede Modulsuchung durch, um zu überprüfen, ob der Cache nicht veraltet ist. Da die Veralterung des Caches von der Granularität der Zustandsinformationen des Betriebssystems über das Dateisystem abhängt, besteht eine potenzielle Race Condition beim Suchen eines Moduls, Erstellen einer neuen Datei und dann Suchen des Moduls, das die neue Datei darstellt. Wenn die Operationen schnell genug stattfinden, um innerhalb der Granularität von stat-Aufrufen zu passen, schlägt die Modulsuchung fehl. Um dies zu verhindern, sollten Sie beim dynamischen Erstellen eines Moduls importlib.invalidate_caches() aufrufen.

Hinzugefügt in Version 3.3.

path¶: Der Pfad, in dem der Finder sucht.

find_spec(fullname, target=None)¶: Versucht, den Spec zu finden, der *fullname* innerhalb von path behandelt.

Hinzugefügt in Version 3.4.

invalidate_caches()¶: Löscht den internen Cache.

classmethod path_hook(*loader_details)¶

Eine Klassenmethode, die einen Closure zurückgibt, der für sys.path_hooks verwendet wird. Eine Instanz von FileFinder wird vom Closure zurückgegeben, wobei das Pfad-Argument, das an das Closure übergeben wird, direkt und *loader_details* indirekt verwendet werden.

Wenn das Argument des Closures kein vorhandenes Verzeichnis ist, wird ImportError ausgelöst.

class importlib.machinery.SourceFileLoader(fullname, path)¶

Eine konkrete Implementierung von importlib.abc.SourceLoader durch Unterklassenbildung von importlib.abc.FileLoader und Bereitstellung einiger konkreter Implementierungen anderer Methoden.

Hinzugefügt in Version 3.3.

name¶: Der Name des Moduls, das dieser Loader verarbeiten wird.

path¶: Der Pfad zur Quelldatei.

is_package(fullname)¶: Gibt True zurück, wenn path einem Paket zu entsprechen scheint.

path_stats(path)¶: Konkrete Implementierung von importlib.abc.SourceLoader.path_stats().

set_data(path, data)¶: Konkrete Implementierung von importlib.abc.SourceLoader.set_data().

load_module(name=None)¶: Konkrete Implementierung von importlib.abc.Loader.load_module(), bei der die Angabe des zu ladenden Modulnamens optional ist.

Veraltet seit Version 3.6, wird in Version 3.15 entfernt: Verwenden Sie stattdessen importlib.abc.Loader.exec_module().

class importlib.machinery.SourcelessFileLoader(fullname, path)¶

Eine konkrete Implementierung von importlib.abc.FileLoader, die Bytecode-Dateien (d.h. keine Quellcodedateien) importieren kann.

Bitte beachten Sie, dass die direkte Verwendung von Bytecode-Dateien (und damit nicht von Quellcodedateien) Ihre Module für alle Python-Implementierungen oder neue Python-Versionen, die das Bytecode-Format ändern, unbrauchbar macht.

Hinzugefügt in Version 3.3.

name¶: Der Name des Moduls, das der Loader verarbeiten wird.

path¶: Der Pfad zur Bytecode-Datei.

is_package(fullname)¶: Bestimmt, ob das Modul ein Paket ist, basierend auf path.

get_code(fullname)¶: Gibt das Code-Objekt für *name* zurück, das aus *path* erstellt wurde.

get_source(fullname)¶: Gibt None zurück, da Bytecode-Dateien bei Verwendung dieses Loaders keine Quelltexte haben.

load_module(name=None)¶

Konkrete Implementierung von importlib.abc.Loader.load_module(), bei der die Angabe des zu ladenden Modulnamens optional ist.

Veraltet seit Version 3.6, wird in Version 3.15 entfernt: Verwenden Sie stattdessen importlib.abc.Loader.exec_module().

class importlib.machinery.ExtensionFileLoader(fullname, path)¶

Eine konkrete Implementierung von importlib.abc.ExecutionLoader für Erweiterungsmodule.

Das Argument *fullname* gibt den Namen des Moduls an, das der Loader unterstützen soll. Das Argument *path* ist der Pfad zur Datei des Erweiterungsmoduls.

Beachten Sie, dass das Importieren eines Erweiterungsmoduls in Subinterpretern standardmäßig fehlschlägt, wenn es keine Multi-Phase-Initialisierung implementiert (siehe PEP 489), auch wenn es sonst erfolgreich importiert würde.

Hinzugefügt in Version 3.3.

Geändert in Version 3.12: Multi-Phase-Initialisierung ist jetzt für die Verwendung in Subinterpretern erforderlich.

name¶: Name des Moduls, das der Loader unterstützt.

path¶: Pfad zum Erweiterungsmodul.

create_module(spec)¶: Erstellt das Modulobjekt aus der gegebenen Spezifikation gemäß PEP 489.

Hinzugefügt in Version 3.5.

exec_module(module)¶: Initialisiert das gegebene Modulobjekt gemäß PEP 489.

Hinzugefügt in Version 3.5.

is_package(fullname)¶: Gibt True zurück, wenn der Dateipfad auf das __init__ Modul eines Pakets verweist, basierend auf EXTENSION_SUFFIXES.

get_code(fullname)¶: Gibt None zurück, da Erweiterungsmodule kein Code-Objekt haben.

get_source(fullname)¶: Gibt None zurück, da Erweiterungsmodule keinen Quellcode haben.

get_filename(fullname)¶: Gibt path zurück.

Hinzugefügt in Version 3.4.

class importlib.machinery.NamespaceLoader(name, path, path_finder)¶

Eine konkrete Implementierung von importlib.abc.InspectLoader für Namespace-Pakete. Dies ist ein Alias für eine private Klasse und wird nur zur Introspektion des Attributs __loader__ bei Namespace-Paketen öffentlich gemacht.

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

Hinzugefügt in Version 3.11.

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

Eine Spezifikation für den Import-System-bezogenen Zustand eines Moduls. Dies wird typischerweise als Attribut __spec__ des Moduls bereitgestellt. Viele dieser Attribute sind auch direkt auf einem Modul verfügbar: zum Beispiel ist module.__spec__.origin == module.__file__. Beachten Sie jedoch, dass, obwohl die *Werte* normalerweise äquivalent sind, sie unterschiedlich sein können, da es keine Synchronisation zwischen den beiden Objekten gibt. Es ist beispielsweise möglich, das Attribut __file__ des Moduls zur Laufzeit zu ändern, und dies wird sich nicht automatisch im Attribut __spec__.origin des Moduls widerspiegeln, und umgekehrt.

Hinzugefügt in Version 3.4.

name¶: Der vollständig qualifizierte Name des Moduls (siehe module.__name__). Der Finder sollte dieses Attribut immer auf einen nicht-leeren String setzen.

loader¶: Der Loader, der zum Laden des Moduls verwendet wird (siehe module.__loader__). Der Finder sollte dieses Attribut immer setzen.

origin¶: Der Ort, den der Loader zum Laden des Moduls verwenden sollte (siehe module.__file__). Zum Beispiel ist dies für aus einer .py-Datei geladene Module der Dateiname. Der Finder sollte dieses Attribut immer auf einen aussagekräftigen Wert für den Loader setzen. In dem seltenen Fall, dass es keinen gibt (wie bei Namespace-Paketen), sollte er auf None gesetzt werden.

submodule_search_locations¶

Eine (möglicherweise leere) Sequenz von Zeichenketten, die die Orte auflistet, an denen die Untermodule eines Pakets gefunden werden (siehe module.__path__). Meistens wird nur ein Verzeichnis in dieser Liste sein.

Der Finder sollte dieses Attribut auf eine Sequenz setzen, auch eine leere, um dem Importsystem anzuzeigen, dass das Modul ein Paket ist. Für Nicht-Paket-Module sollte es auf None gesetzt werden. Für Namespace-Pakete wird es später automatisch auf ein spezielles Objekt gesetzt.

loader_state¶: Der Finder kann dieses Attribut auf ein Objekt setzen, das zusätzliche, modulspezifische Daten zur Verwendung beim Laden des Moduls enthält. Andernfalls sollte es auf None gesetzt werden.

cached¶: Der Dateiname einer kompilierten Version des Modulcodes (siehe module.__cached__). Der Finder sollte dieses Attribut immer setzen, es kann jedoch None für Module sein, bei denen kein kompilierter Code gespeichert werden muss.

parent¶: (Schreibgeschützt) Der vollständig qualifizierte Name des Pakets, in dem sich das Modul befindet (oder der leere String für ein Top-Level-Modul). Siehe module.__package__. Wenn das Modul ein Paket ist, ist dies dasselbe wie name.

has_location¶: True, wenn der Spec-Attribut origin auf einen ladbaren Speicherort verweist, andernfalls False. Dieser Wert beeinflusst, wie origin interpretiert wird und wie das Attribut __file__ des Moduls gefüllt wird.

class importlib.machinery.AppleFrameworkLoader(name, path)¶

Eine Spezialisierung von importlib.machinery.ExtensionFileLoader, die Erweiterungsmodule im Framework-Format laden kann.

Zur Kompatibilität mit dem iOS App Store müssen *alle* Binärmodule in einer iOS-App dynamische Bibliotheken sein, die in einem Framework mit entsprechenden Metadaten enthalten sind und im Ordner Frameworks der gepackten App gespeichert sind. Es kann nur ein Binärmodul pro Framework geben, und außerhalb des Ordners Frameworks dürfen sich keine ausführbaren Binärmaterialien befinden.

Um diese Anforderung zu erfüllen, werden bei der Ausführung unter iOS Erweiterungsmodulbinärdateien nicht als .so-Dateien auf sys.path verpackt, sondern als einzelne, eigenständige Frameworks. Um diese Frameworks zu finden, wird dieser Loader für die Dateiendung .fwork registriert, wobei eine .fwork-Datei als Platzhalter an der ursprünglichen Position der Binärdatei auf sys.path dient. Die .fwork-Datei enthält den Pfad zur tatsächlichen Binärdatei im Ordner Frameworks, relativ zum App-Bundle. Um die Auflösung einer Framework-verpackten Binärdatei zurück zur ursprünglichen Position zu ermöglichen, wird erwartet, dass das Framework eine .origin-Datei enthält, die den Pfad zur .fwork-Datei enthält, relativ zum App-Bundle.

Betrachten wir zum Beispiel den Fall eines Imports from foo.bar import _whiz, wobei _whiz mit dem Binärmodul sources/foo/bar/_whiz.abi3.so implementiert ist, wobei sources der auf sys.path registrierte Pfad ist, relativ zum Anwendungsbundle. Dieses Modul muss als Frameworks/foo.bar._whiz.framework/foo.bar._whiz verteilt werden (wobei der Framework-Name aus dem vollständigen Importpfad des Moduls gebildet wird), mit einer Info.plist-Datei im Verzeichnis .framework, die die Binärdatei als Framework identifiziert. Das Modul foo.bar._whiz würde an der ursprünglichen Position mit einer sources/foo/bar/_whiz.abi3.fwork-Markierungsdatei repräsentiert werden, die den Pfad Frameworks/foo.bar._whiz/foo.bar._whiz enthält. Das Framework würde auch Frameworks/foo.bar._whiz.framework/foo.bar._whiz.origin enthalten, das den Pfad zur .fwork-Datei enthält.

Wenn ein Modul mit diesem Loader geladen wird, meldet __file__ für das Modul den Speicherort der .fwork-Datei. Dies ermöglicht es dem Code, __file__ eines Moduls als Anker für die Dateisystemtraversierung zu verwenden. Der Spec-Ursprung verweist jedoch auf den Speicherort der tatsächlichen Binärdatei im Ordner .framework.

Das Xcode-Projekt, das die App erstellt, ist dafür verantwortlich, alle .so-Dateien, wo auch immer sie sich im PYTHONPATH befinden, in Frameworks im Ordner Frameworks umzuwandeln (einschließlich des Entfernens von Erweiterungen aus der Moduldatei, der Hinzufügung von Framework-Metadaten und der Signierung des resultierenden Frameworks) und die .fwork- und .origin-Dateien zu erstellen. Dies geschieht normalerweise mit einem Build-Schritt im Xcode-Projekt; siehe die iOS-Dokumentation für Details, wie dieser Build-Schritt konstruiert wird.

Hinzugefügt in Version 3.13.

Verfügbarkeit: iOS.

name¶: Name des Moduls, das der Loader unterstützt.

path¶: Pfad zur .fwork-Datei für das Erweiterungsmodul.

`importlib.util` – Hilfscode für Importer¶

Quellcode: Lib/importlib/util.py

Dieses Modul enthält die verschiedenen Objekte, die beim Erstellen eines Importers helfen.

importlib.util.MAGIC_NUMBER¶: Die Bytes, die die Bytecode-Versionsnummer darstellen. Wenn Sie Hilfe beim Laden/Schreiben von Bytecode benötigen, sollten Sie importlib.abc.SourceLoader in Betracht ziehen.

Hinzugefügt in Version 3.4.

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

Gibt den Pfad gemäß PEP 3147/PEP 488 zur Bytecode-Datei zurück, die mit dem Quellcode-Pfad assoziiert ist. Wenn path beispielsweise /foo/bar/baz.py ist, wäre der Rückgabewert /foo/bar/__pycache__/baz.cpython-32.pyc für Python 3.2. Der String cpython-32 stammt vom aktuellen Magic-Tag (siehe get_tag(); wenn sys.implementation.cache_tag nicht definiert ist, wird NotImplementedError ausgelöst).

Der Parameter optimization wird verwendet, um das Optimierungslevel der Bytecode-Datei anzugeben. Ein leerer String bedeutet keine Optimierung, sodass /foo/bar/baz.py mit einer optimization von '' zu einem Bytecode-Pfad von /foo/bar/__pycache__/baz.cpython-32.pyc führt. None bewirkt, dass das Optimierungslevel des Interpreters verwendet wird. Bei jedem anderen Wert wird seine String-Repräsentation verwendet. /foo/bar/baz.py mit einer optimization von 2 führt zum Bytecode-Pfad /foo/bar/__pycache__/baz.cpython-32.opt-2.pyc. Die String-Repräsentation von optimization darf nur alphanumerisch sein, andernfalls wird ValueError ausgelöst.

Der Parameter debug_override ist veraltet und kann verwendet werden, um den Wert des Systems für __debug__ zu überschreiben. Ein Wert von True entspricht der Einstellung von optimization auf den leeren String. Ein Wert von False entspricht der Einstellung von optimization auf 1. Wenn sowohl debug_override als auch optimization nicht None sind, wird TypeError ausgelöst.

Hinzugefügt in Version 3.4.

Geändert in Version 3.5: Der Parameter optimization wurde hinzugefügt und der Parameter debug_override wurde als veraltet markiert.

Geändert in Version 3.6: Akzeptiert ein pfadähnliches Objekt.

importlib.util.source_from_cache(path)¶: Gegeben den Pfad zu einem Dateinamen gemäß PEP 3147, wird der zugehörige Pfad zur Quellcodedatei zurückgegeben. Wenn path beispielsweise /foo/bar/__pycache__/baz.cpython-32.pyc ist, wäre der zurückgegebene Pfad /foo/bar/baz.py. path muss nicht existieren. Wenn er jedoch nicht dem Format von PEP 3147 oder PEP 488 entspricht, wird ValueError ausgelöst. Wenn sys.implementation.cache_tag nicht definiert ist, wird NotImplementedError ausgelöst.

Hinzugefügt in Version 3.4.

Geändert in Version 3.6: Akzeptiert ein pfadähnliches Objekt.

importlib.util.decode_source(source_bytes)¶: Dekodiert die gegebenen Bytes, die Quellcode darstellen, und gibt sie als String mit universellen Zeilenumbrüchen zurück (wie von importlib.abc.InspectLoader.get_source() gefordert).

Hinzugefügt in Version 3.4.

importlib.util.resolve_name(name, package)¶

Löst einen relativen Modulnamen in einen absoluten auf.

Wenn name keine führenden Punkte hat, wird name einfach zurückgegeben. Dies ermöglicht die Verwendung von z.B. importlib.util.resolve_name('sys', __spec__.parent) ohne eine Überprüfung, ob das Argument package benötigt wird.

ImportError wird ausgelöst, wenn name ein relativer Modulname ist, package aber ein falscher Wert ist (z.B. None oder ein leerer String). ImportError wird ebenfalls ausgelöst, wenn ein relativer Name sein enthaltendes Paket verlassen würde (z.B. Anforderung von ..bacon aus dem Paket spam).

Hinzugefügt in Version 3.3.

Geändert in Version 3.9: Um die Konsistenz mit Importanweisungen zu verbessern, wird ImportError anstelle von ValueError für ungültige relative Importversuche ausgelöst.

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

Findet die spec für ein Modul, optional relativ zum angegebenen Paketnamen package. Wenn sich das Modul in sys.modules befindet, wird sys.modules[name].__spec__ zurückgegeben (es sei denn, die spec wäre None oder nicht gesetzt, in welchem Fall ValueError ausgelöst wird). Andernfalls wird eine Suche über sys.meta_path durchgeführt. None wird zurückgegeben, wenn keine spec gefunden wird.

Wenn name für ein Untermodul (enthält einen Punkt) ist, wird das Elternmodul automatisch importiert.

name und package funktionieren genauso wie für import_module().

Hinzugefügt in Version 3.4.

Geändert in Version 3.7: Löst ModuleNotFoundError anstelle von AttributeError aus, wenn package tatsächlich kein Paket ist (d.h. keine __path__-Attribut hat).

importlib.util.module_from_spec(spec)¶

Erstellt ein neues Modul basierend auf spec und spec.loader.create_module.

Wenn spec.loader.create_module nicht None zurückgibt, werden vorhandene Attribute nicht zurückgesetzt. Außerdem wird kein AttributeError ausgelöst, wenn beim Zugriff auf spec oder beim Setzen eines Attributs auf dem Modul darauf zugegriffen wird.

Diese Funktion ist der Verwendung von types.ModuleType zum Erstellen eines neuen Moduls vorzuziehen, da spec verwendet wird, um so viele Import-kontrollierte Attribute wie möglich auf dem Modul zu setzen.

Hinzugefügt in Version 3.5.

importlib.util.spec_from_loader(name, loader, *, origin=None, is_package=None)¶: Eine Factory-Funktion zum Erstellen einer ModuleSpec-Instanz basierend auf einem Loader. Die Parameter haben die gleiche Bedeutung wie bei ModuleSpec. Die Funktion verwendet verfügbare Loader-APIs, wie z.B. InspectLoader.is_package(), um fehlende Informationen im Spec zu ergänzen.

Hinzugefügt in Version 3.4.

importlib.util.spec_from_file_location(name, location, *, loader=None, submodule_search_locations=None)¶: Eine Factory-Funktion zum Erstellen einer ModuleSpec-Instanz basierend auf dem Pfad zu einer Datei. Fehlende Informationen werden im Spec durch Nutzung von Loader-APIs und durch die Annahme, dass das Modul dateibasiert ist, ergänzt.

Hinzugefügt in Version 3.4.

Geändert in Version 3.6: Akzeptiert ein pfadähnliches Objekt.

importlib.util.source_hash(source_bytes)¶: Gibt den Hash von source_bytes als Bytes zurück. Eine Hash-basierte .pyc-Datei bettet den source_hash() des Inhalts der entsprechenden Quelldatei in ihren Header ein.

Hinzugefügt in Version 3.7.

importlib.util._incompatible_extension_module_restrictions(*, disable_check)¶

Ein Kontextmanager, der die Kompatibilitätsprüfung für Erweiterungsmodule vorübergehend überspringen kann. Standardmäßig ist die Prüfung aktiviert und schlägt fehl, wenn ein Modul mit einphasiger Initialisierung in einem Subinterpreter importiert wird. Sie schlägt auch für ein Modul mit mehrphasiger Initialisierung fehl, das nicht explizit einen pro-Interpreter-GIL unterstützt, wenn es in einem Interpreter mit eigenem GIL importiert wird.

Beachten Sie, dass diese Funktion einen ungewöhnlichen Fall behandeln soll; einen, der wahrscheinlich irgendwann verschwinden wird. Es ist sehr wahrscheinlich, dass dies nicht das ist, wonach Sie gesucht haben.

Sie können denselben Effekt wie mit dieser Funktion erzielen, indem Sie die grundlegende Schnittstelle der mehrphasigen Initialisierung (PEP 489) implementieren und die Unterstützung für mehrere Interpreter (oder pro-Interpreter-GIL) vortäuschen.

Warnung

Die Verwendung dieser Funktion zum Deaktivieren der Prüfung kann zu unerwartetem Verhalten und sogar zu Abstürzen führen. Sie sollte nur während der Entwicklung von Erweiterungsmodulen verwendet werden.

Hinzugefügt in Version 3.12.

class importlib.util.LazyLoader(loader)¶

Eine Klasse, die die Ausführung des Loaders eines Moduls verzögert, bis auf ein Attribut des Moduls zugegriffen wird.

Diese Klasse funktioniert nur mit Loadern, die exec_module() definieren, da Kontrolle darüber erforderlich ist, welcher Modultyp für das Modul verwendet wird. Aus denselben Gründen muss die Methode create_module() des Loaders None oder einen Typ zurückgeben, dessen __class__-Attribut mutiert werden kann und der keine slots verwendet. Schließlich funktionieren Module, die das Objekt in sys.modules eingefügt überschreiben, nicht, da es keine Möglichkeit gibt, die Modulreferenzen im Interpreter sicher zu ersetzen; ValueError wird ausgelöst, wenn eine solche Ersetzung erkannt wird.

Hinweis

Für Projekte, bei denen die Startzeit kritisch ist, ermöglicht diese Klasse eine potenziell Minimierung der Kosten für das Laden eines Moduls, wenn es nie verwendet wird. Für Projekte, bei denen die Startzeit nicht wichtig ist, wird die Verwendung dieser Klasse dringend abgeraten, da Fehlermeldungen während des Ladens verzögert und somit aus dem Kontext gerissen auftreten.

Hinzugefügt in Version 3.5.

Geändert in Version 3.6: Beginnt mit dem Aufruf von create_module(), wodurch die Kompatibilitätswarnung für importlib.machinery.BuiltinImporter und importlib.machinery.ExtensionFileLoader entfernt wurde.

classmethod factory(loader)¶

Eine Klassenmethode, die einen aufrufbaren Rückgabewert zurückgibt, der einen Lazy-Loader erstellt. Dies ist für Situationen gedacht, in denen der Loader als Klasse und nicht als Instanz übergeben wird.

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

Beispiele¶

Programmgesteuertes Importieren¶

Um ein Modul programmgesteuert zu importieren, verwenden Sie importlib.import_module().

import importlib

itertools = importlib.import_module('itertools')

Überprüfen, ob ein Modul importiert werden kann¶

Wenn Sie feststellen müssen, ob ein Modul importiert werden kann, ohne es tatsächlich zu importieren, sollten Sie importlib.util.find_spec() verwenden.

Beachten Sie, dass importlib.util.find_spec() das Elternmodul importiert, wenn name ein Untermodul ist (einen Punkt enthält).

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

Eine Quelldatei direkt importieren¶

Dieses Rezept sollte mit Vorsicht verwendet werden: Es ist eine Annäherung an eine Importanweisung, bei der der Dateipfad direkt angegeben wird, anstatt sys.path zu durchsuchen. Alternativen sollten zuerst in Betracht gezogen werden, wie z.B. die Änderung von sys.path, wenn ein korrektes Modul benötigt wird, oder die Verwendung von runpy.run_path(), wenn der globale Namensraum, der sich aus der Ausführung einer Python-Datei ergibt, angemessen ist.

Um eine Python-Quelldatei direkt aus einem Pfad zu importieren, verwenden Sie das folgende Rezept

import importlib.util
import sys


def import_from_path(module_name, file_path):
    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)
    return module


# For illustrative purposes only (use of `json` is arbitrary).
import json
file_path = json.__file__
module_name = json.__name__

# Similar outcome as `import json`.
json = import_from_path(module_name, file_path)

Lazy Imports implementieren¶

Das folgende Beispiel zeigt, wie Lazy Imports implementiert werden können

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

Einen Importer einrichten¶

Für tiefgreifende Anpassungen des Imports möchten Sie typischerweise einen Importer implementieren. Dies bedeutet, sowohl die Finder- als auch die Loader-Seite zu verwalten. Für Finder gibt es je nach Bedarf zwei Varianten zur Auswahl: einen Meta-Path-Finder oder einen Path-Entry-Finder. Ersteres ist das, was Sie auf sys.meta_path setzen würden, während letzteres das ist, was Sie mit einem Path-Entry-Hook auf sys.path_hooks erstellen, das mit sys.path-Einträgen arbeitet, um potenziell einen Finder zu erstellen. Dieses Beispiel zeigt Ihnen, wie Sie Ihre eigenen Importer registrieren, damit import sie verwendet (für die Erstellung eines Importers für sich selbst lesen Sie die Dokumentation der entsprechenden Klassen, die in diesem Paket definiert sind).

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

Annäherung an `importlib.import_module()`¶

Der Import selbst ist in Python-Code implementiert, was es möglich macht, die meisten Import-Mechanismen über importlib offenzulegen. Das Folgende hilft, die verschiedenen APIs zu veranschaulichen, die importlib freilegt, indem eine ungefähre Implementierung von importlib.import_module() bereitgestellt wird.

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

`importlib` — Die Implementierung von `import`¶

Einleitung¶

Funktionen¶

`importlib.abc` – Abstrakte Basisklassen im Zusammenhang mit dem Import¶

`importlib.machinery` – Importer und Pfadhaken¶

`importlib.util` – Hilfscode für Importer¶

Beispiele¶

Programmgesteuertes Importieren¶

Überprüfen, ob ein Modul importiert werden kann¶

Eine Quelldatei direkt importieren¶

Lazy Imports implementieren¶

Einen Importer einrichten¶

Annäherung an `importlib.import_module()`¶

Inhaltsverzeichnis

Vorheriges Thema

Nächstes Thema

Diese Seite

importlib — Die Implementierung von import¶

Einleitung¶

Funktionen¶

importlib.abc – Abstrakte Basisklassen im Zusammenhang mit dem Import¶

importlib.machinery – Importer und Pfadhaken¶

importlib.util – Hilfscode für Importer¶

Beispiele¶

Programmgesteuertes Importieren¶

Überprüfen, ob ein Modul importiert werden kann¶

Eine Quelldatei direkt importieren¶

Lazy Imports implementieren¶

Einen Importer einrichten¶

Annäherung an importlib.import_module()¶

`importlib` — Die Implementierung von `import`¶

`importlib.abc` – Abstrakte Basisklassen im Zusammenhang mit dem Import¶

`importlib.machinery` – Importer und Pfadhaken¶

`importlib.util` – Hilfscode für Importer¶

Annäherung an `importlib.import_module()`¶