| algorithm borrowed from file objects; |
| |
| * Sequential (de)compression supported by :class:`BZ2Compressor` and |
| :class:`BZ2Decompressor` classes; |
| |
| * One-shot (de)compression supported by :func:`compress` and :func:`decompress` |
| functions; |
| |
n | * Thread safety uses individual locking mechanism; |
n | * Thread safety uses individual locking mechanism. |
| |
| * Complete inline documentation; |
| |
| |
| (De)compression of files |
| ------------------------ |
| |
| Handling of compressed files is offered by the :class:`BZ2File` class. |
| |
| |
| .. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]]) |
| |
n | Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default) |
n | Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default) |
| or writing. When opened for writing, the file will be created if it doesn't |
n | exist, and truncated otherwise. If *buffering* is given, ``0`` means unbuffered, |
n | exist, and truncated otherwise. If *buffering* is given, ``0`` means |
| and larger numbers specify the buffer size; the default is ``0``. If |
| unbuffered, and larger numbers specify the buffer size; the default is |
| *compresslevel* is given, it must be a number between ``1`` and ``9``; the |
| ``0``. If *compresslevel* is given, it must be a number between ``1`` and |
| default is ``9``. Add a ``'U'`` to mode to open the file for input with |
| ``9``; the default is ``9``. Add a ``'U'`` to mode to open the file for input |
| universal newline support. Any line ending in the input file will be seen as a |
| with universal newline support. Any line ending in the input file will be |
| ``'\n'`` in Python. Also, a file so opened gains the attribute |
| seen as a ``'\n'`` in Python. Also, a file so opened gains the attribute |
| :attr:`newlines`; the value for this attribute is one of ``None`` (no newline |
n | read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the newline |
n | read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the |
| types seen. Universal newlines are available only when reading. Instances |
| newline types seen. Universal newlines are available only when |
| support iteration in the same way as normal :class:`file` instances. |
| reading. Instances support iteration in the same way as normal :class:`file` |
| instances. |
| |
| |
n | .. method:: BZ2File.close() |
n | .. method:: close() |
| |
n | Close the file. Sets data attribute :attr:`closed` to true. A closed file cannot |
n | Close the file. Sets data attribute :attr:`closed` to true. A closed file |
| be used for further I/O operations. :meth:`close` may be called more than once |
| cannot be used for further I/O operations. :meth:`close` may be called |
| without error. |
| more than once without error. |
| |
| |
n | .. method:: BZ2File.read([size]) |
n | .. method:: read([size]) |
| |
n | Read at most *size* uncompressed bytes, returned as a string. If the *size* |
n | Read at most *size* uncompressed bytes, returned as a string. If the |
| argument is negative or omitted, read until EOF is reached. |
| *size* argument is negative or omitted, read until EOF is reached. |
| |
| |
n | .. method:: BZ2File.readline([size]) |
n | .. method:: readline([size]) |
| |
n | Return the next line from the file, as a string, retaining newline. A non- |
n | Return the next line from the file, as a string, retaining newline. A |
| negative *size* argument limits the maximum number of bytes to return (an |
| non-negative *size* argument limits the maximum number of bytes to return |
| incomplete line may be returned then). Return an empty string at EOF. |
| (an incomplete line may be returned then). Return an empty string at EOF. |
| |
| |
n | .. method:: BZ2File.readlines([size]) |
n | .. method:: readlines([size]) |
| |
n | Return a list of lines read. The optional *size* argument, if given, is an |
n | Return a list of lines read. The optional *size* argument, if given, is an |
| approximate bound on the total number of bytes in the lines returned. |
| approximate bound on the total number of bytes in the lines returned. |
| |
| |
n | .. method:: BZ2File.xreadlines() |
n | .. method:: xreadlines() |
| |
n | For backward compatibility. :class:`BZ2File` objects now include the performance |
n | For backward compatibility. :class:`BZ2File` objects now include the |
| optimizations previously implemented in the :mod:`xreadlines` module. |
| performance optimizations previously implemented in the :mod:`xreadlines` |
| module. |
| |
n | .. deprecated:: 2.3 |
n | .. deprecated:: 2.3 |
| This exists only for compatibility with the method by this name on :class:`file` |
| This exists only for compatibility with the method by this name on |
| objects, which is deprecated. Use ``for line in file`` instead. |
| :class:`file` objects, which is deprecated. Use ``for line in file`` |
| instead. |
| |
| |
n | .. method:: BZ2File.seek(offset[, whence]) |
n | .. method:: seek(offset[, whence]) |
| |
n | Move to new file position. Argument *offset* is a byte count. Optional argument |
n | Move to new file position. Argument *offset* is a byte count. Optional |
| *whence* defaults to ``0`` (offset from start of file, offset should be ``>= |
| argument *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start |
| 0``); other values are ``1`` (move relative to current position, positive or |
| of file; offset should be ``>= 0``); other values are ``os.SEEK_CUR`` or |
| negative), and ``2`` (move relative to end of file, usually negative, although |
| ``1`` (move relative to current position; offset can be positive or |
| many platforms allow seeking beyond the end of a file). |
| negative), and ``os.SEEK_END`` or ``2`` (move relative to end of file; |
| offset is usually negative, although many platforms allow seeking beyond |
| the end of a file). |
| |
n | Note that seeking of bz2 files is emulated, and depending on the parameters the |
n | Note that seeking of bz2 files is emulated, and depending on the |
| operation may be extremely slow. |
| parameters the operation may be extremely slow. |
| |
| |
n | .. method:: BZ2File.tell() |
n | .. method:: tell() |
| |
n | Return the current file position, an integer (may be a long integer). |
n | Return the current file position, an integer (may be a long integer). |
| |
| |
n | .. method:: BZ2File.write(data) |
n | .. method:: write(data) |
| |
n | Write string *data* to file. Note that due to buffering, :meth:`close` may be |
n | Write string *data* to file. Note that due to buffering, :meth:`close` may |
| needed before the file on disk reflects the data written. |
| be needed before the file on disk reflects the data written. |
| |
| |
n | .. method:: BZ2File.writelines(sequence_of_strings) |
n | .. method:: writelines(sequence_of_strings) |
| |
n | Write the sequence of strings to the file. Note that newlines are not added. The |
n | Write the sequence of strings to the file. Note that newlines are not |
| sequence can be any iterable object producing strings. This is equivalent to |
| added. The sequence can be any iterable object producing strings. This is |
| calling write() for each string. |
| equivalent to calling write() for each string. |
| |
| |
| Sequential (de)compression |
| -------------------------- |
| |
| Sequential compression and decompression is done using the classes |
| :class:`BZ2Compressor` and :class:`BZ2Decompressor`. |
| |
| |
| .. class:: BZ2Compressor([compresslevel]) |
| |
| Create a new compressor object. This object may be used to compress data |
n | sequentially. If you want to compress data in one shot, use the :func:`compress` |
n | sequentially. If you want to compress data in one shot, use the |
| function instead. The *compresslevel* parameter, if given, must be a number |
| :func:`compress` function instead. The *compresslevel* parameter, if given, |
| between ``1`` and ``9``; the default is ``9``. |
| must be a number between ``1`` and ``9``; the default is ``9``. |
| |
| |
n | .. method:: BZ2Compressor.compress(data) |
n | .. method:: compress(data) |
| |
n | Provide more data to the compressor object. It will return chunks of compressed |
n | Provide more data to the compressor object. It will return chunks of |
| data whenever possible. When you've finished providing data to compress, call |
| compressed data whenever possible. When you've finished providing data to |
| the :meth:`flush` method to finish the compression process, and return what is |
| compress, call the :meth:`flush` method to finish the compression process, |
| left in internal buffers. |
| and return what is left in internal buffers. |
| |
| |
n | .. method:: BZ2Compressor.flush() |
n | .. method:: flush() |
| |
n | Finish the compression process and return what is left in internal buffers. You |
n | Finish the compression process and return what is left in internal |
| must not use the compressor object after calling this method. |
| buffers. You must not use the compressor object after calling this method. |
| |
| |
| .. class:: BZ2Decompressor() |
| |
| Create a new decompressor object. This object may be used to decompress data |
| sequentially. If you want to decompress data in one shot, use the |
| :func:`decompress` function instead. |
| |
| |
n | .. method:: BZ2Decompressor.decompress(data) |
n | .. method:: decompress(data) |
| |
n | Provide more data to the decompressor object. It will return chunks of |
n | Provide more data to the decompressor object. It will return chunks of |
| decompressed data whenever possible. If you try to decompress data after the end |
| decompressed data whenever possible. If you try to decompress data after |
| of stream is found, :exc:`EOFError` will be raised. If any data was found after |
| the end of stream is found, :exc:`EOFError` will be raised. If any data |
| the end of stream, it'll be ignored and saved in :attr:`unused_data` attribute. |
| was found after the end of stream, it'll be ignored and saved in |
| :attr:`unused_data` attribute. |
| |
| |
| One-shot (de)compression |
| ------------------------ |
| |
| One-shot compression and decompression is provided through the :func:`compress` |
| and :func:`decompress` functions. |
| |
| |
| .. function:: compress(data[, compresslevel]) |
| |
n | Compress *data* in one shot. If you want to compress data sequentially, use an |
n | Compress *data* in one shot. If you want to compress data sequentially, use |
| instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter, if |
| an instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter, |
| given, must be a number between ``1`` and ``9``; the default is ``9``. |
| if given, must be a number between ``1`` and ``9``; the default is ``9``. |
| |
| |
| .. function:: decompress(data) |
| |
t | Decompress *data* in one shot. If you want to decompress data sequentially, use |
t | Decompress *data* in one shot. If you want to decompress data sequentially, |
| an instance of :class:`BZ2Decompressor` instead. |
| use an instance of :class:`BZ2Decompressor` instead. |
| |