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