Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libxdrlib.tex @ 4566:6403c94de50d legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added safeguard against failure in __del__.
author Guido van Rossum <guido@python.org>
date Wed, 27 Nov 1996 19:39:58 +0000
parents e7ba092c3cf3
children e3f71ce8e6bb
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Standard module \sectcode{xdrlib}}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
2 \stmodindex{xdrlib}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \index{XDR}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
4
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
5 \renewcommand{\indexsubitem}{(in module xdrlib)}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
6
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 The \code{xdrlib} module supports the External Data Representation
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 Standard as described in RFC 1014, written by Sun Microsystems,
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 Inc. June 1987. It supports most of the data types described in the
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 RFC, although some, most notably \code{float} and \code{double} are
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 only supported on those operating systems that provide an XDR
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 library.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
14
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 The \code{xdrlib} module defines two classes, one for packing
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 variables into XDR representation, and another for unpacking from XDR
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 representation. There are also two exception classes.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
18
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
19
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 \subsection{Packer Objects}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
21
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 \code{Packer} is the class for packing data into XDR representation.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 The \code{Packer} class is instantiated with no arguments.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
24
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 \begin{funcdesc}{get_buffer}{}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 Returns the current pack buffer as a string.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
28
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 \begin{funcdesc}{reset}{}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 Resets the pack buffer to the empty string.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
32
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 In general, you can pack any of the most common XDR data types by
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 calling the appropriate \code{pack_\var{type}} method. Each method
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 takes a single argument, the value to pack. The following simple data
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 type packing methods are supported: \code{pack_uint}, \code{pack_int},
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 \code{pack_enum}, \code{pack_bool}, \code{pack_uhyper},
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 and \code{pack_hyper}.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
39
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 The following methods pack floating point numbers, however they
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 require C library support. Without the optional C built-in module,
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
42 both of these methods will raise an \code{xdrlib.ConversionError}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 exception. See the note at the end of this chapter for details.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 \begin{funcdesc}{pack_float}{value}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 Packs the single-precision floating point number \var{value}.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
48
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 \begin{funcdesc}{pack_double}{value}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 Packs the double-precision floating point number \var{value}.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
52
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 The following methods support packing strings, bytes, and opaque data:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
54
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 \begin{funcdesc}{pack_fstring}{n\, s}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 Packs a fixed length string, \var{s}. \var{n} is the length of the
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 string but it is \emph{not} packed into the data buffer. The string
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 is padded with null bytes if necessary to guaranteed 4 byte alignment.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
60
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 \begin{funcdesc}{pack_fopaque}{n\, data}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 Packs a fixed length opaque data stream, similarly to
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 \code{pack_fstring}.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
65
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 \begin{funcdesc}{pack_string}{s}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 Packs a variable length string, \var{s}. The length of the string is
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 first packed as an unsigned integer, then the string data is packed
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 with \code{pack_fstring}.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
71
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 \begin{funcdesc}{pack_opaque}{data}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 Packs a variable length opaque data string, similarly to
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 \code{pack_string}.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
76
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 \begin{funcdesc}{pack_bytes}{bytes}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 Packs a variable length byte stream, similarly to \code{pack_string}.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
79 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
80
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
81 The following methods support packing arrays and lists:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
82
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
83 \begin{funcdesc}{pack_list}{list\, pack_item}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
84 Packs a \var{list} of homogeneous items. This method is useful for
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
85 lists with an indeterminate size; i.e. the size is not available until
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
86 the entire list has been walked. For each item in the list, an
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
87 unsigned integer \code{1} is packed first, followed by the data value
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 from the list. \var{pack_item} is the function that is called to pack
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
89 the individual item. At the end of the list, an unsigned integer
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
90 \code{0} is packed.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
91 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
92
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
93 \begin{funcdesc}{pack_farray}{n\, array\, pack_item}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 Packs a fixed length list (\var{array}) of homogeneous items. \var{n}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
95 is the length of the list; it is \emph{not} packed into the buffer,
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
96 but a \code{ValueError} exception is raised if \code{len(array)} is not
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
97 equal to \var{n}. As above, \var{pack_item} is the function used to
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
98 pack each element.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
99 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
100
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
101 \begin{funcdesc}{pack_array}{list\, pack_item}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
102 Packs a variable length \var{list} of homogeneous items. First, the
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
103 length of the list is packed as an unsigned integer, then each element
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
104 is packed as in \code{pack_farray} above.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
105 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
106
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
107 \subsection{Unpacker Objects}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
108
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
109 \code{Unpacker} is the complementary class which unpacks XDR data
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
110 values from a string buffer, and has the following methods:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
111
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
112 \begin{funcdesc}{__init__}{data}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
113 Instantiates an \code{Unpacker} object with the string buffer
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
114 \var{data}.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
115 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
116
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
117 \begin{funcdesc}{reset}{data}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
118 Resets the string buffer with the given \var{data}.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
119 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
120
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
121 \begin{funcdesc}{get_position}{}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
122 Returns the current unpack position in the data buffer.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
124
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
125 \begin{funcdesc}{set_position}{position}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
126 Sets the data buffer unpack position to \var{position}. You should be
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
127 careful about using \code{get_position()} and \code{set_position()}.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
128 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
129
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
130 \begin{funcdesc}{done}{}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
131 Indicates unpack completion. Raises an \code{xdrlib.Error} exception
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
132 if all of the data has not been unpacked.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
133 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
134
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
135 In addition, every data type that can be packed with a \code{Packer},
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 can be unpacked with an \code{Unpacker}. Unpacking methods are of the
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
137 form \code{unpack_\var{type}}, and take no arguments. They return the
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
138 unpacked object. The same caveats apply for \code{unpack_float} and
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
139 \code{unpack_double} as above.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
140
4339
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
141 \begin{funcdesc}{unpack_float}{}
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
142 Unpacks a single-precision floating point number.
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
143 \end{funcdesc}
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
144
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
145 \begin{funcdesc}{unpack_double}{}
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
146 Unpacks a double-precision floating point number, similarly to
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
147 \code{unpack_float}.
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
148 \end{funcdesc}
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
149
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
150 In addition, the following methods unpack strings, bytes, and opaque
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
151 data:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
152
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
153 \begin{funcdesc}{unpack_fstring}{n}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
154 Unpacks and returns a fixed length string. \var{n} is the number of
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
155 characters expected. Padding with null bytes to guaranteed 4 byte
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
156 alignment is assumed.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
157 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
158
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
159 \begin{funcdesc}{unpack_fopaque}{n}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
160 Unpacks and returns a fixed length opaque data stream, similarly to
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
161 \code{unpack_fstring}.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
162 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
163
4339
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
164 \begin{funcdesc}{unpack_string}{}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
165 Unpacks and returns a variable length string. The length of the
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
166 string is first unpacked as an unsigned integer, then the string data
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
167 is unpacked with \code{unpack_fstring}.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
168 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
169
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
170 \begin{funcdesc}{unpack_opaque}{}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
171 Unpacks and returns a variable length opaque data string, similarly to
4339
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
172 \code{unpack_string}.
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
173 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
174
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
175 \begin{funcdesc}{unpack_bytes}{}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
176 Unpacks and returns a variable length byte stream, similarly to
4339
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
177 \code{unpack_string}.
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
178 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
179
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
180 The following methods support unpacking arrays and lists:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
181
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
182 \begin{funcdesc}{unpack_list}{unpack_item}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
183 Unpacks and returns a list of homogeneous items. The list is unpacked
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
184 one element at a time
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
185 by first unpacking an unsigned integer flag. If the flag is \code{1},
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
186 then the item is unpacked and appended to the list. A flag of
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
187 \code{0} indicates the end of the list. \var{unpack_item} is the
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
188 function that is called to unpack the items.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
189 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
190
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
191 \begin{funcdesc}{unpack_farray}{n\, unpack_item}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
192 Unpacks and returns (as a list) a fixed length array of homogeneous
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
193 items. \var{n} is number of list elements to expect in the buffer.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
194 As above, \var{unpack_item} is the function used to unpack each element.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
195 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
196
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
197 \begin{funcdesc}{unpack_array}{unpack_item}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
198 Unpacks and returns a variable length \var{list} of homogeneous items.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
199 First, the length of the list is unpacked as an unsigned integer, then
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
200 each element is unpacked as in \code{unpack_farray} above.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
201 \end{funcdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
202
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
203 \subsection{Exceptions}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
204
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
205 Exceptions in this module are coded as class instances:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
206
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
207 \begin{excdesc}{Error}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
208 The base exception class. \code{Error} has a single public data
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
209 member \code{msg} containing the description of the error.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
210 \end{excdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
211
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
212 \begin{excdesc}{ConversionError}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
213 Class derived from \code{Error}. Contains no additional instance
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
214 variables.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
215 \end{excdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
216
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
217 Here is an example of how you would catch one of these exceptions:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
218
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
219 \begin{verbatim}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
220 import xdrlib
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
221 p = xdrlib.Packer()
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
222 try:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
223 p.pack_double(8.01)
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
224 except xdrlib.ConversionError, instance:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
225 print 'packing the double failed:', instance.msg
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
226 \end{verbatim}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
227
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
228 \subsection{Supporting Floating Point Data}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
229
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
230 Packing and unpacking floating point data,
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
231 i.e. \code{Packer.pack_float}, \code{Packer.pack_double},
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
232 \code{Unpacker.unpack_float}, and \code{Unpacker.unpack_double}, are
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
233 only supported with the helper built-in \code{_xdr} module, which
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
234 relies on your operating system having the appropriate XDR library
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
235 routines.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
236
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
237 If you have built the Python interpeter with the \code{_xdr} module,
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
238 or have built the \code{_xdr} module as a shared library,
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
239 \code{xdrlib} will use these to pack and unpack floating point
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
240 numbers. Otherwise, using these routines will raise a
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
241 \code{ConversionError} exception.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
242
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
243 See the Python installation instructions for details on building the
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
244 \code{_xdr} module.