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

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

Это необязательный модуль. Если он отсутствует в вашей копии CPython, обратитесь к документации вашего дистрибутива (то есть поставщика Python). Если вы являетесь поставщиком, см. раздел Требования к необязательным модулям.

Функции zlib имеют множество параметров, и часто их необходимо использовать в определённом порядке. В этой документации не рассматриваются все возможные варианты; авторитетную информацию см. в руководстве zlib.

Для чтения и записи файлов .gz см. модуль gzip.

В этом модуле доступны следующие исключение и функции:

exception zlib.error

Исключение, возникающее при ошибках сжатия и распаковки.

zlib.adler32(data, value=1, /)

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

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

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

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

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

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

Если возникает ошибка, вызывает исключение error.

Изменено в версии 3.6: Теперь level можно указывать как именованный параметр.

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

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

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

level — уровень сжатия, целое число от 0 до 9 или -1. Дополнительные сведения об этих значениях см. в описании Z_BEST_SPEED (1), Z_BEST_COMPRESSION (9), Z_NO_COMPRESSION (0) и значения по умолчанию — Z_DEFAULT_COMPRESSION (-1).

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

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

Аргумент memLevel задаёт объём памяти, используемый для внутреннего состояния сжатия. Допустимые значения — от 1 до 9. Большие значения требуют больше памяти, но обеспечивают более высокую скорость и меньший размер выходных данных.

strategy используется для настройки алгоритма сжатия. Возможные значения: Z_DEFAULT_STRATEGY, Z_FILTERED, Z_HUFFMAN_ONLY, Z_RLE и Z_FIXED.

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

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

zlib.crc32(data, value=0, /)

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

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

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=b'')

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

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

Параметр zdict задаёт предварительно определённый словарь сжатия. Если он указан, это должен быть тот же словарь, который использовался компрессором, создавшим распаковываемые данные.

Примечание

Если zdict — изменяемый объект (например, bytearray), его содержимое нельзя изменять между вызовом decompressobj() и первым вызовом метода decompress() объекта распаковки.

Изменено в версии 3.3: Добавлен параметр zdict.

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

Compress.compress(data, /)

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

Compress.flush(mode=Z_FINISH, /)

Обрабатывает все ожидающие входные данные и возвращает объект bytes, содержащий оставшиеся сжатые выходные данные. Для mode можно выбрать одну из констант Z_NO_FLUSH, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, Z_FULL_FLUSH, Z_BLOCK или 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=DEF_BUF_SIZE, /)

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

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

Decompress.copy()

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

Для настройки поведения сжатия и распаковки доступны следующие константы:

zlib.DEFLATED

Метод сжатия deflate.

zlib.MAX_WBITS

Максимальный размер окна, выраженный как степень числа 2. Например, если MAX_WBITS равно 15, размер окна составит 32 KiB.

zlib.DEF_MEM_LEVEL

Уровень использования памяти по умолчанию для объектов сжатия.

zlib.DEF_BUF_SIZE

Размер буфера по умолчанию для операций распаковки.

zlib.Z_NO_COMPRESSION

Уровень сжатия 0; без сжатия.

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

zlib.Z_BEST_SPEED

Уровень сжатия 1; самая высокая скорость и наименьшая степень сжатия.

zlib.Z_BEST_COMPRESSION

Уровень сжатия 9; самая низкая скорость и наибольшая степень сжатия.

zlib.Z_DEFAULT_COMPRESSION

Уровень сжатия по умолчанию (-1); компромисс между скоростью и степенью сжатия. В настоящее время эквивалентен уровню сжатия 6.

zlib.Z_DEFAULT_STRATEGY

Стратегия сжатия по умолчанию для обычных данных.

zlib.Z_FILTERED

Стратегия сжатия для данных, полученных фильтром (или предиктором).

zlib.Z_HUFFMAN_ONLY

Стратегия сжатия, которая использует только кодирование Хаффмана.

zlib.Z_RLE

Стратегия сжатия, ограничивающая расстояние совпадений единицей (кодирование длин серий).

Эта константа доступна, только если Python был собран с zlib версии 1.2.0.1 или новее.

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

zlib.Z_FIXED

Стратегия сжатия, запрещающая использование динамических кодов Хаффмана.

Эта константа доступна, только если Python был собран с zlib версии 1.2.2.2 или новее.

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

zlib.Z_NO_FLUSH

Режим сброса 0. Специальное поведение сброса не используется.

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

zlib.Z_PARTIAL_FLUSH

Режим сброса 1. Сбрасывает максимально возможный объём выходных данных.

zlib.Z_SYNC_FLUSH

Режим сброса 2. Все выходные данные сбрасываются, а вывод выравнивается по границе байта.

zlib.Z_FULL_FLUSH

Режим сброса 3. Все выходные данные сбрасываются, а состояние сжатия сбрасывается.

zlib.Z_FINISH

Режим сброса 4. Все ожидающие входные данные обрабатываются; дальнейшие входные данные не ожидаются.

zlib.Z_BLOCK

Режим сброса 5. Блок deflate завершается и выводится.

Эта константа доступна, только если Python был собран с zlib версии 1.2.2.2 или новее.

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

zlib.Z_TREES

Режим сброса 6 для операций inflate. Предписывает inflate вернуть управление при достижении следующей границы блока deflate.

Эта константа доступна, только если Python был собран с zlib версии 1.2.3.4 или новее.

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

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

zlib.ZLIB_VERSION

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

zlib.ZLIB_RUNTIME_VERSION

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

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

zlib.ZLIBNG_VERSION

Строка версии библиотеки zlib-ng, использованной для сборки модуля, если использовалась zlib-ng. Если эта константа присутствует, константы ZLIB_VERSION и ZLIB_RUNTIME_VERSION отражают версию API zlib, предоставляемого zlib-ng.

Если для сборки модуля не использовалась zlib-ng, эта константа отсутствует.

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