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

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

bz2.open(filename, mode='rb', 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', *, compresslevel=9)

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

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

Аргумент 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])

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

Примечание

Хотя вызов 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: Принимает объект-путь.

Изменено в версии 3.9: Параметр buffering удален. Он игнорировался и был устаревшим с 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 (объект-подобный байтам), возвращая несжатые данные в виде байтов. Некоторые из 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, объект-подобный байтам.

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

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

bz2.decompress(data)

Распаковывает data, объект-подобный байтам.

Если 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