Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame^] | 1 | \section{\module{marshal} --- |
| 2 | Python object serialization (with different constraints).} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | \declaremodule{builtin}{marshal} |
| 4 | |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame^] | 5 | \modulesynopsis{Convert Python objects to streams of bytes and back |
| 6 | (with different constraints).} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 7 | |
Fred Drake | 0c2af2b | 1998-03-08 06:28:00 +0000 | [diff] [blame] | 8 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 9 | This module contains functions that can read and write Python |
| 10 | values in a binary format. The format is specific to Python, but |
| 11 | independent of machine architecture issues (e.g., you can write a |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 12 | Python value to a file on a PC, transport the file to a Sun, and read |
| 13 | it back there). Details of the format are undocumented on purpose; |
| 14 | it may change between Python versions (although it rarely does).% |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 15 | \footnote{The name of this module stems from a bit of terminology used |
| 16 | by the designers of Modula-3 (amongst others), who use the term |
| 17 | ``marshalling'' for shipping of data around in a self-contained form. |
| 18 | Strictly speaking, ``to marshal'' means to convert some data from |
| 19 | internal to external form (in an RPC buffer for instance) and |
| 20 | ``unmarshalling'' for the reverse process.} |
| 21 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 22 | This is not a general ``persistency'' module. For general persistency |
| 23 | and transfer of Python objects through RPC calls, see the modules |
Fred Drake | 7506298 | 1998-02-16 20:40:37 +0000 | [diff] [blame] | 24 | \module{pickle} and \module{shelve}. The \module{marshal} module exists |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 25 | mainly to support reading and writing the ``pseudo-compiled'' code for |
Fred Drake | 7506298 | 1998-02-16 20:40:37 +0000 | [diff] [blame] | 26 | Python modules of \file{.pyc} files. |
Fred Drake | 54820dc | 1997-12-15 21:56:05 +0000 | [diff] [blame] | 27 | \refstmodindex{pickle} |
| 28 | \refstmodindex{shelve} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 29 | \obindex{code} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 30 | |
| 31 | Not all Python object types are supported; in general, only objects |
| 32 | whose value is independent from a particular invocation of Python can |
| 33 | be written and read by this module. The following types are supported: |
| 34 | \code{None}, integers, long integers, floating point numbers, |
| 35 | strings, tuples, lists, dictionaries, and code objects, where it |
| 36 | should be understood that tuples, lists and dictionaries are only |
| 37 | supported as long as the values contained therein are themselves |
| 38 | supported; and recursive lists and dictionaries should not be written |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 39 | (they will cause infinite loops). |
| 40 | |
Fred Drake | af8a015 | 1998-01-14 14:51:31 +0000 | [diff] [blame] | 41 | \strong{Caveat:} On machines where C's \code{long int} type has more than |
Guido van Rossum | 93cf55e | 1995-09-13 17:35:28 +0000 | [diff] [blame] | 42 | 32 bits (such as the DEC Alpha), it |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 43 | is possible to create plain Python integers that are longer than 32 |
Fred Drake | 7506298 | 1998-02-16 20:40:37 +0000 | [diff] [blame] | 44 | bits. Since the current \module{marshal} module uses 32 bits to |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 45 | transfer plain Python integers, such values are silently truncated. |
| 46 | This particularly affects the use of very long integer literals in |
| 47 | Python modules --- these will be accepted by the parser on such |
| 48 | machines, but will be silently be truncated when the module is read |
Fred Drake | 7506298 | 1998-02-16 20:40:37 +0000 | [diff] [blame] | 49 | from the \file{.pyc} instead.% |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 50 | \footnote{A solution would be to refuse such literals in the parser, |
| 51 | since they are inherently non-portable. Another solution would be to |
Fred Drake | 7506298 | 1998-02-16 20:40:37 +0000 | [diff] [blame] | 52 | let the \module{marshal} module raise an exception when an integer |
| 53 | value would be truncated. At least one of these solutions will be |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 54 | implemented in a future version.} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 55 | |
| 56 | There are functions that read/write files as well as functions |
| 57 | operating on strings. |
| 58 | |
| 59 | The module defines these functions: |
| 60 | |
Fred Drake | 0c2af2b | 1998-03-08 06:28:00 +0000 | [diff] [blame] | 61 | \begin{funcdesc}{dump}{value, file} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 62 | Write the value on the open file. The value must be a supported |
| 63 | type. The file must be an open file object such as |
Fred Drake | 7506298 | 1998-02-16 20:40:37 +0000 | [diff] [blame] | 64 | \code{sys.stdout} or returned by \function{open()} or |
| 65 | \function{posix.popen()}. |
| 66 | |
Guido van Rossum | bbb1e26 | 1996-06-26 20:20:57 +0000 | [diff] [blame] | 67 | If the value has (or contains an object that has) an unsupported type, |
Fred Drake | 0c2af2b | 1998-03-08 06:28:00 +0000 | [diff] [blame] | 68 | a \exception{ValueError} exception is raised --- but garbage data |
Fred Drake | 7506298 | 1998-02-16 20:40:37 +0000 | [diff] [blame] | 69 | will also be written to the file. The object will not be properly |
| 70 | read back by \function{load()}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 71 | \end{funcdesc} |
| 72 | |
| 73 | \begin{funcdesc}{load}{file} |
| 74 | Read one value from the open file and return it. If no valid value |
Fred Drake | 7506298 | 1998-02-16 20:40:37 +0000 | [diff] [blame] | 75 | is read, raise \exception{EOFError}, \exception{ValueError} or |
| 76 | \exception{TypeError}. The file must be an open file object. |
Guido van Rossum | bbb1e26 | 1996-06-26 20:20:57 +0000 | [diff] [blame] | 77 | |
Fred Drake | 0c2af2b | 1998-03-08 06:28:00 +0000 | [diff] [blame] | 78 | \strong{Warning:} If an object containing an unsupported type was |
| 79 | marshalled with \function{dump()}, \function{load()} will substitute |
Fred Drake | 7506298 | 1998-02-16 20:40:37 +0000 | [diff] [blame] | 80 | \code{None} for the unmarshallable type. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 81 | \end{funcdesc} |
| 82 | |
| 83 | \begin{funcdesc}{dumps}{value} |
| 84 | Return the string that would be written to a file by |
Fred Drake | 7506298 | 1998-02-16 20:40:37 +0000 | [diff] [blame] | 85 | \code{dump(\var{value}, \var{file})}. The value must be a supported |
| 86 | type. Raise a \exception{ValueError} exception if value has (or |
| 87 | contains an object that has) an unsupported type. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 88 | \end{funcdesc} |
| 89 | |
| 90 | \begin{funcdesc}{loads}{string} |
| 91 | Convert the string to a value. If no valid value is found, raise |
Fred Drake | 7506298 | 1998-02-16 20:40:37 +0000 | [diff] [blame] | 92 | \exception{EOFError}, \exception{ValueError} or |
| 93 | \exception{TypeError}. Extra characters in the string are ignored. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 94 | \end{funcdesc} |