1 

     2 :mod:`xdrlib` --- Encode and decode XDR data

     3 ============================================

     4 

     5 .. module:: xdrlib

     6    :synopsis: Encoders and decoders for the External Data Representation (XDR).

     7 

     8 

     9 .. index::

    10    single: XDR

    11    single: External Data Representation

    12 

    13 The :mod:`xdrlib` module supports the External Data Representation Standard as

    14 described in :rfc:`1014`, written by Sun Microsystems, Inc. June 1987.  It

    15 supports most of the data types described in the RFC.

    16 

    17 The :mod:`xdrlib` module defines two classes, one for packing variables into XDR

    18 representation, and another for unpacking from XDR representation.  There are

    19 also two exception classes.

    20 

    21 

    22 .. class:: Packer()

    23 

    24    :class:`Packer` is the class for packing data into XDR representation. The

    25    :class:`Packer` class is instantiated with no arguments.

    26 

    27 

    28 .. class:: Unpacker(data)

    29 

    30    ``Unpacker`` is the complementary class which unpacks XDR data values from a

    31    string buffer.  The input buffer is given as *data*.

    32 

    33 

    34 .. seealso::

    35 

    36    :rfc:`1014` - XDR: External Data Representation Standard

    37       This RFC defined the encoding of data which was XDR at the time this module was

    38       originally written.  It has apparently been obsoleted by :rfc:`1832`.

    39 

    40    :rfc:`1832` - XDR: External Data Representation Standard

    41       Newer RFC that provides a revised definition of XDR.

    42 

    43 

    44 .. _xdr-packer-objects:

    45 

    46 Packer Objects

    47 --------------

    48 

    49 :class:`Packer` instances have the following methods:

    50 

    51 

    52 .. method:: Packer.get_buffer()

    53 

    54    Returns the current pack buffer as a string.

    55 

    56 

    57 .. method:: Packer.reset()

    58 

    59    Resets the pack buffer to the empty string.

    60 

    61 In general, you can pack any of the most common XDR data types by calling the

    62 appropriate ``pack_type()`` method.  Each method takes a single argument, the

    63 value to pack.  The following simple data type packing methods are supported:

    64 :meth:`pack_uint`, :meth:`pack_int`, :meth:`pack_enum`, :meth:`pack_bool`,

    65 :meth:`pack_uhyper`, and :meth:`pack_hyper`.

    66 

    67 

    68 .. method:: Packer.pack_float(value)

    69 

    70    Packs the single-precision floating point number *value*.

    71 

    72 

    73 .. method:: Packer.pack_double(value)

    74 

    75    Packs the double-precision floating point number *value*.

    76 

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

    78 

    79 

    80 .. method:: Packer.pack_fstring(n, s)

    81 

    82    Packs a fixed length string, *s*.  *n* is the length of the string but it is

    83    *not* packed into the data buffer.  The string is padded with null bytes if

    84    necessary to guaranteed 4 byte alignment.

    85 

    86 

    87 .. method:: Packer.pack_fopaque(n, data)

    88 

    89    Packs a fixed length opaque data stream, similarly to :meth:`pack_fstring`.

    90 

    91 

    92 .. method:: Packer.pack_string(s)

    93 

    94    Packs a variable length string, *s*.  The length of the string is first packed

    95    as an unsigned integer, then the string data is packed with

    96    :meth:`pack_fstring`.

    97 

    98 

    99 .. method:: Packer.pack_opaque(data)

   100 

   101    Packs a variable length opaque data string, similarly to :meth:`pack_string`.

   102 

   103 

   104 .. method:: Packer.pack_bytes(bytes)

   105 

   106    Packs a variable length byte stream, similarly to :meth:`pack_string`.

   107 

   108 The following methods support packing arrays and lists:

   109 

   110 

   111 .. method:: Packer.pack_list(list, pack_item)

   112 

   113    Packs a *list* of homogeneous items.  This method is useful for lists with an

   114    indeterminate size; i.e. the size is not available until the entire list has

   115    been walked.  For each item in the list, an unsigned integer ``1`` is packed

   116    first, followed by the data value from the list.  *pack_item* is the function

   117    that is called to pack the individual item.  At the end of the list, an unsigned

   118    integer ``0`` is packed.

   119 

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

   121 

   122       import xdrlib

   123       p = xdrlib.Packer()

   124       p.pack_list([1, 2, 3], p.pack_int)

   125 

   126 

   127 .. method:: Packer.pack_farray(n, array, pack_item)

   128 

   129    Packs a fixed length list (*array*) of homogeneous items.  *n* is the length of

   130    the list; it is *not* packed into the buffer, but a :exc:`ValueError` exception

   131    is raised if ``len(array)`` is not equal to *n*.  As above, *pack_item* is the

   132    function used to pack each element.

   133 

   134 

   135 .. method:: Packer.pack_array(list, pack_item)

   136 

   137    Packs a variable length *list* of homogeneous items.  First, the length of the

   138    list is packed as an unsigned integer, then each element is packed as in

   139    :meth:`pack_farray` above.

   140 

   141 

   142 .. _xdr-unpacker-objects:

   143 

   144 Unpacker Objects

   145 ----------------

   146 

   147 The :class:`Unpacker` class offers the following methods:

   148 

   149 

   150 .. method:: Unpacker.reset(data)

   151 

   152    Resets the string buffer with the given *data*.

   153 

   154 

   155 .. method:: Unpacker.get_position()

   156 

   157    Returns the current unpack position in the data buffer.

   158 

   159 

   160 .. method:: Unpacker.set_position(position)

   161 

   162    Sets the data buffer unpack position to *position*.  You should be careful about

   163    using :meth:`get_position` and :meth:`set_position`.

   164 

   165 

   166 .. method:: Unpacker.get_buffer()

   167 

   168    Returns the current unpack data buffer as a string.

   169 

   170 

   171 .. method:: Unpacker.done()

   172 

   173    Indicates unpack completion.  Raises an :exc:`Error` exception if all of the

   174    data has not been unpacked.

   175 

   176 In addition, every data type that can be packed with a :class:`Packer`, can be

   177 unpacked with an :class:`Unpacker`.  Unpacking methods are of the form

   178 ``unpack_type()``, and take no arguments.  They return the unpacked object.

   179 

   180 

   181 .. method:: Unpacker.unpack_float()

   182 

   183    Unpacks a single-precision floating point number.

   184 

   185 

   186 .. method:: Unpacker.unpack_double()

   187 

   188    Unpacks a double-precision floating point number, similarly to

   189    :meth:`unpack_float`.

   190 

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

   192 

   193 

   194 .. method:: Unpacker.unpack_fstring(n)

   195 

   196    Unpacks and returns a fixed length string.  *n* is the number of characters

   197    expected.  Padding with null bytes to guaranteed 4 byte alignment is assumed.

   198 

   199 

   200 .. method:: Unpacker.unpack_fopaque(n)

   201 

   202    Unpacks and returns a fixed length opaque data stream, similarly to

   203    :meth:`unpack_fstring`.

   204 

   205 

   206 .. method:: Unpacker.unpack_string()

   207 

   208    Unpacks and returns a variable length string.  The length of the string is first

   209    unpacked as an unsigned integer, then the string data is unpacked with

   210    :meth:`unpack_fstring`.

   211 

   212 

   213 .. method:: Unpacker.unpack_opaque()

   214 

   215    Unpacks and returns a variable length opaque data string, similarly to

   216    :meth:`unpack_string`.

   217 

   218 

   219 .. method:: Unpacker.unpack_bytes()

   220 

   221    Unpacks and returns a variable length byte stream, similarly to

   222    :meth:`unpack_string`.

   223 

   224 The following methods support unpacking arrays and lists:

   225 

   226 

   227 .. method:: Unpacker.unpack_list(unpack_item)

   228 

   229    Unpacks and returns a list of homogeneous items.  The list is unpacked one

   230    element at a time by first unpacking an unsigned integer flag.  If the flag is

   231    ``1``, then the item is unpacked and appended to the list.  A flag of ``0``

   232    indicates the end of the list.  *unpack_item* is the function that is called to

   233    unpack the items.

   234 

   235 

   236 .. method:: Unpacker.unpack_farray(n, unpack_item)

   237 

   238    Unpacks and returns (as a list) a fixed length array of homogeneous items.  *n*

   239    is number of list elements to expect in the buffer. As above, *unpack_item* is

   240    the function used to unpack each element.

   241 

   242 

   243 .. method:: Unpacker.unpack_array(unpack_item)

   244 

   245    Unpacks and returns a variable length *list* of homogeneous items. First, the

   246    length of the list is unpacked as an unsigned integer, then each element is

   247    unpacked as in :meth:`unpack_farray` above.

   248 

   249 

   250 .. _xdr-exceptions:

   251 

   252 Exceptions

   253 ----------

   254 

   255 Exceptions in this module are coded as class instances:

   256 

   257 

   258 .. exception:: Error

   259 

   260    The base exception class.  :exc:`Error` has a single public data member

   261    :attr:`msg` containing the description of the error.

   262 

   263 

   264 .. exception:: ConversionError

   265 

   266    Class derived from :exc:`Error`.  Contains no additional instance variables.

   267 

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

   269 

   270    import xdrlib

   271    p = xdrlib.Packer()

   272    try:

   273        p.pack_double(8.01)

   274    except xdrlib.ConversionError, instance:

   275        print 'packing the double failed:', instance.msg

   276