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. Для других форматов архивов см. модули bz2, zipfile и tarfile.

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

exception zlib.error¶

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

zlib.adler32(data[, value])¶

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

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

Изменено в версии 3.0: Возвращаемое значение беззнаковое и находится в диапазоне [0, 2**32-1] независимо от платформы.

zlib.compress(string[, level])¶

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

zlib.compressobj([level])¶

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

zlib.crc32(data[, value])¶

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

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

Изменено в версии 3.0: Возвращаемое значение беззнаковое и находится в диапазоне [0, 2**32-1] независимо от платформы.

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

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

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

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

zlib.decompressobj([wbits])¶

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

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

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

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

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

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

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