12.1. zlib – Сжатие, совместимое с gzip¶zlib – Compression compatible with 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])¶

Вычисляет контрольную сумму Adler-32 для data. (Контрольная сумма Adler-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 управляет размером буфера истории (или «размером окна»), используемого при сжатии данных, а также тем, включаются ли заголовок и концевик в выходные данные. Он может принимать несколько диапазонов значений. По умолчанию – 15.

• +9 … +15: двоичный логарифм размера окна, который соответственно находится в диапазоне от 512 до 32768. Большие значения дают лучшее сжатие за счёт большего расхода памяти. Полученный выходной поток будет включать заголовок и концевик, специфичные для zlib.

• −9 … −15: использует абсолютное значение wbits как логарифм размера окна, при этом создаётся необработанный выходной поток без заголовка и концевой контрольной суммы.

• +25 … +31 = 16 + (9 … 15): использует младшие 4 бита значения как логарифм размера окна, при этом в выходные данные включается простой заголовок gzip и концевая контрольная сумма.

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

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])¶

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

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

Decompress.flush([length])¶

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

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

Decompress.copy()¶

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

Новое в версии 2.5.