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