importlib.resources – Lesen, Öffnen und Zugriff auf Paketressourcen

Quellcode: Lib/importlib/resources/__init__.py

---

Hinzugefügt in Version 3.7.

Dieses Modul nutzt Pythons Importsystem, um Zugriff auf Ressourcen innerhalb von Paketen zu ermöglichen.

„Ressourcen“ sind dateiähnliche Ressourcen, die mit einem Modul oder Paket in Python verknüpft sind. Die Ressourcen können direkt in einem Paket enthalten sein, innerhalb eines Unterverzeichnisses, das in diesem Paket enthalten ist, oder neben Modulen außerhalb eines Pakets. Ressourcen können Text oder Binärdaten sein. Infolgedessen sind die Python-Modulquellen (.py), Kompilierungsartefakte (pycache) und Installationsartefakte eines Pakets (wie reservierte Dateinamen in Verzeichnissen) technisch de-facto Ressourcen dieses Pakets. In der Praxis sind Ressourcen jedoch hauptsächlich die Nicht-Python-Artefakte, die speziell vom Paketautor bereitgestellt werden.

Ressourcen können entweder im Binär- oder im Textmodus geöffnet oder gelesen werden.

Ressourcen sind ungefähr vergleichbar mit Dateien in Verzeichnissen, obwohl es wichtig ist zu bedenken, dass dies nur eine Metapher ist. Ressourcen und Pakete müssen **nicht** als physische Dateien und Verzeichnisse im Dateisystem existieren: Beispielsweise können ein Paket und seine Ressourcen über eine Zip-Datei mit zipimport importiert werden.

Hinweis

Dieses Modul bietet Funktionalität ähnlich wie pkg_resources Basic Resource Access ohne den Performance-Overhead dieses Pakets. Dies erleichtert das Lesen von in Paketen enthaltenen Ressourcen mit stabileren und konsistenteren Semantiken.

Der eigenständige Backport dieses Moduls bietet weitere Informationen unter Verwendung von importlib.resources und Migration von pkg_resources zu importlib.resources.

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

class importlib.resources.Anchor

Stellt einen Anker für Ressourcen dar, entweder ein Modulobjekt oder einen Modulnamen als Zeichenkette. Definiert als Union[str, ModuleType].

importlib.resources.files(anchor: Anchor | None = None)

Gibt ein Traversable Objekt zurück, das den Ressourcencontainer (als Verzeichnis gedacht) und seine Ressourcen (als Dateien gedacht) darstellt. Ein Traversable kann andere Container enthalten (als Unterverzeichnisse gedacht).

anchor ist ein optionaler Anchor. Wenn der Anker ein Paket ist, werden Ressourcen aus diesem Paket aufgelöst. Wenn ein Modul, werden Ressourcen neben diesem Modul (im selben Paket oder im Paket-Root) aufgelöst. Wenn der Anker weggelassen wird, wird das Modul des Aufrufers verwendet.

Hinzugefügt in Version 3.9.

Geändert in Version 3.12: Der Parameter package wurde in anchor umbenannt. anchor kann jetzt ein Nicht-Paket-Modul sein und wird standardmäßig auf das Modul des Aufrufers gesetzt, wenn es weggelassen wird. package wird weiterhin zur Kompatibilität akzeptiert, löst aber eine DeprecationWarning aus. Ziehen Sie in Erwägung, den Anker positionsabhängig zu übergeben oder importlib_resources >= 5.10 für eine kompatible Schnittstelle auf älteren Pythons zu verwenden.

importlib.resources.as_file(traversable)

Nimmt ein Traversable Objekt zurück, das eine Datei oder ein Verzeichnis darstellt, typischerweise von importlib.resources.files(), und gibt einen Kontextmanager für die Verwendung in einer with-Anweisung zurück. Der Kontextmanager liefert ein pathlib.Path Objekt.

Beim Verlassen des Kontextmanagers werden alle temporären Dateien oder Verzeichnisse bereinigt, die beim Extrahieren der Ressource z. B. aus einer Zip-Datei erstellt wurden.

Verwenden Sie as_file, wenn die Traversable-Methoden (read_text, etc.) unzureichend sind und eine tatsächliche Datei oder ein Verzeichnis im Dateisystem benötigt wird.

Hinzugefügt in Version 3.9.

Geändert in Version 3.12: Unterstützung für traversable, das ein Verzeichnis darstellt, hinzugefügt.

Funktionale API

Eine Reihe vereinfachter, abwärtskompatibler Helfer ist verfügbar. Diese ermöglichen gängige Operationen in einem einzigen Funktionsaufruf.

Für alle folgenden Funktionen

• anchor ist ein Anchor, wie in files(). Im Gegensatz zu files kann es nicht weggelassen werden.

• path_names sind Komponenten eines Ressourcennamens, relativ zum Anker. Um beispielsweise den Text der Ressource info.txt zu erhalten, verwenden Sie

  importlib.resources.read_text(my_module, "info.txt")
  

  Ähnlich wie bei Traversable.joinpath sollten die einzelnen Komponenten Vorwärts-Schrägstriche (/) als Pfadtrenner verwenden. Beispielsweise sind die folgenden äquivalent

  importlib.resources.read_binary(my_module, "pics/painting.png")
  importlib.resources.read_binary(my_module, "pics", "painting.png")
  

  Aus Gründen der Abwärtskompatibilität erfordern Funktionen, die Text lesen, ein explizites encoding-Argument, wenn mehrere path_names angegeben werden. Um beispielsweise den Text von info/chapter1.txt zu erhalten, verwenden Sie

  importlib.resources.read_text(my_module, "info", "chapter1.txt",
                                encoding='utf-8')
  

importlib.resources.open_binary(anchor, *path_names)

Öffnet die benannte Ressource zum binären Lesen.

Siehe die Einleitung für Details zu anchor und path_names.

Diese Funktion gibt ein BinaryIO-Objekt zurück, d.h. einen Binärstrom, der zum Lesen geöffnet ist.

Diese Funktion ist ungefähr äquivalent zu

files(anchor).joinpath(*path_names).open('rb')

Geändert in Version 3.13: Mehrere path_names werden akzeptiert.

importlib.resources.open_text(anchor, *path_names, encoding='utf-8', errors='strict')

Öffnet die benannte Ressource zum Textlesen. Standardmäßig werden die Inhalte als striktes UTF-8 gelesen.

Siehe die Einleitung für Details zu anchor und path_names. encoding und errors haben die gleiche Bedeutung wie in der integrierten Funktion open().

Aus Gründen der Abwärtskompatibilität muss das encoding-Argument explizit angegeben werden, wenn mehrere path_names vorhanden sind. Diese Einschränkung wird voraussichtlich in Python 3.15 aufgehoben.

Diese Funktion gibt ein TextIO-Objekt zurück, d.h. einen Textstrom, der zum Lesen geöffnet ist.

Diese Funktion ist ungefähr äquivalent zu

files(anchor).joinpath(*path_names).open('r', encoding=encoding)

Geändert in Version 3.13: Mehrere path_names werden akzeptiert. encoding und errors müssen als Schlüsselwortargumente übergeben werden.

importlib.resources.read_binary(anchor, *path_names)

Liest und gibt den Inhalt der benannten Ressource als bytes zurück.

Siehe die Einleitung für Details zu anchor und path_names.

Diese Funktion ist ungefähr äquivalent zu

files(anchor).joinpath(*path_names).read_bytes()

Geändert in Version 3.13: Mehrere path_names werden akzeptiert.

importlib.resources.read_text(anchor, *path_names, encoding='utf-8', errors='strict')

Liest und gibt den Inhalt der benannten Ressource als str zurück. Standardmäßig werden die Inhalte als striktes UTF-8 gelesen.

Siehe die Einleitung für Details zu anchor und path_names. encoding und errors haben die gleiche Bedeutung wie in der integrierten Funktion open().

Aus Gründen der Abwärtskompatibilität muss das encoding-Argument explizit angegeben werden, wenn mehrere path_names vorhanden sind. Diese Einschränkung wird voraussichtlich in Python 3.15 aufgehoben.

Diese Funktion ist ungefähr äquivalent zu

files(anchor).joinpath(*path_names).read_text(encoding=encoding)

Geändert in Version 3.13: Mehrere path_names werden akzeptiert. encoding und errors müssen als Schlüsselwortargumente übergeben werden.

importlib.resources.path(anchor, *path_names)

Bietet den Pfad zur Ressource als tatsächlichen Dateisystempfad. Diese Funktion gibt einen Kontextmanager für die Verwendung in einer with-Anweisung zurück. Der Kontextmanager liefert ein pathlib.Path Objekt.

Beim Verlassen des Kontextmanagers werden alle temporären Dateien bereinigt, die erstellt wurden, z. B. wenn die Ressource aus einer Zip-Datei extrahiert werden muss.

Beispielsweise erfordert die Methode stat() einen tatsächlichen Dateisystempfad; sie kann wie folgt verwendet werden

with importlib.resources.path(anchor, "resource.txt") as fspath:
    result = fspath.stat()

Siehe die Einleitung für Details zu anchor und path_names.

Diese Funktion ist ungefähr äquivalent zu

as_file(files(anchor).joinpath(*path_names))

Geändert in Version 3.13: Mehrere path_names werden akzeptiert. encoding und errors müssen als Schlüsselwortargumente übergeben werden.

importlib.resources.is_resource(anchor, *path_names)

Gibt True zurück, wenn die benannte Ressource existiert, andernfalls False. Diese Funktion betrachtet Verzeichnisse nicht als Ressourcen.

Siehe die Einleitung für Details zu anchor und path_names.

Diese Funktion ist ungefähr äquivalent zu

files(anchor).joinpath(*path_names).is_file()

Geändert in Version 3.13: Mehrere path_names werden akzeptiert.

importlib.resources.contents(anchor, *path_names)

Gibt ein iterierbares Objekt über die benannten Elemente innerhalb des Pakets oder Pfads zurück. Das iterierbare Objekt liefert Namen von Ressourcen (z. B. Dateien) und Nicht-Ressourcen (z. B. Verzeichnisse) als str. Das iterierbare Objekt rekursiert nicht in Unterverzeichnisse.

Siehe die Einleitung für Details zu anchor und path_names.

Diese Funktion ist ungefähr äquivalent zu

for resource in files(anchor).joinpath(*path_names).iterdir():
    yield resource.name

Veraltet seit Version 3.11: Bevorzugen Sie iterdir() wie oben, das mehr Kontrolle über die Ergebnisse und reichhaltigere Funktionalität bietet.