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.

fileno()

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

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

readable()

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

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

seekable()

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

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

writable()

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

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

read1(size=-1)

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

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

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

readinto(b)

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

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

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

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