zlib.md

1> **Источник:** https://python-all.ru/3.5/library/zlib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 13.1. [`zlib`](https://python-all.ru/3.5/library/zlib.html#module-zlib) – Сжатие, совместимое с **gzip**89---1011Для приложений, которым требуется сжатие данных, функции этого модуля позволяют выполнять сжатие и распаковку с помощью библиотеки zlib. Библиотека zlib имеет собственную домашнюю страницу по адресу [http://www.zlib.net](https://python-all.ru/3.5/library/zlib.html). Существуют известные несовместимости между модулем Python и версиями библиотеки zlib старше 1.1.3; в версии 1.1.3 есть уязвимость безопасности, поэтому рекомендуется использовать версию 1.1.4 или новее.1213Функции zlib имеют множество опций и зачастую должны вызываться в определённом порядке. Данная документация не пытается охватить все комбинации; за авторитетной информацией обращайтесь к руководству zlib по адресу [http://www.zlib.net/manual.html](https://python-all.ru/3.5/library/zlib.html).1415Для чтения и записи файлов `.gz` обратитесь к модулю [`gzip`](https://python-all.ru/3.5/library/gzip.html#module-gzip).1617Доступные исключение и функции в этом модуле:1819#### `exception zlib.error`2021Исключение, возникающее при ошибках сжатия и распаковки.2223#### `zlib.adler32(data[, value])`2425Вычисляет контрольную сумму Адлера-32 для *data*. (Контрольная сумма Адлера-32 почти так же надёжна, как CRC32, но вычисляется гораздо быстрее.) Результат – 32-битное целое число без знака. Если указан *value*, он используется как начальное значение контрольной суммы; в противном случае используется значение 1 по умолчанию. Передача *value* позволяет вычислять накопленную контрольную сумму для объединения нескольких входных данных. Алгоритм не является криптостойким и не должен использоваться для аутентификации или цифровых подписей. Поскольку алгоритм разработан для использования в качестве алгоритма контрольной суммы, он не подходит для использования в качестве общего алгоритма хеширования.2627Изменено в версии 3.0: Всегда возвращает беззнаковое значение. Чтобы получить одинаковое числовое значение во всех версиях Python и на всех платформах, используйте `adler32(data) & 0xffffffff`.2829#### `zlib.compress(data[, level])`3031Сжимает байты в *data*, возвращая объект bytes со сжатыми данными. *level* – целое число от `0` до `9`, задающее степень сжатия; `1` – самое быстрое и даёт наименьшее сжатие, `9` – самое медленное и даёт наибольшее. `0` – без сжатия. Значение по умолчанию – `6`. При возникновении ошибки возбуждается исключение [`error`](https://python-all.ru/3.5/library/zlib.html#zlib.error).3233#### `zlib.compressobj(level=-1, method=DEFLATED, wbits=15, memLevel=8, strategy=Z_DEFAULT_STRATEGY[, zdict])`3435Возвращает объект сжатия, который используется для сжатия потоков данных, не помещающихся в память целиком.3637*level* – степень сжатия: целое число от `0` до `9` или `-1`. Значение `1` – самое быстрое и даёт наименьшее сжатие, а значение `9` – самое медленное и даёт наибольшее. `0` – без сжатия. Значение по умолчанию – `-1` (Z\_DEFAULT\_COMPRESSION). Z\_DEFAULT\_COMPRESSION представляет собой компромисс между скоростью и степенью сжатия (в настоящее время соответствует уровню 6).3839*method* – алгоритм сжатия. В настоящее время поддерживается только значение `DEFLATED`.4041Аргумент *wbits* управляет размером буфера истории (или «размером окна»), используемого при сжатии данных, а также определяет, включать ли заголовок и концевик в выходные данные. Он может принимать несколько диапазонов значений:4243- +9 … +15: двоичный логарифм размера окна, который соответственно находится в диапазоне от 512 до 32768. Большие значения дают лучшее сжатие за счёт большего расхода памяти. Полученный выходной поток будет включать заголовок и концевик, специфичные для zlib.44- −9 … −15: использует абсолютное значение *wbits* как логарифм размера окна, при этом создаётся необработанный выходной поток без заголовка и концевой контрольной суммы.45- +25 … +31 = 16 + (9 … 15): использует младшие 4 бита значения как логарифм размера окна, при этом в выходные данные включается простой заголовок **gzip** и концевая контрольная сумма.4647Аргумент *memLevel* управляет объёмом памяти, используемой для внутреннего состояния сжатия. Допустимые значения – от `1` до `9`. Большие значения используют больше памяти, но работают быстрее и дают меньший выходной поток.4849*strategy* используется для настройки алгоритма сжатия. Возможные значения: `Z_DEFAULT_STRATEGY`, `Z_FILTERED` и `Z_HUFFMAN_ONLY`.5051*zdict* – предопределённый словарь сжатия. Это последовательность байтов (например, объект [`bytes`](https://python-all.ru/3.5/library/functions.html#bytes)), содержащая подпоследовательности, которые, как ожидается, часто встречаются в сжимаемых данных. Подпоследовательности, которые, как ожидается, встречаются чаще всего, должны располагаться в конце словаря.5253Изменено в версии 3.3: Добавлен параметр *zdict* и поддержка именованных аргументов.5455#### `zlib.crc32(data[, value])`5657Вычисляет контрольную сумму CRC (Cyclic Redundancy Check) для *data*. Результат – 32-битное целое число без знака. Если указан *value*, он используется как начальное значение контрольной суммы; в противном случае используется значение 0 по умолчанию. Передача *value* позволяет вычислять накопленную контрольную сумму для объединения нескольких входных данных. Алгоритм не является криптостойким и не должен использоваться для аутентификации или цифровых подписей. Поскольку алгоритм разработан для использования в качестве алгоритма контрольной суммы, он не подходит для использования в качестве общего алгоритма хеширования.5859Изменено в версии 3.0: Всегда возвращает беззнаковое значение. Чтобы получить одинаковое числовое значение во всех версиях Python и на всех платформах, используйте `crc32(data) & 0xffffffff`.6061#### `zlib.decompress(data[, wbits[, bufsize]])`6263Распаковывает байты в *data* и возвращает объект bytes, содержащий несжатые данные. Параметр *wbits* зависит от формата *data*; подробнее это обсуждается ниже. Если указан *bufsize*, он используется как начальный размер выходного буфера. Возбуждает исключение [`error`](https://python-all.ru/3.5/library/zlib.html#zlib.error) в случае возникновения ошибки.6465Параметр *wbits* управляет размером буфера истории (или «размером окна»), а также тем, какой формат заголовка и трейлера ожидается. Он аналогичен параметру для [`compressobj()`](https://python-all.ru/3.5/library/zlib.html#zlib.compressobj), но принимает больше диапазонов значений:6667- +8 … +15: двоичный логарифм размера окна. Входные данные должны содержать заголовок и трейлер zlib.68- 0: автоматически определять размер окна из заголовка zlib. Поддерживается только начиная с zlib 1.2.3.5.69- −8 … −15: использует абсолютное значение *wbits* как логарифм размера окна. Входные данные должны быть сырым потоком без заголовка или трейлера.70- +24 … +31 = 16 + (8 … 15): использует младшие 4 бита значения как логарифм размера окна. Входные данные должны содержать заголовок и трейлер gzip.71- +40 … +47 = 32 + (8 … 15): использует младшие 4 бита значения как логарифм размера окна и автоматически принимает как формат zlib, так и gzip.7273При декомпрессии потока размер окна не должен быть меньше размера, использованного при сжатии потока; слишком маленькое значение может привести к исключению [`error`](https://python-all.ru/3.5/library/zlib.html#zlib.error). Значение *wbits* по умолчанию равно 15, что соответствует наибольшему размеру окна и требует включения заголовка и концевика zlib.7475*bufsize* – начальный размер буфера для хранения распакованных данных. Если требуется больше места, размер буфера будет увеличен по мере необходимости, так что не нужно точно подбирать это значение; его настройка лишь сэкономит несколько вызовов `malloc()`. Размер по умолчанию – 16384.7677#### `zlib.decompressobj(wbits=15[, zdict])`7879Возвращает объект распаковки, предназначенный для распаковки потоков данных, которые не помещаются в память целиком.8081Параметр *wbits* управляет размером буфера истории (или «размером окна») и тем, какой формат заголовка и трейлера ожидается. Он имеет то же значение, что и [описанный для decompress()](https://python-all.ru/3.5/library/zlib.html#decompress-wbits).8283Параметр *zdict* задаёт предопределённый словарь сжатия. Если он указан, это должен быть тот же словарь, который использовался компрессором, создавшим подлежащие распаковке данные.8485> **Примечание**86>87> Если *zdict* является изменяемым объектом (например, [`bytearray`](https://python-all.ru/3.5/library/functions.html#bytearray)), его содержимое нельзя изменять между вызовом [`decompressobj()`](https://python-all.ru/3.5/library/zlib.html#zlib.decompressobj) и первым вызовом метода `decompress()` распаковщика.8889Изменено в версии 3.3: Добавлен параметр *zdict*.9091Объекты сжатия поддерживают следующие методы:9293#### `Compress.compress(data)`9495Сжимает *data*, возвращая объект bytes, содержащий сжатые данные, по крайней мере для части данных из *data*. Эти данные следует добавить к выводу, полученному от любых предыдущих вызовов метода [`compress()`](https://python-all.ru/3.5/library/zlib.html#zlib.compress). Некоторые входные данные могут быть сохранены во внутренних буферах для последующей обработки.9697#### `Compress.flush([mode])`9899Все ожидающие входные данные обрабатываются, и возвращается объект bytes, содержащий оставшиеся сжатые выходные данные. *mode* можно выбрать из констант `Z_SYNC_FLUSH`, `Z_FULL_FLUSH` или `Z_FINISH`, по умолчанию `Z_FINISH`. `Z_SYNC_FLUSH` и `Z_FULL_FLUSH` позволяют продолжать сжатие следующих строк байтов, а `Z_FINISH` завершает сжатый поток и запрещает дальнейшее сжатие. После вызова [`flush()`](https://python-all.ru/3.5/library/zlib.html#zlib.Compress.flush) с *mode*, установленным в `Z_FINISH`, метод [`compress()`](https://python-all.ru/3.5/library/zlib.html#zlib.compress) нельзя вызывать снова; единственное разумное действие – удалить объект.100101#### `Compress.copy()`102103Возвращает копию объекта сжатия. Это может быть использовано для эффективного сжатия набора данных, имеющих общий начальный префикс.104105Объекты распаковки поддерживают следующие методы и атрибуты:106107#### `Decompress.unused_data`108109Объект bytes, содержащий любые байты после конца сжатых данных. То есть он остаётся `b""` до тех пор, пока не станет доступен последний байт, содержащий сжатые данные. Если вся строка байт оказалась состоящей из сжатых данных, это `b""`, пустой объект bytes.110111#### `Decompress.unconsumed_tail`112113Объект bytes, содержащий любые данные, которые не были потреблены последним вызовом [`decompress()`](https://python-all.ru/3.5/library/zlib.html#zlib.decompress), так как они превысили лимит буфера распакованных данных. Эти данные ещё не были обработаны механизмом zlib, поэтому их необходимо снова передать (возможно, с добавлением дополнительных данных) в последующий вызов метода [`decompress()`](https://python-all.ru/3.5/library/zlib.html#zlib.decompress), чтобы получить правильный вывод.114115#### `Decompress.eof`116117Логическое значение, указывающее, достигнут ли конец сжатого потока данных.118119Это позволяет различать правильно сформированный сжатый поток и неполный или усечённый.120121Новое в версии 3.3.122123#### `Decompress.decompress(data[, max_length])`124125Распаковывает *data*, возвращая bytes-объект с распакованными данными, соответствующими по меньшей мере части данных из *string*. Эти данные следует добавить к результату, полученному от предыдущих вызовов метода [`decompress()`](https://python-all.ru/3.5/library/zlib.html#zlib.decompress). Некоторые входные данные могут сохраняться во внутренних буферах для последующей обработки.126127Если необязательный параметр *max\_length* ненулевой, то возвращаемое значение будет не длиннее *max\_length*. Это может означать, что не все сжатые входные данные могут быть обработаны; неиспользованные данные будут сохранены в атрибуте [`unconsumed_tail`](https://python-all.ru/3.5/library/zlib.html#zlib.Decompress.unconsumed_tail). Эту байтовую строку необходимо передать последующему вызову [`decompress()`](https://python-all.ru/3.5/library/zlib.html#zlib.decompress), если декомпрессия должна быть продолжена. Если *max\_length* не указан, то декомпрессируется весь входной поток, и [`unconsumed_tail`](https://python-all.ru/3.5/library/zlib.html#zlib.Decompress.unconsumed_tail) пуст.128129#### `Decompress.flush([length])`130131Все ожидающие обработки входные данные обрабатываются, и возвращается bytes-объект, содержащий оставшиеся распакованные выходные данные. После вызова [`flush()`](https://python-all.ru/3.5/library/zlib.html#zlib.Decompress.flush) метод [`decompress()`](https://python-all.ru/3.5/library/zlib.html#zlib.decompress) больше нельзя вызывать; единственное разумное действие – удалить объект.132133Необязательный параметр *length* задаёт начальный размер выходного буфера.134135#### `Decompress.copy()`136137Возвращает копию объекта распаковки. Это можно использовать для сохранения состояния распаковщика на середине потока данных, чтобы ускорить произвольный доступ к потоку в будущем.138139Информацию о версии используемой библиотеки zlib можно получить через следующие константы:140141#### `zlib.ZLIB_VERSION`142143Строка версии библиотеки zlib, использовавшейся для сборки модуля. Она может отличаться от библиотеки zlib, фактически используемой во время выполнения, которая доступна как [`ZLIB_RUNTIME_VERSION`](https://python-all.ru/3.5/library/zlib.html#zlib.ZLIB_RUNTIME_VERSION).144145#### `zlib.ZLIB_RUNTIME_VERSION`146147Строка версии библиотеки zlib, фактически загруженной интерпретатором.148149Новое в версии 3.3.150151> **См. также**152>153> **Модуль [`gzip`](https://python-all.ru/3.5/library/gzip.html#module-gzip)**154>155> Чтение и запись файлов в формате156>157> **gzip**158>159> .160>161> **[http://www.zlib.net](https://python-all.ru/3.5/library/zlib.html)**162>163> Домашняя страница библиотеки zlib.164>165> **[http://www.zlib.net/manual.html](https://python-all.ru/3.5/library/zlib.html)**166>167> Руководство zlib объясняет семантику и использование многих функций библиотеки.168