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 70.. function:: load(file) 71 72 Read one value from the open file and return it. If no valid value is read 73 (e.g. because the data has a different Python version's incompatible marshal 74 format), raise :exc:`EOFError`, :exc:`ValueError` or :exc:`TypeError`. The 75 file must be a readable :term:`binary file`. 76 77 .. note:: 78 79 If an object containing an unsupported type was marshalled with :func:`dump`, 80 :func:`load` will substitute ``None`` for the unmarshallable type. 81 82 83.. function:: dumps(value[, version]) 84 85 Return the bytes object that would be written to a file by ``dump(value, file)``. The 86 value must be a supported type. Raise a :exc:`ValueError` exception if value 87 has (or contains an object that has) an unsupported type. 88 89 The *version* argument indicates the data format that ``dumps`` should use 90 (see below). 91 92 93.. function:: loads(bytes) 94 95 Convert the :term:`bytes-like object` to a value. If no valid value is found, raise 96 :exc:`EOFError`, :exc:`ValueError` or :exc:`TypeError`. Extra bytes in the 97 input are ignored. 98 99 100In addition, the following constants are defined: 101 102.. data:: version 103 104 Indicates the format that the module uses. Version 0 is the historical 105 format, version 1 shares interned strings and version 2 uses a binary format 106 for floating point numbers. 107 Version 3 adds support for object instancing and recursion. 108 The current version is 4. 109 110 111.. rubric:: Footnotes 112 113.. [#] The name of this module stems from a bit of terminology used by the designers of 114 Modula-3 (amongst others), who use the term "marshalling" for shipping of data 115 around in a self-contained form. Strictly speaking, "to marshal" means to 116 convert some data from internal to external form (in an RPC buffer for instance) 117 and "unmarshalling" for the reverse process. 118 119