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

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

Примечание

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

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

fileno()

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

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

readable()

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

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

seekable()

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

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

writable()

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

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

read1(size=- 1)

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

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

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

readinto(b)

Прочитать байты в b.

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

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

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

Изменено в версии 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 (объект типа 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