marshal — Interne Serialisierung von Python-Objekten

Dieses Modul enthält Funktionen, die Python-Werte in einem Binärformat lesen und schreiben können. Das Format ist Python-spezifisch, aber unabhängig von der Maschinenarchitektur. Du kannst zum Beispiel einen Python-Wert auf einem PC in eine Datei schreiben, die Datei auf einen Mac übertragen und dort wieder einlesen. Einzelheiten zum Format sind absichtlich nicht dokumentiert, denn es kann sich zwischen Python-Versionen ändern (was allerdings selten vorkommt). [1]

Dies ist kein allgemeines Modul zur „Persistenz“. Für allgemeine Persistenz und für die Übertragung von Python-Objekten über RPC-Aufrufe siehe die Module pickle und shelve. Das Modul marshal ist vor allem dafür da, den „pseudokompilierten“ Code von Python-Modulen aus .pyc-Dateien zu lesen und zu schreiben. Die Python-Betreuer behalten sich deshalb vor, das marshal-Format bei Bedarf in nicht rückwärtskompatibler Weise zu ändern. Das Format von Code-Objekten ist zwischen Python-Versionen nicht kompatibel, selbst wenn die Formatversion dieselbe ist. Ein Code-Objekt in der falschen Python-Version zu deserialisieren hat undefiniertes Verhalten. Willst du Python-Objekte serialisieren und deserialisieren, verwende stattdessen das Modul pickle – die Geschwindigkeit ist vergleichbar, Versionsunabhängigkeit ist zugesichert, und pickle unterstützt deutlich mehr Objekttypen als marshal.

Warnung

Das Modul marshal ist nicht darauf ausgelegt, gegen fehlerhafte oder bösartig erzeugte Daten abgesichert zu sein. Lies mit marshal niemals Daten ein, die aus einer nicht vertrauenswürdigen oder nicht authentifizierten Quelle stammen.

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

Nicht alle Python-Objekttypen werden unterstützt. Grundsätzlich kann dieses Modul nur Objekte schreiben und lesen, deren Wert von einem bestimmten Python-Aufruf unabhängig ist. Die folgenden Typen werden unterstützt:

Geändert in Version 3.4:

  • Formatversion 3 hinzugefügt, die das Schreiben rekursiver Listen, Mengen und Dictionarys unterstützt.

  • Formatversion 4 hinzugefügt, die eine effiziente Darstellung kurzer Zeichenketten unterstützt.

Geändert in Version 3.14: Formatversion 5 hinzugefügt, die das Schreiben von Slices erlaubt.

Geändert in Version 3.15: Formatversion 6 hinzugefügt, die das Schreiben von frozendict erlaubt.

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 von einem unterstützten Typ sein. Die Datei muss eine beschreibbare Binärdatei sein.

Hat der Wert einen nicht unterstützten Typ oder enthält er ein Objekt mit einem solchen Typ, wird eine ValueError-Ausnahme ausgelöst — es werden dann aber auch unbrauchbare Daten in die Datei geschrieben. Das Objekt lässt sich mit load() nicht korrekt wieder einlesen. Code-Objekte werden nur unterstützt, wenn allow_code wahr ist.

Das Argument version gibt an, welches Datenformat 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. Wird kein gültiger Wert gelesen, etwa weil die Daten im inkompatiblen marshal-Format einer anderen Python-Version vorliegen, wird EOFError, ValueError oder TypeError ausgelöst. Code-Objekte werden nur unterstützt, wenn allow_code wahr ist. Die Datei muss eine lesbare Binärdatei sein.

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

Bemerkung

Wurde ein Objekt, das einen nicht unterstützten Typ enthält, mit dump() geschrieben, setzt load() an die Stelle dieses Typs None.

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

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

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

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

Das Argument version gibt an, welches Datenformat 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)

Wandelt das byte-ähnliche Objekt in einen Wert um. Wird kein gültiger Wert gefunden, wird EOFError, ValueError oder TypeError ausgelöst. Code-Objekte werden nur unterstützt, wenn allow_code wahr 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 für jedes Code-Objekt ein code.__new__-Audit-Ereignis aus. Jetzt löst er für den gesamten Ladevorgang ein einzelnes marshal.loads-Ereignis aus.

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

Außerdem sind die folgenden Konstanten definiert:

marshal.version

Gibt das Format an, das das Modul verwendet. Version 0 ist die historisch erste Version, die späteren Versionen bringen jeweils neue Features hinzu. In der Regel wird eine neue Version mit ihrer Einführung zur Voreinstellung.

Version

Verfügbar ab

Neue Features

1

Python 2.4

Gemeinsame Nutzung internierter Zeichenketten

2

Python 2.5

Binärdarstellung von Gleitkommazahlen

3

Python 3.4

Unterstützung für Objektinstanzierung und Rekursion

4

Python 3.4

Effiziente Darstellung kurzer Zeichenketten

5

Python 3.14

Unterstützung für slice-Objekte

6

Python 3.15

Unterstützung für frozendict-Objekte

Fußnoten