zlib — Сжатие, совместимое с gzip

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

Изменено в версии 3.0: Результат всегда без знака.

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

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

Аргумент wbits контролирует размер буфера истории (или «размер окна»), используемого при сжатии данных, и включение заголовка и концевика в выходные данные. Он может принимать несколько диапазонов значений, по умолчанию 15 (MAX_WBITS):

• +9 до +15: Двоичный логарифм размера окна, который, следовательно, изменяется от 512 до 32768. Более крупные значения обеспечивают лучшее сжатие за счет большего использования памяти. Результирующие выходные данные будут включать специфичный для zlib заголовок и концевик.
• −9 до −15: Использует абсолютное значение wbits как логарифм размера окна, при этом генерирует поток сырых данных без заголовка или контрольной суммы концевика.
• +25 до +31 = 16 + (9 до 15): Использует низкие 4 бита значения в качестве логарифма размера окна, при этом в выходные данные включается базовый заголовок gzip и контрольная сумма концевика.

Поднимает исключение error, если возникнет какая-либо ошибка.

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

Изменено в версии 3.11: Параметр wbits теперь доступен для установки битов окна и типа сжатия.

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

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

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

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

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

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

Изменено в версии 3.0: Результат всегда без знака.

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

Распаковывает байты в данных, возвращая объект bytes, содержащий несжатые данные. Параметр wbits зависит от формата данных и обсуждается далее. Если задан 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)

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

Compress.flush([mode])

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

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

Decompress.unconsumed_tail

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

Decompress.eof

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

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

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

Decompress.decompress(data, max_length=0)

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

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

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

Decompress.flush([length])

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

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

Decompress.copy()

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

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

zlib.ZLIB_VERSION

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

zlib.ZLIB_RUNTIME_VERSION

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

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