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

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

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

seekable()

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

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

writable()

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

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

read1(size=-1)

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

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

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

readinto(b)

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

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

Добавлено в версии 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) и возвращает распакованные данные в виде байтов. Часть 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.

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

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

bz2.decompress(data)

Распаковывает data — объект подобный bytes.

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