`zlib.md`

320 строк · 31.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.15/library/zlib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `zlib` – сжатие, совместимое с **gzip**89---1011Для приложений, которым требуется сжатие данных, функции этого модуля позволяют выполнять сжатие и распаковку с помощью [библиотеки zlib](https://python-all.ru/3.15/library/zlib.html).1213Это [опциональный модуль](https://python-all.ru/3.15/glossary.html#term-optional-module). Если его нет в вашей копии CPython, обратитесь к документации от вашего дистрибьютора (то есть того, кто предоставил вам Python). Если вы дистрибьютор, обратитесь к [требованиям к опциональным модулям](https://python-all.ru/3.15/using/configure.html#optional-module-requirements).1415Функции zlib имеют множество параметров и часто требуют определённого порядка вызова. В этой документации нет попытки охватить все комбинации; для получения исчерпывающей информации обращайтесь к [руководству по zlib](https://python-all.ru/3.15/library/zlib.html).1617Для чтения и записи файлов `.gz` обратитесь к модулю [`gzip`](https://python-all.ru/3.15/library/gzip.html#module-gzip).1819Доступные исключение и функции в этом модуле:2021#### `exception zlib.error`2223Исключение, возникающее при ошибках сжатия и распаковки.2425#### `zlib.adler32(data[, value])`2627Вычисляет контрольную сумму Адлера-32 для *data*. (Контрольная сумма Адлера-32 почти так же надёжна, как CRC32, но вычисляется гораздо быстрее.) Результат – 32-битное целое число без знака. Если указан *value*, он используется как начальное значение контрольной суммы; в противном случае используется значение 1 по умолчанию. Передача *value* позволяет вычислять накопленную контрольную сумму для объединения нескольких входных данных. Алгоритм не является криптостойким и не должен использоваться для аутентификации или цифровых подписей. Поскольку алгоритм разработан для использования в качестве алгоритма контрольной суммы, он не подходит для использования в качестве общего алгоритма хеширования.2829Изменено в версии 3.0: Результат всегда беззнаковый.3031#### `zlib.adler32_combine(adler1, adler2, len2, /)`3233Объединяет две контрольные суммы Adler-32 в одну.3435По контрольной сумме Adler-32 *adler1* последовательности `A` и контрольной сумме Adler-32 *adler2* последовательности `B` длины *len2* возвращает контрольную сумму Adler-32 для объединённых `A` и `B`.3637Эта функция обычно полезна для объединения контрольных сумм Adler-32, вычисленных параллельно. Для последовательного вычисления контрольных сумм используйте [`adler32()`](https://python-all.ru/3.15/library/zlib.html#zlib.adler32), передавая текущую контрольную сумму в качестве аргумента `value`.3839Добавлено в версии 3.15.4041#### `zlib.compress(data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)`4243Сжимает байты в *data* и возвращает объект bytes, содержащий сжатые данные. *level* – целое число от `0` до `9` или `-1`, управляющее степенью сжатия. Подробнее об этих значениях см. [`Z_BEST_SPEED`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_BEST_SPEED) (`1`), [`Z_BEST_COMPRESSION`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_BEST_COMPRESSION) (`9`), [`Z_NO_COMPRESSION`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_NO_COMPRESSION) (`0`) и значение по умолчанию [`Z_DEFAULT_COMPRESSION`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_DEFAULT_COMPRESSION) (`-1`).4445Аргумент *wbits* управляет размером буфера истории (или «размером окна»), используемого при сжатии данных, а также тем, включаются ли заголовок и концевая часть в выходные данные. Он может принимать несколько диапазонов значений, по умолчанию `15` ([`MAX_WBITS`](https://python-all.ru/3.15/library/zlib.html#zlib.MAX_WBITS)):4647- +9 … +15: двоичный логарифм размера окна, который соответственно находится в диапазоне от 512 до 32768. Большие значения дают лучшее сжатие за счёт большего расхода памяти. Полученный выходной поток будет включать заголовок и концевик, специфичные для zlib.48- −9 … −15: использует абсолютное значение *wbits* как логарифм размера окна, при этом создаётся необработанный выходной поток без заголовка и концевой контрольной суммы.49- +25 … +31 = 16 + (9 … 15): использует младшие 4 бита значения как логарифм размера окна, при этом в выходные данные включается простой заголовок **gzip** и концевая контрольная сумма.5051Возбуждает исключение [`error`](https://python-all.ru/3.15/library/zlib.html#zlib.error) в случае возникновения ошибки.5253Изменено в версии 3.6: *level* теперь можно использовать как именованный параметр.5455Изменено в версии 3.11: Параметр *wbits* теперь доступен для установки битов окна и типа сжатия.5657#### `zlib.compressobj(level=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])`5859Возвращает объект сжатия, который используется для сжатия потоков данных, не помещающихся в память целиком.6061*level* – степень сжатия: целое число от `0` до `9` или `-1`. Подробнее об этих значениях см. [`Z_BEST_SPEED`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_BEST_SPEED) (`1`), [`Z_BEST_COMPRESSION`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_BEST_COMPRESSION) (`9`), [`Z_NO_COMPRESSION`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_NO_COMPRESSION) (`0`) и значение по умолчанию [`Z_DEFAULT_COMPRESSION`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_DEFAULT_COMPRESSION) (`-1`).6263*method* – алгоритм сжатия. В настоящее время поддерживается только значение [`DEFLATED`](https://python-all.ru/3.15/library/zlib.html#zlib.DEFLATED).6465Параметр *wbits* управляет размером буфера истории (или «размером окна») и тем, какой формат заголовка и концевика будет использоваться. Его смысл такой же, как [описано для compress()](https://python-all.ru/3.15/library/zlib.html#compress-wbits).6667Аргумент *memLevel* управляет объёмом памяти, используемой для внутреннего состояния сжатия. Допустимые значения – от `1` до `9`. Большие значения используют больше памяти, но работают быстрее и дают меньший выходной поток.6869*strategy* используется для настройки алгоритма сжатия. Возможные значения: [`Z_DEFAULT_STRATEGY`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_DEFAULT_STRATEGY), [`Z_FILTERED`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_FILTERED), [`Z_HUFFMAN_ONLY`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_HUFFMAN_ONLY), [`Z_RLE`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_RLE) и [`Z_FIXED`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_FIXED).7071*zdict* – предопределённый словарь сжатия. Это последовательность байтов (например, объект [`bytes`](https://python-all.ru/3.15/library/stdtypes.html#bytes)), содержащая подпоследовательности, которые, как ожидается, часто встречаются в сжимаемых данных. Подпоследовательности, которые, как ожидается, встречаются чаще всего, должны располагаться в конце словаря.7273Изменено в версии 3.3: Добавлен параметр *zdict* и поддержка именованных аргументов.7475#### `zlib.crc32(data[, value])`7677Вычисляет контрольную сумму CRC (Cyclic Redundancy Check) для *data*. Результат – 32-битное целое число без знака. Если указан *value*, он используется как начальное значение контрольной суммы; в противном случае используется значение 0 по умолчанию. Передача *value* позволяет вычислять накопленную контрольную сумму для объединения нескольких входных данных. Алгоритм не является криптостойким и не должен использоваться для аутентификации или цифровых подписей. Поскольку алгоритм разработан для использования в качестве алгоритма контрольной суммы, он не подходит для использования в качестве общего алгоритма хеширования.7879Изменено в версии 3.0: Результат всегда беззнаковый.8081#### `zlib.crc32_combine(crc1, crc2, len2, /)`8283Объединяет две контрольные суммы CRC-32 в одну.8485По контрольной сумме CRC-32 *crc1* последовательности `A` и контрольной сумме CRC-32 *crc2* последовательности `B` длины *len2* возвращает контрольную сумму CRC-32 для объединённых `A` и `B`.8687Эта функция обычно полезна для объединения контрольных сумм CRC-32, вычисленных параллельно. Для последовательного вычисления контрольных сумм используйте [`crc32()`](https://python-all.ru/3.15/library/zlib.html#zlib.crc32), передавая текущую контрольную сумму в качестве аргумента `value`.8889Добавлено в версии 3.15.9091#### `zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)`9293Распаковывает байты в *data* и возвращает объект bytes, содержащий несжатые данные. Параметр *wbits* зависит от формата *data*; подробнее это обсуждается ниже. Если указан *bufsize*, он используется как начальный размер выходного буфера. Возбуждает исключение [`error`](https://python-all.ru/3.15/library/zlib.html#zlib.error) в случае возникновения ошибки.9495Параметр *wbits* управляет размером буфера истории (или «размером окна»), а также тем, какой формат заголовка и трейлера ожидается. Он аналогичен параметру для [`compressobj()`](https://python-all.ru/3.15/library/zlib.html#zlib.compressobj), но принимает больше диапазонов значений:9697- +8 … +15: двоичный логарифм размера окна. Входные данные должны содержать заголовок и трейлер zlib.98- 0: автоматически определять размер окна из заголовка zlib. Поддерживается только начиная с zlib 1.2.3.5.99- −8 … −15: использует абсолютное значение *wbits* как логарифм размера окна. Входные данные должны быть сырым потоком без заголовка или трейлера.100- +24 … +31 = 16 + (8 … 15): использует младшие 4 бита значения как логарифм размера окна. Входные данные должны содержать заголовок и трейлер gzip.101- +40 … +47 = 32 + (8 … 15): использует младшие 4 бита значения как логарифм размера окна и автоматически принимает как формат zlib, так и gzip.102103При распаковке потока размер окна не должен быть меньше размера, изначально использованного для сжатия потока; слишком маленькое значение может привести к исключению [`error`](https://python-all.ru/3.15/library/zlib.html#zlib.error). Значение *wbits* по умолчанию соответствует наибольшему размеру окна и требует включения заголовка и трейлера zlib.104105*bufsize* – это начальный размер буфера для хранения распакованных данных. Если требуется больше места, размер буфера будет увеличен по мере необходимости, так что необязательно подбирать это значение точно; его настройка лишь позволит сэкономить несколько вызовов `malloc()`.106107Изменено в версии 3.6: *wbits* и *bufsize* можно использовать как именованные аргументы.108109#### `zlib.decompressobj(wbits=MAX_WBITS[, zdict])`110111Возвращает объект распаковки, предназначенный для распаковки потоков данных, которые не помещаются в память целиком.112113Параметр *wbits* управляет размером буфера истории (или «размером окна») и тем, какой формат заголовка и трейлера ожидается. Он имеет то же значение, что и [описанный для decompress()](https://python-all.ru/3.15/library/zlib.html#decompress-wbits).114115Параметр *zdict* задаёт предопределённый словарь сжатия. Если он указан, это должен быть тот же словарь, который использовался компрессором, создавшим подлежащие распаковке данные.116117> **Примечание**118>119> Если *zdict* является изменяемым объектом (например, [`bytearray`](https://python-all.ru/3.15/library/stdtypes.html#bytearray)), его содержимое нельзя изменять между вызовом `decompressobj()` и первым вызовом метода `decompress()` распаковщика.120121Изменено в версии 3.3: Добавлен параметр *zdict*.122123Объекты сжатия поддерживают следующие методы:124125#### `Compress.compress(data)`126127Сжимает *data*, возвращая объект bytes, содержащий сжатые данные, по крайней мере для части данных из *data*. Эти данные следует добавить к выводу, полученному от любых предыдущих вызовов метода `compress()`. Некоторые входные данные могут быть сохранены во внутренних буферах для последующей обработки.128129#### `Compress.flush([mode])`130131Все ожидающие входные данные обрабатываются, и возвращается объект bytes, содержащий оставшийся сжатый вывод. *mode* может быть выбран из констант [`Z_NO_FLUSH`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_NO_FLUSH), [`Z_PARTIAL_FLUSH`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_PARTIAL_FLUSH), [`Z_SYNC_FLUSH`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_SYNC_FLUSH), [`Z_FULL_FLUSH`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_FULL_FLUSH), [`Z_BLOCK`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_BLOCK) или [`Z_FINISH`](https://python-all.ru/3.15/library/zlib.html#zlib.Z_FINISH), по умолчанию `Z_FINISH`. За исключением `Z_FINISH`, все константы позволяют сжимать дальнейшие строки байт, в то время как `Z_FINISH` завершает сжатый поток и предотвращает сжатие дальнейших данных. После вызова `flush()` с *mode*, установленным в `Z_FINISH`, метод [`compress()`](https://python-all.ru/3.15/library/zlib.html#zlib.compress) больше нельзя вызывать; единственное разумное действие – удалить объект.132133#### `Compress.copy()`134135Возвращает копию объекта сжатия. Это может быть использовано для эффективного сжатия набора данных, имеющих общий начальный префикс.136137Изменено в версии 3.8: Добавлена поддержка [`copy.copy()`](https://python-all.ru/3.15/library/copy.html#copy.copy) и [`copy.deepcopy()`](https://python-all.ru/3.15/library/copy.html#copy.deepcopy) для объектов сжатия.138139Объекты распаковки поддерживают следующие методы и атрибуты:140141#### `Decompress.unused_data`142143Объект bytes, содержащий любые байты после конца сжатых данных. То есть он остаётся `b""` до тех пор, пока не станет доступен последний байт, содержащий сжатые данные. Если вся строка байт оказалась состоящей из сжатых данных, это `b""`, пустой объект bytes.144145#### `Decompress.unconsumed_tail`146147Объект bytes, содержащий любые данные, которые не были потреблены последним вызовом [`decompress()`](https://python-all.ru/3.15/library/zlib.html#zlib.decompress), так как они превысили лимит буфера распакованных данных. Эти данные ещё не были обработаны механизмом zlib, поэтому их необходимо снова передать (возможно, с добавлением дополнительных данных) в последующий вызов метода `decompress()`, чтобы получить правильный вывод.148149#### `Decompress.eof`150151Логическое значение, указывающее, достигнут ли конец сжатого потока данных.152153Это позволяет различать правильно сформированный сжатый поток и неполный или усечённый.154155Добавлено в версии 3.3.156157#### `Decompress.decompress(data, max_length=0)`158159Распаковывает *data*, возвращая bytes-объект с распакованными данными, соответствующими по меньшей мере части данных из *string*. Эти данные следует добавить к результату, полученному от предыдущих вызовов метода `decompress()`. Некоторые входные данные могут сохраняться во внутренних буферах для последующей обработки.160161Если необязательный параметр *max\_length* не равен нулю, возвращаемое значение будет не длиннее *max\_length*. Это может означать, что не все сжатые входные данные могут быть обработаны; необработанные данные будут сохранены в атрибуте [`unconsumed_tail`](https://python-all.ru/3.15/library/zlib.html#zlib.Decompress.unconsumed_tail). Эта байтовая строка должна быть передана последующему вызову `decompress()`, если декомпрессия должна продолжаться. Если *max\_length* равно нулю, то все входные данные декомпрессируются, и `unconsumed_tail` пусто. Например, полное содержимое можно прочитать так:162163```python164process_output(d.decompress(data, max_length))165while chunk := d.decompress(d.unconsumed_tail, max_length):166    process_output(chunk)167```168169Изменено в версии 3.6: *max\_length* можно использовать как именованный аргумент.170171#### `Decompress.flush([length])`172173Все ожидающие обработки входные данные обрабатываются, и возвращается bytes-объект, содержащий оставшиеся распакованные выходные данные. После вызова `flush()` метод [`decompress()`](https://python-all.ru/3.15/library/zlib.html#zlib.decompress) больше нельзя вызывать; единственное разумное действие – удалить объект.174175Необязательный параметр *length* задаёт начальный размер выходного буфера.176177#### `Decompress.copy()`178179Возвращает копию объекта распаковки. Это можно использовать для сохранения состояния распаковщика на середине потока данных, чтобы ускорить произвольный доступ к потоку в будущем.180181Изменено в версии 3.8: Добавлена поддержка [`copy.copy()`](https://python-all.ru/3.15/library/copy.html#copy.copy) и [`copy.deepcopy()`](https://python-all.ru/3.15/library/copy.html#copy.deepcopy) для объектов распаковки.182183Следующие константы доступны для настройки поведения сжатия и распаковки:184185#### `zlib.DEFLATED`186187Метод сжатия deflate.188189#### `zlib.MAX_WBITS`190191Максимальный размер окна, выраженный как степень двойки. Например, если `MAX_WBITS` равен `15`, то размер окна составит `32 KiB`.192193#### `zlib.DEF_MEM_LEVEL`194195Уровень памяти по умолчанию для объектов сжатия.196197#### `zlib.DEF_BUF_SIZE`198199Размер буфера по умолчанию для операций распаковки.200201#### `zlib.Z_NO_COMPRESSION`202203Уровень сжатия `0`; без сжатия.204205Добавлено в версии 3.6.206207#### `zlib.Z_BEST_SPEED`208209Уровень сжатия `1`; самый быстрый, обеспечивает наименьшее сжатие.210211#### `zlib.Z_BEST_COMPRESSION`212213Уровень сжатия `9`; самый медленный, обеспечивает наибольшее сжатие.214215#### `zlib.Z_DEFAULT_COMPRESSION`216217Уровень сжатия по умолчанию (`-1`); компромисс между скоростью и сжатием. В настоящее время эквивалентен уровню сжатия `6`.218219#### `zlib.Z_DEFAULT_STRATEGY`220221Стратегия сжатия по умолчанию для обычных данных.222223#### `zlib.Z_FILTERED`224225Стратегия сжатия для данных, полученных от фильтра (или предсказателя).226227#### `zlib.Z_HUFFMAN_ONLY`228229Стратегия сжатия, использующая только кодирование Хаффмана.230231#### `zlib.Z_RLE`232233Стратегия сжатия, ограничивающая расстояния совпадений до одного (кодирование длин серий).234235Эта константа доступна только если Python был собран с zlib 1.2.0.1 или новее.236237Добавлено в версии 3.6.238239#### `zlib.Z_FIXED`240241Стратегия сжатия, предотвращающая использование динамических кодов Хаффмана.242243Эта константа доступна только если Python был собран с zlib 1.2.2.2 или новее.244245Добавлено в версии 3.6.246247#### `zlib.Z_NO_FLUSH`248249Режим сброса `0`. Особого поведения при сбросе нет.250251Добавлено в версии 3.6.252253#### `zlib.Z_PARTIAL_FLUSH`254255Режим сброса `1`. Сбрасывает как можно больше выходных данных.256257#### `zlib.Z_SYNC_FLUSH`258259Режим сброса `2`. Все выходные данные сбрасываются, и выходные данные выравниваются по границе байта.260261#### `zlib.Z_FULL_FLUSH`262263Режим сброса `3`. Все выходные данные сбрасываются, а состояние сжатия сбрасывается.264265#### `zlib.Z_FINISH`266267Режим сброса `4`. Все отложенные входные данные обрабатываются; новых данных не ожидается.268269#### `zlib.Z_BLOCK`270271Режим сброса `5`. Блок deflate завершается и выводится.272273Эта константа доступна только если Python был собран с zlib 1.2.2.2 или новее.274275Добавлено в версии 3.6.276277#### `zlib.Z_TREES`278279Режим сброса `6` для операций inflate. Указывает inflate вернуться, когда он достигнет границы следующего блока deflate.280281Эта константа доступна только если Python был собран с zlib 1.2.3.4 или новее.282283Добавлено в версии 3.6.284285Информацию о версии используемой библиотеки zlib можно получить через следующие константы:286287#### `zlib.ZLIB_VERSION`288289Строка версии библиотеки zlib, использовавшейся для сборки модуля. Она может отличаться от библиотеки zlib, фактически используемой во время выполнения, которая доступна как [`ZLIB_RUNTIME_VERSION`](https://python-all.ru/3.15/library/zlib.html#zlib.ZLIB_RUNTIME_VERSION).290291#### `zlib.ZLIB_RUNTIME_VERSION`292293Строка версии библиотеки zlib, фактически загруженной интерпретатором.294295Добавлено в версии 3.3.296297#### `zlib.ZLIBNG_VERSION`298299Строка версии библиотеки zlib-ng, использовавшейся для сборки модуля, если использовалась zlib-ng. При наличии константы [`ZLIB_VERSION`](https://python-all.ru/3.15/library/zlib.html#zlib.ZLIB_VERSION) и [`ZLIB_RUNTIME_VERSION`](https://python-all.ru/3.15/library/zlib.html#zlib.ZLIB_RUNTIME_VERSION) отражают версию API zlib, предоставляемого zlib-ng.300301Если zlib-ng не использовалась для сборки модуля, эта константа будет отсутствовать.302303Добавлено в версии 3.14.304305> **См. также**306>307> **Модуль [`gzip`](https://python-all.ru/3.15/library/gzip.html#module-gzip)**308>309> Чтение и запись файлов в формате **gzip**.310>311> **[https://www.zlib.net](https://python-all.ru/3.15/library/zlib.html)**312>313> Домашняя страница библиотеки zlib.314>315> **[https://www.zlib.net/manual.html](https://python-all.ru/3.15/library/zlib.html)**316>317> Руководство zlib объясняет семантику и использование многих функций библиотеки.318>319> Если сжатие/распаковка gzip является узким местом, пакет [python-isal](https://python-all.ru/3.15/library/zlib.html) ускоряет сжатие/распаковку с помощью почти совместимого API.320