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 и возвращает объект 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 задаёт размер буфера истории (или «размер окна»), а также определяет формат используемых заголовка и трейлера. Он имеет то же значение, что и описанный для 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 и возвращает объект 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.