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 до 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 до 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, возвращая объект 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.