pkgutil — Paket-Erweiterungsdienstprogramm¶
Quellcode: Lib/pkgutil.py
Dieses Modul stellt Dienstprogramme für das Importsystem, insbesondere Paketunterstützung, bereit.
- class pkgutil.ModuleInfo(module_finder, name, ispkg)¶
Ein Namedtuple, das eine kurze Zusammenfassung der Modulinformationen enthält.
Hinzugefügt in Version 3.6.
- pkgutil.extend_path(path, name)¶
Erweitert den Suchpfad für die Module, aus denen ein Paket besteht. Die vorgesehene Verwendung ist, den folgenden Code in die
__init__.pyeines Pakets zu platzierenfrom pkgutil import extend_path __path__ = extend_path(__path__, __name__)
Für jedes Verzeichnis in
sys.path, das ein Unterverzeichnis mit dem Paketnamen hat, wird das Unterverzeichnis zum__path__des Pakets hinzugefügt. Dies ist nützlich, wenn man verschiedene Teile eines einzigen logischen Pakets als mehrere Verzeichnisse verteilen möchte.Es sucht auch nach
*.pkg-Dateien, bei denen*dem Argument name entspricht. Dieses Feature ist ähnlich zu*.pth-Dateien (siehe dassite-Modul für weitere Informationen), außer dass Zeilen, die mitimportbeginnen, nicht speziell behandelt werden. Eine*.pkg-Datei wird wörtlich genommen: abgesehen vom Überspringen leerer Zeilen und dem Ignorieren von Kommentaren werden alle Einträge, die in einer*.pkg-Datei gefunden werden, zum Pfad hinzugefügt, unabhängig davon, ob sie im Dateisystem existieren (dies ist ein Feature).Wenn der Eingabepfad keine Liste ist (wie bei gefrorenen Paketen), wird er unverändert zurückgegeben. Der Eingabepfad wird nicht geändert; eine erweiterte Kopie wird zurückgegeben. Elemente werden nur am Ende der Kopie angehängt.
Es wird davon ausgegangen, dass
sys.patheine Sequenz ist. Elemente vonsys.path, die keine Strings sind, die auf existierende Verzeichnisse verweisen, werden ignoriert. Unicode-Elemente insys.path, die Fehler verursachen, wenn sie als Dateinamen verwendet werden, können dazu führen, dass diese Funktion eine Ausnahme auslöst (im Einklang mit dem Verhalten vonos.path.isdir()).
- pkgutil.get_importer(path_item)¶
Ruft einen Finder für das gegebene path_item ab.
Der zurückgegebene Finder wird in
sys.path_importer_cachezwischengespeichert, wenn er neu von einem Pfadhaken erstellt wurde.Der Cache (oder ein Teil davon) kann manuell gelöscht werden, wenn ein erneutes Scannen von
sys.path_hookserforderlich ist.
- pkgutil.iter_importers(fullname='')¶
Gibt Finder-Objekte für den gegebenen Modulnamen zurück.
Wenn fullname einen Punkt (
'.') enthält, sind die Finder für das Paket, das fullname enthält, andernfalls sind es alle registrierten Top-Level-Finder (d. h. die in sowohlsys.meta_pathals auchsys.path_hooks).Wenn das benannte Modul in einem Paket liegt, wird dieses Paket als Nebeneffekt des Aufrufs dieser Funktion importiert.
Wenn kein Modulname angegeben ist, werden alle Top-Level-Finder zurückgegeben.
- pkgutil.iter_modules(path=None, prefix='')¶
Gibt
ModuleInfofür alle Untermodule in path zurück, oder, wenn pathNoneist, für alle Top-Level-Module insys.path.path sollte entweder
Noneoder eine Liste von Pfaden sein, in denen nach Modulen gesucht werden soll.prefix ist ein String, der am Anfang jedes Modulnamens in der Ausgabe ausgegeben wird.
Hinweis
Funktioniert nur für einen Finder, der eine
iter_modules()-Methode definiert. Diese Schnittstelle ist nicht standardmäßig, daher stellt das Modul auch Implementierungen fürimportlib.machinery.FileFinderundzipimport.zipimporterbereit.
- pkgutil.walk_packages(path=None, prefix='', onerror=None)¶
Gibt rekursiv
ModuleInfofür alle Module auf path zurück, oder, wenn pathNoneist, für alle zugänglichen Module.path sollte entweder
Noneoder eine Liste von Pfaden sein, in denen nach Modulen gesucht werden soll.prefix ist ein String, der am Anfang jedes Modulnamens in der Ausgabe ausgegeben wird.
Beachten Sie, dass diese Funktion alle *Pakete* (nicht alle Module!) auf dem gegebenen path importieren muss, um auf das
__path__-Attribut zuzugreifen und Untermodule zu finden.onerror ist eine Funktion, die mit einem Argument (dem Namen des Pakets, das gerade importiert wurde) aufgerufen wird, wenn beim Importieren eines Pakets eine Ausnahme auftritt. Wenn keine onerror-Funktion bereitgestellt wird, werden
ImportErrors abgefangen und ignoriert, während alle anderen Ausnahmen weitergegeben werden und die Suche beenden.Beispiele
# list all modules python can access walk_packages() # list all submodules of ctypes walk_packages(ctypes.__path__, ctypes.__name__ + '.')
Hinweis
Funktioniert nur für einen Finder, der eine
iter_modules()-Methode definiert. Diese Schnittstelle ist nicht standardmäßig, daher stellt das Modul auch Implementierungen fürimportlib.machinery.FileFinderundzipimport.zipimporterbereit.
- pkgutil.get_data(package, resource)¶
Ruft eine Ressource aus einem Paket ab.
Dies ist ein Wrapper für die Loader
get_data-API. Das Argument package sollte der Name eines Pakets sein, im Standardmodulformat (foo.bar). Das Argument resource sollte im Format eines relativen Dateinamens sein, wobei/als Pfadtrenner verwendet wird. Das Elternverzeichnis (..) ist nicht erlaubt, ebenso wenig ein absoluter Pfad (beginnend mit einem/).Die Funktion gibt eine binäre Zeichenkette zurück, die den Inhalt der angegebenen Ressource darstellt.
Für im Dateisystem befindliche Pakete, die bereits importiert wurden, ist dies das grobe Äquivalent von
d = os.path.dirname(sys.modules[package].__file__) data = open(os.path.join(d, resource), 'rb').read()
Wenn das Paket nicht gefunden oder geladen werden kann, oder wenn es einen Loader verwendet, der
get_datanicht unterstützt, wirdNonezurückgegeben. Insbesondere der Loader für Namespace-Pakete unterstütztget_datanicht.
- pkgutil.resolve_name(name)¶
Löst einen Namen in ein Objekt auf.
Diese Funktionalität wird an zahlreichen Stellen in der Standardbibliothek verwendet (siehe bpo-12915) – und äquivalente Funktionalität ist auch in weit verbreiteten Drittanbieterpaketen wie setuptools, Django und Pyramid enthalten.
Es wird erwartet, dass name ein String in einem der folgenden Formate ist, wobei W als Platzhalter für einen gültigen Python-Bezeichner steht und ein Punkt eine tatsächliche Periode in diesen Pseudo-Regexes darstellt
W(.W)*W(.W)*:(W(.W)*)?
Die erste Form ist nur für die Abwärtskompatibilität gedacht. Sie geht davon aus, dass ein Teil des gepunkteten Namens ein Paket ist und der Rest ein Objekt irgendwo innerhalb dieses Pakets ist, möglicherweise verschachtelt in anderen Objekten. Da der Punkt, an dem das Paket endet und die Objekt-Hierarchie beginnt, nicht durch Inspektion abgeleitet werden kann, müssen wiederholte Importversuche mit dieser Form durchgeführt werden.
In der zweiten Form macht der Aufrufer den Trennpunkt durch die Bereitstellung eines einzelnen Doppelpunkts deutlich: der gepunktete Name links vom Doppelpunkt ist ein zu importierendes Paket, und der gepunktete Name rechts ist die Objekt-Hierarchie innerhalb dieses Pakets. Nur ein Import ist bei dieser Form erforderlich. Wenn es mit dem Doppelpunkt endet, wird ein Modulobjekt zurückgegeben.
Die Funktion gibt ein Objekt zurück (das ein Modul sein kann) oder löst eine der folgenden Ausnahmen aus
ValueError– wenn name keinem anerkannten Format entspricht.ImportError– wenn ein Import fehlschlug, obwohl er nicht hätte fehlschlagen dürfen.AttributeError– Wenn beim Durchlaufen der Objekt-Hierarchie innerhalb des importierten Pakets ein Fehler auftrat, um zum gewünschten Objekt zu gelangen.Hinzugefügt in Version 3.9.