Issue #5863: Rewrite BZ2File in pure Python, and allow it to accept

file-like objects using a new `fileobj` constructor argument.  Patch by
Nadeem Vawda.

1 files changed, 82 insertions, 122 deletions

diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index d9a2bad..2ccdb51 100644
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -1,189 +1,149 @@
-: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 <niemeyer@conectiva.com>
+.. moduleauthor:: Nadeem Vawda <nadeem.vawda@gmail.com>
 .. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
+.. sectionauthor:: Nadeem Vawda <nadeem.vawda@gmail.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.
+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
+  incremental (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.
-
-   :class:`BZ2File` supports the :keyword:`with` statement.
-
-   .. versionchanged:: 3.1
-      Support for the :keyword:`with` statement was added.
+   The *mode* argument can be either ``'r'`` for reading (default), or ``'w'``
+   for writing.
 
+   The *buffering* argument is ignored. Its use is deprecated.
 
-   .. method:: close()
+   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.
 
-      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.
+   :class:`BZ2File` provides all of the members specified by the
+   :class:`io.BufferedIOBase`, except for :meth:`detach` and :meth:`truncate`.
+   Iteration and the :keyword:`with` statement are supported.
 
+   :class:`BZ2File` also provides the following method:
 
-   .. method:: read([size])
+   .. method:: peek([n])
 
-      Read at most *size* uncompressed bytes, returned as a byte string. If the
-      *size* argument is negative or omitted, read until EOF is reached.
+      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:: 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.
-
-
-   .. 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.
-
-
-   .. method:: seek(offset[, whence])
+   .. versionchanged:: 3.1
+      Support for the :keyword:`with` statement was added.
 
-      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).
+   .. versionchanged:: 3.3
+      The :meth:`fileno`, :meth:`readable`, :meth:`seekable`, :meth:`writable`,
+      :meth:`read1` and :meth:`readinto` methods were added.
 
-      Note that seeking of bz2 files is emulated, and depending on the
-      parameters the operation may be extremely slow.
+   .. versionchanged:: 3.3
+      The *fileobj* argument to the constructor was added.
 
 
-   .. method:: tell()
+Incremental (de)compression
+---------------------------
 
-      Return the current file position, an integer.
+.. class:: BZ2Compressor(compresslevel=9)
 
+   Create a new compressor object. This object may be used to compress data
+   incrementally. For one-shot compression, use the :func:`compress` function
+   instead.
 
-   .. method:: write(data)
+   *compresslevel*, if given, must be a number between ``1`` and ``9``. The
+   default is ``9``.
 
-      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.
+   .. method:: compress(data)
 
+      Provide data to the compressor object. Returns a chunk of compressed data
+      if possible, or an empty byte string otherwise.
 
-   .. method:: writelines(sequence_of_byte_strings)
+      When you have finished providing data to the compressor, call the
+      :meth:`flush` method to finish the compression process.
 
-      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:: flush()
 
-Sequential (de)compression
---------------------------
+      Finish the compression process. Returns the compressed data left in
+      internal buffers.
 
-Sequential compression and decompression is done using the classes
-:class:`BZ2Compressor` and :class:`BZ2Decompressor`.
+      The compressor object may not be used after this method has been called.
 
 
-.. class:: BZ2Compressor(compresslevel=9)
+.. 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
-   :func:`compress` function instead. The *compresslevel* parameter, if given,
-   must be a number between ``1`` and ``9``; the default is ``9``.
+   Create a new decompressor object. This object may be used to decompress data
+   incrementally. For one-shot compression, use the :func:`decompress` function
+   instead.
 
-   .. method:: compress(data)
+   .. method:: decompress(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 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.
 
-   .. 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.
+   .. attribute:: eof
 
+      True if the end-of-stream marker has been reached.
 
-.. class:: BZ2Decompressor()
+      .. versionadded:: 3.3
 
-   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.
 
-   .. method:: decompress(data)
+   .. attribute:: unused_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.
+      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*.
 
-.. function:: compress(data, compresslevel=9)
+   *compresslevel*, if given, must be a number between ``1`` and ``9``. The
+   default is ``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``.
+   For incremental compression, use a :class:`BZ2Compressor` 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` instead.