:mod:`bz2` --- Support for :program:`bzip2` compression

.. module:: bz2
   :synopsis: Interfaces for bzip2 compression and decompression.

.. moduleauthor:: Gustavo Niemeyer <[email protected]>

.. moduleauthor:: Nadeem Vawda <[email protected]>

.. sectionauthor:: Gustavo Niemeyer <[email protected]>

.. sectionauthor:: Nadeem Vawda <[email protected]>

This module provides a comprehensive interface for compressing and decompressing data using the bzip2 compression algorithm.

The :mod:`bz2` module contains:

• 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.

All of the classes in this module may safely be accessed from multiple threads.

(De)compression of files

Incremental (de)compression

Create a new compressor object. This object may be used to compress data 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 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. Returns the compressed data left in
   internal buffers.

   The compressor object may not be used after this method has been called.

Create a new decompressor object. This object may be used to decompress data 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 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

   True if the end-of-stream marker has been reached.

   .. versionadded:: 3.3

.. attribute:: unused_data

   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

.. function:: compress(data, compresslevel=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` instead.

.. function:: decompress(data)

   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.