xdrlib —- Encode and decode XDR data

Source code:Lib/xdrlib.py

The xdrlib module supports the External Data Representation Standard asdescribed in RFC 1014, written by Sun Microsystems, Inc. June 1987. Itsupports most of the data types described in the RFC.

The xdrlib module defines two classes, one for packing variables into XDRrepresentation, and another for unpacking from XDR representation. There arealso two exception classes.

  • class xdrlib.Packer
  • Packer is the class for packing data into XDR representation. ThePacker class is instantiated with no arguments.
  • class xdrlib.Unpacker(data)
  • Unpacker is the complementary class which unpacks XDR data values from astring buffer. The input buffer is given as data.

参见

  • RFC 1014 - XDR: External Data Representation Standard

  • This RFC defined the encoding of data which was XDR at the time this module wasoriginally written. It has apparently been obsoleted by RFC 1832.

  • RFC 1832 - XDR: External Data Representation Standard

  • Newer RFC that provides a revised definition of XDR.

Packer Objects

Packer instances have the following methods:

  • Packer.get_buffer()
  • Returns the current pack buffer as a string.
  • Packer.reset()
  • Resets the pack buffer to the empty string.

In general, you can pack any of the most common XDR data types by calling theappropriate pack_type() method. Each method takes a single argument, thevalue to pack. The following simple data type packing methods are supported:pack_uint(), pack_int(), pack_enum(), pack_bool(),pack_uhyper(), and pack_hyper().

  • Packer.packfloat(_value)
  • Packs the single-precision floating point number value.
  • Packer.packdouble(_value)
  • Packs the double-precision floating point number value.

The following methods support packing strings, bytes, and opaque data:

  • Packer.packfstring(_n, s)
  • Packs a fixed length string, s. n is the length of the string but it isnot packed into the data buffer. The string is padded with null bytes ifnecessary to guaranteed 4 byte alignment.
  • Packer.packfopaque(_n, data)
  • Packs a fixed length opaque data stream, similarly to pack_fstring().
  • Packer.packstring(_s)
  • Packs a variable length string, s. The length of the string is first packedas an unsigned integer, then the string data is packed withpack_fstring().
  • Packer.packopaque(_data)
  • Packs a variable length opaque data string, similarly to pack_string().
  • Packer.packbytes(_bytes)
  • Packs a variable length byte stream, similarly to pack_string().

The following methods support packing arrays and lists:

  • Packer.packlist(_list, pack_item)
  • Packs a list of homogeneous items. This method is useful for lists with anindeterminate size; i.e. the size is not available until the entire list hasbeen walked. For each item in the list, an unsigned integer 1 is packedfirst, followed by the data value from the list. pack_item is the functionthat is called to pack the individual item. At the end of the list, an unsignedinteger 0 is packed.

For example, to pack a list of integers, the code might appear like this:

  1. import xdrlib
  2. p = xdrlib.Packer()
  3. p.pack_list([1, 2, 3], p.pack_int)
  • Packer.packfarray(_n, array, pack_item)
  • Packs a fixed length list (array) of homogeneous items. n is the length ofthe list; it is not packed into the buffer, but a ValueError exceptionis raised if len(array) is not equal to n. As above, pack_item is thefunction used to pack each element.
  • Packer.packarray(_list, pack_item)
  • Packs a variable length list of homogeneous items. First, the length of thelist is packed as an unsigned integer, then each element is packed as inpack_farray() above.

Unpacker Objects

The Unpacker class offers the following methods:

  • Unpacker.reset(data)
  • Resets the string buffer with the given data.
  • Unpacker.get_position()
  • Returns the current unpack position in the data buffer.
  • Unpacker.setposition(_position)
  • Sets the data buffer unpack position to position. You should be careful aboutusing get_position() and set_position().
  • Unpacker.get_buffer()
  • Returns the current unpack data buffer as a string.
  • Unpacker.done()
  • Indicates unpack completion. Raises an Error exception if all of thedata has not been unpacked.

In addition, every data type that can be packed with a Packer, can beunpacked with an Unpacker. Unpacking methods are of the formunpack_type(), and take no arguments. They return the unpacked object.

  • Unpacker.unpack_float()
  • Unpacks a single-precision floating point number.
  • Unpacker.unpack_double()
  • Unpacks a double-precision floating point number, similarly tounpack_float().

In addition, the following methods unpack strings, bytes, and opaque data:

  • Unpacker.unpackfstring(_n)
  • Unpacks and returns a fixed length string. n is the number of charactersexpected. Padding with null bytes to guaranteed 4 byte alignment is assumed.
  • Unpacker.unpackfopaque(_n)
  • Unpacks and returns a fixed length opaque data stream, similarly tounpack_fstring().
  • Unpacker.unpack_string()
  • Unpacks and returns a variable length string. The length of the string is firstunpacked as an unsigned integer, then the string data is unpacked withunpack_fstring().
  • Unpacker.unpack_opaque()
  • Unpacks and returns a variable length opaque data string, similarly tounpack_string().
  • Unpacker.unpack_bytes()
  • Unpacks and returns a variable length byte stream, similarly tounpack_string().

The following methods support unpacking arrays and lists:

  • Unpacker.unpacklist(_unpack_item)
  • Unpacks and returns a list of homogeneous items. The list is unpacked oneelement at a time by first unpacking an unsigned integer flag. If the flag is1, then the item is unpacked and appended to the list. A flag of 0indicates the end of the list. unpack_item is the function that is called tounpack the items.
  • Unpacker.unpackfarray(_n, unpack_item)
  • Unpacks and returns (as a list) a fixed length array of homogeneous items. n_is number of list elements to expect in the buffer. As above, _unpack_item isthe function used to unpack each element.
  • Unpacker.unpackarray(_unpack_item)
  • Unpacks and returns a variable length list of homogeneous items. First, thelength of the list is unpacked as an unsigned integer, then each element isunpacked as in unpack_farray() above.

异常

Exceptions in this module are coded as class instances:

  • exception xdrlib.Error
  • The base exception class. Error has a single public attributemsg containing the description of the error.
  • exception xdrlib.ConversionError
  • Class derived from Error. Contains no additional instance variables.

Here is an example of how you would catch one of these exceptions:

  1. import xdrlib
  2. p = xdrlib.Packer()
  3. try:
  4.     p.pack_double(8.01)
  5. except xdrlib.ConversionError as instance:
  6.     print('packing the double failed:', instance.msg)