1 

     2 :mod:`bz2` --- Compression compatible with :program:`bzip2`

     3 ===========================================================

     4 

     5 .. module:: bz2

     6    :synopsis: Interface to compression and decompression routines compatible with bzip2.

     7 .. moduleauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>

     8 .. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>

     9 

    10 

    11 .. versionadded:: 2.3

    12 

    13 This module provides a comprehensive interface for the bz2 compression library.

    14 It implements a complete file interface, one-shot (de)compression functions, and

    15 types for sequential (de)compression.

    16 

    17 For other archive formats, see the :mod:`gzip`, :mod:`zipfile`, and

    18 :mod:`tarfile` modules.

    19 

    20 Here is a summary of the features offered by the bz2 module:

    21 

    22 * :class:`BZ2File` class implements a complete file interface, including

    23   :meth:`readline`, :meth:`readlines`, :meth:`writelines`, :meth:`seek`, etc;

    24 

    25 * :class:`BZ2File` class implements emulated :meth:`seek` support;

    26 

    27 * :class:`BZ2File` class implements universal newline support;

    28 

    29 * :class:`BZ2File` class offers an optimized line iteration using the readahead

    30   algorithm borrowed from file objects;

    31 

    32 * Sequential (de)compression supported by :class:`BZ2Compressor` and

    33   :class:`BZ2Decompressor` classes;

    34 

    35 * One-shot (de)compression supported by :func:`compress` and :func:`decompress`

    36   functions;

    37 

    38 * Thread safety uses individual locking mechanism.

    39 

    40 

    41 (De)compression of files

    42 ------------------------

    43 

    44 Handling of compressed files is offered by the :class:`BZ2File` class.

    45 

    46 

    47 .. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]])

    48 

    49    Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)

    50    or writing. When opened for writing, the file will be created if it doesn't

    51    exist, and truncated otherwise. If *buffering* is given, ``0`` means

    52    unbuffered, and larger numbers specify the buffer size; the default is

    53    ``0``. If *compresslevel* is given, it must be a number between ``1`` and

    54    ``9``; the default is ``9``. Add a ``'U'`` to mode to open the file for input

    55    with universal newline support. Any line ending in the input file will be

    56    seen as a ``'\n'`` in Python.  Also, a file so opened gains the attribute

    57    :attr:`newlines`; the value for this attribute is one of ``None`` (no newline

    58    read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the

    59    newline types seen. Universal newlines are available only when

    60    reading. Instances support iteration in the same way as normal :class:`file`

    61    instances.

    62 

    63 

    64    .. method:: close()

    65 

    66       Close the file. Sets data attribute :attr:`closed` to true. A closed file

    67       cannot be used for further I/O operations. :meth:`close` may be called

    68       more than once without error.

    69 

    70 

    71    .. method:: read([size])

    72 

    73       Read at most *size* uncompressed bytes, returned as a string. If the

    74       *size* argument is negative or omitted, read until EOF is reached.

    75 

    76 

    77    .. method:: readline([size])

    78 

    79       Return the next line from the file, as a string, retaining newline. A

    80       non-negative *size* argument limits the maximum number of bytes to return

    81       (an incomplete line may be returned then). Return an empty string at EOF.

    82 

    83 

    84    .. method:: readlines([size])

    85 

    86       Return a list of lines read. The optional *size* argument, if given, is an

    87       approximate bound on the total number of bytes in the lines returned.

    88 

    89 

    90    .. method:: xreadlines()

    91 

    92       For backward compatibility. :class:`BZ2File` objects now include the

    93       performance optimizations previously implemented in the :mod:`xreadlines`

    94       module.

    95 

    96       .. deprecated:: 2.3 

    97          This exists only for compatibility with the method by this name on

    98          :class:`file` objects, which is deprecated.  Use ``for line in file``

    99          instead.

   100 

   101 

   102    .. method:: seek(offset[, whence])

   103 

   104       Move to new file position. Argument *offset* is a byte count. Optional

   105       argument *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start

   106       of file; offset should be ``>= 0``); other values are ``os.SEEK_CUR`` or

   107       ``1`` (move relative to current position; offset can be positive or

   108       negative), and ``os.SEEK_END`` or ``2`` (move relative to end of file;

   109       offset is usually negative, although many platforms allow seeking beyond

   110       the end of a file).

   111 

   112       Note that seeking of bz2 files is emulated, and depending on the

   113       parameters the operation may be extremely slow.

   114 

   115 

   116    .. method:: tell()

   117 

   118       Return the current file position, an integer (may be a long integer).

   119 

   120 

   121    .. method:: write(data)

   122 

   123       Write string *data* to file. Note that due to buffering, :meth:`close` may

   124       be needed before the file on disk reflects the data written.

   125 

   126 

   127    .. method:: writelines(sequence_of_strings)

   128 

   129       Write the sequence of strings to the file. Note that newlines are not

   130       added. The sequence can be any iterable object producing strings. This is

   131       equivalent to calling write() for each string.

   132 

   133 

   134 Sequential (de)compression

   135 --------------------------

   136 

   137 Sequential compression and decompression is done using the classes

   138 :class:`BZ2Compressor` and :class:`BZ2Decompressor`.

   139 

   140 

   141 .. class:: BZ2Compressor([compresslevel])

   142 

   143    Create a new compressor object. This object may be used to compress data

   144    sequentially. If you want to compress data in one shot, use the

   145    :func:`compress` function instead. The *compresslevel* parameter, if given,

   146    must be a number between ``1`` and ``9``; the default is ``9``.

   147 

   148 

   149    .. method:: compress(data)

   150 

   151       Provide more data to the compressor object. It will return chunks of

   152       compressed data whenever possible. When you've finished providing data to

   153       compress, call the :meth:`flush` method to finish the compression process,

   154       and return what is left in internal buffers.

   155 

   156 

   157    .. method:: flush()

   158 

   159       Finish the compression process and return what is left in internal

   160       buffers. You must not use the compressor object after calling this method.

   161 

   162 

   163 .. class:: BZ2Decompressor()

   164 

   165    Create a new decompressor object. This object may be used to decompress data

   166    sequentially. If you want to decompress data in one shot, use the

   167    :func:`decompress` function instead.

   168 

   169 

   170    .. method:: decompress(data)

   171 

   172       Provide more data to the decompressor object. It will return chunks of

   173       decompressed data whenever possible. If you try to decompress data after

   174       the end of stream is found, :exc:`EOFError` will be raised. If any data

   175       was found after the end of stream, it'll be ignored and saved in

   176       :attr:`unused_data` attribute.

   177 

   178 

   179 One-shot (de)compression

   180 ------------------------

   181 

   182 One-shot compression and decompression is provided through the :func:`compress`

   183 and :func:`decompress` functions.

   184 

   185 

   186 .. function:: compress(data[, compresslevel])

   187 

   188    Compress *data* in one shot. If you want to compress data sequentially, use

   189    an instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter,

   190    if given, must be a number between ``1`` and ``9``; the default is ``9``.

   191 

   192 

   193 .. function:: decompress(data)

   194 

   195    Decompress *data* in one shot. If you want to decompress data sequentially,

   196    use an instance of :class:`BZ2Decompressor` instead.

   197