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

Для приложений, требующих сжатия данных, функции данного модуля позволяют сжимать и распаковывать данные, используя библиотеку zlib. Библиотека zlib имеет свою домашнюю страницу по адресу http://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])

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

Эта функция всегда возвращает объект целого типа.

zlib.compress(string[, level])

Сжимает данные в string, возвращая строку, содержащую сжатые данные. level — целое число от 0 до 9, управляющее уровнем сжатия; 1 — самый быстрый и даёт наименьшее сжатие, 9 — самый медленный и даёт наибольшее сжатие. 0 — без сжатия. Значение по умолчанию — 6. Вызывает исключение error, если произошла ошибка.

zlib.compressobj([level[, method[, wbits[, memlevel[, strategy]]]]])

Возвращает объект сжатия, используемый для сжатия потоков данных, которые не помещаются в память целиком. level — целое число от 0 до 9 или -1, управляющее уровнем сжатия; 1 — самый быстрый и даёт наименьшее сжатие, 9 — самый медленный и даёт наибольшее сжатие. 0 — без сжатия. Значение по умолчанию — -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION представляет собой компромисс между скоростью и степенью сжатия (в настоящее время эквивалентно уровню 6).

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

Аргумент 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_DEFAULT_STRATEGY.

zlib.crc32(data[, value])

Вычисляет контрольную сумму CRC (Cyclic Redundancy Check) для data. Если value задан, он используется в качестве начального значения контрольной суммы; в противном случае используется фиксированное значение по умолчанию. Это позволяет вычислять текущую контрольную сумму для конкатенации нескольких входных данных. Алгоритм не является криптографически стойким и не должен использоваться для аутентификации или цифровых подписей. Поскольку алгоритм предназначен для использования в качестве алгоритма контрольной суммы, он не подходит для использования в качестве общего алгоритма хеширования.

Эта функция всегда возвращает объект целого типа.

zlib.decompress(string[, wbits[, bufsize]])

Распаковывает данные в string, возвращая строку, содержащую распакованные данные. Параметр wbits зависит от формата string и подробно обсуждается ниже. Если задан 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 по умолчанию равно 15, что соответствует максимальному размеру окна и требует включения заголовка и фиксатора zlib.

bufsize — начальный размер буфера, используемого для хранения распакованных данных. Если требуется больше места, размер буфера будет увеличиваться по мере необходимости, поэтому вам не нужно точно угадывать это значение; настройка его сэкономит только несколько вызовов malloc(). Значение по умолчанию — 16384.

zlib.decompressobj([wbits])

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

Параметр wbits управляет размером буфера истории (или «размером окна») и ожидаемым форматом заголовка и фиксатора. Он имеет то же значение, что и описано для decompress().

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

Compress.compress(string)

Сжимает string, возвращая строку, содержащую сжатые данные для по меньшей мере части данных в string. Эти данные должны быть соединены с выходными данными, полученными при предыдущих вызовах метода compress(). Некоторые входные данные могут храниться во внутренних буферах для последующей обработки.

Compress.flush([mode])

Все ожидающие входные данные обрабатываются, и возвращается строка, содержащая оставшиеся сжатые выходные данные. mode может быть выбран из констант Z_SYNC_FLUSH, Z_FULL_FLUSH, или Z_FINISH, по умолчанию Z_FINISH. Z_SYNC_FLUSH и Z_FULL_FLUSH позволяют сжимать дополнительные строки данных, в то время как Z_FINISH завершает поток сжатых данных и предотвращает сжатие дополнительных данных. После вызова flush() с mode, установленным на Z_FINISH, метод compress() не может быть вызван снова; единственно реалистичное действие — удалить объект.

Compress.copy()

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

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

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

Decompress.unused_data

Строка, содержащая любые байты, расположенные за пределами сжатых данных. То есть, она остается "" до тех пор, пока не будет доступен последний байт, содержащий данные сжатия. Если вся строка оказалась содержать сжатые данные, то это "", пустая строка.

Единственный способ определить, где заканчивается строка сжатых данных, — это фактически декомпрессировать её. Это означает, что при сжатии данных, которые составляют часть большего файла, вы можете найти его конец, считывая данные и передавая их, а затем некоторую непустую строку методу декомпрессии объекта decompress(), пока атрибут unused_data не станет снова пустой строкой.

Decompress.unconsumed_tail

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

Decompress.decompress(string[, max_length])

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

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

Decompress.flush([length])

Все ожидающие входные данные обрабатываются, и возвращается строка, содержащая оставшиеся необработанные выходные данные. После вызова flush() метод decompress() не может быть вызван повторно; единственно реалистичным действием является удаление объекта.

Необязательный параметр length задаёт начальный размер буфера вывода.

Decompress.copy()

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

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