< BACKMake Note | BookmarkCONTINUE >
152015024128143245168232148039199167010047123209178152124239215162148042031165113061128045

XDR Data Exchange Format

XDR is best described as a standard for data description and encoding. It uses a implicit typing language to describe intricate data formats in a concise manner—note that this language is not a programming language. Protocols such as Sun RPC (Remote Procedure Call) and the NFS (Network File System, which was initially built on top of RPC) use XDR to describe the format of their data because XDR is useful for transferring data between different computer architectures. XDR has been used to communicate with data between such diverse machines as the SUN WORKSTATION, VAX, IBM-PC, and Cray. It is a very portable implementation. For more information, check out

Internet standards—RFC 1014, External Data Representation

http://info.internet.isi.edu/in-notes/rfc/files/rfc1014.txt

xdrlib

The xdrlib module almost entirely supports the External Data Representation Standard (XDR) as described in RFC 1014, written by Sun Microsystems, Inc. on June 1987. Therefore, it is used extensively in networked applications, mainly the ones that need to handle RPC.

This module defines two exceptions, and two classes—one for packing variables into XDR representation, and another for unpacking from XDR representation:

Packer()—  Packer is the class for packing data into XDR representation. The Packer class is instantiated with no arguments.

Unpacker(data)—  Unpacker is the complementary class, which unpacks XDR data values from a string buffer. The input buffer is given as data.

Packer Objects

Packer instances have the following methods:

get_buffer()—  Returns the current pack buffer as a string.

reset()—  Resets the pack buffer to the empty string.

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

pack_float(value)—  Packs the single-precision floating point number value.

pack_double(value)—  Packs the double-precision floating point number value.

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

pack_fstring(n, s)—  Packs a fixed length string, s.n is the length of the string, but it is not packed into the data buffer. The string is padded with null bytes if necessary to guarantee 4 byte alignment.

pack_fopaque(n, data)—  Packs a fixed length opaque data stream, similar to pack_fstring().

pack_string(s)—  Packs a variable length string, s. The length of the string is first packed as an unsigned integer, and then the string data is packed with pack_fstring().

pack_opaque(data)—  Packs a variable length opaque data string, similar to pack_string().

pack_bytes(bytes)—  Packs a variable length byte stream, similar to pack_string().

The following methods support packing arrays and lists:

pack_list(list, pack_item)—  Packs a list of homogeneous items. This method is useful for lists with an indeterminate size; that is, the size is not available until the entire list has been walked. For each item in the list, an unsigned integer 1 is packed first, followed by the data value from the list. pack_item is the function called to pack the individual item. At the end of the list, an unsigned integer 0 is packed.

pack_farray(n, array, pack_item)—  Packs a fixed length list (array) of homogeneous items. n is the length of the list; it is not packed into the buffer, but a ValueError exception is raised if len(array) is not equal to n. As stated previously, pack_item is the function used to pack each element.

pack_array(list, pack_item)—  Packs a variable length list of homogeneous items. First, the length of the list is packed as an unsigned integer, and then each element is packed as in pack_farray() stated previously.

Unpacker Objects

The Unpacker class offers the following methods:

reset(data)—  Resets the string buffer with the given data.

get_position()—  Returns the current unpack position in the data buffer.

set_position(position)—  Sets the data buffer unpack position to position. You should be careful about using get_position() and set_position().

get_buffer()—  Returns the current unpack data buffer as a string.

done()—  Indicates unpack completion. Raises an error exception if all the data has not been unpacked.

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

unpack_float()—  Unpacks a single-precision floating point number.

unpack_double()—  Unpacks a double-precision floating point number, similar to unpack_float().

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

unpack_fstring(n)—  Unpacks and returns a fixed length string. n is the number of characters expected. Padding with null bytes to guaranteed 4 byte alignment is assumed.

unpack_fopaque(n)—  Unpacks and returns a fixed length opaque data stream, similar to unpack_fstring().

unpack_string()—  Unpacks and returns a variable length string. The length of the string is first unpacked as an unsigned integer, and then the string data is unpacked with unpack_fstring().

unpack_opaque()—  Unpacks and returns a variable length opaque data string, similar to unpack_string().

unpack_bytes()—  Unpacks and returns a variable length byte stream, similar to unpack_string().

The following methods support unpacking arrays and lists:

unpack_list(unpack_item)—  Unpacks and returns a list of homogeneous items. The list is unpacked one element at a time by first unpacking an unsigned integer flag. If the flag is 1, the item is unpacked and appended to the list. A flag of 0 indicates the end of the list. unpack_item is the function called to unpack the items.

unpack_farray(n, unpack_item)—  Unpacks and returns (as a list) a fixed length array of homogeneous items. n is the number of list elements to expect in the buffer. As stated previously, unpack_item is the function used to unpack each element.

unpack_array(unpack_item)—  Unpacks and returns a variable length list of homogeneous items. First, the length of the list is unpacked as an unsigned integer, and then each element is unpacked as in unpack_farray() previously.

In the following example, we pack a group of variables, unpacking them later.

						
import xdrlib

def f_packer(name, author, month, year):
    data = xdrlib.Packer()
    data.pack_string(name)
    data.pack_string(author)
    data.pack_uint(month)
    data.pack_uint(year)
    packed = data.get_buffer()
    return packed 

def f_unpacker(packer):
    data = xdrlib.Unpacker(packer)
    return data

print "The original values are: 'Andre', 'Author', 10, 2000"
print

packed = f_packer('Andre', 'Author', 10, 2000)
print "The packed data is now defined by:", repr(packed)
print
print "And now, the original data again. (After unpacking it!)"
unpacked = f_unpacker(packed)
print repr(unpacked.unpack_string()), ", ", \
      repr(unpacked.unpack_string()), ", ",  \
      unpacked.unpack_uint(), ", ",           \
      unpacked.unpack_uint()
unpacked.done()

The original values are: 'Andre', 'Author', 10, 2000

The packed data is now defined by:
'\000\000\000\005Andre\000\000\000\000\000\000\006Author\000\000\000\000\
000\012\000\000\007\320'

And now, the original data again. (After unpacking it!)
'Andre', 'Author', 10 , 2000

					

Note

If you are only handling simple data types and only with Python, it is probably easier to just use the marshal module.



Exceptions

Exceptions in this module are coded as class instances:

Error—  This is the base exception class. Error has a single public data member msg containing the description of the error.

ConversionError—  This class is derived from Error. Contains no additional instance variables.

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

						
>>> import xdrlib
>>> data = xdrlib.Packer()
>>> try:
…       data.pack_double("8.01")
… except xdrlib.ConversionError, ErrorObj:
…     print 'Error while packing the data:', ErrorObj.msg
…
Error while packing the data: required argument is not a float
>>>

					


Last updated on 1/30/2002
Python Developer's Handbook, © 2002 Sams Publishing

< BACKMake Note | BookmarkCONTINUE >

Index terms contained in this section

arrays
      packing methods 2nd
bytes
      packing methods 2nd
classes
      Packer() 2nd 3rd 4th
      Unpacker(data) 2nd 3rd 4th
      xdrlib module 2nd 3rd 4th 5th 6th
ConversionError exception
data
     manipulating
            XDR Data Exchange Format 2nd 3rd 4th 5th
     opaque
            packing methods 2nd
done() method
Error exception
exceptions
      ConversionError
      Error
External Data Representation Standard (XDR)
floating points
      packing methods
formats
      XDR Data Exchange 2nd 3rd 4th 5th
get_buffer() method 2nd
get_position() method
lists
      packing methods 2nd
manipulating
     data
            XDR Data Exchange Format 2nd 3rd 4th 5th
methods
      done()
      get_buffer() 2nd
      get_position()
      pack_array(list, pack_item)
      pack_bytes(bytes)
      pack_double(value)
      pack_farray(n, array, pack_item)
      pack_float(value)
      pack_fopaque(n, data)
      pack_fstring(n, s)
      pack_list(list, pack_item)
      pack_opaque(data)
      pack_string(s)
      Packer() class 2nd 3rd 4th
     packing
            arrays 2nd
            bytes 2nd
            floating point number
            lists 2nd
            opaque data 2nd
            strings 2nd
      reset()
      reset(data)
      set_position(position)
      unpack_array(unpack_item)
      unpack_bytes()
      unpack_double()
      unpack_farray(n, unpack item)
      unpack_float()
      unpack_fopaque(n)
      unpack_fstring(n)
      unpack_list(unpack_item)
      unpack_opaque()
      unpack_string()
      Unpacker(data) class 2nd 3rd
modules
      xdrlib 2nd 3rd 4th 5th 6th
numbers
     floating points
            packing methods
objects
      Packer() 2nd 3rd
      Unacker() 2nd 3rd
opaque data
      packing methods 2nd
pack_array(list, pack_item) method
pack_bytes(bytes) method
pack_double(value) method
pack_farray(n, array, pack_item) method
pack_float(value) method
pack_fopaque(n, data) method
pack_fstring(n, s) method
pack_list(list, pack_item) method
pack_opaque(data) method
pack_string(s) method
Packer() class 2nd 3rd 4th
packing
      variables
reset() method
reset(data) method
set_position(position) method
strings
      packing methods 2nd
unpack_array(unpack_item) method
unpack_bytes() method
unpack_double() method
unpack_farray(n, unpack item) method
unpack_float() method
unpack_fopaque(n) method
unpack_fstring(n) method
unpack_list(unpack_item) method
unpack_opaque() method
unpack_string() method
Unpacker(data) class 2nd 3rd 4th
unpacking
      variables
variables
      packing
XDR (External Data Representation Standard)
XDR Data Exchange Format
      manipulating data 2nd 3rd 4th 5th
xdrlib module 2nd 3rd 4th 5th 6th

© 2002, O'Reilly & Associates, Inc.