1:mod:`marshal` --- Internal Python object serialization 2======================================================= 3 4.. module:: marshal 5 :synopsis: Convert Python objects to streams of bytes and back (with different 6 constraints). 7 8-------------- 9 10This module contains functions that can read and write Python values in a binary 11format. The format is specific to Python, but independent of machine 12architecture issues (e.g., you can write a Python value to a file on a PC, 13transport the file to a Sun, and read it back there). Details of the format are 14undocumented on purpose; it may change between Python versions (although it 15rarely does). [#]_ 16 17.. index:: 18 module: pickle 19 module: shelve 20 21This is not a general "persistence" module. For general persistence and 22transfer of Python objects through RPC calls, see the modules :mod:`pickle` and 23:mod:`shelve`. The :mod:`marshal` module exists mainly to support reading and 24writing the "pseudo-compiled" code for Python modules of :file:`.pyc` files. 25Therefore, the Python maintainers reserve the right to modify the marshal format 26in backward incompatible ways should the need arise. If you're serializing and 27de-serializing Python objects, use the :mod:`pickle` module instead -- the 28performance is comparable, version independence is guaranteed, and pickle 29supports a substantially wider range of objects than marshal. 30 31.. warning:: 32 33 The :mod:`marshal` module is not intended to be secure against erroneous or 34 maliciously constructed data. Never unmarshal data received from an 35 untrusted or unauthenticated source. 36 37.. index:: object; code, code object 38 39Not all Python object types are supported; in general, only objects whose value 40is independent from a particular invocation of Python can be written and read by 41this module. The following types are supported: booleans, integers, floating 42point numbers, complex numbers, strings, bytes, bytearrays, tuples, lists, sets, 43frozensets, dictionaries, and code objects, where it should be understood that 44tuples, lists, sets, frozensets and dictionaries are only supported as long as 45the values contained therein are themselves supported. The 46singletons :const:`None`, :const:`Ellipsis` and :exc:`StopIteration` can also be 47marshalled and unmarshalled. 48For format *version* lower than 3, recursive lists, sets and dictionaries cannot 49be written (see below). 50 51There are functions that read/write files as well as functions operating on 52bytes-like objects. 53 54The module defines these functions: 55 56 57.. function:: dump(value, file[, version]) 58 59 Write the value on the open file. The value must be a supported type. The 60 file must be a writeable :term:`binary file`. 61 62 If the value has (or contains an object that has) an unsupported type, a 63 :exc:`ValueError` exception is raised --- but garbage data will also be written 64 to the file. The object will not be properly read back by :func:`load`. 65 66 The *version* argument indicates the data format that ``dump`` should use 67 (see below). 68 69 .. audit-event:: marshal.dumps value,version marshal.dump 70 71 72.. function:: load(file) 73 74 Read one value from the open file and return it. If no valid value is read 75 (e.g. because the data has a different Python version's incompatible marshal 76 format), raise :exc:`EOFError`, :exc:`ValueError` or :exc:`TypeError`. The 77 file must be a readable :term:`binary file`. 78 79 .. audit-event:: marshal.load "" marshal.load 80 81 .. note:: 82 83 If an object containing an unsupported type was marshalled with :func:`dump`, 84 :func:`load` will substitute ``None`` for the unmarshallable type. 85 86 .. versionchanged:: 3.10 87 88 This call used to raise a ``code.__new__`` audit event for each code object. Now 89 it raises a single ``marshal.load`` event for the entire load operation. 90 91 92.. function:: dumps(value[, version]) 93 94 Return the bytes object that would be written to a file by ``dump(value, file)``. The 95 value must be a supported type. Raise a :exc:`ValueError` exception if value 96 has (or contains an object that has) an unsupported type. 97 98 The *version* argument indicates the data format that ``dumps`` should use 99 (see below). 100 101 .. audit-event:: marshal.dumps value,version marshal.dump 102 103 104.. function:: loads(bytes) 105 106 Convert the :term:`bytes-like object` to a value. If no valid value is found, raise 107 :exc:`EOFError`, :exc:`ValueError` or :exc:`TypeError`. Extra bytes in the 108 input are ignored. 109 110 .. audit-event:: marshal.loads bytes marshal.load 111 112 .. versionchanged:: 3.10 113 114 This call used to raise a ``code.__new__`` audit event for each code object. Now 115 it raises a single ``marshal.loads`` event for the entire load operation. 116 117 118In addition, the following constants are defined: 119 120.. data:: version 121 122 Indicates the format that the module uses. Version 0 is the historical 123 format, version 1 shares interned strings and version 2 uses a binary format 124 for floating point numbers. 125 Version 3 adds support for object instancing and recursion. 126 The current version is 4. 127 128 129.. rubric:: Footnotes 130 131.. [#] The name of this module stems from a bit of terminology used by the designers of 132 Modula-3 (amongst others), who use the term "marshalling" for shipping of data 133 around in a self-contained form. Strictly speaking, "to marshal" means to 134 convert some data from internal to external form (in an RPC buffer for instance) 135 and "unmarshalling" for the reverse process. 136 137