:mod:`bz2` --- Support for :program:`bzip2` compression ======================================================= .. module:: bz2 :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 compressing and decompressing data using the bzip2 compression algorithm. The :mod:`bz2` module contains: * The :func:`.open` function and :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 ------------------------ .. function:: open(filename, mode='r', compresslevel=9, encoding=None, errors=None, newline=None) Open a bzip2-compressed file in binary or text mode, returning a :term:`file object`. As with the constructor for :class:`BZ2File`, the *filename* argument can be an actual filename (a :class:`str` or :class:`bytes` object), or an existing file object to read from or write to. The *mode* argument can be any of ``'r'``, ``'rb'``, ``'w'``, ``'wb'``, ``'x'``, ``'xb'``, ``'a'`` or ``'ab'`` for binary mode, or ``'rt'``, ``'wt'``, ``'xt'``, or ``'at'`` for text mode. The default is ``'rb'``. The *compresslevel* argument is an integer from 1 to 9, as for the :class:`BZ2File` constructor. For binary mode, this function is equivalent to the :class:`BZ2File` constructor: ``BZ2File(filename, mode, compresslevel=compresslevel)``. In this case, the *encoding*, *errors* and *newline* arguments must not be provided. For text mode, a :class:`BZ2File` object is created, and wrapped in an :class:`io.TextIOWrapper` instance with the specified encoding, error handling behavior, and line ending(s). .. versionadded:: 3.3 .. versionchanged:: 3.4 The ``'x'`` (exclusive creation) mode was added. .. class:: BZ2File(filename, mode='r', buffering=None, compresslevel=9) Open a bzip2-compressed file in binary mode. If *filename* is a :class:`str` or :class:`bytes` object, open the named file directly. Otherwise, *filename* should be a :term:`file object`, which will be used to read or write the compressed data. The *mode* argument can be either ``'r'`` for reading (default), ``'w'`` for overwriting, ``'x'`` for exclusive creation, or ``'a'`` for appending. These can equivalently be given as ``'rb'``, ``'wb'``, ``'xb'`` and ``'ab'`` respectively. If *filename* is a file object (rather than an actual file name), 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'`` 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`. Iteration and the :keyword:`with` statement are supported. :class:`BZ2File` also provides the following method: .. 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. .. note:: While calling :meth:`peek` does not change the file position of the :class:`BZ2File`, it may change the position of the underlying file object (e.g. if the :class:`BZ2File` was constructed by passing a file object for *filename*). .. versionadded:: 3.3 .. versionchanged:: 3.1 Support for the :keyword:`with` statement was added. .. versionchanged:: 3.3 The :meth:`fileno`, :meth:`readable`, :meth:`seekable`, :meth:`writable`, :meth:`read1` and :meth:`readinto` methods were added. .. versionchanged:: 3.3 Support was added for *filename* being a :term:`file object` instead of an actual filename. .. versionchanged:: 3.3 The ``'a'`` (append) mode was added, along with support for reading multi-stream files. .. versionchanged:: 3.4 The ``'x'`` (exclusive creation) mode was added. Incremental (de)compression --------------------------- .. 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. *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. .. class:: BZ2Decompressor() 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.