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

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