summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorNadeem Vawda <nadeem.vawda@gmail.com>2011-05-27 00:03:06 (GMT)
committerNadeem Vawda <nadeem.vawda@gmail.com>2011-05-27 00:03:06 (GMT)
commit4e18ac850f4ba24d5de10137b9e04a900fc3e215 (patch)
tree8ad2e5db8bf20315d0bbd95351ed2c6a518661f6 /Doc
parent98fe1a0c3bacdc51071d960d8d76b3b9f5b0d8c6 (diff)
parent200e00a90441f0ee40a71306256774feb0beca7b (diff)
downloadcpython-4e18ac850f4ba24d5de10137b9e04a900fc3e215.zip
cpython-4e18ac850f4ba24d5de10137b9e04a900fc3e215.tar.gz
cpython-4e18ac850f4ba24d5de10137b9e04a900fc3e215.tar.bz2
Merge heads
Diffstat (limited to 'Doc')
-rw-r--r--Doc/library/bz2.rst39
1 files changed, 31 insertions, 8 deletions
diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index 2ccdb51..87f2cf3 100644
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -37,14 +37,18 @@ All of the classes in this module may safely be accessed from multiple threads.
*fileobj*), or operate directly on a named file (named by *filename*).
Exactly one of these two parameters should be provided.
- The *mode* argument can be either ``'r'`` for reading (default), or ``'w'``
- for writing.
+ The *mode* argument can be either ``'r'`` for reading (default), ``'w'`` for
+ overwriting, or ``'a'`` for appending. If *fileobj* is provided, a mode of
+ ``'w'`` does not truncate the file, and is instead equivalent to ``'a'``.
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.
+ If *mode* is ``'w'`` or ``'a'``, *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.
+
+ If *mode* is ``'r'``, the input file may be the concatenation of multiple
+ compressed streams.
:class:`BZ2File` provides all of the members specified by the
:class:`io.BufferedIOBase`, except for :meth:`detach` and :meth:`truncate`.
@@ -70,6 +74,10 @@ All of the classes in this module may safely be accessed from multiple threads.
.. versionchanged:: 3.3
The *fileobj* argument to the constructor was added.
+ .. versionchanged:: 3.3
+ The ``'a'`` (append) mode was added, along with support for reading
+ multi-stream files.
+
Incremental (de)compression
---------------------------
@@ -106,14 +114,20 @@ Incremental (de)compression
incrementally. For one-shot compression, use the :func:`decompress` function
instead.
+ .. note::
+ This class does not transparently handle inputs containing multiple
+ compressed streams, unlike :func:`decompress` and :class:`BZ2File`. If
+ you need to decompress a multi-stream input with :class:`BZ2Decompressor`,
+ you must use a new decompressor for each stream.
+
.. method:: decompress(data)
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.
+ Attempting to decompress data after the end of the current 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
@@ -127,6 +141,9 @@ Incremental (de)compression
Data found after the end of the compressed stream.
+ If this attribute is accessed before the end of the stream has been
+ reached, its value will be ``b''``.
+
One-shot (de)compression
------------------------
@@ -145,5 +162,11 @@ One-shot (de)compression
Decompress *data*.
+ If *data* is the concatenation of multiple compressed streams, decompress
+ all of the streams.
+
For incremental decompression, use a :class:`BZ2Decompressor` instead.
+ .. versionchanged:: 3.3
+ Support for multi-stream inputs was added.
+