bz2 — Поддержка сжатия bzip2¶

(De)сжатие файлов¶

bz2.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)¶

Откройте файл, сжатый с помощью bzip2, в двоичном или текстовом режиме, возвращая значение file object.

Как и в случае с конструктором для BZ2File, аргументом filename может быть фактическое имя файла (объект str или bytes) или существующий файловый объект для чтения или записи.

Аргументом mode может быть любой из 'r', 'rb', 'w', 'wb', 'x', 'xb', 'a' или 'ab' для двоичного режима, или 'rt', 'wt', 'xt', или 'at' для текстового режима. Значение по умолчанию равно 'rb'.

Аргумент compresslevel представляет собой целое число от 1 до 9, как и для конструктора BZ2File.

Для двоичного режима эта функция эквивалентна конструктору BZ2File: BZ2File(filename, mode, compresslevel=compresslevel). В этом случае аргументы encoding, errors и newline не должны указываться.

Для текстового режима создается объект BZ2File и помещается в экземпляр io.TextIOWrapper с указанной кодировкой, режимом обработки ошибок и окончаниями строк.

Добавлено в версии 3.3.

Изменено в версии 3.4: Был добавлен режим 'x' (эксклюзивное создание).

Изменено в версии 3.6: Принимает значение path-like object.

class bz2.BZ2File(filename, mode='r', *, compresslevel=9)¶

Откройте файл, сжатый в формате bzip2, в двоичном режиме.

Если имя файла является объектом str или bytes, откройте непосредственно указанный файл. В противном случае имя файла должно быть file object, которое будет использоваться для чтения или записи сжатых данных.

Аргументом mode может быть либо 'r' для чтения (по умолчанию), 'w' для перезаписи, 'x' для эксклюзивного создания, либо 'a' для добавления. Они могут быть эквивалентно представлены как 'rb', 'wb', 'xb' и 'ab' соответственно.

Если filename является файловым объектом (а не фактическим именем файла), режим 'w' не приводит к усечению файла, а вместо этого эквивалентен 'a'.

Если mode равно 'w' или 'a', compresslevel может быть целым числом в диапазоне от 1 до 9, задающим уровень сжатия: 1 дает наименьший сжатие, и 9 (по умолчанию) обеспечивает максимальное сжатие.

Если значение mode равно 'r', входной файл может представлять собой объединение нескольких сжатых потоков.

BZ2File содержит все элементы, указанные в io.BufferedIOBase, за исключением detach() и truncate(). Поддерживаются итерация и оператор with.

BZ2File также предоставляет следующие методы:

peek([n])¶

Возвращает буферизованные данные без изменения позиции файла. Будет возвращен, по крайней мере, один байт данных (за исключением EOF). Точное количество возвращаемых байт не указано.

Примечание

Хотя вызов peek() не изменяет положение файла в BZ2File, он может изменить положение базового файлового объекта (например, если BZ2File был создан путем передачи файлового объекта для filename).

Добавлено в версии 3.3.

fileno()¶

Возвращает файловый дескриптор для базового файла.

Добавлено в версии 3.3.

readable()¶

Возвращает, был ли файл открыт для чтения.

Добавлено в версии 3.3.

seekable()¶

Возвращает, поддерживает ли файл поиск.

Добавлено в версии 3.3.

writable()¶

Возвращает, был ли файл открыт для записи.

Добавлено в версии 3.3.

read1(size=-1)¶

Считывает до размера несжатых байт, стараясь избежать многократного чтения из базового потока. Считывает до объема данных в буфере, если размер отрицательный.

Возвращает b'', если файл находится в EOF.

Добавлено в версии 3.3.

readinto(b)¶

Считывает байты в b.

Возвращает количество прочитанных байт (0 для EOF).

Добавлено в версии 3.3.

Изменено в версии 3.1: Была добавлена поддержка инструкции with.

Изменено в версии 3.3: Была добавлена поддержка для того, чтобы имя файла было file object вместо фактического имени файла.

Был добавлен режим 'a' (добавить), а также поддержка чтения многопоточных файлов.

Изменено в версии 3.4: Был добавлен режим 'x' (эксклюзивное создание).

Изменено в версии 3.5: Метод read() теперь принимает аргумент None.

Изменено в версии 3.6: Принимает значение path-like object.

Изменено в версии 3.9: Параметр buffering был удален. Начиная с версии Python 3.0, он игнорировался и стал устаревшим. Передайте объект open file, чтобы управлять открытием файла.

Параметр compresslevel стал доступен только для ключевых слов.

Изменено в версии 3.10: Этот класс небезопасен для потоков из-за нескольких одновременных операций чтения или записи, точно так же, как всегда были его эквивалентные классы в gzip и lzma.

Постепенное сжатие (de)¶

class bz2.BZ2Compressor(compresslevel=9)¶

Создайте новый объект compressor. Этот объект может использоваться для поэтапного сжатия данных. Для однократного сжатия используйте функцию compress().

уровень сжатия, если он задан, должен быть целым числом в диапазоне от 1 до 9. Значение по умолчанию - 9.

compress(data)¶

Предоставьте данные объекту compressor. Возвращает фрагмент сжатых данных, если это возможно, или пустую строку байтов в противном случае.

Когда вы закончите передавать данные в компрессор, вызовите метод flush(), чтобы завершить процесс сжатия.

flush()¶

Завершите процесс сжатия. Возвращает сжатые данные, оставшиеся во внутренних буферах.

Объект compressor не может быть использован после вызова этого метода.

class bz2.BZ2Decompressor¶

Создайте новый объект-распаковщик. Этот объект можно использовать для поэтапной распаковки данных. Для однократного сжатия используйте функцию decompress().

Примечание

Этот класс не обеспечивает прозрачную обработку входных данных, содержащих несколько сжатых потоков, в отличие от decompress() и BZ2File. Если вам нужно распаковать многопоточные входные данные с помощью BZ2Decompressor, вы должны использовать новый распаковщик для каждого потока.

decompress(data, max_length=-1)¶

Распакуйте данные (bytes-like object), возвращая несжатые данные в виде байтов. Некоторые из данных могут быть сохранены внутри буфера для использования в последующих вызовах decompress(). Возвращаемые данные должны быть объединены с выводом всех предыдущих вызовов decompress().

Если значение max_length неотрицательно, возвращается не более max_length байт распакованных данных. Если этот предел достигнут и возможен дальнейший вывод, атрибуту needs_input будет присвоено значение False. В этом случае следующий вызов decompress() может предоставить данные в виде b'', чтобы получить больше выходных данных.

Если все входные данные были распакованы и возвращены (либо потому, что это значение было меньше, чем max_length байт, либо потому, что max_length было отрицательным), атрибуту needs_input будет присвоено значение True.

При попытке распаковать данные после достижения конца потока возникает ошибка EOFError. Любые данные, найденные после окончания потока, игнорируются и сохраняются в атрибуте unused_data.

Изменено в версии 3.5: Добавлен параметр max_length.

eof¶

True если достигнут маркер конца потока.

Добавлено в версии 3.3.

unused_data¶

Данные, найденные после завершения сжатого потока.

Если доступ к этому атрибуту будет получен до того, как будет достигнут конец потока, его значение будет равно b''.

needs_input¶

False если метод decompress() может предоставить больше распакованных данных, прежде чем потребуется новый несжатый ввод.

Добавлено в версии 3.5.

Однократное сжатие (de)¶

bz2.compress(data, compresslevel=9)¶

Сжимать данные, a bytes-like object.

уровень сжатия, если он задан, должен быть целым числом в диапазоне от 1 до 9. Значение по умолчанию - 9.

Для постепенного сжатия используйте вместо этого BZ2Compressor.

bz2.decompress(data)¶

Распакуйте данные, a bytes-like object.

Если данные представляют собой объединение нескольких сжатых потоков, распакуйте все потоки.

Для постепенной распаковки используйте вместо этого BZ2Decompressor.

Изменено в версии 3.3: Была добавлена поддержка многопоточного ввода данных.

Примеры использования¶

Ниже приведены некоторые примеры типичного использования модуля bz2.

Использование compress() и decompress() для демонстрации обратного сжатия:

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c)  # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d  # Check equality to original object after round-trip
True

Использование BZ2Compressor для постепенного сжатия:

>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
...     """Yield incremental blocks of chunksize bytes."""
...     for _ in range(chunks):
...         yield b"z" * chunksize
...
>>> comp = bz2.BZ2Compressor()
>>> out = b""
>>> for chunk in gen_data():
...     # Provide data to the compressor object
...     out = out + comp.compress(chunk)
...
>>> # Finish the compression process.  Call this once you have
>>> # finished providing data to the compressor.
>>> out = out + comp.flush()

В приведенном выше примере используется очень «неслучайный» поток данных (поток b"z" фрагментов). Случайные данные, как правило, плохо сжимаются, в то время как упорядоченные, повторяющиеся данные обычно обеспечивают высокую степень сжатия.

Запись и чтение файла, сжатого в формате bzip2, в двоичном режиме:

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
...     # Write compressed data to file
...     unused = f.write(data)
>>> with bz2.open("myfile.bz2", "rb") as f:
...     # Decompress data from file
...     content = f.read()
>>> content == data  # Check equality to original object after round-trip
True