diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt --- a/Doc/ACKS.txt +++ b/Doc/ACKS.txt @@ -199,6 +199,7 @@ * Jim Tittsler * David Turner * Ville Vainio + * Nadeem Vawda * Martijn Vries * Charles G. Waldman * Greg Ward diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst --- a/Doc/library/bz2.rst +++ b/Doc/library/bz2.rst @@ -1,189 +1,216 @@ -:mod:`bz2` --- Compression compatible with :program:`bzip2` -=========================================================== +:mod:`bz2` --- Support for :program:`bzip2` compression +======================================================= .. module:: bz2 - :synopsis: Interface to compression and decompression routines - compatible with bzip2. + :synopsis: Interfaces for bzip2 compression and decompression. .. moduleauthor:: Gustavo Niemeyer +.. moduleauthor:: Nadeem Vawda .. sectionauthor:: Gustavo Niemeyer +.. sectionauthor:: Nadeem Vawda -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. +This module provides a comprehensive interface for compressing and decompressing +data using the bzip2 compression algorithm. -For other archive formats, see the :mod:`gzip`, :mod:`zipfile`, and +For related file formats, see the :mod:`gzip`, :mod:`zipfile`, and :mod:`tarfile` modules. -Here is a summary of the features offered by the bz2 module: +The :mod:`bz2` module contains: -* :class:`BZ2File` class implements a complete file interface, including - :meth:`~BZ2File.readline`, :meth:`~BZ2File.readlines`, - :meth:`~BZ2File.writelines`, :meth:`~BZ2File.seek`, etc; +* The :class:`BZ2File` class for reading and writing compressed files. +* The :class:`BZ2Compressor` and :class:`BZ2Decompressor` classes for + sequential (de)compression. +* The :func:`compress` and :func:`decompress` functions for one-shot + (de)compression. -* :class:`BZ2File` class implements emulated :meth:`~BZ2File.seek` support; - -* :class:`BZ2File` class implements universal newline support; - -* :class:`BZ2File` class offers an optimized line iteration using a readahead - algorithm; - -* Sequential (de)compression supported by :class:`BZ2Compressor` and - :class:`BZ2Decompressor` classes; - -* One-shot (de)compression supported by :func:`compress` and :func:`decompress` - functions; - -* Thread safety uses individual locking mechanism. +All of the classes in this module may safely be accessed from multiple threads. (De)compression of files ------------------------ -Handling of compressed files is offered by the :class:`BZ2File` class. +.. class:: BZ2File(filename=None, mode='r', buffering=None, compresslevel=9, fileobj=None) + Open a bzip2-compressed file. -.. class:: BZ2File(filename, mode='r', buffering=0, compresslevel=9) + The :class:`BZ2File` can wrap an existing :term:`file object` (given by + *fileobj*), or operate directly on a named file (named by *filename*). + Exactly one of these two parameters should be provided. - Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default) - or writing. When opened for writing, the file will be created if it doesn't - exist, and truncated otherwise. If *buffering* is given, ``0`` means - unbuffered, and larger numbers specify the buffer size; the default is - ``0``. If *compresslevel* is given, it must be a number between ``1`` and - ``9``; the default is ``9``. Add a ``'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 ``'\n'`` in Python. Also, a file so opened gains the attribute - :attr:`newlines`; the value for this attribute is one of ``None`` (no newline - read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the - newline types seen. Universal newlines are available only when - reading. Instances support iteration in the same way as normal :class:`file` - instances. + The *mode* argument can be either ``'r'`` for reading (default), or ``'w'`` + for writing. - :class:`BZ2File` supports the :keyword:`with` statement. + The *buffering* argument is ignored. Its use is deprecated. + + If *mode* is ``'w'``, *compresslevel* can be a number between ``1`` and ``9`` + specifying the level of compression: ``1`` produces the least compression, + and ``9`` (default) produces the most compression. + + :class:`BZ2File` supports iteration and the :keyword:`with` statement. .. versionchanged:: 3.1 Support for the :keyword:`with` statement was added. + .. versionchanged:: 3.3 + The *fileobj* argument was added. + + :class:`BZ2File` provides the following data attributes and methods: .. method:: close() - Close the file. Sets data attribute :attr:`closed` to true. A closed file - cannot be used for further I/O operations. :meth:`close` may be called - more than once without error. + Flush and close the file. :meth:`close` may be called more than once + without error. Once the file is closed, any other operation on it will + raise a :exc:`ValueError`. + + + .. attribute:: closed + + True if the file is closed. + + + .. method:: peek([n]) + + Return buffered data without advancing the file position. At least one + byte of data will be returned (unless at EOF). The exact number of bytes + returned is unspecified. + + .. versionadded:: 3.3 .. method:: read([size]) - Read at most *size* uncompressed bytes, returned as a byte string. If the - *size* argument is negative or omitted, read until EOF is reached. + Read up to *size* uncompressed bytes from the file. If *size* is negative + or omitted, read until EOF is reached. An empty byte string is returned + if the file is already at EOF. .. method:: readline([size]) - Return the next line from the file, as a byte string, retaining newline. - A non-negative *size* argument limits the maximum number of bytes to - return (an incomplete line may be returned then). Return an empty byte - string at EOF. + Read a line of uncompressed bytes from the file. The terminating newline + (if present) is retained. If *size* is non-negative, no more than *size* + bytes will be returned (in which case the line may be incomplete). An + empty byte string is returned if the file is already at EOF. .. method:: readlines([size]) - Return a list of lines read. The optional *size* argument, if given, is an - approximate bound on the total number of bytes in the lines returned. + Read a list of lines of uncompressed bytes from the file. *size* can be + specified to control the number of lines read: no further lines will be + read once the total size of the lines read so far equals or exceeds + *size*. .. method:: seek(offset[, whence]) - Move to new file position. Argument *offset* is a byte count. Optional - argument *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start - of file; offset should be ``>= 0``); other values are ``os.SEEK_CUR`` or - ``1`` (move relative to current position; offset can be positive or - negative), and ``os.SEEK_END`` or ``2`` (move relative to end of file; - offset is usually negative, although many platforms allow seeking beyond - the end of a file). + Change the file position. - Note that seeking of bz2 files is emulated, and depending on the - parameters the operation may be extremely slow. + The new position is specified by *offset*, relative to the position + indicated by *whence*. Values for *whence* are: + + * ``0`` -- start of stream (default); *offset* must not be negative + * ``1`` -- current stream position + * ``2`` -- end of stream; *offset* must not be positive + + Returns the new file position. + + Note that seeking is emulated, so depending on the parameters, this + operation may be extremely slow. .. method:: tell() - Return the current file position, an integer. + Return the current file position. .. method:: write(data) - Write the byte string *data* to file. Note that due to buffering, - :meth:`close` may be needed before the file on disk reflects the data - written. + Write the byte string *data* to file. Returns the number of uncompressed + bytes written, which is always ``len(data)``. + Note that due to buffering, the file on disk may not reflect the data + written until :meth:`close` is called. - .. method:: writelines(sequence_of_byte_strings) - Write the sequence of byte strings to the file. Note that newlines are not - added. The sequence can be any iterable object producing byte strings. - This is equivalent to calling write() for each byte string. + .. method:: writelines(seq) + Write a sequence of byte strings to the file. Returns the number of bytes + uncompressed written. *seq* can be any iterable yielding byte strings. + Line separators are not added between the written byte strings. -Sequential (de)compression --------------------------- -Sequential compression and decompression is done using the classes -:class:`BZ2Compressor` and :class:`BZ2Decompressor`. - +Incremental (de)compression +--------------------------- .. class:: BZ2Compressor(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 - :func:`compress` function instead. The *compresslevel* parameter, if given, - must be a number between ``1`` and ``9``; the default is ``9``. + incrementally. For one-shot compression, use the :func:`compress` function + instead. + + *compresslevel*, if given, must be a number between ``1`` and ``9``. The + default is ``9``. .. method:: 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 :meth:`flush` method to finish the compression process, - and return what is left in internal buffers. + Provide data to the compressor object. Returns a chunk of compressed data + if possible, or an empty byte string otherwise. + + When you have finished providing data to the compressor, call the + :meth:`flush` method to finish the compression process. .. method:: flush() - Finish the compression process and return what is left in internal - buffers. You must not use the compressor object after calling this method. + Flush the internal buffers of the compressor object. Returns any + compressed data that was not returned by earlier calls to + :meth:`compress`. + + One this method has been called, the compressor object may no longer be + used. .. class:: 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 - :func:`decompress` function instead. + incrementally. For one-shot compression, use the :func:`decompress` function + instead. .. method:: 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, :exc:`EOFError` will be raised. If any data - was found after the end of stream, it'll be ignored and saved in - :attr:`unused_data` attribute. + Provide data to the decompressor object. Returns a chunk of decompressed + data if possible, or an empty byte string otherwise. + + Attempting to decompress data after the end of stream is reached raises an + :exc:`EOFError`. If any data is found after the end of the stream, it is + ignored and saved in the :attr:`unused_data` attribute. + + + .. attribute:: eof + + True if the end-of-stream marker has been reached. + + + .. attribute:: unused_data + + Data found after the end of the compressed stream. One-shot (de)compression ------------------------ -One-shot compression and decompression is provided through the :func:`compress` -and :func:`decompress` functions. - - .. function:: compress(data, compresslevel=9) - Compress *data* in one shot. If you want to compress data sequentially, use - an instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter, - if given, must be a number between ``1`` and ``9``; the default is ``9``. + Compress *data*. + + *compresslevel*, if given, must be a number between ``1`` and ``9``. The + default is ``9``. + + For incremental compression, use a :class:`BZ2Compressor` object instead. .. function:: decompress(data) - Decompress *data* in one shot. If you want to decompress data sequentially, - use an instance of :class:`BZ2Decompressor` instead. + Decompress *data*. + For incremental decompression, use a :class:`BZ2Decompressor` object instead. +