bz2 – Поддержка сжатия bzip2¶bz2 – Support for bzip2 compression

Сжатие и распаковка файлов¶(De)compression of files

bz2.open(filename, mode='r', 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', buffering=None, compresslevel=9)¶

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

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

Аргумент mode может быть 'r' для чтения (по умолчанию), 'w' для перезаписи, 'x' для исключительного создания или 'a' для добавления. Им эквивалентно соответствуют 'rb', 'wb', 'xb' и 'ab' соответственно.

Если filename – файловый объект (а не фактическое имя файла), режим 'w' не усекает файл, а вместо этого эквивалентен 'a'.

Аргумент buffering игнорируется. Его использование устарело.

Если 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: Принимает объект, подобный пути.

Инкрементальное (де)сжатие¶Incremental (de)compression

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.

Одноразовое (де)сжатие¶One-shot (de)compression

bz2.compress(data, compresslevel=9)¶

Сжимает data, байтоподобный объект.

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

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

bz2.decompress(data)¶

Декомпрессирует data, байтоподобный объект.

Если data является объединением нескольких сжатых потоков, декомпрессирует все потоки.

Для инкрементальной декомпрессии используйте BZ2Decompressor.

Изменено в версии 3.3: Добавлена поддержка многопоточных входных данных.

Примеры использования¶Examples of usage

Ниже приведены несколько примеров типичного использования модуля 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)  # Коэффициент сжатия данных
1.513595166163142

>>> d = bz2.decompress(c)
>>> data == d  # Проверка равенства исходному объекту после полного цикла сжатия-распаковки
True

Использование BZ2Compressor для инкрементального сжатия:

>>> import bz2

>>> def gen_data(chunks=10, chunksize=1000):
...     """Выдаёт инкрементальные блоки по chunksize байт."""
...     for _ in range(chunks):
...         yield b"z" * chunksize
...
>>> comp = bz2.BZ2Compressor()
>>> out = b""
>>> for chunk in gen_data():
...     # Передаёт данные объекту сжатия
...     out = out + comp.compress(chunk)
...
>>> # Завершает процесс сжатия. Вызывайте этот метод после того, как
>>> # завершена передача данных компрессору.
>>> 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:
...     # Записать сжатые данные в файл
...     unused = f.write(data)

>>> with bz2.open("myfile.bz2", "rb") as f:
...     # Распаковать данные из файла
...     content = f.read()

>>> content == data  # Проверка равенства исходному объекту после полного цикла сжатия-распаковки
True