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

Для приложений, которым требуется сжатие данных, функции этого модуля позволяют выполнять сжатие и распаковку с использованием библиотеки zlib. У библиотеки zlib есть собственная домашняя страница по адресу https://www.zlib.net. Известны несовместимости между модулем Python и версиями библиотеки zlib, более ранними, чем 1.1.3; в 1.1.3 есть security vulnerability, поэтому мы рекомендуем использовать 1.1.4 или более позднюю версию.

функции zlib имеют множество опций, и часто их необходимо использовать в определенном порядке. В данной документации не рассматриваются все варианты перестановок; для получения достоверной информации обратитесь к руководству zlib по адресу http://www.zlib.net/manual.html.

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

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

exception zlib.error¶

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

zlib.adler32(data[, value])¶

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

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

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

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

Аргумент wbits определяет размер буфера истории (или «размер окна»), используемого при сжатии данных, и включает ли заголовок и концовку в выходные данные. Он может принимать несколько диапазонов значений, по умолчанию - 15 (MAX_W БИТ):

• От +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=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])¶

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

уровень - это уровень сжатия - целое число от 0 до 9 или -1. Значение 1 (Z_BEST_SPEED) является самым быстрым и обеспечивает наименьшее сжатие, в то время как значение 9 (Z_BEST_COMPRESSION) является самым медленным и обеспечивает наибольшее сжатие. 0 (Z_NO_COMPRESSION) - это отсутствие сжатия. Значение по умолчанию - -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION представляет собой компромисс между скоростью и сжатием по умолчанию (в настоящее время соответствует уровню 6).

метод - это алгоритм сжатия. В настоящее время единственным поддерживаемым значением является DEFLATED.

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

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

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

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

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

zlib.crc32(data[, value])¶

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

Изменено в версии 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: Использует абсолютное значение в битах в качестве логарифма размера окна. Входные данные должны быть необработанным потоком без заголовка или концовки.

• От +24 до +31 = 16 + (от 8 до 15): в качестве логарифма размера окна используются младшие 4 бита значения. Входные данные должны содержать заголовок и концевую часть gzip.

• От +40 до +47 = 32 + (от 8 до 15): использует младшие 4 бита значения в качестве логарифма размера окна и автоматически принимает формат zlib или gzip.

При распаковке потока размер окна не должен быть меньше размера, первоначально использованного для сжатия потока; использование слишком малого значения может привести к исключению error. Значение по умолчанию wbits соответствует наибольшему размеру окна и требует включения заголовка zlib и трейлера.

bufsize - это начальный размер буфера, используемого для хранения распакованных данных. Если требуется больше места, размер буфера будет увеличен по мере необходимости, так что вам не обязательно точно указывать это значение; его настройка сэкономит всего несколько вызовов:c:func:malloc.

Изменено в версии 3.6: в качестве аргументов ключевых слов можно использовать wbits и bufsize.

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

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

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

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

Примечание

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

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

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

Compress.compress(data)¶

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

Compress.flush([mode])¶

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

Compress.copy()¶

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

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

Decompress.unused_data¶

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

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 доступна с помощью следующих констант:

zlib.ZLIB_VERSION¶

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

zlib.ZLIB_RUNTIME_VERSION¶

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

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