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: Результат всегда беззнаковый. Чтобы получить то же числовое значение, что и при использовании Python 2 или более ранних версий, используйте adler32(data) & 0xffffffff.

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

Сжимает байты в 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). Выбрасывает исключение error, если произошла какая-либо ошибка.

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

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 управляет размером буфера истории (или «размером окна»), используемого при сжатии данных, и включением заголовка и концевика в выходные данные. Он может принимать несколько диапазонов значений, по умолчанию равных 15 (MAX_WBITS):

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

Аргумент 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: Результат всегда беззнаковый. Чтобы получить то же числовое значение, что и при использовании Python 2 или более ранних версий, используйте crc32(data) & 0xffffffff.

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)

Сжимает data, возвращая объект bytes, содержащий сжатые данные для как минимум части данных в data. Эти данные должны быть соединены с результатами, полученными от предыдущих вызовов метода 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)

Распаковывает data, возвращая объект bytes, содержащий данные без сжатия, соответствующие хотя бы части данных в string. Эти данные следует конкатенировать с выводом, полученным от предыдущих вызовов метода 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.