diff options
Diffstat (limited to 'Doc/lib/libmarshal.tex')
| -rw-r--r-- | Doc/lib/libmarshal.tex | 32 |
1 files changed, 28 insertions, 4 deletions
diff --git a/Doc/lib/libmarshal.tex b/Doc/lib/libmarshal.tex index 2b0a400..319c195 100644 --- a/Doc/lib/libmarshal.tex +++ b/Doc/lib/libmarshal.tex @@ -4,9 +4,9 @@ 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 VAX, transport the file to a Mac, and read -it back there). Details of the format not explained here; read the -source if you're interested.% +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. @@ -14,6 +14,14 @@ 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 +\code{pickle} and \code{shelve}. The \code{marshal} module exists +mainly to support reading and writing the ``pseudo-compiled'' code for +Python modules of \samp{.pyc} files. +\stmodindex{pickle} +\stmodindex{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 @@ -23,7 +31,22 @@ 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 an infinite loop). +(they will cause infinite loops). + +{\bf Caveat:} On machines where C's \code{long int} type has more than +32 bits (such as the DEC Alpha or the HP Precision Architecture), it +is possible to create plain Python integers that are longer than 32 +bits. Since the current \code{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 \code{.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 \code{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. @@ -31,6 +54,7 @@ operating on strings. The module defines these functions: \renewcommand{\indexsubitem}{(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 |