# cpython-withatomic / Doc / libxdrlib.tex

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 \section{Standard module \sectcode{xdrlib}} \label{module-xdrlib} \stmodindex{xdrlib} \index{XDR} \renewcommand{\indexsubitem}{(in module xdrlib)} The \code{xdrlib} module supports the External Data Representation Standard as described in RFC 1014, written by Sun Microsystems, Inc. June 1987. It supports most of the data types described in the RFC. The \code{xdrlib} module defines two classes, one for packing variables into XDR representation, and another for unpacking from XDR representation. There are also two exception classes. \subsection{Packer Objects} \code{Packer} is the class for packing data into XDR representation. The \code{Packer} class is instantiated with no arguments. \begin{funcdesc}{get_buffer}{} Returns the current pack buffer as a string. \end{funcdesc} \begin{funcdesc}{reset}{} Resets the pack buffer to the empty string. \end{funcdesc} In general, you can pack any of the most common XDR data types by calling the appropriate \code{pack_\var{type}} method. Each method takes a single argument, the value to pack. The following simple data type packing methods are supported: \code{pack_uint}, \code{pack_int}, \code{pack_enum}, \code{pack_bool}, \code{pack_uhyper}, and \code{pack_hyper}. \begin{funcdesc}{pack_float}{value} Packs the single-precision floating point number \var{value}. \end{funcdesc} \begin{funcdesc}{pack_double}{value} Packs the double-precision floating point number \var{value}. \end{funcdesc} The following methods support packing strings, bytes, and opaque data: \begin{funcdesc}{pack_fstring}{n\, s} Packs a fixed length string, \var{s}. \var{n} is the length of the string but it is \emph{not} packed into the data buffer. The string is padded with null bytes if necessary to guaranteed 4 byte alignment. \end{funcdesc} \begin{funcdesc}{pack_fopaque}{n\, data} Packs a fixed length opaque data stream, similarly to \code{pack_fstring}. \end{funcdesc} \begin{funcdesc}{pack_string}{s} Packs a variable length string, \var{s}. The length of the string is first packed as an unsigned integer, then the string data is packed with \code{pack_fstring}. \end{funcdesc} \begin{funcdesc}{pack_opaque}{data} Packs a variable length opaque data string, similarly to \code{pack_string}. \end{funcdesc} \begin{funcdesc}{pack_bytes}{bytes} Packs a variable length byte stream, similarly to \code{pack_string}. \end{funcdesc} The following methods support packing arrays and lists: \begin{funcdesc}{pack_list}{list\, pack_item} Packs a \var{list} of homogeneous items. This method is useful for lists with an indeterminate size; i.e. the size is not available until the entire list has been walked. For each item in the list, an unsigned integer \code{1} is packed first, followed by the data value from the list. \var{pack_item} is the function that is called to pack the individual item. At the end of the list, an unsigned integer \code{0} is packed. \end{funcdesc} \begin{funcdesc}{pack_farray}{n\, array\, pack_item} Packs a fixed length list (\var{array}) of homogeneous items. \var{n} is the length of the list; it is \emph{not} packed into the buffer, but a \code{ValueError} exception is raised if \code{len(array)} is not equal to \var{n}. As above, \var{pack_item} is the function used to pack each element. \end{funcdesc} \begin{funcdesc}{pack_array}{list\, pack_item} Packs a variable length \var{list} of homogeneous items. First, the length of the list is packed as an unsigned integer, then each element is packed as in \code{pack_farray} above. \end{funcdesc} \subsection{Unpacker Objects} \code{Unpacker} is the complementary class which unpacks XDR data values from a string buffer, and has the following methods: \begin{funcdesc}{__init__}{data} Instantiates an \code{Unpacker} object with the string buffer \var{data}. \end{funcdesc} \begin{funcdesc}{reset}{data} Resets the string buffer with the given \var{data}. \end{funcdesc} \begin{funcdesc}{get_position}{} Returns the current unpack position in the data buffer. \end{funcdesc} \begin{funcdesc}{set_position}{position} Sets the data buffer unpack position to \var{position}. You should be careful about using \code{get_position()} and \code{set_position()}. \end{funcdesc} \begin{funcdesc}{get_buffer}{} Returns the current unpack data buffer as a string. \end{funcdesc} \begin{funcdesc}{done}{} Indicates unpack completion. Raises an \code{xdrlib.Error} exception if all of the data has not been unpacked. \end{funcdesc} In addition, every data type that can be packed with a \code{Packer}, can be unpacked with an \code{Unpacker}. Unpacking methods are of the form \code{unpack_\var{type}}, and take no arguments. They return the unpacked object. \begin{funcdesc}{unpack_float}{} Unpacks a single-precision floating point number. \end{funcdesc} \begin{funcdesc}{unpack_double}{} Unpacks a double-precision floating point number, similarly to \code{unpack_float}. \end{funcdesc} In addition, the following methods unpack strings, bytes, and opaque data: \begin{funcdesc}{unpack_fstring}{n} Unpacks and returns a fixed length string. \var{n} is the number of characters expected. Padding with null bytes to guaranteed 4 byte alignment is assumed. \end{funcdesc} \begin{funcdesc}{unpack_fopaque}{n} Unpacks and returns a fixed length opaque data stream, similarly to \code{unpack_fstring}. \end{funcdesc} \begin{funcdesc}{unpack_string}{} Unpacks and returns a variable length string. The length of the string is first unpacked as an unsigned integer, then the string data is unpacked with \code{unpack_fstring}. \end{funcdesc} \begin{funcdesc}{unpack_opaque}{} Unpacks and returns a variable length opaque data string, similarly to \code{unpack_string}. \end{funcdesc} \begin{funcdesc}{unpack_bytes}{} Unpacks and returns a variable length byte stream, similarly to \code{unpack_string}. \end{funcdesc} The following methods support unpacking arrays and lists: \begin{funcdesc}{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 \code{1}, then the item is unpacked and appended to the list. A flag of \code{0} indicates the end of the list. \var{unpack_item} is the function that is called to unpack the items. \end{funcdesc} \begin{funcdesc}{unpack_farray}{n\, unpack_item} Unpacks and returns (as a list) a fixed length array of homogeneous items. \var{n} is number of list elements to expect in the buffer. As above, \var{unpack_item} is the function used to unpack each element. \end{funcdesc} \begin{funcdesc}{unpack_array}{unpack_item} Unpacks and returns a variable length \var{list} of homogeneous items. First, the length of the list is unpacked as an unsigned integer, then each element is unpacked as in \code{unpack_farray} above. \end{funcdesc} \subsection{Exceptions} \nodename{Exceptions in xdrlib module} Exceptions in this module are coded as class instances: \begin{excdesc}{Error} The base exception class. \code{Error} has a single public data member \code{msg} containing the description of the error. \end{excdesc} \begin{excdesc}{ConversionError} Class derived from \code{Error}. Contains no additional instance variables. \end{excdesc} Here is an example of how you would catch one of these exceptions: \bcode\begin{verbatim} import xdrlib p = xdrlib.Packer() try: p.pack_double(8.01) except xdrlib.ConversionError, instance: print 'packing the double failed:', instance.msg \end{verbatim}\ecode 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.