marshal — Intern serialisering av Python-objekt

---

Denna modul innehåller funktioner som kan läsa och skriva Python-värden i ett binärt format. Formatet är specifikt för Python, men oberoende av maskinarkitekturfrågor (t.ex. kan du skriva ett Python-värde till en fil på en PC, transportera filen till en Mac och läsa tillbaka den där). Detaljer om formatet är avsiktligt odokumenterade; det kan ändras mellan Python-versioner (även om det sällan gör det). [1]

Detta är inte en allmän ”persistens”-modul. För allmän persistens och överföring av Python-objekt genom RPC-anrop, se modulerna pickle och shelve. Modulen marshal existerar huvudsakligen för att stödja läsning och skrivning av den ”pseudokompilerade” koden för Python-moduler i .pyc-filer. Därför förbehåller sig Python-underhållarna rätten att modifiera marshal-formatet på bakåtkompatibla sätt om behov skulle uppstå. Formatet för kodobjekt är inte kompatibelt mellan Python-versioner, även om versionen av formatet är densamma. Att avserialisera ett kodobjekt i den felaktiga Python-versionen har ett odefinierat beteende. Om du ska serialisera och de-serialisera Python-objekt, använd pickle-modulen istället – prestandan är jämförbar, versionsoberoende garanteras och pickle stöder ett betydligt bredare utbud av objekt än marshal.

Varning

Modulen marshal är inte avsedd att vara säker mot felaktiga eller illvilligt konstruerade data. Unmarshala aldrig data som mottagits från en icke betrodd eller oautentiserad källa.

Det finns funktioner som läser/skriver filer samt funktioner som arbetar med bytesliknande objekt.

Inte alla Python-objekttyper stöds; i allmänhet kan endast objekt vars värde är oberoende av en viss anropning av Python skrivas och läsas av denna modul. Följande typer stöds:

• Numeriska typer: int, bool, float, complex.

• Strängar (str) och bytes. Bytes-like objects som bytearray marshallas som bytes.

• Innehåller: tuple, list, set, frozenset, och (sedan version 5), slice. Det bör förstås att dessa endast stöds om de värden som ingår i dem själva stöds. Rekursiva behållare stöds sedan version 3.

• Singletonerna None, Ellipsis och StopIteration.

• code-objekt, om allow_code är sant. Se anmärkning ovan om versionsberoende.

Ändrad i version 3.4:

• Lagt till formatversion 3, som stöder marshalling av rekursiva listor, set och dictionaries.

• Lagt till formatversion 4, som stöder effektiva representationer av korta strängar.

Ändrad i version 3.14: Lagt till formatversion 5, som tillåter marshalling av slices.

Modulen definierar dessa funktioner:

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

Skriv värdet på den öppna filen. Värdet måste vara av en typ som stöds. Filen måste vara en skrivbar binary file.

Om värdet har (eller innehåller ett objekt som har) en typ som inte stöds, kommer ett ValueError undantag att uppstå — men skräpdata kommer också att skrivas till filen. Objektet kommer inte att kunna läsas tillbaka korrekt av load(). Code objects stöds endast om allow_code är true.

Argumentet version anger det dataformat som dump ska använda (se nedan).

Utlöser en auditing-händelse marshal.dumps med argumenten value, version.

Ändrad i version 3.13: Parametern allow_code har lagts till.

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

Läser ett värde från den öppna filen och returnerar det. Om inget giltigt värde läses (t.ex. för att data har ett inkompatibelt marshal-format i en annan Python-version), anges EOFError, ValueError eller TypeError. Code objects stöds endast om allow_code är true. Filen måste vara en läsbar binary file.

Utlöser en auditing event marshal.load utan argument.

Anteckning

Om ett objekt som innehåller en typ som inte stöds marshallades med dump(), kommer load() att ersätta den icke marshallbara typen med None.

Ändrad i version 3.10: Detta anrop skapade tidigare en granskningshändelse code.__new__ för varje kodobjekt. Nu utlöser det en enda marshal.load-händelse för hela laddningsoperationen.

Ändrad i version 3.13: Parametern allow_code har lagts till.

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

Returnerar bytesobjektet som skulle skrivas till en fil med dump(value, file). Värdet måste vara en typ som stöds. Utlös ett ValueError undantag om värdet har (eller innehåller ett objekt som har) en typ som inte stöds. Code objects stöds endast om allow_code är true.

Argumentet version anger det dataformat som dumps ska använda (se nedan).

Utlöser en auditing-händelse marshal.dumps med argumenten value, version.

Ändrad i version 3.13: Parametern allow_code har lagts till.

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

Konverterar bytesliknande objekt till ett värde. Om inget giltigt värde hittas, skapa EOFError, ValueError eller TypeError. Code objects stöds endast om allow_code är true. Extra bytes i indata ignoreras.

Utlöser en auditing event marshal.loads med argumentet bytes.

Ändrad i version 3.10: Detta anrop skapade tidigare en granskningshändelse code.__new__ för varje kodobjekt. Nu utlöser det en enda marshal.loads-händelse för hela laddningsoperationen.

Ändrad i version 3.13: Parametern allow_code har lagts till.

Dessutom definieras följande konstanter:

marshal.version

Anger det format som modulen använder. Version 0 är den historiskt första versionen; efterföljande versioner lägger till nya funktioner. Generellt gäller att en ny version blir standard när den introduceras.

Version	Tillgänglig sedan	Nya funktioner
1	Python 2.4	Delning av internerade strängar
2	Python 2.5	Binär representation av flyttal
3	Python 3.4	Stöd för objektinstansiering och rekursion
4	Python 3.4	Effektiv representation av korta strängar
5	Python 3.14	Stöd för slice-objekt

Fotnoter

[1]

Namnet på den här modulen kommer från en terminologi som används av konstruktörerna av Modula-3 (bland andra), som använder termen ”marshalling” för att skicka runt data i en fristående form. Strängt taget innebär ”to marshalling” att konvertera data från intern till extern form (t.ex. i en RPC-buffert) och ”unmarshalling” innebär den omvända processen.