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])

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

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

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. Значение 1 — самое быстрое и производит наименьшее сжатие, а значение 9 — самое медленное и производит наибольшее. 0 — без сжатия. Значение по умолчанию — -1 (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION представляет собой компромисс между скоростью и сжатием (в настоящее время эквивалентно уровню 6).

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

Аргумент 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.

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

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

zlib.crc32(data[, value])

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

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

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

Распаковывает байты в 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 равно 15, что соответствует максимальному размеру окна и требует включения заголовка и трейлера zlib.

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

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

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

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

Параметр 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

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

Decompress.unconsumed_tail

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

Decompress.eof

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

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

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

Decompress.decompress(data[, max_length])

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

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

Decompress.flush([length])

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

Необязательный параметр length задаёт начальный размер буфера вывода.

Decompress.copy()

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

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

zlib.ZLIB_VERSION

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

zlib.ZLIB_RUNTIME_VERSION

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

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