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

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

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

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

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

exception zlib.error

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

zlib.adler32(data[, value])

Вычисляет контрольную сумму Adler-32 для данных. (Контрольная сумма 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 управляет размером буфера истории (или «размером окна»), а также тем, какой формат заголовка и трейлера будет использоваться. Он имеет то же значение, что и described for 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) для данных. Результатом является беззнаковое 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 управляет размером буфера истории (или «размером окна»), а также тем, какой формат заголовка и трейлера ожидается. Он имеет то же значение, что и described for 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() с режимом, установленным в Z_FINISH, метод compress() не может быть вызван снова; единственным реальным действием является удаление объекта.

Compress.copy()

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

Изменено в версии 3.8: Добавлена поддержка copy.copy() и copy.deepcopy() для объектов сжатия.

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

Decompress.unused_data

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

Decompress.unconsumed_tail

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

Decompress.eof

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

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

Added in version 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()

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

Изменено в версии 3.8: Добавлена поддержка copy.copy() и copy.deepcopy() для объектов распаковки.

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

zlib.ZLIB_VERSION

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

zlib.ZLIB_RUNTIME_VERSION

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

Added in version 3.3.

См.также

Модуль gzip

Чтение и запись файлов gzip-формата.

http://www.zlib.net

Домашняя страница библиотеки zlib.

http://www.zlib.net/manual.html

Руководство по zlib объясняет семантику и использование множества функций библиотеки.