summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libmarshal.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/lib/libmarshal.tex')
-rw-r--r--Doc/lib/libmarshal.tex117
1 files changed, 0 insertions, 117 deletions
diff --git a/Doc/lib/libmarshal.tex b/Doc/lib/libmarshal.tex
deleted file mode 100644
index 63ff392..0000000
--- a/Doc/lib/libmarshal.tex
+++ /dev/null
@@ -1,117 +0,0 @@
-\section{\module{marshal} ---
- Internal Python object serialization}
-
-\declaremodule{builtin}{marshal}
-\modulesynopsis{Convert Python objects to streams of bytes and back
- (with different constraints).}
-
-
-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 ``persistence'' module. For general persistence
-and transfer of Python objects through RPC calls, see the modules
-\refmodule{pickle} and \refmodule{shelve}. The \module{marshal} module exists
-mainly to support reading and writing the ``pseudo-compiled'' code for
-Python modules of \file{.pyc} files. Therefore, the Python
-maintainers reserve the right to modify the marshal format in backward
-incompatible ways should the need arise. If you're serializing and
-de-serializing Python objects, use the \module{pickle} module instead.
-\refstmodindex{pickle}
-\refstmodindex{shelve}
-\obindex{code}
-
-\begin{notice}[warning]
-The \module{marshal} module is not intended to be secure against
-erroneous or maliciously constructed data. Never unmarshal data
-received from an untrusted or unauthenticated source.
-\end{notice}
-
-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, Unicode objects, 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.
-If such an integer is marshaled and read back in on a machine where
-C's \code{long int} type has only 32 bits, a Python long integer object
-is returned instead. While of a different type, the numeric value is
-the same. (This behavior is new in Python 2.2. In earlier versions,
-all but the least-significant 32 bits of the value were lost, and a
-warning message was printed.)
-
-There are functions that read/write files as well as functions
-operating on strings.
-
-The module defines these functions:
-
-\begin{funcdesc}{dump}{value, file\optional{, version}}
- 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()}. It must be opened in binary mode
- (\code{'wb'} or \code{'w+b'}).
-
- 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()}.
-
- \versionadded[The \var{version} argument indicates the data
- format that \code{dump} should use (see below)]{2.4}
-\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 opened
- in binary mode (\code{'rb'} or \code{'r+b'}).
-
- \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\optional{, version}}
- 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.
-
- \versionadded[The \var{version} argument indicates the data
- format that \code{dumps} should use (see below)]{2.4}
-\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}
-
-In addition, the following constants are defined:
-
-\begin{datadesc}{version}
- Indicates the format that the module uses. Version 0 is the
- historical format, version 1 (added in Python 2.4) shares interned
- strings and version 2 (added in Python 2.5) uses a binary format for
- floating point numbers. The current version is 2.
-
- \versionadded{2.4}
-\end{datadesc}