zlib – сжатие, совместимое с gzip¶zlib – Compression compatible with gzip

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

Это опциональный модуль. Если его нет в вашей копии CPython, обратитесь к документации от вашего дистрибьютора (то есть того, кто предоставил вам Python). Если вы дистрибьютор, обратитесь к требованиям к опциональным модулям.

Функции zlib имеют множество параметров и часто требуют определённого порядка вызова. В этой документации нет попытки охватить все комбинации; для получения исчерпывающей информации обращайтесь к руководству по zlib.

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

Доступные исключение и функции в этом модуле:

exception zlib.error¶

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

zlib.adler32(data[, value])¶

Вычисляет контрольную сумму Адлера-32 для data. (Контрольная сумма Адлера-32 почти так же надёжна, как CRC32, но вычисляется гораздо быстрее.) Результат – 32-битное целое число без знака. Если указан value, он используется как начальное значение контрольной суммы; в противном случае используется значение 1 по умолчанию. Передача value позволяет вычислять накопленную контрольную сумму для объединения нескольких входных данных. Алгоритм не является криптостойким и не должен использоваться для аутентификации или цифровых подписей. Поскольку алгоритм разработан для использования в качестве алгоритма контрольной суммы, он не подходит для использования в качестве общего алгоритма хеширования.

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

zlib.compress(data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)¶

Сжимает байты в data и возвращает объект bytes, содержащий сжатые данные. level – целое число от 0 до 9 или -1, управляющее степенью сжатия. Подробнее об этих значениях см. Z_BEST_SPEED (1), Z_BEST_COMPRESSION (9), Z_NO_COMPRESSION (0) и значение по умолчанию Z_DEFAULT_COMPRESSION (-1).

Аргумент 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=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])¶

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

level – степень сжатия: целое число от 0 до 9 или -1. Подробнее об этих значениях см. Z_BEST_SPEED (1), Z_BEST_COMPRESSION (9), Z_NO_COMPRESSION (0) и значение по умолчанию Z_DEFAULT_COMPRESSION (-1).

method – алгоритм сжатия. В настоящее время поддерживается только значение DEFLATED.

Параметр wbits управляет размером буфера истории (или «размером окна») и тем, какой формат заголовка и концевика будет использоваться. Его смысл такой же, как описано для compress().

Аргумент memLevel управляет объёмом памяти, используемой для внутреннего состояния сжатия. Допустимые значения – от 1 до 9. Большие значения используют больше памяти, но работают быстрее и дают меньший выходной поток.

strategy используется для настройки алгоритма сжатия. Возможные значения: Z_DEFAULT_STRATEGY, Z_FILTERED, Z_HUFFMAN_ONLY, Z_RLE и Z_FIXED.

zdict – предопределённый словарь сжатия. Это последовательность байтов (например, объект bytes), содержащая подпоследовательности, которые, как ожидается, часто встречаются в сжимаемых данных. Подпоследовательности, которые, как ожидается, встречаются чаще всего, должны располагаться в конце словаря.

Изменено в версии 3.3: Добавлен параметр zdict и поддержка именованных аргументов.

zlib.crc32(data[, value])¶

Вычисляет контрольную сумму CRC (Cyclic Redundancy Check) для 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 или 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.DEFLATED¶

Метод сжатия deflate.

zlib.MAX_WBITS¶

Максимальный размер окна, выраженный как степень двойки. Например, если MAX_WBITS равен 15, то размер окна составит 32 KiB.

zlib.DEF_MEM_LEVEL¶

Уровень памяти по умолчанию для объектов сжатия.

zlib.DEF_BUF_SIZE¶

Размер буфера по умолчанию для операций распаковки.

zlib.Z_NO_COMPRESSION¶

Уровень сжатия 0; без сжатия.

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

zlib.Z_BEST_SPEED¶

Уровень сжатия 1; самый быстрый, обеспечивает наименьшее сжатие.

zlib.Z_BEST_COMPRESSION¶

Уровень сжатия 9; самый медленный, обеспечивает наибольшее сжатие.

zlib.Z_DEFAULT_COMPRESSION¶

Уровень сжатия по умолчанию (-1); компромисс между скоростью и сжатием. В настоящее время эквивалентен уровню сжатия 6.

zlib.Z_DEFAULT_STRATEGY¶

Стратегия сжатия по умолчанию для обычных данных.

zlib.Z_FILTERED¶

Стратегия сжатия для данных, полученных от фильтра (или предсказателя).

zlib.Z_HUFFMAN_ONLY¶

Стратегия сжатия, использующая только кодирование Хаффмана.

zlib.Z_RLE¶

Стратегия сжатия, ограничивающая расстояния совпадений до одного (кодирование длин серий).

Эта константа доступна только если Python был собран с zlib 1.2.0.1 или новее.

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

zlib.Z_FIXED¶

Стратегия сжатия, предотвращающая использование динамических кодов Хаффмана.

Эта константа доступна только если Python был собран с zlib 1.2.2.2 или новее.

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

zlib.Z_NO_FLUSH¶

Режим сброса 0. Особого поведения при сбросе нет.

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

zlib.Z_PARTIAL_FLUSH¶

Режим сброса 1. Сбрасывает как можно больше выходных данных.

zlib.Z_SYNC_FLUSH¶

Режим сброса 2. Все выходные данные сбрасываются, и выходные данные выравниваются по границе байта.

zlib.Z_FULL_FLUSH¶

Режим сброса 3. Все выходные данные сбрасываются, а состояние сжатия сбрасывается.

zlib.Z_FINISH¶

Режим сброса 4. Все отложенные входные данные обрабатываются; новых данных не ожидается.

zlib.Z_BLOCK¶

Режим сброса 5. Блок deflate завершается и выводится.

Эта константа доступна только если Python был собран с zlib 1.2.2.2 или новее.

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

zlib.Z_TREES¶

Режим сброса 6 для операций inflate. Указывает inflate вернуться, когда он достигнет границы следующего блока deflate.

Эта константа доступна только если Python был собран с zlib 1.2.3.4 или новее.

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

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

zlib.ZLIB_VERSION¶

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

zlib.ZLIB_RUNTIME_VERSION¶

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

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

zlib.ZLIBNG_VERSION¶

Строка версии библиотеки zlib-ng, использовавшейся для сборки модуля, если использовалась zlib-ng. При наличии константы ZLIB_VERSION и ZLIB_RUNTIME_VERSION отражают версию API zlib, предоставляемого zlib-ng.

Если zlib-ng не использовалась для сборки модуля, эта константа будет отсутствовать.

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