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

Изменено в версии 3.0: Результат всегда беззнаковый. Чтобы получить такое же числовое значение при использовании Python 2 или более ранних версий, используйте adler32(data) & 0xffffffff.

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

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

Изменено в версии 3.6: Теперь level можно использовать в качестве параметра ключевого слова.

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

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

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

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

Аргумент wbits определяет размер буфера истории (или «размер окна»), используемого при сжатии данных, а также включает ли в вывод заголовок и трейлер. Он может принимать несколько диапазонов значений, по умолчанию 15 (MAX_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_RLE (zlib 1.2.0.1) и Z_FIXED (zlib 1.2.2.2).

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

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

zlib.crc32(data[, value])¶

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

Изменено в версии 3.0: Результат всегда беззнаковый. Чтобы получить такое же числовое значение при использовании Python 2 или более ранних версий, используйте crc32(data) & 0xffffffff.

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

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

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

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

bufsize - это начальный размер буфера, используемого для хранения распакованных данных. Если потребуется больше места, размер буфера будет увеличиваться по мере необходимости, поэтому не обязательно добиваться точного значения этого параметра; его настройка сэкономит лишь несколько вызовов 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)¶

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

Compress.flush([mode])¶

Все ожидающие входные данные обрабатываются, и возвращается объект bytes, содержащий оставшийся сжатый выход. Режим mode может быть выбран из констант 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"", пустой объект bytes.

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.