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 mannernote 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 standardsRFC 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
classesone 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
>>>