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.