diff options
Diffstat (limited to 'Doc/libmarshal.tex')
-rw-r--r-- | Doc/libmarshal.tex | 90 |
1 files changed, 0 insertions, 90 deletions
diff --git a/Doc/libmarshal.tex b/Doc/libmarshal.tex deleted file mode 100644 index 5878cfa..0000000 --- a/Doc/libmarshal.tex +++ /dev/null @@ -1,90 +0,0 @@ -\section{Built-in Module \module{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: - -\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. - - \strong{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} |