marshal — Internal Python object serialization¶

This module contains functions that can read and write Python values in a binaryformat. The format is specific to Python, but independent of machinearchitecture issues (e.g., you can write a Python value to a file on a PC,transport the file to a Mac, and read it back there). Details of the format areundocumented on purpose; it may change between Python versions (although itrarely does).[1]

This is not a general “persistence” module. For general persistence andtransfer of Python objects through RPC calls, see the modulespickle andshelve. Themarshal module exists mainly to support reading andwriting the “pseudo-compiled” code for Python modules of.pyc files.Therefore, the Python maintainers reserve the right to modify the marshal formatin backward incompatible ways should the need arise.The format of code objects is not compatible between Python versions,even if the version of the format is the same.De-serializing a code object in the incorrect Python version has undefined behavior.If you’re serializing andde-serializing Python objects, use thepickle module instead – theperformance is comparable, version independence is guaranteed, and picklesupports a substantially wider range of objects than marshal.

Not all Python object types are supported; in general, only objects whose valueis independent from a particular invocation of Python can be written and read bythis module. The following types are supported: booleans, integers, floating-pointnumbers, complex numbers, strings, bytes, bytearrays, tuples, lists, sets,frozensets, dictionaries, and code objects (ifallow_code is true),where it should be understood thattuples, lists, sets, frozensets and dictionaries are only supported as long asthe values contained therein are themselves supported. ThesingletonsNone,Ellipsis andStopIteration can also bemarshalled and unmarshalled.For formatversion lower than 3, recursive lists, sets and dictionaries cannotbe written (see below).

There are functions that read/write files as well as functions operating onbytes-like objects.

The module defines these functions:

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

Write the value on the open file. The value must be a supported type. Thefile must be a writeablebinary file.

If the value has (or contains an object that has) an unsupported type, aValueError exception is raised — but garbage data will also be writtento the file. The object will not be properly read back byload().Code objects are only supported ifallow_code is true.

Theversion argument indicates the data format thatdump should use(see below).

Raises anauditing eventmarshal.dumps with argumentsvalue,version.

Changed in version 3.13:Added theallow_code parameter.

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

Read one value from the open file and return it. If no valid value is read(e.g. because the data has a different Python version’s incompatible marshalformat), raiseEOFError,ValueError orTypeError.Code objects are only supported ifallow_code is true.The file must be a readablebinary file.

Raises anauditing eventmarshal.load with no arguments.

Note

If an object containing an unsupported type was marshalled withdump(),load() will substituteNone for the unmarshallable type.

Changed in version 3.10:This call used to raise acode.__new__ audit event for each code object. Nowit raises a singlemarshal.load event for the entire load operation.

Changed in version 3.13:Added theallow_code parameter.

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

Return the bytes object that would be written to a file bydump(value,file). Thevalue must be a supported type. Raise aValueError exception if valuehas (or contains an object that has) an unsupported type.Code objects are only supported ifallow_code is true.

Theversion argument indicates the data format thatdumps should use(see below).

Raises anauditing eventmarshal.dumps with argumentsvalue,version.

Changed in version 3.13:Added theallow_code parameter.

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

Convert thebytes-like object to a value. If no valid value is found, raiseEOFError,ValueError orTypeError.Code objects are only supported ifallow_code is true.Extra bytes in the input are ignored.

Raises anauditing eventmarshal.loads with argumentbytes.

Changed in version 3.10:This call used to raise acode.__new__ audit event for each code object. Nowit raises a singlemarshal.loads event for the entire load operation.

Changed in version 3.13:Added theallow_code parameter.

In addition, the following constants are defined:

marshal.version¶

Indicates the format that the module uses. Version 0 is the historicalformat, version 1 shares interned strings and version 2 uses a binary formatfor floating-point numbers.Version 3 adds support for object instancing and recursion.The current version is 4.

Footnotes

The name of this module stems from a bit of terminology used by the designers ofModula-3 (amongst others), who use the term “marshalling” for shipping of dataaround in a self-contained form. Strictly speaking, “to marshal” means toconvert some data from internal to external form (in an RPC buffer for instance)and “unmarshalling” for the reverse process.