Mercurial > cpython-lru_cache-weakref

annotate Doc/libmarshal.tex @ 5817:48b94de85bf3 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Extensive changes by AMK.
author Guido van Rossum <guido@python.org>
date Thu, 17 Jul 1997 16:29:42 +0000
parents ba84d7e8554b
children 3468ea8645ca
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Built-in Module \sectcode{marshal}}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
2
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \bimodindex{marshal}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 This module contains functions that can read and write Python
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
5 values in a binary format. The format is specific to Python, but
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
6 independent of machine architecture issues (e.g., you can write a
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
7 Python value to a file on a PC, transport the file to a Sun, and read
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
8 it back there). Details of the format are undocumented on purpose;
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
9 it may change between Python versions (although it rarely does).%
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 \footnote{The name of this module stems from a bit of terminology used
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 by the designers of Modula-3 (amongst others), who use the term
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 ``marshalling'' for shipping of data around in a self-contained form.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 Strictly speaking, ``to marshal'' means to convert some data from
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 internal to external form (in an RPC buffer for instance) and
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 ``unmarshalling'' for the reverse process.}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
17 This is not a general ``persistency'' module. For general persistency
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
18 and transfer of Python objects through RPC calls, see the modules
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
19 \code{pickle} and \code{shelve}. The \code{marshal} module exists
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
20 mainly to support reading and writing the ``pseudo-compiled'' code for
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
21 Python modules of \samp{.pyc} files.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
22 \stmodindex{pickle}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
23 \stmodindex{shelve}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
24 \obindex{code}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 Not all Python object types are supported; in general, only objects
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 whose value is independent from a particular invocation of Python can
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 be written and read by this module. The following types are supported:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 \code{None}, integers, long integers, floating point numbers,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 strings, tuples, lists, dictionaries, and code objects, where it
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 should be understood that tuples, lists and dictionaries are only
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 supported as long as the values contained therein are themselves
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 supported; and recursive lists and dictionaries should not be written
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
34 (they will cause infinite loops).
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
35
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
36 {\bf Caveat:} On machines where C's \code{long int} type has more than
3082
87fea261a263 HP-Prec is not 64-bit
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
37 32 bits (such as the DEC Alpha), it
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
38 is possible to create plain Python integers that are longer than 32
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
39 bits. Since the current \code{marshal} module uses 32 bits to
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
40 transfer plain Python integers, such values are silently truncated.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
41 This particularly affects the use of very long integer literals in
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
42 Python modules --- these will be accepted by the parser on such
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
43 machines, but will be silently be truncated when the module is read
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
44 from the \code{.pyc} instead.%
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
45 \footnote{A solution would be to refuse such literals in the parser,
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
46 since they are inherently non-portable. Another solution would be to
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
47 let the \code{marshal} module raise an exception when an integer value
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
48 would be truncated. At least one of these solutions will be
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
49 implemented in a future version.}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 There are functions that read/write files as well as functions
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 operating on strings.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 The module defines these functions:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 \renewcommand{\indexsubitem}{(in module marshal)}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
57
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 \begin{funcdesc}{dump}{value\, file}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 Write the value on the open file. The value must be a supported
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 type. The file must be an open file object such as
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 \code{sys.stdout} or returned by \code{open()} or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 \code{posix.popen()}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
63
3730
ba84d7e8554b Add docs for planned improved handling of the marshalling of
Guido van Rossum <guido@python.org>
parents: 3082
diff changeset
64 If the value has (or contains an object that has) an unsupported type,
ba84d7e8554b Add docs for planned improved handling of the marshalling of
Guido van Rossum <guido@python.org>
parents: 3082
diff changeset
65 a \code{ValueError} exception is raised -- but garbage data will also
ba84d7e8554b Add docs for planned improved handling of the marshalling of
Guido van Rossum <guido@python.org>
parents: 3082
diff changeset
66 be written to the file. The object will not be properly read back by
ba84d7e8554b Add docs for planned improved handling of the marshalling of
Guido van Rossum <guido@python.org>
parents: 3082
diff changeset
67 \code{load()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
69
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 \begin{funcdesc}{load}{file}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 Read one value from the open file and return it. If no valid value
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 is read, raise \code{EOFError}, \code{ValueError} or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 \code{TypeError}. The file must be an open file object.
3730
ba84d7e8554b Add docs for planned improved handling of the marshalling of
Guido van Rossum <guido@python.org>
parents: 3082
diff changeset
74
ba84d7e8554b Add docs for planned improved handling of the marshalling of
Guido van Rossum <guido@python.org>
parents: 3082
diff changeset
75 Warning: If an object containing an unsupported type was marshalled
ba84d7e8554b Add docs for planned improved handling of the marshalling of
Guido van Rossum <guido@python.org>
parents: 3082
diff changeset
76 with \code{dump()}, \code{load()} will substitute \code{None} for the
ba84d7e8554b Add docs for planned improved handling of the marshalling of
Guido van Rossum <guido@python.org>
parents: 3082
diff changeset
77 unmarshallable type.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
79
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 \begin{funcdesc}{dumps}{value}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81 Return the string that would be written to a file by
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
82 \code{dump(value, file)}. The value must be a supported type.
3730
ba84d7e8554b Add docs for planned improved handling of the marshalling of
Guido van Rossum <guido@python.org>
parents: 3082
diff changeset
83 Raise a \code{ValueError} exception if value has (or contains an
ba84d7e8554b Add docs for planned improved handling of the marshalling of
Guido van Rossum <guido@python.org>
parents: 3082
diff changeset
84 object that has) an unsupported type.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
85 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
86
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
87 \begin{funcdesc}{loads}{string}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 Convert the string to a value. If no valid value is found, raise
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
89 \code{EOFError}, \code{ValueError} or \code{TypeError}. Extra
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
90 characters in the string are ignored.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
91 \end{funcdesc}