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

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

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

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

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

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

1. (Распаковка) сжатие файлов

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' (исключительное создание).

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.

2. Инкрементное (распаковки) сжатие

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.

3. Одноразовая (де)компрессия

bz2.compress(data, compresslevel=9)

Сжать data.

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

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

bz2.decompress(data)

Декомпрессировать data.

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

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

Изменено в версии 3.3: Добавлена поддержка входов, содержащих несколько потоков.