Fred Drake | 20417b7 | 1997-12-17 14:17:35 +0000 | [diff] [blame] | 1 | \section{Standard Module \sectcode{xdrlib}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-xdrlib} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 3 | \stmodindex{xdrlib} |
| 4 | \index{XDR} |
Fred Drake | 3c3d7ce | 1998-01-08 04:00:30 +0000 | [diff] [blame] | 5 | \index{External Data Representation} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 6 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 7 | \setindexsubitem{(in module xdrlib)} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 8 | |
| 9 | |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 10 | The \module{xdrlib} module supports the External Data Representation |
Fred Drake | c589124 | 1998-02-09 19:16:20 +0000 | [diff] [blame] | 11 | Standard as described in \rfc{1014}, written by Sun Microsystems, |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 12 | Inc. June 1987. It supports most of the data types described in the |
Fred Drake | ae18e9f | 1997-10-24 21:14:36 +0000 | [diff] [blame] | 13 | RFC. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 14 | |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 15 | The \module{xdrlib} module defines two classes, one for packing |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 16 | variables into XDR representation, and another for unpacking from XDR |
| 17 | representation. There are also two exception classes. |
| 18 | |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 19 | \begin{classdesc}{Packer}{} |
| 20 | \class{Packer} is the class for packing data into XDR representation. |
| 21 | The \class{Packer} class is instantiated with no arguments. |
| 22 | \end{classdesc} |
| 23 | |
| 24 | \begin{classdesc}{Unpacker}{data} |
| 25 | \code{Unpacker} is the complementary class which unpacks XDR data |
| 26 | values from a string buffer. The input buffer is given as |
| 27 | \var{data}. |
| 28 | \end{classdesc} |
| 29 | |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 30 | |
| 31 | \subsection{Packer Objects} |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 32 | \label{xdr-packer-objects} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 33 | |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 34 | \class{Packer} instances have the following methods: |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 35 | |
| 36 | \begin{funcdesc}{get_buffer}{} |
| 37 | Returns the current pack buffer as a string. |
| 38 | \end{funcdesc} |
| 39 | |
| 40 | \begin{funcdesc}{reset}{} |
| 41 | Resets the pack buffer to the empty string. |
| 42 | \end{funcdesc} |
| 43 | |
| 44 | In general, you can pack any of the most common XDR data types by |
Fred Drake | 3c3d7ce | 1998-01-08 04:00:30 +0000 | [diff] [blame] | 45 | calling the appropriate \code{pack_\var{type}()} method. Each method |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 46 | takes a single argument, the value to pack. The following simple data |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 47 | type packing methods are supported: \method{pack_uint()}, |
| 48 | \method{pack_int()}, \method{pack_enum()}, \method{pack_bool()}, |
| 49 | \method{pack_uhyper()}, and \method{pack_hyper()}. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 50 | |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 51 | \begin{funcdesc}{pack_float}{value} |
| 52 | Packs the single-precision floating point number \var{value}. |
| 53 | \end{funcdesc} |
| 54 | |
| 55 | \begin{funcdesc}{pack_double}{value} |
| 56 | Packs the double-precision floating point number \var{value}. |
| 57 | \end{funcdesc} |
| 58 | |
| 59 | The following methods support packing strings, bytes, and opaque data: |
| 60 | |
Fred Drake | 3c3d7ce | 1998-01-08 04:00:30 +0000 | [diff] [blame] | 61 | \begin{funcdesc}{pack_fstring}{n, s} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 62 | Packs a fixed length string, \var{s}. \var{n} is the length of the |
| 63 | string but it is \emph{not} packed into the data buffer. The string |
| 64 | is padded with null bytes if necessary to guaranteed 4 byte alignment. |
| 65 | \end{funcdesc} |
| 66 | |
Fred Drake | 3c3d7ce | 1998-01-08 04:00:30 +0000 | [diff] [blame] | 67 | \begin{funcdesc}{pack_fopaque}{n, data} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 68 | Packs a fixed length opaque data stream, similarly to |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 69 | \method{pack_fstring()}. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 70 | \end{funcdesc} |
| 71 | |
| 72 | \begin{funcdesc}{pack_string}{s} |
| 73 | Packs a variable length string, \var{s}. The length of the string is |
| 74 | first packed as an unsigned integer, then the string data is packed |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 75 | with \method{pack_fstring()}. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 76 | \end{funcdesc} |
| 77 | |
| 78 | \begin{funcdesc}{pack_opaque}{data} |
| 79 | Packs a variable length opaque data string, similarly to |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 80 | \method{pack_string()}. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 81 | \end{funcdesc} |
| 82 | |
| 83 | \begin{funcdesc}{pack_bytes}{bytes} |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 84 | Packs a variable length byte stream, similarly to \method{pack_string()}. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 85 | \end{funcdesc} |
| 86 | |
| 87 | The following methods support packing arrays and lists: |
| 88 | |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 89 | \begin{funcdesc}{pack_list}{list, pack_item} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 90 | Packs a \var{list} of homogeneous items. This method is useful for |
| 91 | lists with an indeterminate size; i.e. the size is not available until |
| 92 | the entire list has been walked. For each item in the list, an |
| 93 | unsigned integer \code{1} is packed first, followed by the data value |
| 94 | from the list. \var{pack_item} is the function that is called to pack |
| 95 | the individual item. At the end of the list, an unsigned integer |
| 96 | \code{0} is packed. |
| 97 | \end{funcdesc} |
| 98 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 99 | \begin{funcdesc}{pack_farray}{n, array, pack_item} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 100 | Packs a fixed length list (\var{array}) of homogeneous items. \var{n} |
| 101 | is the length of the list; it is \emph{not} packed into the buffer, |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 102 | but a \exception{ValueError} exception is raised if |
| 103 | \code{len(\var{array})} is not equal to \var{n}. As above, |
| 104 | \var{pack_item} is the function used to pack each element. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 105 | \end{funcdesc} |
| 106 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 107 | \begin{funcdesc}{pack_array}{list, pack_item} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 108 | Packs a variable length \var{list} of homogeneous items. First, the |
| 109 | length of the list is packed as an unsigned integer, then each element |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 110 | is packed as in \method{pack_farray()} above. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 111 | \end{funcdesc} |
| 112 | |
| 113 | \subsection{Unpacker Objects} |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 114 | \label{xdr-unpacker-objects} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 115 | |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 116 | The \class{Unpacker} class offers the following methods: |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 117 | |
| 118 | \begin{funcdesc}{reset}{data} |
| 119 | Resets the string buffer with the given \var{data}. |
| 120 | \end{funcdesc} |
| 121 | |
| 122 | \begin{funcdesc}{get_position}{} |
| 123 | Returns the current unpack position in the data buffer. |
| 124 | \end{funcdesc} |
| 125 | |
| 126 | \begin{funcdesc}{set_position}{position} |
| 127 | Sets the data buffer unpack position to \var{position}. You should be |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 128 | careful about using \method{get_position()} and \method{set_position()}. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 129 | \end{funcdesc} |
| 130 | |
Barry Warsaw | 102dc41 | 1996-12-04 22:05:42 +0000 | [diff] [blame] | 131 | \begin{funcdesc}{get_buffer}{} |
| 132 | Returns the current unpack data buffer as a string. |
| 133 | \end{funcdesc} |
| 134 | |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 135 | \begin{funcdesc}{done}{} |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 136 | Indicates unpack completion. Raises an \exception{Error} exception |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 137 | if all of the data has not been unpacked. |
| 138 | \end{funcdesc} |
| 139 | |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 140 | In addition, every data type that can be packed with a \class{Packer}, |
| 141 | can be unpacked with an \class{Unpacker}. Unpacking methods are of the |
Fred Drake | 3c3d7ce | 1998-01-08 04:00:30 +0000 | [diff] [blame] | 142 | form \code{unpack_\var{type}()}, and take no arguments. They return the |
Fred Drake | 040e565 | 1997-10-24 21:15:55 +0000 | [diff] [blame] | 143 | unpacked object. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 144 | |
Guido van Rossum | 3f247ad | 1996-09-27 17:11:24 +0000 | [diff] [blame] | 145 | \begin{funcdesc}{unpack_float}{} |
| 146 | Unpacks a single-precision floating point number. |
| 147 | \end{funcdesc} |
| 148 | |
| 149 | \begin{funcdesc}{unpack_double}{} |
| 150 | Unpacks a double-precision floating point number, similarly to |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 151 | \method{unpack_float()}. |
Guido van Rossum | 3f247ad | 1996-09-27 17:11:24 +0000 | [diff] [blame] | 152 | \end{funcdesc} |
| 153 | |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 154 | In addition, the following methods unpack strings, bytes, and opaque |
| 155 | data: |
| 156 | |
| 157 | \begin{funcdesc}{unpack_fstring}{n} |
| 158 | Unpacks and returns a fixed length string. \var{n} is the number of |
| 159 | characters expected. Padding with null bytes to guaranteed 4 byte |
| 160 | alignment is assumed. |
| 161 | \end{funcdesc} |
| 162 | |
| 163 | \begin{funcdesc}{unpack_fopaque}{n} |
| 164 | Unpacks and returns a fixed length opaque data stream, similarly to |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 165 | \method{unpack_fstring()}. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 166 | \end{funcdesc} |
| 167 | |
Guido van Rossum | 3f247ad | 1996-09-27 17:11:24 +0000 | [diff] [blame] | 168 | \begin{funcdesc}{unpack_string}{} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 169 | Unpacks and returns a variable length string. The length of the |
| 170 | string is first unpacked as an unsigned integer, then the string data |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 171 | is unpacked with \method{unpack_fstring()}. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 172 | \end{funcdesc} |
| 173 | |
| 174 | \begin{funcdesc}{unpack_opaque}{} |
| 175 | Unpacks and returns a variable length opaque data string, similarly to |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 176 | \method{unpack_string()}. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 177 | \end{funcdesc} |
| 178 | |
| 179 | \begin{funcdesc}{unpack_bytes}{} |
| 180 | Unpacks and returns a variable length byte stream, similarly to |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 181 | \method{unpack_string()}. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 182 | \end{funcdesc} |
| 183 | |
| 184 | The following methods support unpacking arrays and lists: |
| 185 | |
| 186 | \begin{funcdesc}{unpack_list}{unpack_item} |
| 187 | Unpacks and returns a list of homogeneous items. The list is unpacked |
| 188 | one element at a time |
| 189 | by first unpacking an unsigned integer flag. If the flag is \code{1}, |
| 190 | then the item is unpacked and appended to the list. A flag of |
| 191 | \code{0} indicates the end of the list. \var{unpack_item} is the |
| 192 | function that is called to unpack the items. |
| 193 | \end{funcdesc} |
| 194 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 195 | \begin{funcdesc}{unpack_farray}{n, unpack_item} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 196 | Unpacks and returns (as a list) a fixed length array of homogeneous |
| 197 | items. \var{n} is number of list elements to expect in the buffer. |
| 198 | As above, \var{unpack_item} is the function used to unpack each element. |
| 199 | \end{funcdesc} |
| 200 | |
| 201 | \begin{funcdesc}{unpack_array}{unpack_item} |
| 202 | Unpacks and returns a variable length \var{list} of homogeneous items. |
| 203 | First, the length of the list is unpacked as an unsigned integer, then |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 204 | each element is unpacked as in \method{unpack_farray()} above. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 205 | \end{funcdesc} |
| 206 | |
| 207 | \subsection{Exceptions} |
Fred Drake | 4b3f031 | 1996-12-13 22:04:31 +0000 | [diff] [blame] | 208 | \nodename{Exceptions in xdrlib module} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 209 | |
| 210 | Exceptions in this module are coded as class instances: |
| 211 | |
| 212 | \begin{excdesc}{Error} |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 213 | The base exception class. \exception{Error} has a single public data |
| 214 | member \member{msg} containing the description of the error. |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 215 | \end{excdesc} |
| 216 | |
| 217 | \begin{excdesc}{ConversionError} |
Fred Drake | ff79a21 | 1998-03-14 06:30:13 +0000 | [diff] [blame] | 218 | Class derived from \exception{Error}. Contains no additional instance |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 219 | variables. |
| 220 | \end{excdesc} |
| 221 | |
| 222 | Here is an example of how you would catch one of these exceptions: |
| 223 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 224 | \begin{verbatim} |
Guido van Rossum | 40006cf | 1996-08-19 22:58:03 +0000 | [diff] [blame] | 225 | import xdrlib |
| 226 | p = xdrlib.Packer() |
| 227 | try: |
| 228 | p.pack_double(8.01) |
| 229 | except xdrlib.ConversionError, instance: |
| 230 | print 'packing the double failed:', instance.msg |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 231 | \end{verbatim} |