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.

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

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:

• Numeric types:int,bool,float,complex.

• Strings (str) andbytes.Bytes-like objects likebytearray aremarshalled asbytes.

• Containers:tuple,list,set,frozenset,and (sinceversion 5),slice.It should be understood that these are supported only if the values containedtherein are themselves supported.Recursive containers are supported sinceversion 3.

• The singletonsNone,Ellipsis andStopIteration.

• code objects, ifallow_code is true. See note above aboutversion dependence.

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.

Άλλαξε στην έκδοση 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.

Σημείωση

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

Άλλαξε στην έκδοση 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.

Άλλαξε στην έκδοση 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.

Άλλαξε στην έκδοση 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.

Άλλαξε στην έκδοση 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.

Άλλαξε στην έκδοση 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 historical first version; subsequent versionsadd new features.Generally, a new version becomes the default when it is introduced.

Version	Available since	New features
1	Python 2.4	Sharing interned strings
2	Python 2.5	Binary representation of floats
3	Python 3.4	Support for object instancing and recursion
4	Python 3.4	Efficient representation of short strings
5	Python 3.14	Support forslice objects

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.