# `zlib` — Compression compatible with gzip

Для програм, які вимагають стиснення даних, функції цього модуля дозволяють стискати та розпаковувати за допомогою бібліотеки zlib. Бібліотека zlib має власну домашню сторінку за адресою https://www.zlib.net. Відомі несумісності між модулем Python і версіями бібліотеки zlib, ранішими за 1.1.3; 1.1.3 має вразливість безпеки, тому ми рекомендуємо використовувати 1.1.4 або новішу версію.

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.compress(data, /, level=-1, 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; `1` (Z_BEST_SPEED) is fastest and produces the least compression, `9` (Z_BEST_COMPRESSION) is slowest and produces the most. `0` (Z_NO_COMPRESSION) is no compression. The default value is `-1` (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION represents a default compromise between speed and compression (currently equivalent to level 6).

  Аргумент wbits контролює розмір буфера історії (або «розмір вікна»), який використовується під час стиснення даних, а також те, чи включено заголовок і трейлер у вивід. Він може приймати кілька діапазонів значень, за замовчуванням `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=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

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

  level — це рівень стиснення – ціле число від `0` до `9` або `-1`. Значення «1» (Z_BEST_SPEED) є найшвидшим і забезпечує найменше стиснення, тоді як значення «9» (Z_BEST_COMPRESSION) є найповільнішим і забезпечує найбільше. `0` (Z_NO_COMPRESSION) не стискає. Значення за замовчуванням – `-1` (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION представляє стандартний компроміс між швидкістю та стисненням (на даний момент еквівалентно рівню 6).

  метод — це алгоритм стиснення. Наразі єдиним підтримуваним значенням є `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». Вищі значення використовують більше пам’яті, але є швидшими та дають менший результат.

  стратегія використовується для налаштування алгоритму стиснення. Можливі значення: `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 (перевірка циклічної надлишковості) даних. Результатом є 32-розрядне ціле число без знаку. Якщо присутнє значення, воно використовується як початкове значення контрольної суми; інакше використовується значення за замовчуванням 0. Передача value дозволяє обчислити поточну контрольну суму для конкатенації кількох вхідних даних. Алгоритм не є криптографічно надійним, тому його не слід використовувати для автентифікації чи цифрових підписів. Оскільки алгоритм розроблено для використання як алгоритм контрольної суми, він не підходить для використання як загальний алгоритм хешування.

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

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

  Усі вхідні дані, що очікують на розгляд, обробляються, і повертається об’єкт bytes, що містить залишковий стиснутий вихід. режим можна вибрати з констант `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()` з mode, встановленим на `Z_FINISH`, метод `compress()` не можна викликати повторно; єдина реалістична дія - це видалити об’єкт.

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()`. Деякі вхідні дані можуть бути збережені у внутрішніх буферах для подальшої обробки.

  Якщо необов’язковий параметр max_length відмінний від нуля, тоді повернуте значення не буде довшим за max_length. Це може означати, що не весь стиснутий вхід може бути оброблений; а неспожиті дані зберігатимуться в атрибуті `unconsumed_tail`. Цей байтовий рядок необхідно передати наступному виклику `decompress()`, якщо розпакування має продовжуватися. Якщо max_length дорівнює нулю, то весь вхід розпаковується, а `unconsumed_tail` порожній.

  Змінено в версії 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`.

  Added in version 3.6.

zlib.Z_BEST_SPEED

  Compression level `1`.

zlib.Z_BEST_COMPRESSION

  Compression level `9`.

zlib.Z_DEFAULT_COMPRESSION

  Default compression level (`-1`).

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.