# `zlib` — Compression compatible with gzip

For applications that require data compression, the functions in this module allow compression and decompression, using the zlib library.

This is an optional module. If it is missing from your copy of CPython, look for documentation from your distributor (that is, whoever provided Python to you). If you are the distributor, see Requirements for optional modules.

zlib’s functions have many options and often need to be used in a particular order. This documentation doesn’t attempt to cover all of the permutations; consult the zlib manual for authoritative information.

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

Доступні винятки та функції в цьому модулі:

exception zlib.error

  Винятком є помилки стиснення та декомпресії.

zlib.adler32(data[, value])

  Обчислює контрольну суму Adler-32 для даних. (Контрольна сума Adler-32 майже така ж надійна, як CRC32, але її можна обчислити набагато швидше.) Результатом є 32-розрядне ціле число без знаку. Якщо присутнє значення, воно використовується як початкове значення контрольної суми; інакше використовується значення за замовчуванням 1. Передача value дозволяє обчислити поточну контрольну суму для конкатенації кількох вхідних даних. Алгоритм не є криптографічно надійним, тому його не слід використовувати для автентифікації чи цифрових підписів. Оскільки алгоритм розроблено для використання як алгоритм контрольної суми, він не підходить для використання як загальний алгоритм хешування.

  Змінено в версії 3.0: The result is always unsigned.

zlib.adler32_combine(adler1, adler2, len2, /)

  Combine two Adler-32 checksums into one.

  Given the Adler-32 checksum adler1 of a sequence `A` and the Adler-32 checksum adler2 of a sequence `B` of length len2, return the Adler-32 checksum of `A` and `B` concatenated.

  This function is typically useful to combine Adler-32 checksums that were concurrently computed. To compute checksums sequentially, use `adler32()` with the running checksum as the `value` argument.

  Added in version 3.15.

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

  Compresses the bytes in data, returning a bytes object containing compressed data. level is an integer from `0` to `9` or `-1` controlling the level of compression; See `Z_BEST_SPEED` (`1`), `Z_BEST_COMPRESSION` (`9`), `Z_NO_COMPRESSION` (`0`), and the default, `Z_DEFAULT_COMPRESSION` (`-1`) for more information about these values.

  The wbits argument controls the size of the history buffer (or the «window size») used when compressing data, and whether a header and trailer is included in the output. It can take several ranges of values, defaulting to `15` (`MAX_WBITS`):

  - Від +9 до +15: логарифм розміру вікна за основою два, який коливається між 512 і 32768. Більші значення забезпечують краще стиснення за рахунок більшого використання пам’яті. Отриманий результат включатиме специфічний для zlib заголовок і трейлер.

  - Від −9 до −15: використовує абсолютне значення wbits як логарифм розміру вікна, водночас створюючи необроблений вихідний потік без заголовка чи контрольної суми в кінці.

  - Від +25 до +31 = 16 + (від 9 до 15): використовує молодші 4 біти значення як логарифм розміру вікна, в той час як базовий заголовок gzip і контрольну суму в кінці виводяться.

  Raises the `error` exception if any error occurs.

  Змінено в версії 3.6: level тепер можна використовувати як параметр ключового слова.

  Змінено в версії 3.11: The wbits parameter is now available to set window bits and compression type.

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

  Повертає об’єкт стиснення для стиснення потоків даних, які не вміщаються в пам’ять одразу.

  level is the compression level – an integer from `0` to `9` or `-1`. See `Z_BEST_SPEED` (`1`), `Z_BEST_COMPRESSION` (`9`), `Z_NO_COMPRESSION` (`0`), and the default, `Z_DEFAULT_COMPRESSION` (`-1`) for more information about these values.

  метод — це алгоритм стиснення. Наразі єдиним підтримуваним значенням є `DEFLATED`.

  The wbits parameter controls the size of the history buffer (or the «window size»), and what header and trailer format will be used. It has the same meaning as described for compress().

  Аргумент memLevel контролює обсяг пам’яті, який використовується для стану внутрішнього стиснення. Діапазон допустимих значень від «1» до «9». Вищі значення використовують більше пам’яті, але є швидшими та дають менший результат.

  strategy is used to tune the compression algorithm. Possible values are `Z_DEFAULT_STRATEGY`, `Z_FILTERED`, `Z_HUFFMAN_ONLY`, `Z_RLE` and `Z_FIXED`.

  zdict — це попередньо визначений словник стиснення. Це послідовність байтів (наприклад, об’єкт `bytes`), що містить підпослідовності, які, як очікується, часто траплятимуться в даних, які потрібно стиснути. Ті підпослідовності, які, як очікується, будуть найбільш поширеними, повинні бути в кінці словника.

  Змінено в версії 3.3: Додано підтримку параметра zdict і ключового слова.

zlib.crc32(data[, value])

  Обчислює контрольну суму CRC (перевірка циклічної надлишковості) даних. Результатом є 32-розрядне ціле число без знаку. Якщо присутнє значення, воно використовується як початкове значення контрольної суми; інакше використовується значення за замовчуванням 0. Передача value дозволяє обчислити поточну контрольну суму для конкатенації кількох вхідних даних. Алгоритм не є криптографічно надійним, тому його не слід використовувати для автентифікації чи цифрових підписів. Оскільки алгоритм розроблено для використання як алгоритм контрольної суми, він не підходить для використання як загальний алгоритм хешування.

  Змінено в версії 3.0: The result is always unsigned.

zlib.crc32_combine(crc1, crc2, len2, /)

  Combine two CRC-32 checksums into one.

  Given the CRC-32 checksum crc1 of a sequence `A` and the CRC-32 checksum crc2 of a sequence `B` of length len2, return the CRC-32 checksum of `A` and `B` concatenated.

  This function is typically useful to combine CRC-32 checksums that were concurrently computed. To compute checksums sequentially, use `crc32()` with the running checksum as the `value` argument.

  Added in version 3.15.

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

  Повертає об’єкт декомпресії, який буде використано для декомпресії потоків даних, які не вміщуються в пам’ять одразу.

  Параметр wbits керує розміром буфера історії (або «розміром вікна»), а також очікуваним форматом заголовка та трейлера. Він має те саме значення, що й описане для decompress().

  Параметр zdict визначає попередньо визначений словник стиснення. Якщо надано, це має бути той самий словник, який використовувався компресором, який створив дані, які потрібно розпакувати.

  Примітка

  Якщо zdict є змінним об’єктом (наприклад, `bytearray`), ви не повинні змінювати його вміст між викликом `decompressobj()` і першим викликом `decompress()` декомпресора. метод.

  Змінено в версії 3.3: Додано параметр zdict.

Об’єкти стиснення підтримують такі методи:

Compress.compress(data)

  Стискати data, повертаючи об’єкт bytes, що містить стислі дані принаймні для частини даних у data. Ці дані мають бути об’єднані з виводом, створеним будь-якими попередніми викликами методу `compress()`. Деякі вхідні дані можуть зберігатися у внутрішніх буферах для подальшої обробки.

Compress.flush([mode])

  All pending input is processed, and a bytes object containing the remaining compressed output is returned. mode can be selected from the constants `Z_NO_FLUSH`, `Z_PARTIAL_FLUSH`, `Z_SYNC_FLUSH`, `Z_FULL_FLUSH`, `Z_BLOCK`, or `Z_FINISH`, defaulting to `Z_FINISH`. Except `Z_FINISH`, all constants allow compressing further bytestrings of data, while `Z_FINISH` finishes the compressed stream and prevents compressing any more data. After calling `flush()` with mode set to `Z_FINISH`, the `compress()` method cannot be called again; the only realistic action is to delete the object.

Compress.copy()

  Повертає копію об’єкта стиснення. Це можна використовувати для ефективного стиснення набору даних, які мають спільний початковий префікс.

Змінено в версії 3.8: Додано підтримку `copy.copy()` і `copy.deepcopy()` для об’єктів стиснення.

Об’єкти декомпресії підтримують такі методи та атрибути:

Decompress.unused_data

  Об’єкт bytes, який містить будь-які байти після кінця стиснутих даних. Тобто це залишається `b""`, поки не стане доступним останній байт, який містить дані стиснення. Якщо виявилося, що весь байтовий рядок містить стислі дані, це `b""`, порожній об’єкт байтів.

Decompress.unconsumed_tail

  Об’єкт bytes, який містить будь-які дані, які не були використані останнім викликом `decompress()`, оскільки він перевищив обмеження для буфера нестиснутих даних. Ці дані ще не були розглянуті механізмом zlib, тому ви повинні передати їх (можливо, з додатковими даними, об’єднаними з ними) до наступного виклику методу `decompress()`, щоб отримати правильний результат.

Decompress.eof

  Логічне значення, яке вказує, чи досягнуто кінця стисненого потоку даних.

  This makes it possible to distinguish between a properly formed compressed stream, and an incomplete or truncated one.

  Added in version 3.3.

Decompress.decompress(data, max_length=0)

  Розпакуйте data, повертаючи об’єкт bytes, що містить нестиснуті дані, що відповідають принаймні частині даних у string. Ці дані мають бути об’єднані з виводом, створеним будь-якими попередніми викликами методу `decompress()`. Деякі вхідні дані можуть бути збережені у внутрішніх буферах для подальшої обробки.

  If the optional parameter max_length is non-zero then the return value will be no longer than max_length. This may mean that not all of the compressed input can be processed; and unconsumed data will be stored in the attribute `unconsumed_tail`. This bytestring must be passed to a subsequent call to `decompress()` if decompression is to continue. If max_length is zero then the whole input is decompressed, and `unconsumed_tail` is empty. For example, the full content could be read like:

      process_output(d.decompress(data, max_length))
      while chunk := d.decompress(d.unconsumed_tail, max_length):
          process_output(chunk)

  Змінено в версії 3.6: max_length можна використовувати як аргумент ключового слова.

Decompress.flush([length])

  Усі вхідні дані, що очікують на розгляд, обробляються, і повертається об’єкт bytes, що містить залишковий нестиснутий вихід. Після виклику `flush()` метод `decompress()` не можна викликати знову; єдина реалістична дія - це видалити об’єкт.

  Додатковий параметр length встановлює початковий розмір вихідного буфера.

Decompress.copy()

  Повертає копію розпакованого об’єкта. Це можна використовувати для збереження стану декомпресора в середині потоку даних, щоб пришвидшити випадковий пошук у потоці в майбутньому.

Змінено в версії 3.8: Додано підтримку `copy.copy()` і `copy.deepcopy()` для об’єктів декомпресії.

The following constants are available to configure compression and decompression behavior:

zlib.DEFLATED

  The deflate compression method.

zlib.MAX_WBITS

  The maximum window size, expressed as a power of 2. For example, if `MAX_WBITS` is `15` it results in a window size of `32 KiB`.

zlib.DEF_MEM_LEVEL

  The default memory level for compression objects.

zlib.DEF_BUF_SIZE

  The default buffer size for decompression operations.

zlib.Z_NO_COMPRESSION

  Compression level `0`; no compression.

  Added in version 3.6.

zlib.Z_BEST_SPEED

  Compression level `1`; fastest and produces the least compression.

zlib.Z_BEST_COMPRESSION

  Compression level `9`; slowest and produces the most compression.

zlib.Z_DEFAULT_COMPRESSION

  Default compression level (`-1`); a compromise between speed and compression. Currently equivalent to compression level `6`.

zlib.Z_DEFAULT_STRATEGY

  Default compression strategy, for normal data.

zlib.Z_FILTERED

  Compression strategy for data produced by a filter (or predictor).

zlib.Z_HUFFMAN_ONLY

  Compression strategy that forces Huffman coding only.

zlib.Z_RLE

  Compression strategy that limits match distances to one (run-length encoding).

  This constant is only available if Python was compiled with zlib 1.2.0.1 or greater.

  Added in version 3.6.

zlib.Z_FIXED

  Compression strategy that prevents the use of dynamic Huffman codes.

  This constant is only available if Python was compiled with zlib 1.2.2.2 or greater.

  Added in version 3.6.

zlib.Z_NO_FLUSH

  Flush mode `0`. No special flushing behavior.

  Added in version 3.6.

zlib.Z_PARTIAL_FLUSH

  Flush mode `1`. Flush as much output as possible.

zlib.Z_SYNC_FLUSH

  Flush mode `2`. All output is flushed and the output is aligned to a byte boundary.

zlib.Z_FULL_FLUSH

  Flush mode `3`. All output is flushed and the compression state is reset.

zlib.Z_FINISH

  Flush mode `4`. All pending input is processed, no more input is expected.

zlib.Z_BLOCK

  Flush mode `5`. A deflate block is completed and emitted.

  This constant is only available if Python was compiled with zlib 1.2.2.2 or greater.

  Added in version 3.6.

zlib.Z_TREES

  Flush mode `6`, for inflate operations. Instructs inflate to return when it gets to the next deflate block boundary.

  This constant is only available if Python was compiled with zlib 1.2.3.4 or greater.

  Added in version 3.6.

Інформація про версію використовуваної бібліотеки zlib доступна через такі константи:

zlib.ZLIB_VERSION

  Рядок версії бібліотеки zlib, який використовувався для створення модуля. Це може відрізнятися від бібліотеки zlib, яка фактично використовується під час виконання, яка доступна як `ZLIB_RUNTIME_VERSION`.

zlib.ZLIB_RUNTIME_VERSION

  Рядок версії бібліотеки zlib, фактично завантажений інтерпретатором.

  Added in version 3.3.

zlib.ZLIBNG_VERSION

  The version string of the zlib-ng library that was used for building the module if zlib-ng was used. When present, the `ZLIB_VERSION` and `ZLIB_RUNTIME_VERSION` constants reflect the version of the zlib API provided by zlib-ng.

  If zlib-ng was not used to build the module, this constant will be absent.

  Added in version 3.14.

Дивись також

Модуль `gzip`

  Читання та запис файлів у форматі gzip.

https://www.zlib.net

  Домашня сторінка бібліотеки zlib.

https://www.zlib.net/manual.html

  У посібнику з zlib пояснюється семантика та використання багатьох функцій бібліотеки.

In case gzip (de)compression is a bottleneck, the python-isal package speeds up (de)compression with a mostly compatible API.