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

Источник: Lib/bz2.py

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

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

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

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 с указанной кодировкой, поведением при обработке ошибок и окончанием строки (строк).

Added in version 3.3.

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

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

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

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

Если filename является объектом str или bytes, откройте именованный файл напрямую. В противном случае filename должно быть объектом 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).

Added in version 3.3.

fileno()

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

Added in version 3.3.

readable()

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

Added in version 3.3.

seekable()

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

Added in version 3.3.

writable()

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

Added in version 3.3.

read1(size=-1)

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

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

Added in version 3.3.

readinto(b)

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

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

Added in version 3.3.

mode

'rb' для чтения и 'wb' для письма.

Added in version 3.13.

name

Имя файла bzip2. Эквивалентно атрибуту name базового file object.

Added in version 3.13.

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

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

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

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

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

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

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

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

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

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

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 (a 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, если был достигнут маркер конца потока.

Added in version 3.3.

unused_data

Данные, найденные после окончания сжатого потока.

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

needs_input

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

Added in version 3.5.

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

bz2.compress(data, compresslevel=9)

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

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

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

bz2.decompress(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