1 :mod:`xdrlib` --- Encode and decode XDR data 2 ============================================ 3 4 .. module:: xdrlib 5 :synopsis: Encoders and decoders for the External Data Representation (XDR). 6 7 **Source code:** :source:`Lib/xdrlib.py` 8 9 .. index:: 10 single: XDR 11 single: External Data Representation 12 13 -------------- 14 15 The :mod:`xdrlib` module supports the External Data Representation Standard as 16 described in :rfc:`1014`, written by Sun Microsystems, Inc. June 1987. It 17 supports most of the data types described in the RFC. 18 19 The :mod:`xdrlib` module defines two classes, one for packing variables into XDR 20 representation, and another for unpacking from XDR representation. There are 21 also two exception classes. 22 23 24 .. class:: Packer() 25 26 :class:`Packer` is the class for packing data into XDR representation. The 27 :class:`Packer` class is instantiated with no arguments. 28 29 30 .. class:: Unpacker(data) 31 32 ``Unpacker`` is the complementary class which unpacks XDR data values from a 33 string buffer. The input buffer is given as *data*. 34 35 36 .. seealso:: 37 38 :rfc:`1014` - XDR: External Data Representation Standard 39 This RFC defined the encoding of data which was XDR at the time this module was 40 originally written. It has apparently been obsoleted by :rfc:`1832`. 41 42 :rfc:`1832` - XDR: External Data Representation Standard 43 Newer RFC that provides a revised definition of XDR. 44 45 46 .. _xdr-packer-objects: 47 48 Packer Objects 49 -------------- 50 51 :class:`Packer` instances have the following methods: 52 53 54 .. method:: Packer.get_buffer() 55 56 Returns the current pack buffer as a string. 57 58 59 .. method:: Packer.reset() 60 61 Resets the pack buffer to the empty string. 62 63 In general, you can pack any of the most common XDR data types by calling the 64 appropriate ``pack_type()`` method. Each method takes a single argument, the 65 value to pack. The following simple data type packing methods are supported: 66 :meth:`pack_uint`, :meth:`pack_int`, :meth:`pack_enum`, :meth:`pack_bool`, 67 :meth:`pack_uhyper`, and :meth:`pack_hyper`. 68 69 70 .. method:: Packer.pack_float(value) 71 72 Packs the single-precision floating point number *value*. 73 74 75 .. method:: Packer.pack_double(value) 76 77 Packs the double-precision floating point number *value*. 78 79 The following methods support packing strings, bytes, and opaque data: 80 81 82 .. method:: Packer.pack_fstring(n, s) 83 84 Packs a fixed length string, *s*. *n* is the length of the string but it is 85 *not* packed into the data buffer. The string is padded with null bytes if 86 necessary to guaranteed 4 byte alignment. 87 88 89 .. method:: Packer.pack_fopaque(n, data) 90 91 Packs a fixed length opaque data stream, similarly to :meth:`pack_fstring`. 92 93 94 .. method:: Packer.pack_string(s) 95 96 Packs a variable length string, *s*. The length of the string is first packed 97 as an unsigned integer, then the string data is packed with 98 :meth:`pack_fstring`. 99 100 101 .. method:: Packer.pack_opaque(data) 102 103 Packs a variable length opaque data string, similarly to :meth:`pack_string`. 104 105 106 .. method:: Packer.pack_bytes(bytes) 107 108 Packs a variable length byte stream, similarly to :meth:`pack_string`. 109 110 The following methods support packing arrays and lists: 111 112 113 .. method:: Packer.pack_list(list, pack_item) 114 115 Packs a *list* of homogeneous items. This method is useful for lists with an 116 indeterminate size; i.e. the size is not available until the entire list has 117 been walked. For each item in the list, an unsigned integer ``1`` is packed 118 first, followed by the data value from the list. *pack_item* is the function 119 that is called to pack the individual item. At the end of the list, an unsigned 120 integer ``0`` is packed. 121 122 For example, to pack a list of integers, the code might appear like this:: 123 124 import xdrlib 125 p = xdrlib.Packer() 126 p.pack_list([1, 2, 3], p.pack_int) 127 128 129 .. method:: Packer.pack_farray(n, array, pack_item) 130 131 Packs a fixed length list (*array*) of homogeneous items. *n* is the length of 132 the list; it is *not* packed into the buffer, but a :exc:`ValueError` exception 133 is raised if ``len(array)`` is not equal to *n*. As above, *pack_item* is the 134 function used to pack each element. 135 136 137 .. method:: Packer.pack_array(list, pack_item) 138 139 Packs a variable length *list* of homogeneous items. First, the length of the 140 list is packed as an unsigned integer, then each element is packed as in 141 :meth:`pack_farray` above. 142 143 144 .. _xdr-unpacker-objects: 145 146 Unpacker Objects 147 ---------------- 148 149 The :class:`Unpacker` class offers the following methods: 150 151 152 .. method:: Unpacker.reset(data) 153 154 Resets the string buffer with the given *data*. 155 156 157 .. method:: Unpacker.get_position() 158 159 Returns the current unpack position in the data buffer. 160 161 162 .. method:: Unpacker.set_position(position) 163 164 Sets the data buffer unpack position to *position*. You should be careful about 165 using :meth:`get_position` and :meth:`set_position`. 166 167 168 .. method:: Unpacker.get_buffer() 169 170 Returns the current unpack data buffer as a string. 171 172 173 .. method:: Unpacker.done() 174 175 Indicates unpack completion. Raises an :exc:`Error` exception if all of the 176 data has not been unpacked. 177 178 In addition, every data type that can be packed with a :class:`Packer`, can be 179 unpacked with an :class:`Unpacker`. Unpacking methods are of the form 180 ``unpack_type()``, and take no arguments. They return the unpacked object. 181 182 183 .. method:: Unpacker.unpack_float() 184 185 Unpacks a single-precision floating point number. 186 187 188 .. method:: Unpacker.unpack_double() 189 190 Unpacks a double-precision floating point number, similarly to 191 :meth:`unpack_float`. 192 193 In addition, the following methods unpack strings, bytes, and opaque data: 194 195 196 .. method:: Unpacker.unpack_fstring(n) 197 198 Unpacks and returns a fixed length string. *n* is the number of characters 199 expected. Padding with null bytes to guaranteed 4 byte alignment is assumed. 200 201 202 .. method:: Unpacker.unpack_fopaque(n) 203 204 Unpacks and returns a fixed length opaque data stream, similarly to 205 :meth:`unpack_fstring`. 206 207 208 .. method:: Unpacker.unpack_string() 209 210 Unpacks and returns a variable length string. The length of the string is first 211 unpacked as an unsigned integer, then the string data is unpacked with 212 :meth:`unpack_fstring`. 213 214 215 .. method:: Unpacker.unpack_opaque() 216 217 Unpacks and returns a variable length opaque data string, similarly to 218 :meth:`unpack_string`. 219 220 221 .. method:: Unpacker.unpack_bytes() 222 223 Unpacks and returns a variable length byte stream, similarly to 224 :meth:`unpack_string`. 225 226 The following methods support unpacking arrays and lists: 227 228 229 .. method:: Unpacker.unpack_list(unpack_item) 230 231 Unpacks and returns a list of homogeneous items. The list is unpacked one 232 element at a time by first unpacking an unsigned integer flag. If the flag is 233 ``1``, then the item is unpacked and appended to the list. A flag of ``0`` 234 indicates the end of the list. *unpack_item* is the function that is called to 235 unpack the items. 236 237 238 .. method:: Unpacker.unpack_farray(n, unpack_item) 239 240 Unpacks and returns (as a list) a fixed length array of homogeneous items. *n* 241 is number of list elements to expect in the buffer. As above, *unpack_item* is 242 the function used to unpack each element. 243 244 245 .. method:: Unpacker.unpack_array(unpack_item) 246 247 Unpacks and returns a variable length *list* of homogeneous items. First, the 248 length of the list is unpacked as an unsigned integer, then each element is 249 unpacked as in :meth:`unpack_farray` above. 250 251 252 .. _xdr-exceptions: 253 254 Exceptions 255 ---------- 256 257 Exceptions in this module are coded as class instances: 258 259 260 .. exception:: Error 261 262 The base exception class. :exc:`Error` has a single public attribute 263 :attr:`msg` containing the description of the error. 264 265 266 .. exception:: ConversionError 267 268 Class derived from :exc:`Error`. Contains no additional instance variables. 269 270 Here is an example of how you would catch one of these exceptions:: 271 272 import xdrlib 273 p = xdrlib.Packer() 274 try: 275 p.pack_double(8.01) 276 except xdrlib.ConversionError as instance: 277 print('packing the double failed:', instance.msg) 278 279
