py_compile — Python-Quellcodedateien kompilieren

Quellcode: Lib/py_compile.py

Das Modul py_compile bietet eine Funktion zum Generieren einer Bytecode-Datei aus einer Quelldatei und eine weitere Funktion, die verwendet wird, wenn die Modulquellcodedatei als Skript aufgerufen wird.

Obwohl nicht oft benötigt, kann diese Funktion bei der Installation von Modulen zur gemeinsamen Nutzung nützlich sein, insbesondere wenn einige Benutzer keine Berechtigung zum Schreiben von Bytecode-Cache-Dateien im Verzeichnis mit dem Quellcode haben.

exception py_compile.PyCompileError

Ausnahme, die ausgelöst wird, wenn beim Kompilieren der Datei ein Fehler auftritt.

py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)

Kompiliert eine Quelldatei zu Bytecode und schreibt die Bytecode-Cache-Datei. Der Quellcode wird aus der Datei namens *file* geladen. Der Bytecode wird in *cfile* geschrieben, das standardmäßig dem PEP 3147/PEP 488-Pfad entspricht und mit .pyc endet. Wenn beispielsweise *file* /foo/bar/baz.py ist, ist *cfile* standardmäßig /foo/bar/__pycache__/baz.cpython-32.pyc für Python 3.2. Wenn *dfile* angegeben ist, wird es anstelle von *file* als Name der Quelldatei verwendet, aus der Quellzeilen für die Anzeige in Ausnahme-Tracebacks bezogen werden. Wenn *doraise* wahr ist, wird eine PyCompileError ausgelöst, wenn beim Kompilieren von *file* ein Fehler auftritt. Wenn *doraise* falsch ist (Standard), wird eine Fehlerzeichenkette nach sys.stderr geschrieben, aber keine Ausnahme ausgelöst. Diese Funktion gibt den Pfad zur Bytecode-kompilierten Datei zurück, d.h. den tatsächlich für *cfile* verwendeten Wert.

Die Argumente *doraise* und *quiet* bestimmen, wie Fehler beim Kompilieren einer Datei behandelt werden. Wenn *quiet* 0 oder 1 ist und *doraise* falsch ist, wird das Standardverhalten aktiviert: Eine Fehlerzeichenkette wird nach sys.stderr geschrieben und die Funktion gibt None anstelle eines Pfads zurück. Wenn *doraise* wahr ist, wird stattdessen eine PyCompileError ausgelöst. Wenn *quiet* jedoch 2 ist, wird keine Meldung ausgegeben und *doraise* hat keine Auswirkung.

Wenn der Pfad, zu dem *cfile* wird (entweder explizit angegeben oder berechnet), ein Symlink oder eine Nicht-Regulärdatei ist, wird FileExistsError ausgelöst. Dies dient als Warnung, dass der Import diese Pfade in reguläre Dateien umwandeln wird, wenn er Bytecode-kompilierte Dateien in diese Pfade schreiben darf. Dies ist eine Nebenwirkung der Verwendung von Dateiumbenennung durch den Import, um die endgültige Bytecode-kompilierte Datei platziert zu bekommen und Probleme beim gleichzeitigen Schreiben von Dateien zu vermeiden.

*optimize* steuert die Optimierungsstufe und wird an die integrierte Funktion compile() übergeben. Der Standardwert von -1 wählt die Optimierungsstufe des aktuellen Interpreters.

*invalidation_mode* sollte ein Mitglied der PycInvalidationMode-Enumeration sein und steuert, wie der generierte Bytecode-Cache zur Laufzeit ungültig gemacht wird. Der Standardwert ist PycInvalidationMode.CHECKED_HASH, wenn die Umgebungsvariable SOURCE_DATE_EPOCH gesetzt ist, andernfalls ist der Standardwert PycInvalidationMode.TIMESTAMP.

Geändert in Version 3.2: Der Standardwert von *cfile* wurde auf PEP 3147-konform geändert. Der vorherige Standardwert war *file* + 'c' ('o', wenn die Optimierung aktiviert war). Außerdem wurde der Parameter *optimize* hinzugefügt.

Geändert in Version 3.4: Der Code wurde geändert, um importlib für das Schreiben von Bytecode-Cache-Dateien zu verwenden. Das bedeutet, dass die Semantik der Dateierstellung/-schreibung jetzt mit der von importlib übereinstimmt, z. B. Berechtigungen, Schreib-und-Verschiebungs-Semantik usw. Es wird auch der Hinweis hinzugefügt, dass FileExistsError ausgelöst wird, wenn *cfile* ein Symlink oder eine Nicht-Regulärdatei ist.

Geändert in Version 3.7: Der Parameter *invalidation_mode* wurde wie in PEP 552 angegeben hinzugefügt. Wenn die Umgebungsvariable SOURCE_DATE_EPOCH gesetzt ist, wird *invalidation_mode* auf PycInvalidationMode.CHECKED_HASH gesetzt.

Geändert in Version 3.7.2: Die Umgebungsvariable SOURCE_DATE_EPOCH überschreibt den Wert des Arguments *invalidation_mode* nicht mehr, sondern bestimmt stattdessen seinen Standardwert.

Geändert in Version 3.8: Der Parameter *quiet* wurde hinzugefügt.

class py_compile.PycInvalidationMode

Eine Enumeration möglicher Methoden, mit denen der Interpreter feststellen kann, ob eine Bytecode-Datei mit einer Quelldatei auf dem neuesten Stand ist. Die .pyc-Datei gibt den gewünschten Ungültigkeitsmodus in ihrem Header an. Weitere Informationen darüber, wie Python .pyc-Dateien zur Laufzeit ungültig macht, finden Sie unter Ungültigkeit von Bytecode-Caches.

Hinzugefügt in Version 3.7.

TIMESTAMP

Die .pyc-Datei enthält den Zeitstempel und die Größe der Quelldatei, die Python zur Laufzeit mit den Metadaten der Quelldatei vergleicht, um festzustellen, ob die .pyc-Datei neu generiert werden muss.

CHECKED_HASH

Die .pyc-Datei enthält einen Hash des Inhalts der Quelldatei, den Python zur Laufzeit mit der Quelle vergleicht, um festzustellen, ob die .pyc-Datei neu generiert werden muss.

UNCHECKED_HASH

Ähnlich wie bei CHECKED_HASH enthält die .pyc-Datei einen Hash des Inhalts der Quelldatei. Python geht jedoch zur Laufzeit davon aus, dass die .pyc-Datei auf dem neuesten Stand ist und validiert die .pyc überhaupt nicht gegen die Quelldatei.

Diese Option ist nützlich, wenn die .pycs von einem System, das extern zu Python ist, wie z. B. einem Build-System, auf dem neuesten Stand gehalten werden.

Befehlszeilenschnittstelle

Dieses Modul kann als Skript aufgerufen werden, um mehrere Quellcodedateien zu kompilieren. Die in *filenames* genannten Dateien werden kompiliert und der resultierende Bytecode wird auf normale Weise im Cache gespeichert. Dieses Programm durchsucht keine Verzeichnisstruktur, um Quelldateien zu finden; es kompiliert nur explizit genannte Dateien. Der Exit-Status ist nicht null, wenn eine der Dateien nicht kompiliert werden konnte.

<file> ... <fileN>
-

Positionsargumente sind zu kompilierende Dateien. Wenn - der einzige Parameter ist, wird die Liste der Dateien von der Standardeingabe genommen.

-q, --quiet

Unterdrückt Fehlerausgaben.

Geändert in Version 3.2: Unterstützung für - hinzugefügt.

Geändert in Version 3.10: Unterstützung für -q hinzugefügt.

Siehe auch

Modul compileall

Dienstprogramme zum Kompilieren aller Python-Quellcodedateien in einem Verzeichnisbaum.