diff options
author | Guido van Rossum <guido@python.org> | 1996-08-19 22:58:03 (GMT) |
---|---|---|
committer | Guido van Rossum <guido@python.org> | 1996-08-19 22:58:03 (GMT) |
commit | 40006cfd9b59ba45e77d763ac14a67eb14f6a8bb (patch) | |
tree | 25f6cbbb49fbc067ae99580c0002b2c869c61dbb | |
parent | 72fba794d61abfe5e1fc9b9412b2f7b48dd7acfd (diff) | |
download | cpython-40006cfd9b59ba45e77d763ac14a67eb14f6a8bb.zip cpython-40006cfd9b59ba45e77d763ac14a67eb14f6a8bb.tar.gz cpython-40006cfd9b59ba45e77d763ac14a67eb14f6a8bb.tar.bz2 |
Added imghdr,xdrlib; reformatted Makefile somewhat
-rw-r--r-- | Doc/Makefile | 51 | ||||
-rw-r--r-- | Doc/lib.tex | 2 | ||||
-rw-r--r-- | Doc/lib/lib.tex | 2 | ||||
-rw-r--r-- | Doc/lib/libimghdr.tex | 60 | ||||
-rw-r--r-- | Doc/lib/libxdrlib.tex | 235 | ||||
-rw-r--r-- | Doc/libimghdr.tex | 60 | ||||
-rw-r--r-- | Doc/libxdrlib.tex | 235 |
7 files changed, 614 insertions, 31 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index ce469ca..81d8e72 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -108,37 +108,26 @@ ref.ps: ref.dvi # LaTeX source files for the Python Library Reference LIBFILES = lib.tex \ -libal.tex libaifc.tex liballos.tex \ - libamoeba.tex libarray.tex libaudio.tex libaudioop.tex \ -libbltin.tex libbinascii.tex \ -libcd.tex \ -libcgi.tex libcopy.tex libctb.tex libcrypto.tex \ -libdbm.tex \ -libexcs.tex \ -libfcntl.tex libfl.tex libfm.tex libftplib.tex libfuncs.tex \ -libgdbm.tex libgetopt.tex libgl.tex libgopherlib.tex libgrp.tex \ -libhtmllib.tex libhttplib.tex \ -libimageop.tex libimgfile.tex libintro.tex \ -libjpeg.tex \ -libmac.tex libmacconsole.tex libmacdnr.tex \ - libmacfs.tex libmacos.tex libmacostools.tex libmactcp.tex \ - libmacspeech.tex libmacui.tex \ - libmain.tex libmarshal.tex libmath.tex \ - libmd5.tex libmimetools.tex libmisc.tex \ - libmm.tex libmpz.tex \ -libnntplib.tex \ -libobjs.tex libos.tex \ -libpanel.tex libparser.tex libpickle.tex libposix.tex libposixfile.tex \ - libppath.tex libprofile.tex libpwd.tex libpython.tex \ -librand.tex libregex.tex libregsub.tex \ - librfc822.tex librgbimg.tex librotor.tex \ -libselect.tex libsgi.tex libsgmllib.tex \ - libshelve.tex libsocket.tex libsomeos.tex libstdwin.tex \ - libstring.tex libstrings.tex libstruct.tex libsun.tex libsys.tex \ -libtempfile.tex libtermios.tex libthread.tex libtime.tex \ - libtraceback.tex libtypes.tex libtypes2.tex \ -libunix.tex liburllib.tex liburlparse.tex \ -libwhrandom.tex libwww.tex + libintro.tex libobjs.tex libtypes.tex libexcs.tex libfuncs.tex \ + libpython.tex libsys.tex libtypes2.tex libtraceback.tex libpickle.tex \ + libshelve.tex libcopy.tex libmarshal.tex libimp.tex libparser.tex \ + libbltin.tex libmain.tex libstrings.tex libstring.tex libregex.tex \ + libregsub.tex libstruct.tex libmisc.tex libmath.tex librand.tex \ + libwhrandom.tex libarray.tex liballos.tex libos.tex libtime.tex \ + libgetopt.tex libtempfile.tex liberrno.tex libsomeos.tex libsignal.tex \ + libsocket.tex libselect.tex libthread.tex libunix.tex libposix.tex \ + libppath.tex libpwd.tex libgrp.tex libcrypt.tex libdbm.tex libgdbm.tex \ + libtermios.tex libfcntl.tex libposixfile.tex libsyslog.tex libpdb.tex \ + libprofile.tex libwww.tex libcgi.tex liburllib.tex libhttplib.tex \ + libftplib.tex libgopherlib.tex libnntplib.tex liburlparse.tex \ + libhtmllib.tex libsgmllib.tex librfc822.tex libmimetools.tex \ + libbinascii.tex libmm.tex libaudioop.tex libimageop.tex libaifc.tex \ + libjpeg.tex librgbimg.tex libcrypto.tex libmd5.tex libmpz.tex \ + librotor.tex libmac.tex libctb.tex libmacconsole.tex libmacdnr.tex \ + libmacfs.tex libmacos.tex libmacostools.tex libmactcp.tex \ + libmacspeech.tex libmacui.tex libstdwin.tex libsgi.tex libal.tex \ + libcd.tex libfl.tex libfm.tex libgl.tex libimgfile.tex libsun.tex \ + libxdrlib.tex libimghdr.tex # Library document lib.dvi: $(LIBFILES) diff --git a/Doc/lib.tex b/Doc/lib.tex index 4239c4a..2c99cbe 100644 --- a/Doc/lib.tex +++ b/Doc/lib.tex @@ -142,6 +142,7 @@ to Python and how to embed it in other applications. \input{librfc822} \input{libmimetools} \input{libbinascii} +\input{libxdrlib} \input{libmm} % Multimedia Services \input{libaudioop} @@ -149,6 +150,7 @@ to Python and how to embed it in other applications. \input{libaifc} \input{libjpeg} \input{librgbimg} +\input{libimghdr} \input{libcrypto} % Cryptographic Services \input{libmd5} diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 4239c4a..2c99cbe 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -142,6 +142,7 @@ to Python and how to embed it in other applications. \input{librfc822} \input{libmimetools} \input{libbinascii} +\input{libxdrlib} \input{libmm} % Multimedia Services \input{libaudioop} @@ -149,6 +150,7 @@ to Python and how to embed it in other applications. \input{libaifc} \input{libjpeg} \input{librgbimg} +\input{libimghdr} \input{libcrypto} % Cryptographic Services \input{libmd5} diff --git a/Doc/lib/libimghdr.tex b/Doc/lib/libimghdr.tex new file mode 100644 index 0000000..22d4d0d --- /dev/null +++ b/Doc/lib/libimghdr.tex @@ -0,0 +1,60 @@ +\section{Standard module \sectcode{imghdr}} +\stmodindex{imghdr} + +The \code{imghdr} module determines the type of image contained in a +file or byte stream. + +The \code{imghdr} module defines the following function: + +\renewcommand{\indexsubitem}{(in module imghdr)} + +\begin{funcdesc}{what}{filename\optional{\, h}} +Tests the image data contained in the file named by \var{filename}, +and returns a string describing the image type. If optional \var{h} +is provided, the \var{filename} is ignored and \var{h} is assumed to +contain the byte stream to test. +\end{funcdesc} + +The following image types are recognized, as listed below with the +return value from \code{what}: + +\begin{enumerate} +\item[``rgb''] SGI ImgLib Files + +\item[``gif''] GIF 87a and 89a Files + +\item[``pbm''] Portable Bitmap Files + +\item[``pgm''] Portable Graymap Files + +\item[``ppm''] Portable Pixmap Files + +\item[``tiff''] TIFF Files + +\item[``rast''] Sun Raster Files + +\item[``xbm''] X Bitmap Files + +\item[``jpeg''] JPEG data in JIFF format +\end{enumerate} + +You can extend the list of file types \code{imghdr} can recognize by +appending to this variable: + +\begin{datadesc}{tests} +A list of functions performing the individual tests. Each function +takes two arguments: the byte-stream and an open file-like object. +When \code{what()} is called with a byte-stream, the file-like +object will be \code{None}. + +The test function should return a string describing the image type if +the test succeeded, or \code{None} if it failed. +\end{datadesc} + +Example: + +\begin{verbatim} +>>> import imghdr +>>> imghdr.what('/tmp/bass.gif') +'gif' +\end{verbatim} diff --git a/Doc/lib/libxdrlib.tex b/Doc/lib/libxdrlib.tex new file mode 100644 index 0000000..705dd0f --- /dev/null +++ b/Doc/lib/libxdrlib.tex @@ -0,0 +1,235 @@ +\section{Standard module \sectcode{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, although some, most notably \code{float} and \code{double} are +only supported on those operating systems that provide an XDR +library. + +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}. + +The following methods pack floating point numbers, however they +require C library support. Without the optional C built-in module, +both of these methods will raise an \code{xdrlib.ConversionError} +exception. See the note at the end of this chapter for details. + +\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}{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. The same caveats apply for \code{unpack_float} and +\code{unpack_double} as above. + +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}{pack_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{pack_string}. +\end{funcdesc} + +\begin{funcdesc}{unpack_bytes}{} +Unpacks and returns a variable length byte stream, similarly to +\code{pack_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} + +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: + +\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} + +\subsection{Supporting Floating Point Data} + +Packing and unpacking floating point data, +i.e. \code{Packer.pack_float}, \code{Packer.pack_double}, +\code{Unpacker.unpack_float}, and \code{Unpacker.unpack_double}, are +only supported with the helper built-in \code{_xdr} module, which +relies on your operating system having the appropriate XDR library +routines. + +If you have built the Python interpeter with the \code{_xdr} module, +or have built the \code{_xdr} module as a shared library, +\code{xdrlib} will use these to pack and unpack floating point +numbers. Otherwise, using these routines will raise a +\code{ConversionError} exception. + +See the Python installation instructions for details on building the +\code{_xdr} module. diff --git a/Doc/libimghdr.tex b/Doc/libimghdr.tex new file mode 100644 index 0000000..22d4d0d --- /dev/null +++ b/Doc/libimghdr.tex @@ -0,0 +1,60 @@ +\section{Standard module \sectcode{imghdr}} +\stmodindex{imghdr} + +The \code{imghdr} module determines the type of image contained in a +file or byte stream. + +The \code{imghdr} module defines the following function: + +\renewcommand{\indexsubitem}{(in module imghdr)} + +\begin{funcdesc}{what}{filename\optional{\, h}} +Tests the image data contained in the file named by \var{filename}, +and returns a string describing the image type. If optional \var{h} +is provided, the \var{filename} is ignored and \var{h} is assumed to +contain the byte stream to test. +\end{funcdesc} + +The following image types are recognized, as listed below with the +return value from \code{what}: + +\begin{enumerate} +\item[``rgb''] SGI ImgLib Files + +\item[``gif''] GIF 87a and 89a Files + +\item[``pbm''] Portable Bitmap Files + +\item[``pgm''] Portable Graymap Files + +\item[``ppm''] Portable Pixmap Files + +\item[``tiff''] TIFF Files + +\item[``rast''] Sun Raster Files + +\item[``xbm''] X Bitmap Files + +\item[``jpeg''] JPEG data in JIFF format +\end{enumerate} + +You can extend the list of file types \code{imghdr} can recognize by +appending to this variable: + +\begin{datadesc}{tests} +A list of functions performing the individual tests. Each function +takes two arguments: the byte-stream and an open file-like object. +When \code{what()} is called with a byte-stream, the file-like +object will be \code{None}. + +The test function should return a string describing the image type if +the test succeeded, or \code{None} if it failed. +\end{datadesc} + +Example: + +\begin{verbatim} +>>> import imghdr +>>> imghdr.what('/tmp/bass.gif') +'gif' +\end{verbatim} diff --git a/Doc/libxdrlib.tex b/Doc/libxdrlib.tex new file mode 100644 index 0000000..705dd0f --- /dev/null +++ b/Doc/libxdrlib.tex @@ -0,0 +1,235 @@ +\section{Standard module \sectcode{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, although some, most notably \code{float} and \code{double} are +only supported on those operating systems that provide an XDR +library. + +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}. + +The following methods pack floating point numbers, however they +require C library support. Without the optional C built-in module, +both of these methods will raise an \code{xdrlib.ConversionError} +exception. See the note at the end of this chapter for details. + +\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}{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. The same caveats apply for \code{unpack_float} and +\code{unpack_double} as above. + +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}{pack_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{pack_string}. +\end{funcdesc} + +\begin{funcdesc}{unpack_bytes}{} +Unpacks and returns a variable length byte stream, similarly to +\code{pack_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} + +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: + +\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} + +\subsection{Supporting Floating Point Data} + +Packing and unpacking floating point data, +i.e. \code{Packer.pack_float}, \code{Packer.pack_double}, +\code{Unpacker.unpack_float}, and \code{Unpacker.unpack_double}, are +only supported with the helper built-in \code{_xdr} module, which +relies on your operating system having the appropriate XDR library +routines. + +If you have built the Python interpeter with the \code{_xdr} module, +or have built the \code{_xdr} module as a shared library, +\code{xdrlib} will use these to pack and unpack floating point +numbers. Otherwise, using these routines will raise a +\code{ConversionError} exception. + +See the Python installation instructions for details on building the +\code{_xdr} module. |