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 13This module provides a comprehensive interface for the bz2 compression library. 14It implements a complete file interface, one-shot (de)compression functions, and 15types for sequential (de)compression. 16 17Here is a summary of the features offered by the bz2 module: 18 19* :class:`BZ2File` class implements a complete file interface, including 20 :meth:`~BZ2File.readline`, :meth:`~BZ2File.readlines`, 21 :meth:`~BZ2File.writelines`, :meth:`~BZ2File.seek`, etc; 22 23* :class:`BZ2File` class implements emulated :meth:`~BZ2File.seek` support; 24 25* :class:`BZ2File` class implements universal newline support; 26 27* :class:`BZ2File` class offers an optimized line iteration using the readahead 28 algorithm borrowed from file objects; 29 30* Sequential (de)compression supported by :class:`BZ2Compressor` and 31 :class:`BZ2Decompressor` classes; 32 33* One-shot (de)compression supported by :func:`compress` and :func:`decompress` 34 functions; 35 36* Thread safety uses individual locking mechanism. 37 38 39(De)compression of files 40------------------------ 41 42Handling of compressed files is offered by the :class:`BZ2File` class. 43 44 45.. index:: 46 single: universal newlines; bz2.BZ2File class 47 48.. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]]) 49 50 Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default) 51 or writing. When opened for writing, the file will be created if it doesn't 52 exist, and truncated otherwise. If *buffering* is given, ``0`` means 53 unbuffered, and larger numbers specify the buffer size; the default is 54 ``0``. If *compresslevel* is given, it must be a number between ``1`` and 55 ``9``; the default is ``9``. Add a ``'U'`` to mode to open the file for input 56 in :term:`universal newlines` mode. Any line ending in the input file will be 57 seen as a ``'\n'`` in Python. Also, a file so opened gains the attribute 58 :attr:`newlines`; the value for this attribute is one of ``None`` (no newline 59 read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the 60 newline types seen. Universal newlines are available only when 61 reading. Instances support iteration in the same way as normal :class:`file` 62 instances. 63 64 :class:`BZ2File` supports the :keyword:`with` statement. 65 66 .. versionchanged:: 2.7 67 Support for the :keyword:`with` statement was added. 68 69 70 .. note:: 71 72 This class does not support input files containing multiple streams (such 73 as those produced by the :program:`pbzip2` tool). When reading such an 74 input file, only the first stream will be accessible. If you require 75 support for multi-stream files, consider using the third-party 76 :mod:`bz2file` module (available from 77 `PyPI <https://pypi.python.org/pypi/bz2file>`_). This module provides a 78 backport of Python 3.3's :class:`BZ2File` class, which does support 79 multi-stream files. 80 81 82 .. method:: close() 83 84 Close the file. Sets data attribute :attr:`closed` to true. A closed file 85 cannot be used for further I/O operations. :meth:`close` may be called 86 more than once without error. 87 88 89 .. method:: read([size]) 90 91 Read at most *size* uncompressed bytes, returned as a string. If the 92 *size* argument is negative or omitted, read until EOF is reached. 93 94 95 .. method:: readline([size]) 96 97 Return the next line from the file, as a string, retaining newline. A 98 non-negative *size* argument limits the maximum number of bytes to return 99 (an incomplete line may be returned then). Return an empty string at EOF. 100 101 102 .. method:: readlines([size]) 103 104 Return a list of lines read. The optional *size* argument, if given, is an 105 approximate bound on the total number of bytes in the lines returned. 106 107 108 .. method:: xreadlines() 109 110 For backward compatibility. :class:`BZ2File` objects now include the 111 performance optimizations previously implemented in the :mod:`xreadlines` 112 module. 113 114 .. deprecated:: 2.3 115 This exists only for compatibility with the method by this name on 116 :class:`file` objects, which is deprecated. Use ``for line in file`` 117 instead. 118 119 120 .. method:: seek(offset[, whence]) 121 122 Move to new file position. Argument *offset* is a byte count. Optional 123 argument *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start 124 of file; offset should be ``>= 0``); other values are ``os.SEEK_CUR`` or 125 ``1`` (move relative to current position; offset can be positive or 126 negative), and ``os.SEEK_END`` or ``2`` (move relative to end of file; 127 offset is usually negative, although many platforms allow seeking beyond 128 the end of a file). 129 130 Note that seeking of bz2 files is emulated, and depending on the 131 parameters the operation may be extremely slow. 132 133 134 .. method:: tell() 135 136 Return the current file position, an integer (may be a long integer). 137 138 139 .. method:: write(data) 140 141 Write string *data* to file. Note that due to buffering, :meth:`close` may 142 be needed before the file on disk reflects the data written. 143 144 145 .. method:: writelines(sequence_of_strings) 146 147 Write the sequence of strings to the file. Note that newlines are not 148 added. The sequence can be any iterable object producing strings. This is 149 equivalent to calling write() for each string. 150 151 152Sequential (de)compression 153-------------------------- 154 155Sequential compression and decompression is done using the classes 156:class:`BZ2Compressor` and :class:`BZ2Decompressor`. 157 158 159.. class:: BZ2Compressor([compresslevel]) 160 161 Create a new compressor object. This object may be used to compress data 162 sequentially. If you want to compress data in one shot, use the 163 :func:`compress` function instead. The *compresslevel* parameter, if given, 164 must be a number between ``1`` and ``9``; the default is ``9``. 165 166 167 .. method:: compress(data) 168 169 Provide more data to the compressor object. It will return chunks of 170 compressed data whenever possible. When you've finished providing data to 171 compress, call the :meth:`flush` method to finish the compression process, 172 and return what is left in internal buffers. 173 174 175 .. method:: flush() 176 177 Finish the compression process and return what is left in internal 178 buffers. You must not use the compressor object after calling this method. 179 180 181.. class:: BZ2Decompressor() 182 183 Create a new decompressor object. This object may be used to decompress data 184 sequentially. If you want to decompress data in one shot, use the 185 :func:`decompress` function instead. 186 187 188 .. method:: decompress(data) 189 190 Provide more data to the decompressor object. It will return chunks of 191 decompressed data whenever possible. If you try to decompress data after 192 the end of stream is found, :exc:`EOFError` will be raised. If any data 193 was found after the end of stream, it'll be ignored and saved in 194 :attr:`unused_data` attribute. 195 196 197One-shot (de)compression 198------------------------ 199 200One-shot compression and decompression is provided through the :func:`compress` 201and :func:`decompress` functions. 202 203 204.. function:: compress(data[, compresslevel]) 205 206 Compress *data* in one shot. If you want to compress data sequentially, use 207 an instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter, 208 if given, must be a number between ``1`` and ``9``; the default is ``9``. 209 210 211.. function:: decompress(data) 212 213 Decompress *data* in one shot. If you want to decompress data sequentially, 214 use an instance of :class:`BZ2Decompressor` instead. 215 216