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

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

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

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

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

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

13.3.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 со специфицированной кодировкой, обработкой ошибок и концами строк.

New in version 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).

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

13.3.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.

13.3.3. Однократная (де)компрессия

bz2.compress(data, compresslevel=9)

Сжимает data.

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

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

bz2.decompress(data)

Декомпрессирует data.

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

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

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