diff options
Diffstat (limited to 'Doc/lib')
| -rw-r--r-- | Doc/lib/lib.tex | 2 | ||||
| -rw-r--r-- | Doc/lib/libimghdr.tex | 60 | ||||
| -rw-r--r-- | Doc/lib/libxdrlib.tex | 235 |
3 files changed, 297 insertions, 0 deletions
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. |