13.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, он используется как начальное значение контрольной суммы; в противном случае используется фиксированное значение по умолчанию. Это позволяет вычислять контрольную сумму на лету для объединения нескольких входных данных. Алгоритм не является криптостойким и не должен использоваться для аутентификации или цифровых подписей. Поскольку алгоритм спроектирован как алгоритм контрольной суммы, он не подходит для использования в качестве универсальной хеш-функции.

Всегда возвращает беззнаковое 32-битное целое число.

zlib.compress(data[, level])¶

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

zlib.compressobj(level=-1, method=DEFLATED, wbits=15, memLevel=8, strategy=Z_DEFAULT_STRATEGY[, zdict])¶

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

level – степень сжатия: целое число от 0 до 9. Значение 1 – самое быстрое и даёт наименьшее сжатие, значение 9 – самое медленное и даёт наибольшее. 0 – без сжатия. Значение по умолчанию – 6.

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

wbits – двоичный логарифм размера буфера окна. Это целое число от 8 до 15. Большие значения обеспечивают лучшее сжатие, но требуют больше памяти.

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

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

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

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

zlib.crc32(data[, value])¶

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

Всегда возвращает беззнаковое 32-битное целое число.

Примечание

Чтобы получать одинаковое числовое значение во всех версиях Python и на всех платформах, используйте crc32(data) & 0xffffffff. Если вы используете контрольную сумму только в упакованном двоичном формате, это необязательно, поскольку возвращаемое значение является правильным 32-битным двоичным представлением независимо от знака.

zlib.decompress(data[, wbits[, bufsize]])¶

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

Абсолютное значение wbits – это двоичный логарифм размера буфера истории («размер окна»), используемого при сжатии данных. Для последних версий библиотеки zlib его абсолютное значение должно быть от 8 до 15: большие значения дают лучшее сжатие ценой большего расхода памяти. При распаковке потока wbits не должен быть меньше размера, использованного при сжатии; слишком маленькое значение приведёт к исключению. Поэтому значение по умолчанию – максимальное, 15. Когда wbits отрицательно, стандартный заголовок gzip подавляется.

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

zlib.decompressobj(wbits=15[, zdict])¶

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

Параметр wbits управляет размером буфера окна.

Параметр zdict задаёт предопределённый словарь сжатия. Если он указан, это должен быть тот же словарь, который использовался компрессором, создавшим подлежащие распаковке данные.

Примечание

Если zdict является изменяемым объектом (например, bytearray), его содержимое нельзя изменять между вызовом decompressobj() и первым вызовом метода decompress() распаковщика.

Изменено в версии 3.3: Добавлен параметр zdict.

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

Compress.compress(data)¶

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

Compress.flush([mode])¶

Обрабатываются все ожидающие входные данные и возвращается объект bytes, содержащий оставшийся сжатый вывод. 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()¶

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

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

Decompress.unused_data¶

Объект bytes, содержащий все байты, которые идут после конца сжатых данных. То есть он остаётся b"" до тех пор, пока не станет доступен последний байт, содержащий данные сжатия. Если вся строка байтов оказалась содержащей сжатые данные, это будет b"", пустой объект bytes.

Decompress.unconsumed_tail¶

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

Decompress.eof¶

Логическое значение, указывающее, достигнут ли конец сжатого потока данных.

Это позволяет различать правильно сформированный сжатый поток и неполный или усечённый.

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

Decompress.decompress(data[, max_length])¶

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

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

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.