mirrors/cpython
mirrors/cpython
0
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2024-11-28 08:20:55 +01:00
Code Issues Releases Activity

Added imghdr,xdrlib; reformatted Makefile somewhat

Browse Source
This commit is contained in:
Guido van Rossum 1996-08-19 22:58:03 +00:00
parent 72fba794d6
commit 40006cfd9b
7 changed files with 614 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
Doc/Makefile
View File

@ -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)

2
Doc/lib.tex
View File

@ -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}

2
Doc/lib/lib.tex
View File

@ -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
View 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
View 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
View 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
View 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.