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: Результат всегда является беззнаковым.

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

Сжимает байты в 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).

Аргумент wbits задаёт размер буфера истории (или «размер окна»), используемого при сжатии данных, а также определяет, включаются ли в выходные данные заголовок и завершающая часть. Он может принимать значения из нескольких диапазонов; по умолчанию используется 15 (MAX_WBITS):

• от +9 до +15: логарифм размера окна по основанию 2, то есть размер окна находится в диапазоне от 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 задаёт размер буфера истории (или «размер окна»), а также формат используемых заголовка и завершающей части. Он имеет то же значение, что и описанный для 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 (циклический избыточный код) для data. Результат представляет собой беззнаковое 32-битное целое число. Если указано value, оно используется в качестве начального значения контрольной суммы; в противном случае используется значение по умолчанию — 0. Передача value позволяет вычислять накапливаемую контрольную сумму для конкатенации нескольких входных данных. Этот алгоритм не является криптографически стойким, поэтому его не следует использовать для аутентификации или цифровых подписей. Поскольку алгоритм предназначен для использования в качестве алгоритма вычисления контрольной суммы, он не подходит для применения в качестве алгоритма хеширования общего назначения.

Изменено в версии 3.0: Результат всегда является беззнаковым.

zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

Распаковывает байты в data и возвращает байтовый объект, содержащий распакованные данные. Значение параметра wbits зависит от формата data; подробнее об этом говорится ниже. Если задан параметр bufsize, он используется в качестве начального размера выходного буфера. При возникновении ошибки возбуждается исключение error.

Параметр wbits задаёт размер буфера истории (или «размер окна»), а также ожидаемый формат заголовка и завершающей части. Он похож на параметр для compressobj(), но допускает больше диапазонов значений:

• от +8 до +15: логарифм размера окна по основанию 2. Входные данные должны содержать заголовок и завершающую часть 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()

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

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

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()

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

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

zlib.ZLIB_VERSION

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

zlib.ZLIB_RUNTIME_VERSION

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

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