zlib — Сжатие, совместимое с gzip

Для приложений, требующих сжатия данных, функции в этом модуле позволяют сжимать и распаковывать данные, используя библиотеку zlib. Библиотека zlib имеет свою домашнюю страницу по адресу https://www.zlib.net. Известны несовместимости между модулем Python и версиями библиотеки zlib, предшествующими 1.1.3; версия 1.1.3 содержит уязвимость безопасности, поэтому рекомендуется использовать версию 1.1.4 или более позднюю.

Функции zlib имеют множество опций и часто должны использоваться в определённом порядке. Данная документация не пытается охватить все возможные комбинации; обратитесь к руководству zlib по адресу http://www.zlib.net/manual.html за авторитетной информацией.

Для чтения и записи файлов .gz см. модуль gzip.

Доступные исключения и функции в этом модуле:

exception zlib.error

Исключение, генерируемое при ошибках сжатия и распаковки.

zlib.adler32(data[, value])

Вычисляет контрольную сумму Adler-32 для данных data. (Контрольная сумма Adler-32 почти так же надёжна, как CRC32, но вычисляется гораздо быстрее). Результат — целое беззнаковое 32-битное число. Если value присутствует, оно используется как начальное значение контрольной суммы; в противном случае используется значение по умолчанию 1. Передача value позволяет вычислять текущую контрольную сумму для конкатенации нескольких входных данных. Алгоритм не является криптографически стойким и не должен использоваться для аутентификации или цифровых подписей. Поскольку алгоритм предназначен для использования в качестве алгоритма контрольной суммы, он не подходит для использования в качестве общего алгоритма хеширования.

Изменено в версии 3.0: Результат всегда беззнаковый.

zlib.compress(data, /, level=-1, wbits=MAX_WBITS)

Сжимает байты в data, возвращая объект bytes, содержащий сжатые данные. level — целое число от 0 до 9 или -1, определяющее уровень сжатия; 1 (Z_BEST_SPEED) — самый быстрый, с наименьшим сжатием, 9 (Z_BEST_COMPRESSION) — самый медленный, с наибольшим сжатием. 0 (Z_NO_COMPRESSION) — без сжатия. Значение по умолчанию — -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION представляет собой компромисс между скоростью и сжатием (в настоящее время эквивалентно уровню 6).

Аргумент wbits управляет размером буфера истории (или «размером окна»), используемого при сжатии данных, а также тем, включается ли заголовок и окончание в выходные данные. Он может принимать несколько диапазонов значений, по умолчанию установленных в 15 (MAX_WBITS):

• +9 до +15: Двоичный логарифм размера окна, следовательно, диапазон от 512 до 32768. Большие значения обеспечивают лучшее сжатие за счёт большего использования памяти. Результирующие выходные данные будут содержать специфичный для zlib заголовок и окончание.
• −9 до −15: Использует абсолютное значение wbits в качестве логарифма размера окна, при этом генерируя поток данных без заголовка или окончательной контрольной суммы.
• +25 до +31 = 16 + (9 до 15): Использует нижние 4 бита значения в качестве логарифма размера окна, при этом включая базовый заголовок gzip и окончательную контрольную сумму в выходные данные.

Если произошла ошибка, генерируется исключение error.

Изменено в версии 3.6: level теперь можно использовать в качестве именованного параметра.

Изменено в версии 3.11: Параметр wbits теперь доступен для установки бит окна и типа сжатия.

zlib.compressobj(level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

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

level — уровень сжатия — целое число от 0 до 9 или -1. Значение 1 (Z_BEST_SPEED) — самое быстрое, с наименьшим сжатием, а значение 9 (Z_BEST_COMPRESSION) — самое медленное, с наибольшим сжатием. 0 (Z_NO_COMPRESSION) — без сжатия. Значение по умолчанию — -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION представляет собой компромисс между скоростью и сжатием (в настоящее время эквивалентно уровню 6).

method — алгоритм сжатия. В настоящее время единственное поддерживаемое значение — DEFLATED.

Параметр wbits управляет размером буфера истории (или «размером окна») и тем, какой формат заголовка и окончаний будет использоваться. Он имеет то же значение, что и описано для compress().

Аргумент memLevel управляет объёмом памяти, используемой для внутреннего состояния сжатия. Допустимые значения варьируются от 1 до 9. Более высокие значения используют больше памяти, но быстрее и дают меньший результат.

strategy используется для настройки алгоритма сжатия. Возможные значения — Z_DEFAULT_STRATEGY, Z_FILTERED, Z_HUFFMAN_ONLY, Z_RLE (zlib 1.2.0.1) и Z_FIXED (zlib 1.2.2.2).

zdict — предопределённый словарь сжатия. Это последовательность байтов (например, объект bytes), содержащая подпоследовательности, которые ожидается часто встречаться в данных, подлежащих сжатию. Те подпоследовательности, которые ожидаются наиболее часто, должны располагаться в конце словаря.

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

zlib.crc32(data[, value])

Вычисляет контрольную сумму CRC (Cyclic Redundancy Check) для data. Результат — целое беззнаковое 32-битное число. Если value присутствует, оно используется в качестве начального значения контрольной суммы; в противном случае используется значение по умолчанию 0. Передача value позволяет вычислять текущую контрольную сумму для конкатенации нескольких входных данных. Алгоритм не является криптографически стойким и не должен использоваться для аутентификации или цифровых подписей. Поскольку алгоритм предназначен для использования в качестве алгоритма контрольной суммы, он не подходит для использования в качестве общего алгоритма хеширования.

Изменено в версии 3.0: Результат всегда беззнаковый.

zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

Распаковывает байты в data, возвращая объект bytes, содержащий нескомпрессированные данные. Параметр wbits зависит от формата data и обсуждается ниже. Если задан bufsize, он используется в качестве начального размера буфера вывода. Если произошла ошибка, генерируется исключение error.

Параметр wbits управляет размером буфера истории (или «размером окна»), а также тем, какой формат заголовка и окончания ожидается. Он похож на параметр для compressobj(), но принимает больше диапазонов значений:

• +8 до +15: Двоичный логарифм размера окна. Входные данные должны включать заголовок и окончание zlib.
• 0: Автоматически определяет размер окна из заголовка zlib. Поддерживается только начиная с zlib 1.2.3.5.
• −8 до −15: Использует абсолютное значение wbits в качестве логарифма размера окна. Входные данные должны быть сырым потоком без заголовка или окончания.
• +24 до +31 = 16 + (8 до 15): Использует нижние 4 бита значения в качестве логарифма размера окна. Входные данные должны включать заголовок и окончание gzip.
• +40 до +47 = 32 + (8 до 15): Использует нижние 4 бита значения в качестве логарифма размера окна, и автоматически принимает либо формат zlib, либо gzip.

При распаковке потока размер окна не должен быть меньше размера, первоначально используемого для сжатия потока; использование слишком малого значения может привести к исключению error. Значение по умолчанию wbits соответствует наибольшему размеру окна и требует включения заголовка и окончания zlib.

bufsize — начальный размер буфера, используемого для хранения распакованных данных. Если требуется больше места, размер буфера будет увеличиваться по мере необходимости, поэтому вам не нужно точно вычислять это значение; настройка его только сэкономит несколько вызовов malloc().

Изменено в версии 3.6: wbits и bufsize могут быть использованы в качестве именованных аргументов.

zlib.decompressobj(wbits=MAX_WBITS[, zdict])

Возвращает объект распаковки, используемый для распаковки потоков данных, которые не помещаются в память сразу.

Параметр wbits управляет размером буфера истории (или «размером окна»), а также ожидаемым форматом заголовка и окончания. Он имеет то же значение, что и описано для decompress().

Параметр zdict определяет предопределённый словарь сжатия. Если он указан, он должен совпадать со словарем, использовавшимся компрессором, который произвел данные, подлежащие распаковке.

Примечание

Если zdict является изменяемым объектом (например, bytearray), не следует изменять его содержимое между вызовом decompressobj() и первым вызовом метода декомпрессора decompress().

Изменено в версии 3.3: Добавлен параметр zdict.

Объекты сжатия поддерживают следующие методы:

Compress.compress(data)

Сжимает данные, возвращая объект bytes, содержащий сжатые данные по крайней мере для части данных в данных. Эти данные следует конкатенировать с выводом, полученным от предыдущих вызовов метода compress(). Некоторые входные данные могут храниться во внутренних буферах для последующей обработки.

Compress.flush([mode])

Все ожидающие входные данные обрабатываются, и возвращается объект bytes, содержащий оставшийся сжатый вывод. mode можно выбрать из констант Z_NO_FLUSH, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, Z_FULL_FLUSH, Z_BLOCK (zlib 1.2.3.4) или Z_FINISH, по умолчанию Z_FINISH. Кроме Z_FINISH, все константы позволяют сжимать дополнительные байтовые строки данных, в то время как Z_FINISH завершает сжатый поток и предотвращает дальнейшее сжатие данных. После вызова flush() с mode, установленным в Z_FINISH, метод compress() не может быть вызван повторно; единственным реалистичным действием является удаление объекта.

Compress.copy()

Возвращает копию объекта сжатия. Это можно использовать для эффективного сжатия набора данных, которые разделяют общий начальный префикс.

Объекты декомпрессии поддерживают следующие методы и атрибуты:

Decompress.unused_data

Объект bytes, содержащий любые байты после конца сжатых данных. То есть, это остается b"" до тех пор, пока последний байт, содержащий данные сжатия, не будет доступен. Если вся байтовая строка оказалась содержать сжатые данные, это b"", пустой объект bytes.

Decompress.unconsumed_tail

Объект bytes, содержащий любые данные, которые не были обработаны последним вызовом decompress(), потому что он превысил предел буфера нескомпрессированных данных. Эти данные еще не были обработаны механизмом zlib, поэтому вы должны передать их (возможно, с дальнейшими данными, конкатенированными к ним) в последующий вызов метода decompress(), чтобы получить правильный результат.

Decompress.eof

Булево значение, указывающее, достигнут ли конец потока сжатых данных.

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

Добавлен в версии 3.3.

Decompress.decompress(data, max_length=0)

Декомпримирует данные, возвращая объект bytes, содержащий нескомпрессированные данные, соответствующие по крайней мере части данных в строке. Эти данные следует конкатенировать с выводом, полученным от предыдущих вызовов метода decompress(). Некоторые данные входных данных могут сохраняться во внутренних буферах для последующей обработки.

Если необязательный параметр max_length отличен от нуля, то возвращаемое значение будет не длиннее max_length. Это может означать, что не все сжатые входные данные могут быть обработаны; необработанные данные будут сохранены в атрибуте unconsumed_tail. Эта байтовая строка должна быть передана в последующий вызов decompress(), если декомпрессия должна продолжаться. Если max_length равно нулю, весь ввод декомпрессируется, и unconsumed_tail пуст.

Изменено в версии 3.6: max_length можно использовать в качестве именованного аргумента.

Decompress.flush([length])

Все ожидающие входные данные обрабатываются, и возвращается объект bytes, содержащий оставшийся нескомпрессированный вывод. После вызова flush(), метод decompress() не может быть вызван повторно; единственным реалистичным действием является удаление объекта.

Необязательный параметр length задаёт начальный размер буфера вывода.

Decompress.copy()

Возвращает копию объекта декомпрессии. Это можно использовать для сохранения состояния декомпрессора на середине потока данных, чтобы ускорить случайный поиск в потоке в будущем.

Информация о версии используемой библиотеки zlib доступна через следующие константы:

zlib.ZLIB_VERSION

Строка версии библиотеки zlib, используемой для построения модуля. Она может отличаться от библиотеки zlib, фактически используемой во время выполнения, которая доступна как ZLIB_RUNTIME_VERSION.

zlib.ZLIB_RUNTIME_VERSION

Строка версии библиотеки zlib, фактически загруженной интерпретатором.

Добавлен в версии 3.3.