Patch implementing bz2 module.

* setup.py
  (PyBuildExt.detect_modules): Included bz2 module detection.

* Modules/bz2module.c
* Lib/test/test_bz2.py
* Doc/lib/libbz2.tex
  Included files implementing, testing, and documenting bz2 module.

* Doc/Makefile.deps
* Doc/lib/lib.tex
  Include references to libbz2.tex.

* Misc/NEWS
  (Library): Mention distutils' c++ linkage patch, and new bz2 module.

1 files changed, 174 insertions, 0 deletions

diff --git a/Doc/lib/libbz2.tex b/Doc/lib/libbz2.tex
new file mode 100644
index 0000000..a6d9f73
--- /dev/null
+++ b/Doc/lib/libbz2.tex
@@ -0,0 +1,174 @@
+\section{\module{bz2} ---
+         Compression compatible with \program{bzip2}}
+
+\declaremodule{builtin}{bz2}
+\modulesynopsis{Interface to compression and decompression
+                routines compatible with \program{bzip2}.}
+\moduleauthor{Gustavo Niemeyer}{niemeyer@conectiva.com}
+\sectionauthor{Gustavo Niemeyer}{niemeyer@conectiva.com}
+
+\versionadded{2.3}
+
+This module provides a comprehensive interface for the bz2 compression library.
+It implements a complete file interface, one-shot (de)compression functions,
+and types for sequential (de)compression.
+
+Here is a resume of the features offered by the bz2 module:
+
+\begin{itemize}
+\item \class{BZ2File} class implements a complete file interface, including
+      \method{readline()}, \method{readlines()}, \method{xreadlines()},
+      \method{writelines()}, \method{seek()}, etc;
+\item \class{BZ2File} class implements emulated \method{seek()} support;
+\item \class{BZ2File} class implements universal newline support;
+\item \class{BZ2File} class offers an optimized line iteration using
+      the readahead algorithm borrowed from file objects;
+\item \class{BZ2File} class developed inheriting builtin file type
+      (\code{isinstance(BZ2File(), file) == 1});
+\item Sequential (de)compression supported by \class{BZ2Compressor} and
+      \class{BZ2Decompressor} classes;
+\item One-shot (de)compression supported by \function{compress()} and
+      \function{decompress()} functions;
+\item Thread safety uses individual locking mechanism;
+\item Complete inline documentation;
+\end{itemize}
+
+
+\subsection{(De)compression of files}
+
+Handling of compressed files is offered by the \class{BZ2File} class.
+
+\begin{classdesc}{BZ2File}{filename \optional{, mode='r'\optional{,
+                           buffering=0\optional{, compresslevel=9}}}}
+Open a bz2 file. Mode can be either \code{'r'} or \code{'w'}, for reading
+(default) or writing. When opened for writing, the file will be created if
+it doesn't exist, and truncated otherwise. If the buffering argument is given,
+\code{0} means unbuffered, and larger numbers specify the buffer size. If
+compresslevel is given, must be a number between \code{1} and \code{9}.
+Add a \code{'U'} to mode to open the file for input with universal newline
+support. Any line ending in the input file will be seen as a
+\code{'\textbackslash n'}
+in Python.  Also, a file so opened gains the attribute \member{newlines};
+the value for this attribute is one of \code{None} (no newline read yet),
+\code{'\textbackslash r'}, \code{'\textbackslash n'},
+\code{'\textbackslash r\textbackslash n'} or a tuple containing all the
+newline types seen. Universal newlines are available only when reading.
+\end{classdesc}
+
+\begin{methoddesc}[BZ2File]{close}{}
+Close the file. Sets data attribute \member{closed} to true. A closed file
+cannot be used for further I/O operations. \method{close()} may be called
+more than once without error.
+\end{methoddesc}
+
+\begin{methoddesc}[BZ2File]{read}{\optional{size}}
+Read at most \var{size} uncompressed bytes, returned as a string. If the
+\var{size} argument is negative or omitted, read until EOF is reached.
+\end{methoddesc}
+
+\begin{methoddesc}[BZ2File]{readline}{\optional{size}}
+Return the next line from the file, as a string, retaining newline.
+A non-negative \var{size} argument limits the maximum number of bytes to
+return (an incomplete line may be returned then). Return an empty
+string at EOF.
+\end{methoddesc}
+
+\begin{methoddesc}[BZ2File]{readlines}{\optional{size}}
+Return a list of lines read. The optional \var{size} argument, if given,
+is an approximate bound on the total number of bytes in the lines returned.
+\end{methoddesc}
+
+\begin{methoddesc}[BZ2File]{xreadlines}{}
+For backward compatibility. \class{BZ2File} objects now include the
+performance optimizations previously implemented in the \module{xreadlines}
+module.
+\end{methoddesc}
+
+\begin{methoddesc}[BZ2File]{\_\_iter\_\_}{}
+Iterate trough the file lines. Iteration optimization is implemented
+using the same readahead algorithm available in \class{file} objects.
+\end{methoddesc}
+
+\begin{methoddesc}[BZ2File]{seek}{offset \optional{, whence}}
+Move to new file position. Argument \var{offset} is a byte count. Optional
+argument \var{whence} defaults to \code{0} (offset from start of file,
+offset should be \code{>= 0}); other values are \code{1} (move relative to
+current position, positive or negative), and \code{2} (move relative to end
+of file, usually negative, although many platforms allow seeking beyond
+the end of a file).
+
+Note that seeking of bz2 files is emulated, and depending on the parameters
+the operation may be extremely slow.
+\end{methoddesc}
+
+\begin{methoddesc}[BZ2File]{tell}{}
+Return the current file position, an integer (may be a long integer).
+\end{methoddesc}
+
+\begin{methoddesc}[BZ2File]{write}{data}
+Write string \var{data} to file. Note that due to buffering, \method{close()}
+may be needed before the file on disk reflects the data written.
+\end{methoddesc}
+
+\begin{methoddesc}[BZ2File]{writelines}{sequence_of_strings}
+Write the sequence of strings to the file. Note that newlines are not added.
+The sequence can be any iterable object producing strings. This is equivalent
+to calling write() for each string.
+\end{methoddesc}
+
+
+\subsection{Sequential (de)compression}
+
+Sequential compression and decompression is done using the classes
+\class{BZ2Compressor} and \class{BZ2Decompressor}.
+
+\begin{classdesc}{BZ2Compressor}{\optional{compresslevel=9}}
+Create a new compressor object. This object may be used to compress
+data sequentially. If you want to compress data in one shot, use the
+\function{compress()} function instead. The \var{compresslevel} parameter,
+if given, must be a number between \code{1} and \code{9}.
+\end{classdesc}
+
+\begin{methoddesc}[BZ2Compressor]{compress}{data}
+Provide more data to the compressor object. It will return chunks of compressed
+data whenever possible. When you've finished providing data to compress, call
+the \method{flush()} method to finish the compression process, and return what
+is left in internal buffers.
+\end{methoddesc}
+
+\begin{methoddesc}[BZ2Compressor]{flush}{}
+Finish the compression process and return what is left in internal buffers. You
+must not use the compressor object after calling this method.
+\end{methoddesc}
+
+\begin{classdesc}{BZ2Decompressor}{}
+Create a new decompressor object. This object may be used to decompress
+data sequentially. If you want to decompress data in one shot, use the
+\function{decompress()} function instead.
+\end{classdesc}
+
+\begin{methoddesc}[BZ2Decompressor]{decompress}{data}
+Provide more data to the decompressor object. It will return chunks of
+decompressed data whenever possible. If you try to decompress data after the
+end of stream is found, \exception{EOFError} will be raised. If any data was
+found after the end of stream, it'll be ignored and saved in
+\member{unused\_data} attribute.
+\end{methoddesc}
+
+
+\subsection{One-shot (de)compression}
+
+One-shot compression and decompression is provided trough the
+\function{compress()} and \function{decompress()} functions.
+
+\begin{funcdesc}{compress}{data\optional{, compresslevel=9}}
+Compress \var{data} in one shot. If you want to compress data sequentially,
+use an instance of \class{BZ2Compressor} instead. The \var{compresslevel}
+parameter, if given, must be a number between \code{1} and \code{9}.
+\end{funcdesc}
+
+\begin{funcdesc}{decompress}{}
+Decompress \var{data} in one shot. If you want to decompress data
+sequentially, use an instance of \class{BZ2Decompressor} instead.
+\end{funcdesc}
+