mirror of
https://github.com/python/cpython.git
synced 2024-11-29 00:56:12 +01:00
93 lines
4.2 KiB
TeX
93 lines
4.2 KiB
TeX
\section{Built-in Module \sectcode{marshal}}
|
|
\label{module-marshal}
|
|
|
|
\bimodindex{marshal}
|
|
This module contains functions that can read and write Python
|
|
values in a binary format. The format is specific to Python, but
|
|
independent of machine architecture issues (e.g., you can write a
|
|
Python value to a file on a PC, transport the file to a Sun, and read
|
|
it back there). Details of the format are undocumented on purpose;
|
|
it may change between Python versions (although it rarely does).%
|
|
\footnote{The name of this module stems from a bit of terminology used
|
|
by the designers of Modula-3 (amongst others), who use the term
|
|
``marshalling'' for shipping of data around in a self-contained form.
|
|
Strictly speaking, ``to marshal'' means to convert some data from
|
|
internal to external form (in an RPC buffer for instance) and
|
|
``unmarshalling'' for the reverse process.}
|
|
|
|
This is not a general ``persistency'' module. For general persistency
|
|
and transfer of Python objects through RPC calls, see the modules
|
|
\module{pickle} and \module{shelve}. The \module{marshal} module exists
|
|
mainly to support reading and writing the ``pseudo-compiled'' code for
|
|
Python modules of \file{.pyc} files.
|
|
\refstmodindex{pickle}
|
|
\refstmodindex{shelve}
|
|
\obindex{code}
|
|
|
|
Not all Python object types are supported; in general, only objects
|
|
whose value is independent from a particular invocation of Python can
|
|
be written and read by this module. The following types are supported:
|
|
\code{None}, integers, long integers, floating point numbers,
|
|
strings, tuples, lists, dictionaries, and code objects, where it
|
|
should be understood that tuples, lists and dictionaries are only
|
|
supported as long as the values contained therein are themselves
|
|
supported; and recursive lists and dictionaries should not be written
|
|
(they will cause infinite loops).
|
|
|
|
\strong{Caveat:} On machines where C's \code{long int} type has more than
|
|
32 bits (such as the DEC Alpha), it
|
|
is possible to create plain Python integers that are longer than 32
|
|
bits. Since the current \module{marshal} module uses 32 bits to
|
|
transfer plain Python integers, such values are silently truncated.
|
|
This particularly affects the use of very long integer literals in
|
|
Python modules --- these will be accepted by the parser on such
|
|
machines, but will be silently be truncated when the module is read
|
|
from the \file{.pyc} instead.%
|
|
\footnote{A solution would be to refuse such literals in the parser,
|
|
since they are inherently non-portable. Another solution would be to
|
|
let the \module{marshal} module raise an exception when an integer
|
|
value would be truncated. At least one of these solutions will be
|
|
implemented in a future version.}
|
|
|
|
There are functions that read/write files as well as functions
|
|
operating on strings.
|
|
|
|
The module defines these functions:
|
|
|
|
\setindexsubitem{(in module marshal)}
|
|
|
|
\begin{funcdesc}{dump}{value\, file}
|
|
Write the value on the open file. The value must be a supported
|
|
type. The file must be an open file object such as
|
|
\code{sys.stdout} or returned by \function{open()} or
|
|
\function{posix.popen()}.
|
|
|
|
If the value has (or contains an object that has) an unsupported type,
|
|
a \exception{ValueError} exception is raised -- but garbage data
|
|
will also be written to the file. The object will not be properly
|
|
read back by \function{load()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{load}{file}
|
|
Read one value from the open file and return it. If no valid value
|
|
is read, raise \exception{EOFError}, \exception{ValueError} or
|
|
\exception{TypeError}. The file must be an open file object.
|
|
|
|
Warning: If an object containing an unsupported type was marshalled
|
|
with \function{dump()}, \function{load()} will substitute
|
|
\code{None} for the unmarshallable type.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{dumps}{value}
|
|
Return the string that would be written to a file by
|
|
\code{dump(\var{value}, \var{file})}. The value must be a supported
|
|
type. Raise a \exception{ValueError} exception if value has (or
|
|
contains an object that has) an unsupported type.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{loads}{string}
|
|
Convert the string to a value. If no valid value is found, raise
|
|
\exception{EOFError}, \exception{ValueError} or
|
|
\exception{TypeError}. Extra characters in the string are ignored.
|
|
\end{funcdesc}
|