Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 1 | :mod:`bz2` --- Support for :program:`bzip2` compression |
| 2 | ======================================================= |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: bz2 |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 5 | :synopsis: Interfaces for bzip2 compression and decompression. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 6 | .. moduleauthor:: Gustavo Niemeyer <niemeyer@conectiva.com> |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 7 | .. moduleauthor:: Nadeem Vawda <nadeem.vawda@gmail.com> |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | .. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com> |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 9 | .. sectionauthor:: Nadeem Vawda <nadeem.vawda@gmail.com> |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
| 11 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 12 | This module provides a comprehensive interface for compressing and |
| 13 | decompressing data using the bzip2 compression algorithm. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 15 | The :mod:`bz2` module contains: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 17 | * The :class:`BZ2File` class for reading and writing compressed files. |
| 18 | * The :class:`BZ2Compressor` and :class:`BZ2Decompressor` classes for |
| 19 | incremental (de)compression. |
| 20 | * The :func:`compress` and :func:`decompress` functions for one-shot |
| 21 | (de)compression. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 22 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 23 | All of the classes in this module may safely be accessed from multiple threads. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | |
| 25 | |
| 26 | (De)compression of files |
| 27 | ------------------------ |
| 28 | |
Nadeem Vawda | aebcdba | 2012-06-04 23:31:20 +0200 | [diff] [blame^] | 29 | .. class:: BZ2File(filename, mode='r', buffering=None, compresslevel=9) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 31 | Open a bzip2-compressed file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 32 | |
Nadeem Vawda | aebcdba | 2012-06-04 23:31:20 +0200 | [diff] [blame^] | 33 | If *filename* is a :class:`str` or :class:`bytes` object, open the named file |
| 34 | directly. Otherwise, *filename* should be a :term:`file object`, which will |
| 35 | be used to read or write the compressed data. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | |
Nadeem Vawda | 200e00a | 2011-05-27 01:52:16 +0200 | [diff] [blame] | 37 | The *mode* argument can be either ``'r'`` for reading (default), ``'w'`` for |
Nadeem Vawda | aebcdba | 2012-06-04 23:31:20 +0200 | [diff] [blame^] | 38 | overwriting, or ``'a'`` for appending. If *filename* is a file object (rather |
| 39 | than an actual file name), a mode of ``'w'`` does not truncate the file, and |
| 40 | is instead equivalent to ``'a'``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 41 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 42 | The *buffering* argument is ignored. Its use is deprecated. |
| 43 | |
Nadeem Vawda | 200e00a | 2011-05-27 01:52:16 +0200 | [diff] [blame] | 44 | If *mode* is ``'w'`` or ``'a'``, *compresslevel* can be a number between |
| 45 | ``1`` and ``9`` specifying the level of compression: ``1`` produces the |
| 46 | least compression, and ``9`` (default) produces the most compression. |
| 47 | |
| 48 | If *mode* is ``'r'``, the input file may be the concatenation of multiple |
| 49 | compressed streams. |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 50 | |
| 51 | :class:`BZ2File` provides all of the members specified by the |
| 52 | :class:`io.BufferedIOBase`, except for :meth:`detach` and :meth:`truncate`. |
| 53 | Iteration and the :keyword:`with` statement are supported. |
| 54 | |
| 55 | :class:`BZ2File` also provides the following method: |
| 56 | |
| 57 | .. method:: peek([n]) |
| 58 | |
| 59 | Return buffered data without advancing the file position. At least one |
| 60 | byte of data will be returned (unless at EOF). The exact number of bytes |
| 61 | returned is unspecified. |
| 62 | |
| 63 | .. versionadded:: 3.3 |
Benjamin Peterson | e0124bd | 2009-03-09 21:04:33 +0000 | [diff] [blame] | 64 | |
Benjamin Peterson | 10745a9 | 2009-03-09 21:08:47 +0000 | [diff] [blame] | 65 | .. versionchanged:: 3.1 |
Benjamin Peterson | e0124bd | 2009-03-09 21:04:33 +0000 | [diff] [blame] | 66 | Support for the :keyword:`with` statement was added. |
| 67 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 68 | .. versionchanged:: 3.3 |
| 69 | The :meth:`fileno`, :meth:`readable`, :meth:`seekable`, :meth:`writable`, |
| 70 | :meth:`read1` and :meth:`readinto` methods were added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 72 | .. versionchanged:: 3.3 |
Nadeem Vawda | aebcdba | 2012-06-04 23:31:20 +0200 | [diff] [blame^] | 73 | Support was added for *filename* being a :term:`file object` instead of an |
| 74 | actual filename. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | |
Nadeem Vawda | 200e00a | 2011-05-27 01:52:16 +0200 | [diff] [blame] | 76 | .. versionchanged:: 3.3 |
| 77 | The ``'a'`` (append) mode was added, along with support for reading |
| 78 | multi-stream files. |
| 79 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 81 | Incremental (de)compression |
| 82 | --------------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | |
Georg Brandl | 0d8f073 | 2009-04-05 22:20:44 +0000 | [diff] [blame] | 84 | .. class:: BZ2Compressor(compresslevel=9) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
| 86 | Create a new compressor object. This object may be used to compress data |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 87 | incrementally. For one-shot compression, use the :func:`compress` function |
| 88 | instead. |
| 89 | |
| 90 | *compresslevel*, if given, must be a number between ``1`` and ``9``. The |
| 91 | default is ``9``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 93 | .. method:: compress(data) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 94 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 95 | Provide data to the compressor object. Returns a chunk of compressed data |
| 96 | if possible, or an empty byte string otherwise. |
| 97 | |
| 98 | When you have finished providing data to the compressor, call the |
| 99 | :meth:`flush` method to finish the compression process. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | |
| 101 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 102 | .. method:: flush() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 104 | Finish the compression process. Returns the compressed data left in |
| 105 | internal buffers. |
| 106 | |
| 107 | The compressor object may not be used after this method has been called. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 108 | |
| 109 | |
| 110 | .. class:: BZ2Decompressor() |
| 111 | |
| 112 | Create a new decompressor object. This object may be used to decompress data |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 113 | incrementally. For one-shot compression, use the :func:`decompress` function |
| 114 | instead. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | |
Nadeem Vawda | 200e00a | 2011-05-27 01:52:16 +0200 | [diff] [blame] | 116 | .. note:: |
| 117 | This class does not transparently handle inputs containing multiple |
| 118 | compressed streams, unlike :func:`decompress` and :class:`BZ2File`. If |
| 119 | you need to decompress a multi-stream input with :class:`BZ2Decompressor`, |
| 120 | you must use a new decompressor for each stream. |
| 121 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 122 | .. method:: decompress(data) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 123 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 124 | Provide data to the decompressor object. Returns a chunk of decompressed |
| 125 | data if possible, or an empty byte string otherwise. |
| 126 | |
Nadeem Vawda | 200e00a | 2011-05-27 01:52:16 +0200 | [diff] [blame] | 127 | Attempting to decompress data after the end of the current stream is |
| 128 | reached raises an :exc:`EOFError`. If any data is found after the end of |
| 129 | the stream, it is ignored and saved in the :attr:`unused_data` attribute. |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 130 | |
| 131 | |
| 132 | .. attribute:: eof |
| 133 | |
| 134 | True if the end-of-stream marker has been reached. |
| 135 | |
| 136 | .. versionadded:: 3.3 |
| 137 | |
| 138 | |
| 139 | .. attribute:: unused_data |
| 140 | |
| 141 | Data found after the end of the compressed stream. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
Nadeem Vawda | 200e00a | 2011-05-27 01:52:16 +0200 | [diff] [blame] | 143 | If this attribute is accessed before the end of the stream has been |
| 144 | reached, its value will be ``b''``. |
| 145 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 146 | |
| 147 | One-shot (de)compression |
| 148 | ------------------------ |
| 149 | |
Georg Brandl | 0d8f073 | 2009-04-05 22:20:44 +0000 | [diff] [blame] | 150 | .. function:: compress(data, compresslevel=9) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 151 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 152 | Compress *data*. |
| 153 | |
| 154 | *compresslevel*, if given, must be a number between ``1`` and ``9``. The |
| 155 | default is ``9``. |
| 156 | |
| 157 | For incremental compression, use a :class:`BZ2Compressor` instead. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 158 | |
| 159 | |
| 160 | .. function:: decompress(data) |
| 161 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 162 | Decompress *data*. |
| 163 | |
Nadeem Vawda | 200e00a | 2011-05-27 01:52:16 +0200 | [diff] [blame] | 164 | If *data* is the concatenation of multiple compressed streams, decompress |
| 165 | all of the streams. |
| 166 | |
Antoine Pitrou | 37dc5f8 | 2011-04-03 17:05:46 +0200 | [diff] [blame] | 167 | For incremental decompression, use a :class:`BZ2Decompressor` instead. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 168 | |
Nadeem Vawda | 200e00a | 2011-05-27 01:52:16 +0200 | [diff] [blame] | 169 | .. versionchanged:: 3.3 |
| 170 | Support for multi-stream inputs was added. |
| 171 | |