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

Для приложений, которым требуется сжатие данных, функции в этом модуле позволяют сжимать и распаковывать данные с использованием библиотеки zlib. Библиотека zlib имеет свою домашнюю страницу по адресу http://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 и на всех платформах, используйте 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 и на всех платформах, используйте 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.