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.

Изменено в версии 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