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

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

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])

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

Примечание

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

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

fileno()

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

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

readable()

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

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

seekable()

Возвращает, поддерживает ли файл перемещение по файлу.

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

writable()

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

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

read1(size=-1)

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

Возвращает b'' если файл достиг конца.

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

readinto(b)

Читает байты в b.

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

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

mode

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

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

name

Имя файла bzip2. Эквивалентно атрибуту name подлежащего объекта файла.

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

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

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

Добавлен режим '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 (объект типа 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