Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libxdrlib.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents 433187466901
children b3c8d9c472dc
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8867
diff changeset
1 \section{\module{xdrlib} ---
15141
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
2 Encode and decode XDR data}
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8056
diff changeset
4 \declaremodule{standard}{xdrlib}
8867
bb78cc27469a Clarify xdrlib synopsis.
Fred Drake <fdrake@acm.org>
parents: 8855
diff changeset
5 \modulesynopsis{Encoders and decoders for the External Data
15141
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
6 Representation (XDR).}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8056
diff changeset
7
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 \index{XDR}
7040
1c927ecfcbb3 For consistency, always use a trailing "()" on function names in the running
Fred Drake <fdrake@acm.org>
parents: 6905
diff changeset
9 \index{External Data Representation}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
10
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
11 The \module{xdrlib} module supports the External Data Representation
7219
640b97d105df Use the new RFC macros wherever RFCs are referenced by number. No other
Fred Drake <fdrake@acm.org>
parents: 7040
diff changeset
12 Standard as described in \rfc{1014}, written by Sun Microsystems,
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 Inc. June 1987. It supports most of the data types described in the
6525
5ccb12affb54 Removed obsolete discussion on _xdr helper module.
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
14 RFC.
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
16 The \module{xdrlib} module defines two classes, one for packing
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 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
18 representation. There are also two exception classes.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
19
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
20 \begin{classdesc}{Packer}{}
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
21 \class{Packer} is the class for packing data into XDR representation.
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
22 The \class{Packer} class is instantiated with no arguments.
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
23 \end{classdesc}
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
24
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
25 \begin{classdesc}{Unpacker}{data}
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
26 \code{Unpacker} is the complementary class which unpacks XDR data
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
27 values from a string buffer. The input buffer is given as
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
28 \var{data}.
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
29 \end{classdesc}
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
30
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
31
15141
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
32 \begin{seealso}
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
33 \seerfc{1014}{XDR: External Data Representation Standard}{This RFC
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
34 defined the encoding of data which was XDR at the time
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
35 this module was originally written. It has
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
36 appearantly been obsoleted by \rfc{1832}.}
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
37
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
38 \seerfc{1832}{XDR: External Data Representation Standard}{Newer RFC
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
39 that provides a revised definition of XDR.}
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
40 \end{seealso}
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
41
433187466901 Minor nit fixes based on suggestions from Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 10629
diff changeset
42
8867
bb78cc27469a Clarify xdrlib synopsis.
Fred Drake <fdrake@acm.org>
parents: 8855
diff changeset
43 \subsection{Packer Objects \label{xdr-packer-objects}}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
45 \class{Packer} instances have the following methods:
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
46
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
47 \begin{methoddesc}[Packer]{get_buffer}{}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 Returns the current pack buffer as a string.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
49 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
50
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
51 \begin{methoddesc}[Packer]{reset}{}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 Resets the pack buffer to the empty string.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
53 \end{methoddesc}
4047
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 In general, you can pack any of the most common XDR data types by
7040
1c927ecfcbb3 For consistency, always use a trailing "()" on function names in the running
Fred Drake <fdrake@acm.org>
parents: 6905
diff changeset
56 calling the appropriate \code{pack_\var{type}()} method. Each method
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 takes a single argument, the value to pack. The following simple data
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
58 type packing methods are supported: \method{pack_uint()},
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
59 \method{pack_int()}, \method{pack_enum()}, \method{pack_bool()},
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
60 \method{pack_uhyper()}, and \method{pack_hyper()}.
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
61
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
62 \begin{methoddesc}[Packer]{pack_float}{value}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 Packs the single-precision floating point number \var{value}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
64 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
65
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
66 \begin{methoddesc}[Packer]{pack_double}{value}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 Packs the double-precision floating point number \var{value}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
68 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
69
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 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
71
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
72 \begin{methoddesc}[Packer]{pack_fstring}{n, s}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 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
74 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
75 is padded with null bytes if necessary to guaranteed 4 byte alignment.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
76 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
77
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
78 \begin{methoddesc}[Packer]{pack_fopaque}{n, data}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
79 Packs a fixed length opaque data stream, similarly to
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
80 \method{pack_fstring()}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
81 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
82
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
83 \begin{methoddesc}[Packer]{pack_string}{s}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
84 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
85 first packed as an unsigned integer, then the string data is packed
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
86 with \method{pack_fstring()}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
87 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
88
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
89 \begin{methoddesc}[Packer]{pack_opaque}{data}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
90 Packs a variable length opaque data string, similarly to
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
91 \method{pack_string()}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
92 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
93
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
94 \begin{methoddesc}[Packer]{pack_bytes}{bytes}
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
95 Packs a variable length byte stream, similarly to \method{pack_string()}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
96 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
97
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
98 The following methods support packing arrays and lists:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
99
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
100 \begin{methoddesc}[Packer]{pack_list}{list, pack_item}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
101 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
102 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
103 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
104 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
105 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
106 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
107 \code{0} is packed.
10629
1bdea17bc471 Added example use of pack_list() to help explain the pack_item
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
108
1bdea17bc471 Added example use of pack_list() to help explain the pack_item
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
109 For example, to pack a list of integers, the code might appear like
1bdea17bc471 Added example use of pack_list() to help explain the pack_item
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
110 this:
1bdea17bc471 Added example use of pack_list() to help explain the pack_item
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
111
1bdea17bc471 Added example use of pack_list() to help explain the pack_item
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
112 \begin{verbatim}
1bdea17bc471 Added example use of pack_list() to help explain the pack_item
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
113 import xdrlib
1bdea17bc471 Added example use of pack_list() to help explain the pack_item
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
114 p = xdrlib.Packer()
1bdea17bc471 Added example use of pack_list() to help explain the pack_item
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
115 p.pack_list([1, 2, 3], p.pack_int)
1bdea17bc471 Added example use of pack_list() to help explain the pack_item
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
116 \end{verbatim}
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
117 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
118
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
119 \begin{methoddesc}[Packer]{pack_farray}{n, array, pack_item}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
120 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
121 is the length of the list; it is \emph{not} packed into the buffer,
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
122 but a \exception{ValueError} exception is raised if
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
123 \code{len(\var{array})} is not equal to \var{n}. As above,
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
124 \var{pack_item} is the function used to pack each element.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
125 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
126
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
127 \begin{methoddesc}[Packer]{pack_array}{list, pack_item}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
128 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
129 length of the list is packed as an unsigned integer, then each element
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
130 is packed as in \method{pack_farray()} above.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
131 \end{methoddesc}
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
132
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
133
8867
bb78cc27469a Clarify xdrlib synopsis.
Fred Drake <fdrake@acm.org>
parents: 8855
diff changeset
134 \subsection{Unpacker Objects \label{xdr-unpacker-objects}}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
135
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
136 The \class{Unpacker} class offers the following methods:
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
137
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
138 \begin{methoddesc}[Unpacker]{reset}{data}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
139 Resets the string buffer with the given \var{data}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
140 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
141
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
142 \begin{methoddesc}[Unpacker]{get_position}{}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
143 Returns the current unpack position in the data buffer.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
144 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
145
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
146 \begin{methoddesc}[Unpacker]{set_position}{position}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
147 Sets the data buffer unpack position to \var{position}. You should be
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
148 careful about using \method{get_position()} and \method{set_position()}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
149 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
150
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
151 \begin{methoddesc}[Unpacker]{get_buffer}{}
4579
e3f71ce8e6bb Describe the new Unpacker.get_buffer() method.
Barry Warsaw <barry@python.org>
parents: 4339
diff changeset
152 Returns the current unpack data buffer as a string.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
153 \end{methoddesc}
4579
e3f71ce8e6bb Describe the new Unpacker.get_buffer() method.
Barry Warsaw <barry@python.org>
parents: 4339
diff changeset
154
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
155 \begin{methoddesc}[Unpacker]{done}{}
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
156 Indicates unpack completion. Raises an \exception{Error} exception
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
157 if all of the data has not been unpacked.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
158 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
159
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
160 In addition, every data type that can be packed with a \class{Packer},
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
161 can be unpacked with an \class{Unpacker}. Unpacking methods are of the
7040
1c927ecfcbb3 For consistency, always use a trailing "()" on function names in the running
Fred Drake <fdrake@acm.org>
parents: 6905
diff changeset
162 form \code{unpack_\var{type}()}, and take no arguments. They return the
6526
46fa4717cf24 Ooops, found too more references to old conditions on floating point values.
Fred Drake <fdrake@acm.org>
parents: 6525
diff changeset
163 unpacked object.
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
164
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
165 \begin{methoddesc}[Unpacker]{unpack_float}{}
4339
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
166 Unpacks a single-precision floating point number.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
167 \end{methoddesc}
4339
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
168
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
169 \begin{methoddesc}[Unpacker]{unpack_double}{}
4339
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
170 Unpacks a double-precision floating point number, similarly to
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
171 \method{unpack_float()}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
172 \end{methoddesc}
4339
e7ba092c3cf3 Nits corrected by Fred
Guido van Rossum <guido@python.org>
parents: 4047
diff changeset
173
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
174 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
175 data:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
176
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
177 \begin{methoddesc}[Unpacker]{unpack_fstring}{n}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
178 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
179 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
180 alignment is assumed.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
181 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
182
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
183 \begin{methoddesc}[Unpacker]{unpack_fopaque}{n}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
184 Unpacks and returns a fixed length opaque data stream, similarly to
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
185 \method{unpack_fstring()}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
186 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
187
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
188 \begin{methoddesc}[Unpacker]{unpack_string}{}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
189 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
190 string is first unpacked as an unsigned integer, then the string data
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
191 is unpacked with \method{unpack_fstring()}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
192 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
193
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
194 \begin{methoddesc}[Unpacker]{unpack_opaque}{}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
195 Unpacks and returns a variable length opaque data string, similarly to
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
196 \method{unpack_string()}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
197 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
198
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
199 \begin{methoddesc}[Unpacker]{unpack_bytes}{}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
200 Unpacks and returns a variable length byte stream, similarly to
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
201 \method{unpack_string()}.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
202 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
203
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
204 The following methods support unpacking arrays and lists:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
205
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
206 \begin{methoddesc}[Unpacker]{unpack_list}{unpack_item}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
207 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
208 one element at a time
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
209 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
210 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
211 \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
212 function that is called to unpack the items.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
213 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
214
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
215 \begin{methoddesc}[Unpacker]{unpack_farray}{n, unpack_item}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
216 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
217 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
218 As above, \var{unpack_item} is the function used to unpack each element.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
219 \end{methoddesc}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
220
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
221 \begin{methoddesc}[Unpacker]{unpack_array}{unpack_item}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
222 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
223 First, the length of the list is unpacked as an unsigned integer, then
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
224 each element is unpacked as in \method{unpack_farray()} above.
8025
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
225 \end{methoddesc}
d1c1b20754a8 Use {methoddesc} instead of {funcdesc} for object methods.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
226
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
227
8867
bb78cc27469a Clarify xdrlib synopsis.
Fred Drake <fdrake@acm.org>
parents: 8855
diff changeset
228 \subsection{Exceptions \label{xdr-exceptions}}
4047
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 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
231
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
232 \begin{excdesc}{Error}
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
233 The base exception class. \exception{Error} has a single public data
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
234 member \member{msg} containing the description of the error.
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
235 \end{excdesc}
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 \begin{excdesc}{ConversionError}
7681
e1e76766d8ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
238 Class derived from \exception{Error}. Contains no additional instance
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
239 variables.
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
240 \end{excdesc}
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
241
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
242 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
243
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
244 \begin{verbatim}
4047
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
245 import xdrlib
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
246 p = xdrlib.Packer()
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
247 try:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
248 p.pack_double(8.01)
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
249 except xdrlib.ConversionError, instance:
3e6863cea383 Added imghdr,xdrlib; reformatted Makefile somewhat
Guido van Rossum <guido@python.org>
parents:
diff changeset
250 print 'packing the double failed:', instance.msg
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7219
diff changeset
251 \end{verbatim}