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

Изменено в версии 3.0: Всегда возвращает беззнаковое значение. Чтобы получить то же числовое значение на всех версиях Python и платформах, используйте 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 to 15): использует низкие 4 бита значения в качестве логарифма размера окна. Входные данные должны содержать заголовок и хвост gzip.
• от +40 до +47 = 32 + (8 to 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, возвращая объект bytes, содержащий сжатые данные по крайней мере для части данных в 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()

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

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

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.