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

(Распаковка) сжатие файлов

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

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

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

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

Если 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.0: Ключевой аргумент buffering устарел и теперь игнорируется.

Изменено в версии 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