Doc/library/bz2.rst

   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    :class:`BZ2File` supports the :keyword:`with` statement.
  64
  65    .. versionchanged:: 2.7
  66       Support for the :keyword:`with` statement was added.
  67
  68
  69    .. method:: close()
  70
  71       Close the file. Sets data attribute :attr:`closed` to true. A closed file
  72       cannot be used for further I/O operations. :meth:`close` may be called
  73       more than once without error.
  74
  75
  76    .. method:: read([size])
  77
  78       Read at most *size* uncompressed bytes, returned as a string. If the
  79       *size* argument is negative or omitted, read until EOF is reached.
  80
  81
  82    .. method:: readline([size])
  83
  84       Return the next line from the file, as a string, retaining newline. A
  85       non-negative *size* argument limits the maximum number of bytes to return
  86       (an incomplete line may be returned then). Return an empty string at EOF.
  87
  88
  89    .. method:: readlines([size])
  90
  91       Return a list of lines read. The optional *size* argument, if given, is an
  92       approximate bound on the total number of bytes in the lines returned.
  93
  94
  95    .. method:: xreadlines()
  96
  97       For backward compatibility. :class:`BZ2File` objects now include the
  98       performance optimizations previously implemented in the :mod:`xreadlines`
  99       module.
 100
 101       .. deprecated:: 2.3
 102          This exists only for compatibility with the method by this name on
 103          :class:`file` objects, which is deprecated.  Use ``for line in file``
 104          instead.
 105
 106
 107    .. method:: seek(offset[, whence])
 108
 109       Move to new file position. Argument *offset* is a byte count. Optional
 110       argument *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start
 111       of file; offset should be ``>= 0``); other values are ``os.SEEK_CUR`` or
 112       ``1`` (move relative to current position; offset can be positive or
 113       negative), and ``os.SEEK_END`` or ``2`` (move relative to end of file;
 114       offset is usually negative, although many platforms allow seeking beyond
 115       the end of a file).
 116
 117       Note that seeking of bz2 files is emulated, and depending on the
 118       parameters the operation may be extremely slow.
 119
 120
 121    .. method:: tell()
 122
 123       Return the current file position, an integer (may be a long integer).
 124
 125
 126    .. method:: write(data)
 127
 128       Write string *data* to file. Note that due to buffering, :meth:`close` may
 129       be needed before the file on disk reflects the data written.
 130
 131
 132    .. method:: writelines(sequence_of_strings)
 133
 134       Write the sequence of strings to the file. Note that newlines are not
 135       added. The sequence can be any iterable object producing strings. This is
 136       equivalent to calling write() for each string.
 137
 138
 139 Sequential (de)compression
 140 --------------------------
 141
 142 Sequential compression and decompression is done using the classes
 143 :class:`BZ2Compressor` and :class:`BZ2Decompressor`.
 144
 145
 146 .. class:: BZ2Compressor([compresslevel])
 147
 148    Create a new compressor object. This object may be used to compress data
 149    sequentially. If you want to compress data in one shot, use the
 150    :func:`compress` function instead. The *compresslevel* parameter, if given,
 151    must be a number between ``1`` and ``9``; the default is ``9``.
 152
 153
 154    .. method:: compress(data)
 155
 156       Provide more data to the compressor object. It will return chunks of
 157       compressed data whenever possible. When you've finished providing data to
 158       compress, call the :meth:`flush` method to finish the compression process,
 159       and return what is left in internal buffers.
 160
 161
 162    .. method:: flush()
 163
 164       Finish the compression process and return what is left in internal
 165       buffers. You must not use the compressor object after calling this method.
 166
 167
 168 .. class:: BZ2Decompressor()
 169
 170    Create a new decompressor object. This object may be used to decompress data
 171    sequentially. If you want to decompress data in one shot, use the
 172    :func:`decompress` function instead.
 173
 174
 175    .. method:: decompress(data)
 176
 177       Provide more data to the decompressor object. It will return chunks of
 178       decompressed data whenever possible. If you try to decompress data after
 179       the end of stream is found, :exc:`EOFError` will be raised. If any data
 180       was found after the end of stream, it'll be ignored and saved in
 181       :attr:`unused_data` attribute.
 182
 183
 184 One-shot (de)compression
 185 ------------------------
 186
 187 One-shot compression and decompression is provided through the :func:`compress`
 188 and :func:`decompress` functions.
 189
 190
 191 .. function:: compress(data[, compresslevel])
 192
 193    Compress *data* in one shot. If you want to compress data sequentially, use
 194    an instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter,
 195    if given, must be a number between ``1`` and ``9``; the default is ``9``.
 196
 197
 198 .. function:: decompress(data)
 199
 200    Decompress *data* in one shot. If you want to decompress data sequentially,
 201    use an instance of :class:`BZ2Decompressor` instead.
 202