Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame^] | 1 | \section{Built-in Module \sectcode{marshal}} |
| 2 | |
| 3 | \bimodindex{marshal} |
| 4 | This module contains functions that can read and write Python |
| 5 | values in a binary format. The format is specific to Python, but |
| 6 | independent of machine architecture issues (e.g., you can write a |
| 7 | Python value to a file on a VAX, transport the file to a Mac, and read |
| 8 | it back there). Details of the format not explained here; read the |
| 9 | source if you're interested.% |
| 10 | \footnote{The name of this module stems from a bit of terminology used |
| 11 | by the designers of Modula-3 (amongst others), who use the term |
| 12 | ``marshalling'' for shipping of data around in a self-contained form. |
| 13 | Strictly speaking, ``to marshal'' means to convert some data from |
| 14 | internal to external form (in an RPC buffer for instance) and |
| 15 | ``unmarshalling'' for the reverse process.} |
| 16 | |
| 17 | |
| 18 | Not all Python object types are supported; in general, only objects |
| 19 | whose value is independent from a particular invocation of Python can |
| 20 | be written and read by this module. The following types are supported: |
| 21 | \code{None}, integers, long integers, floating point numbers, |
| 22 | strings, tuples, lists, dictionaries, and code objects, where it |
| 23 | should be understood that tuples, lists and dictionaries are only |
| 24 | supported as long as the values contained therein are themselves |
| 25 | supported; and recursive lists and dictionaries should not be written |
| 26 | (they will cause an infinite loop). |
| 27 | |
| 28 | There are functions that read/write files as well as functions |
| 29 | operating on strings. |
| 30 | |
| 31 | The module defines these functions: |
| 32 | |
| 33 | \renewcommand{\indexsubitem}{(in module marshal)} |
| 34 | \begin{funcdesc}{dump}{value\, file} |
| 35 | Write the value on the open file. The value must be a supported |
| 36 | type. The file must be an open file object such as |
| 37 | \code{sys.stdout} or returned by \code{open()} or |
| 38 | \code{posix.popen()}. |
| 39 | |
| 40 | If the value has an unsupported type, garbage is written which cannot |
| 41 | be read back by \code{load()}. |
| 42 | \end{funcdesc} |
| 43 | |
| 44 | \begin{funcdesc}{load}{file} |
| 45 | Read one value from the open file and return it. If no valid value |
| 46 | is read, raise \code{EOFError}, \code{ValueError} or |
| 47 | \code{TypeError}. The file must be an open file object. |
| 48 | \end{funcdesc} |
| 49 | |
| 50 | \begin{funcdesc}{dumps}{value} |
| 51 | Return the string that would be written to a file by |
| 52 | \code{dump(value, file)}. The value must be a supported type. |
| 53 | \end{funcdesc} |
| 54 | |
| 55 | \begin{funcdesc}{loads}{string} |
| 56 | Convert the string to a value. If no valid value is found, raise |
| 57 | \code{EOFError}, \code{ValueError} or \code{TypeError}. Extra |
| 58 | characters in the string are ignored. |
| 59 | \end{funcdesc} |