marshal — Interne Python-Objektserialisierung

---

Dieses Modul enthält Funktionen, die Python-Werte in einem Binärformat lesen und schreiben können. Das Format ist spezifisch für Python, aber unabhängig von Problemen mit der Maschinenarchitektur (z. B. können Sie einen Python-Wert in eine Datei auf einem PC schreiben, die Datei auf einen Mac transportieren und dort wieder einlesen). Details des Formats sind absichtlich undokumentiert; es kann sich zwischen Python-Versionen ändern (obwohl es selten vorkommt). [1]

Dies ist kein allgemeines „Persistenz“-Modul. Für allgemeine Persistenz und den Transfer von Python-Objekten über RPC-Aufrufe siehe die Module pickle und shelve. Das Modul marshal existiert hauptsächlich zur Unterstützung des Lesens und Schreibens des „pseudo-kompilierten“ Codes für Python-Module in .pyc-Dateien. Daher behalten sich die Python-Entwickler das Recht vor, das Marshal-Format bei Bedarf auf nicht abwärtskompatible Weise zu ändern. Das Format von Code-Objekten ist nicht mit verschiedenen Python-Versionen kompatibel, auch wenn die Version des Formats gleich ist. Das Deserialisieren eines Code-Objekts in der falschen Python-Version hat undefiniertes Verhalten. Wenn Sie Python-Objekte serialisieren und deserialisieren, verwenden Sie stattdessen das Modul pickle – die Leistung ist vergleichbar, die Versionsunabhängigkeit ist garantiert und Pickle unterstützt eine erheblich größere Bandbreite von Objekten als Marshal.

Warnung

Das Modul marshal ist nicht dazu bestimmt, gegen fehlerhafte oder böswillig konstruierte Daten sicher zu sein. Ent-serialisieren Sie niemals Daten, die von einer nicht vertrauenswürdigen oder nicht authentifizierten Quelle empfangen wurden.

Es gibt Funktionen, die Dateien lesen/schreiben, sowie Funktionen, die auf byteähnlichen Objekten arbeiten.

Nicht alle Python-Objekttypen werden unterstützt; im Allgemeinen können nur Objekte, deren Wert unabhängig von einer bestimmten Python-Ausführung ist, von diesem Modul gelesen und geschrieben werden. Die folgenden Typen werden unterstützt

• Numerische Typen: int, bool, float, complex.

• Strings (str) und bytes. Byteähnliche Objekte wie bytearray werden als bytes marshallt.

• Container: tuple, list, set, frozenset und (seit version 5) slice. Es ist zu verstehen, dass diese nur unterstützt werden, wenn die darin enthaltenen Werte selbst unterstützt werden. Rekursive Container werden seit version 3 unterstützt.

• Die Singletons None, Ellipsis und StopIteration.

• code-Objekte, wenn allow_code true ist. Siehe Hinweis oben zur Versionsabhängigkeit.

Geändert in Version 3.4

• Formatversion 3 hinzugefügt, die das Marshalling rekursiver Listen, Mengen und Wörterbücher unterstützt.

• Formatversion 4 hinzugefügt, die effiziente Darstellungen kurzer Strings unterstützt.

Geändert in Version 3.14: Formatversion 5 hinzugefügt, die das Marshalling von Slices ermöglicht.

Das Modul definiert diese Funktionen

marshal.dump(value, file, version=version, /, *, allow_code=True)

Schreibt den Wert in die geöffnete Datei. Der Wert muss ein unterstützter Typ sein. Die Datei muss eine beschreibbare Binärdatei sein.

Wenn der Wert einen nicht unterstützten Typ hat (oder einen Objekt enthält, das einen hat), wird eine ValueError-Ausnahme ausgelöst – aber es werden auch fehlerhafte Daten in die Datei geschrieben. Das Objekt wird von load() nicht korrekt eingelesen. Code-Objekte werden nur unterstützt, wenn allow_code true ist.

Das Argument version gibt das Datenformat an, das dump verwenden soll (siehe unten).

Löst ein Auditing-Ereignis marshal.dumps mit den Argumenten value, version aus.

Geändert in Version 3.13: Der Parameter allow_code wurde hinzugefügt.

marshal.load(file, /, *, allow_code=True)

Liest einen Wert aus der geöffneten Datei und gibt ihn zurück. Wenn kein gültiger Wert gelesen wird (z. B. weil die Daten ein inkompatibles Marshal-Format einer anderen Python-Version haben), wird EOFError, ValueError oder TypeError ausgelöst. Code-Objekte werden nur unterstützt, wenn allow_code true ist. Die Datei muss eine lesbare Binärdatei sein.

Löst ein Auditing-Ereignis marshal.load ohne Argumente aus.

Hinweis

Wenn ein Objekt, das einen nicht unterstützten Typ enthält, mit dump() marshallt wurde, substituiert load() None für den nicht marshallbaren Typ.

Geändert in Version 3.10: Dieser Aufruf löste früher ein code.__new__-Audit-Ereignis für jedes Code-Objekt aus. Jetzt löst es ein einzelnes marshal.load-Ereignis für den gesamten Ladevorgang aus.

Geändert in Version 3.13: Der Parameter allow_code wurde hinzugefügt.

marshal.dumps(value, version=version, /, *, allow_code=True)

Gibt das Byte-Objekt zurück, das von dump(value, file) in eine Datei geschrieben würde. Der Wert muss ein unterstützter Typ sein. Löst eine ValueError-Ausnahme aus, wenn der Wert einen nicht unterstützten Typ hat (oder ein Objekt enthält, das einen hat). Code-Objekte werden nur unterstützt, wenn allow_code true ist.

Das Argument version gibt das Datenformat an, das dumps verwenden soll (siehe unten).

Löst ein Auditing-Ereignis marshal.dumps mit den Argumenten value, version aus.

Geändert in Version 3.13: Der Parameter allow_code wurde hinzugefügt.

marshal.loads(bytes, /, *, allow_code=True)

Konvertiert das byteähnliche Objekt in einen Wert. Wenn kein gültiger Wert gefunden wird, wird EOFError, ValueError oder TypeError ausgelöst. Code-Objekte werden nur unterstützt, wenn allow_code true ist. Zusätzliche Bytes in der Eingabe werden ignoriert.

Löst ein Auditing-Ereignis marshal.loads mit dem Argument bytes aus.

Geändert in Version 3.10: Dieser Aufruf löste früher ein code.__new__-Audit-Ereignis für jedes Code-Objekt aus. Jetzt löst es ein einzelnes marshal.loads-Ereignis für den gesamten Ladevorgang aus.

Geändert in Version 3.13: Der Parameter allow_code wurde hinzugefügt.

Zusätzlich werden die folgenden Konstanten definiert

marshal.version

Gibt das Format an, das das Modul verwendet. Version 0 ist die historische erste Version; nachfolgende Versionen fügen neue Funktionen hinzu. Im Allgemeinen wird eine neue Version zum Standard, wenn sie eingeführt wird.

Version	Verfügbar seit	Neue Funktionen
1	Python 2.4	Teilen von internen Strings
2	Python 2.5	Binäre Darstellung von Gleitkommazahlen
3	Python 3.4	Unterstützung für Objekterzeugung und Rekursion
4	Python 3.4	Effiziente Darstellung kurzer Strings
5	Python 3.14	Unterstützung für slice-Objekte

Fußnoten

[1]

Der Name dieses Moduls leitet sich von einem Begriff ab, der von den Entwicklern von Modula-3 (u. a.) verwendet wird, die den Begriff „Marshalling“ für den Transport von Daten in einem eigenständigen Format verwenden. Streng genommen bedeutet „to marshal“ die Konvertierung von Daten von der internen in die externe Form (z. B. in einem RPC-Puffer) und „unmarshalling“ für den umgekehrten Vorgang.