Diff of /Doc/lib/libbz2.tex [000000] .. [521e89]  Maximize  Restore

  Switch to side-by-side view

--- a
+++ b/Doc/lib/libbz2.tex
@@ -0,0 +1,174 @@
+\section{\module{bz2} ---
+         Compression compatible with \program{bzip2}}
+\modulesynopsis{Interface to compression and decompression
+                routines compatible with \program{bzip2}.}
+\moduleauthor{Gustavo Niemeyer}{niemeyer@conectiva.com}
+\sectionauthor{Gustavo Niemeyer}{niemeyer@conectiva.com}
+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:
+\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;
+\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.
+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.
+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.
+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.
+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.
+For backward compatibility. \class{BZ2File} objects now include the
+performance optimizations previously implemented in the \module{xreadlines}
+Iterate trough the file lines. Iteration optimization is implemented
+using the same readahead algorithm available in \class{file} objects.
+\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.
+Return the current file position, an integer (may be a long integer).
+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.
+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.
+\subsection{Sequential (de)compression}
+Sequential compression and decompression is done using the classes
+\class{BZ2Compressor} and \class{BZ2Decompressor}.
+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}.
+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.
+Finish the compression process and return what is left in internal buffers. You
+must not use the compressor object after calling this method.
+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.
+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.
+\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}.
+Decompress \var{data} in one shot. If you want to decompress data
+sequentially, use an instance of \class{BZ2Decompressor} instead.