mirror of
https://github.com/python/cpython
synced 2024-09-06 02:38:55 +00:00
Added imghdr,xdrlib; reformatted Makefile somewhat
This commit is contained in:
Guido van Rossum
parent
72fba794d6
commit
40006cfd9b
51
Doc/Makefile
51
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)
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
|
|||
60
Doc/lib/libimghdr.tex
Normal file
60
Doc/lib/libimghdr.tex
Normal file
|
|
@ -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}
|
||||
235
Doc/lib/libxdrlib.tex
Normal file
235
Doc/lib/libxdrlib.tex
Normal file
|
|
@ -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.
|
||||
60
Doc/libimghdr.tex
Normal file
60
Doc/libimghdr.tex
Normal file
|
|
@ -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}
|
||||
235
Doc/libxdrlib.tex
Normal file
235
Doc/libxdrlib.tex
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in a new issue