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

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

У функции zlib есть множество опций, и их часто нужно использовать в определённом порядке. Данная документация не пытается охватить все перестановки; обратитесь к официальному руководству по zlib для получения достоверной информации.

Для чтения и записи .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, возвращая объект байтов, содержащий сжатые данные. 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, возвращая объект байтов, содержащий несжатые данные. Параметр 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, возвращая объект байтов, содержащий сжатые данные, по крайней мере, для части данных в data. Данные должны быть объединены с выводом, произведенным любыми предыдущими вызовами метода compress(). Часть входных данных может храниться во внутренних буферах для последующей обработки.

Compress.flush([mode])

Все ожидающие ввода данные обрабатываются, и возвращается объект байтов, содержащий оставшиеся сжатые выходные данные. 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()

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

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

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

Decompress.unused_data

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

Decompress.unconsumed_tail

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

Decompress.eof

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

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

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

Decompress.decompress(data, max_length=0)

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

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

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

Decompress.flush([length])

Все ожидающие ввода обрабатываются, и возвращается объект байтов, содержащий оставшийся несжатый вывод. После вызова 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, фактически загруженной интерпретатором.

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

См.также

Модуль gzip
Чтение и запись файлов gzip-формат.
Официальный сайт zlib
Домашняя страница библиотеки zlib.
Мануал по библиотеке zlib
В руководстве по zlib объясняется семантика и использование многих функций библиотеки.