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

Исходный код: Lib/bz2.py

Этот модуль предоставляет комплексный интерфейс для сжатия и распаковки данных с использованием алгоритма сжатия bzip2.

Модуль bz2 содержит:

Функцию open() и класс BZ2File для чтения и записи сжатых файлов.
Классы BZ2Compressor и BZ2Decompressor для инкрементального (де)сжатия.
Функции compress() и decompress() для одноразового (де)сжатия.

Все классы в этом модуле могут безопасно использоваться из нескольких потоков.

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

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

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

Как и для конструктора 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: Принимает объект пути.

class bz2.BZ2File(filename, mode='r', buffering=None, compresslevel=9)

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

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

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

Если filename — объект файла (а не фактическое имя файла), режим 'w' не обрезает файл и эквивалентен 'a'.

Аргумент buffering игнорируется. Его использование устарело.

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

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

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

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

peek([n]): Возвращает буферизованные данные без изменения позиции файла. Будет возвращено как минимум один байт данных (если не достигнут конец файла). Точное количество возвращаемых байтов не определено.

Примечание

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

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

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

Изменено в версии 3.3: Добавлены методы fileno(), readable(), seekable(), writable(), read1() и readinto().

Изменено в версии 3.3: Добавлена поддержка filename в качестве объекта файла вместо фактического имени файла.

Изменено в версии 3.3: Добавлен режим 'a' (дополнение), а также поддержка чтения файлов из нескольких потоков.

Изменено в версии 3.4: Добавлен режим 'x' (исключительного создания).

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

Изменено в версии 3.6: Принимает объект пути.

Инкрементальное (де)сжатие

class bz2.BZ2Compressor(compresslevel=9)

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

Если указан compresslevel, он должен быть целым числом от 1 до 9. По умолчанию 9.

compress(data)

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

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

flush()

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

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

class bz2.BZ2Decompressor

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

Примечание

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

decompress(data, max_length=-1)

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

Если max_length неотрицательно, возвращает не более max_length байтов декомпрессированных данных. Если этот лимит достигнут, и дальнейший вывод может быть произведён, то атрибут needs_input будет установлен в значение False. В этом случае, следующий вызов decompress() может предоставить data в качестве 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.

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

bz2.compress(data, compresslevel=9)

Сжать data, объект типа bytes-like object.

compresslevel, если указан, должен быть целым числом от 1 до 9. По умолчанию 9.

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

bz2.decompress(data)

Декомпрессировать data, объект типа bytes-like object.

Если data является конкатенацией нескольких сжатых потоков, декомпрессируйте все потоки.

Для поэтапной декомпрессии используйте 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