zlib — Сжатие совместимое с 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, но может быть вычислена гораздо быстрее). Результатом является беззнаковое 32-разрядное целое число. Если value присутствует, он используемый в качестве начального значение контрольной суммы; в противном случае значение по умолчанию 1 равно используемый. Передача value позволяет вычислить текущую контрольную сумму по конкатенации нескольких входов. Алгоритм не является криптографически сильным и не должен быть используемый для аутентификации или цифровых подписей. Поскольку алгоритм предназначен для использования в качестве алгоритма контрольной суммы, он не подходит для использования в качестве общего хэш-алгоритма.

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

zlib.compress(data, level=-1)

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

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

zlib.decompress(data, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

Распаковывает байты в data, возвращая объект байтов, содержащий несжатые данные. Параметр 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 определяет размер буфера истории (или «размер окна»), а также ожидаемый формат заголовка и трейлера. Имеет то же значение, что и описан для decompress().

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

Примечание

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

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

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

Compress.compress(data)

Сжимает data, возвращая объект байтов, содержащий сжатые данные, по меньшей мере, для части данных в data. Эти данные должны быть объединены с выходными данными, создаваемыми любыми предыдущими вызовами метода 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()

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

Изменено в версии 3.8: Добавлена поддержка copy.copy() и copy.deepcopy() для объектов сжатия.

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

Decompress.unused_data

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

Decompress.unconsumed_tail

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

Decompress.eof

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

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

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

Decompress.decompress(data, max_length=0)

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

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

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

Decompress.flush([length])

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

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

Decompress.copy()

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

Изменено в версии 3.8: Добавлена поддержка copy.copy() и copy.deepcopy() для объектов декомпрессии.

Информация об используемой версии библиотеки zlib доступна через следующие константы:

zlib.ZLIB_VERSION

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

zlib.ZLIB_RUNTIME_VERSION

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

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

См.также

Модуль gzip

Чтение и запись файлов gzip-формата.

http://www.zlib.net

Домашняя страница библиотеки zlib.

http://www.zlib.net/manual.html

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