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

Исходный код: Lib/bz2.py

---

Модуль предоставляет исчерпывающий интерфейс для сжатия и распаковки данных с использованием алгоритма сжатия bzip2.

Модуль bz2 содержит:

• Функцию open() и класс BZ2File для чтения и записи сжатых файлов.
• Классы BZ2Compressor и BZ2Decompressor для инкрементного сжатия-разжатия.
• Функции compress() и decompress() для однокадрового сжатия-разжатия.

Все классы в этом модуле могут быть безопасно доступны из нескольких потоков.

Сжатие-разжатие файлов

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 игнорируется. Его использование устарело с Python 3.0.

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

Не рекомендуется, начиная с версии 3.0: Ключевой аргумент buffering устарел и теперь игнорируется.

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

Инкрементальное сжатие-разжатие

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)  # Степень сжатия данных
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d  # Проверить равенство исходному объекту после приема-передачи
True

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

>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
...     """Yield инкрементные блоки байтов размера чангов."""
...     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()

В приведенном выше примере используется поток данных «nonrandom» (поток чангов 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