zlib — Compression compatible with gzip

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

Функції zlib мають багато параметрів і часто їх потрібно використовувати в певному порядку. Ця документація не намагається охопити всі перестановки; зверніться до посібника з zlib на http://www.zlib.net/manual.html для отримання достовірної інформації.

Для читання та запису файлів .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.

Нове в версії 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() для об’єктів декомпресії.

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

zlib.ZLIB_VERSION

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

zlib.ZLIB_RUNTIME_VERSION

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

Нове в версії 3.3.

Дивись також

Модуль gzip

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

http://www.zlib.net

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

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

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