lzma
— Compression using the LZMA algorithm¶
Нове в версії 3.3.
Вихідний код: Lib/lzma.py
Цей модуль надає класи та зручні функції для стиснення та розпакування даних за допомогою алгоритму стиснення LZMA. Також включено файловий інтерфейс, що підтримує формати файлів .xz
і застарілі .lzma
, які використовуються утилітою xz, а також необроблені стиснені потоки.
The interface provided by this module is very similar to that of the bz2
module. However, note that LZMAFile
is not thread-safe, unlike
bz2.BZ2File
, so if you need to use a single LZMAFile
instance
from multiple threads, it is necessary to protect it with a lock.
-
exception
lzma.
LZMAError
¶ Цей виняток виникає, коли виникає помилка під час стиснення чи розпакування або під час ініціалізації стану компресора/декомпресора.
Читання та запис стиснутих файлів¶
-
lzma.
open
(filename, mode="rb", *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)¶ Відкрийте файл, стиснутий за допомогою LZMA, у двійковому або текстовому режимі, повертаючи file object.
Аргументом filename може бути або фактичне ім’я файлу (надане як об’єкт
str
,bytes
або path-like), у такому випадку відкривається названий файл або це може бути існуючий файловий об’єкт для читання або запису.Аргумент mode може бути будь-яким із
"r"
,"rb"
,"w"
,"wb"
,"x"
,"xb"
,"a"
або"ab"
для двійкового режиму, або"rt"
,"wt"
,"xt"
або"at"
для текстового режиму. Типовим є"rb"
.Під час відкриття файлу для читання аргументи format і filters мають такі ж значення, як і для
LZMADecompressor
. У цьому випадку аргументи check і preset не повинні використовуватися.Під час відкриття файлу для запису аргументи format, check, preset і filters мають таке ж значення, як і для
LZMACompressor
.Для бінарного режиму ця функція еквівалентна конструктору
LZMAFile
:LZMAFile(filename, mode, ...)
. У цьому випадку аргументи encoding, errors і newline не повинні надаватися.Для текстового режиму створюється об’єкт
LZMAFile
, який загортається в екземплярio.TextIOWrapper
із вказаним кодуванням, поведінкою обробки помилок і закінченнями рядків.Змінено в версії 3.4: Додано підтримку режимів
"x"
,"xb"
і"xt"
.Змінено в версії 3.6: Приймає path-like object.
-
class
lzma.
LZMAFile
(filename=None, mode="r", *, format=None, check=-1, preset=None, filters=None)¶ Відкрийте файл, стиснутий за допомогою LZMA, у двійковому режимі.
LZMAFile
може обернути вже відкритий file object або працювати безпосередньо з іменованим файлом. Аргумент filename визначає або об’єкт файлу, який потрібно обернути, або ім’я файлу, який потрібно відкрити (як об’єктstr
,bytes
або path-like). Під час обгортання існуючого файлового об’єкта обернутий файл не буде закрито, коли закритоLZMAFile
.Аргументом mode може бути
"r"
для читання (за замовчуванням),"w"
для перезапису,"x"
для ексклюзивного створення або"a"
для додавання. Їх можна еквівалентно подати як"rb"
,"wb"
,"xb"
і"ab"
відповідно.Якщо filename є файловим об’єктом (а не справжнім ім’ям файлу), режим
"w"
не скорочує файл, а замість цього еквівалентний"a"
.Під час відкриття файлу для читання вхідний файл може бути конкатенацією кількох окремих стиснутих потоків. Вони прозоро декодуються як єдиний логічний потік.
Під час відкриття файлу для читання аргументи format і filters мають такі ж значення, як і для
LZMADecompressor
. У цьому випадку аргументи check і preset не повинні використовуватися.Під час відкриття файлу для запису аргументи format, check, preset і filters мають таке ж значення, як і для
LZMACompressor
.LZMAFile
supports all the members specified byio.BufferedIOBase
, except fordetach()
andtruncate()
. Iteration and thewith
statement are supported.The following method is also provided:
-
peek
(size=-1)¶ Повернути буферизовані дані без просування позиції файлу. Принаймні один байт даних буде повернуто, якщо не досягнуто EOF. Точна кількість повернутих байтів не вказана (аргумент size ігнорується).
Змінено в версії 3.4: Додано підтримку режимів
"x"
і"xb"
.Змінено в версії 3.5: Метод
read()
тепер приймає аргументNone
.Змінено в версії 3.6: Приймає path-like object.
-
Стиснення та розпакування даних у пам’яті¶
-
class
lzma.
LZMACompressor
(format=FORMAT_XZ, check=-1, preset=None, filters=None)¶ Створіть об’єкт компресора, який можна використовувати для поступового стиснення даних.
Для більш зручного способу стиснення окремої частини даних див.
compress()
.Аргумент format визначає, який формат контейнера слід використовувати. Можливі значення:
FORMAT_XZ
: Формат контейнера.xz
.Це стандартний формат.
FORMAT_ALONE
: Застарілий формат контейнера.lzma
.Цей формат є більш обмеженим, ніж
.xz
- він не підтримує перевірку цілісності або кілька фільтрів.
FORMAT_RAW
: Потік необроблених даних без використання формату контейнера.Цей специфікатор формату не підтримує перевірки цілісності та вимагає, щоб ви завжди вказували настроюваний ланцюжок фільтрів (як для стиснення, так і для розпакування). Крім того, дані, стиснуті таким чином, не можна розпакувати за допомогою
FORMAT_AUTO
(див.LZMADecompressor
).
Аргумент check визначає тип перевірки цілісності, який слід включити до стиснутих даних. Ця перевірка використовується під час розпакування, щоб переконатися, що дані не пошкоджено. Можливі значення:
CHECK_NONE
: Без перевірки цілісності. Це стандартне (і єдине прийнятне значення) дляFORMAT_ALONE
іFORMAT_RAW
.CHECK_CRC32
: 32-розрядна циклічна перевірка надмірності.CHECK_CRC64
: 64-бітна циклічна перевірка надмірності. Це типове значення дляFORMAT_XZ
.CHECK_SHA256
: 256-бітний безпечний алгоритм хешування.
Якщо зазначена перевірка не підтримується, виникає
LZMAError
.Параметри стиснення можна вказати або як попередньо встановлений рівень стиснення (за допомогою аргументу preset), або детально як спеціальний ланцюжок фільтрів (за допомогою аргументу filters).
Аргумент preset (якщо надано) має бути цілим числом від
0
до9
(включно), необов’язково через АБО з константоюPRESET_EXTREME
. Якщо ні попереднє налаштування, ні фільтри не вказано, поведінка за замовчуванням полягає у використанніPRESET_DEFAULT
(рівень попереднього налаштування6
). Більш високі налаштування дають менший вихід, але сповільнюють процес стиснення.Примітка
Окрім того, що стиснення з вищими попередніми настройками вимагає більшого навантаження на ЦП, воно також потребує набагато більше пам’яті (і створює вивід, для розпакування якого потрібно більше пам’яті). Наприклад, із заданим значенням
9
накладні витрати для об’єктаLZMACompressor
можуть сягати 800 МіБ. З цієї причини, як правило, краще дотримуватися попереднього налаштування за замовчуванням.Аргумент filters (якщо надається) має бути специфікатором ланцюжка фільтрів. Дивіться Визначення власних ланцюжків фільтрів для деталей.
-
compress
(data)¶ Стиснути дані (об’єкт
bytes
), повертаючи об’єктbytes
, що містить стислі дані принаймні для частини вхідних даних. Деякі з даних можуть буферизуватися усередині для використання в наступних викликахcompress()
іflush()
. Повернуті дані мають бути об’єднані з результатами будь-яких попередніх викликівcompress()
.
-
class
lzma.
LZMADecompressor
(format=FORMAT_AUTO, memlimit=None, filters=None)¶ Створіть об’єкт декомпресії, який можна використовувати для поступового розпакування даних.
Для більш зручного способу розпакування всього стисненого потоку одночасно див.
decompress()
.Аргумент format визначає формат контейнера, який слід використовувати. Типовим є
FORMAT_AUTO
, який може розпакувати як файли.xz
, так і.lzma
. Інші можливі значення:FORMAT_XZ
,FORMAT_ALONE
іFORMAT_RAW
.Аргумент memlimit визначає обмеження (у байтах) на обсяг пам’яті, який може використовувати розпаковувач. Коли цей аргумент використовується, декомпресія буде невдалою з
LZMAError
, якщо неможливо розпакувати вхідні дані в межах заданого ліміту пам’яті.Аргумент filters визначає ланцюжок фільтрів, який використовувався для створення потоку, що розпаковується. Цей аргумент є обов’язковим, якщо format має значення
FORMAT_RAW
, але його не слід використовувати для інших форматів. Перегляньте Визначення власних ланцюжків фільтрів для отримання додаткової інформації про ланцюги фільтрів.Примітка
Цей клас не обробляє прозоро вхідні дані, що містять кілька стиснутих потоків, на відміну від
decompress()
іLZMAFile
. Щоб розпакувати багатопотоковий вхід за допомогоюLZMADecompressor
, ви повинні створити новий розпаковувач для кожного потоку.-
decompress
(data, max_length=-1)¶ Розпакуйте дані (bytes-like object), повертаючи нестиснуті дані у вигляді байтів. Деякі з даних можуть бути збережені у внутрішньому буфері для використання в подальших викликах
decompress()
. Повернуті дані мають бути об’єднані з результатами будь-яких попередніх викликівdecompress()
.Якщо max_length є невід’ємним, повертає щонайбільше max_length байтів розпакованих даних. Якщо цей ліміт буде досягнуто, і буде створено подальший вихід, атрибут
needs_input
буде встановлено наFalse
. У цьому випадку наступний викликdecompress()
може надати data якb''
, щоб отримати більше вихідних даних.Якщо всі вхідні дані було розпаковано та повернуто (або через те, що вони були меншими за max_length байтів, або через те, що max_length було від’ємним), для атрибута
needs_input
буде встановлено значенняTrue
.Attempting to decompress data after the end of stream is reached raises an EOFError. Any data found after the end of the stream is ignored and saved in the
unused_data
attribute.Змінено в версії 3.5: Додано параметр max_length.
-
check
¶ Ідентифікатор перевірки цілісності, який використовується вхідним потоком. Це може бути
CHECK_UNKNOWN
, поки не буде декодовано достатньо вхідних даних, щоб визначити, яку перевірку цілісності він використовує.
-
eof
¶ True
, якщо досягнуто маркера кінця потоку.
-
unused_data
¶ Дані знайдено після закінчення стисненого потоку.
До кінця потоку це буде
b""
.
-
needs_input
¶ False
, якщо методdecompress()
може надати більше розпакованих даних перед запитом нового нестисненого введення.Нове в версії 3.5.
-
-
lzma.
compress
(data, format=FORMAT_XZ, check=-1, preset=None, filters=None)¶ Стискати data (об’єкт
bytes
), повертаючи стислі дані як об’єктbytes
.Перегляньте
LZMACompressor
вище для опису аргументів format, check, preset і filters.
-
lzma.
decompress
(data, format=FORMAT_AUTO, memlimit=None, filters=None)¶ Розархівуйте data (об’єкт
bytes
), повертаючи нестиснуті дані як об’єктbytes
.Якщо data є конкатенацією кількох окремих стиснутих потоків, розпакуйте всі ці потоки та поверніть конкатенацію результатів.
Перегляньте
LZMADecompressor
вище для опису аргументів format, memlimit і filters.
Різне¶
-
lzma.
is_check_supported
(check)¶ Повертає
True
, якщо ця перевірка цілісності підтримується цією системою.CHECK_NONE
іCHECK_CRC32
підтримуються завжди.CHECK_CRC64
іCHECK_SHA256
можуть бути недоступні, якщо ви використовуєте версію liblzma, яка була скомпільована з обмеженим набором функцій.
Визначення власних ланцюжків фільтрів¶
Специфікатор ланцюжка фільтрів — це послідовність словників, де кожен словник містить ідентифікатор і параметри для одного фільтра. Кожен словник має містити ключ "id"
і може містити додаткові ключі для визначення залежних від фільтрів параметрів. Дійсні ідентифікатори фільтрів:
- Компресійні фільтри:
FILTER_LZMA1
(для використання зFORMAT_ALONE
)FILTER_LZMA2
(для використання зFORMAT_XZ
іFORMAT_RAW
)
- Дельта-фільтр:
FILTER_DELTA
- Фільтри Branch-Call-Jump (BCJ):
FILTER_X86
FILTER_IA64
FILTER_ARM
FILTER_ARMTHUMB
FILTER_POWERPC
FILTER_SPARC
Ланцюг фільтрів може складатися з 4 фільтрів і не може бути порожнім. Останній фільтр у ланцюжку має бути фільтром стиснення, а будь-які інші фільтри мають бути фільтрами дельта або BCJ.
Фільтри стиснення підтримують такі параметри (зазначені як додаткові записи в словнику, що представляє фільтр):
попереднє налаштування
: Попереднє налаштування стиснення, яке використовується як джерело значень за замовчуванням для параметрів, які не вказані явно.
dict_size
: розмір словника в байтах. Це має бути від 4 КіБ до 1,5 ГіБ (включно).
lc
: кількість літеральних бітів контексту.
lp
: кількість літеральних бітів позиції. Сума «lc + lp» має бути не більше 4.
pb
: кількість бітів позиції; повинно бути не більше 4.
режим
:MODE_FAST
абоMODE_NORMAL
.
nice_len
: що слід вважати «гарною довжиною» для збігу. Це має бути 273 або менше.
mf
: Який засіб пошуку збігів використовувати –MF_HC3
,MF_HC4
,MF_BT2
,MF_BT3
абоMF_BT4
.
depth
: максимальна глибина пошуку, яка використовується шукачем збігів. 0 (за замовчуванням) означає автоматичний вибір на основі інших параметрів фільтра.
Дельта-фільтр зберігає відмінності між байтами, створюючи більш повторювані вхідні дані для компресора за певних обставин. Він підтримує один параметр, dist
. Це вказує на відстань між байтами, які потрібно відняти. За замовчуванням 1, тобто беруться різниці між сусідніми байтами.
Фільтри BCJ призначені для застосування до машинного коду. Вони перетворюють відносні розгалуження, виклики та переходи в коді на використання абсолютної адресації з метою збільшення надмірності, яку може використовувати компресор. Ці фільтри підтримують один параметр, start_offset
. Це вказує адресу, яку слід відобразити на початку вхідних даних. За замовчуванням 0.
Приклади¶
Читання у стисненому файлі:
import lzma
with lzma.open("file.xz") as f:
file_content = f.read()
Створення стисненого файлу:
import lzma
data = b"Insert Data Here"
with lzma.open("file.xz", "w") as f:
f.write(data)
Стиснення даних у пам’яті:
import lzma
data_in = b"Insert Data Here"
data_out = lzma.compress(data_in)
Поступове стиснення:
import lzma
lzc = lzma.LZMACompressor()
out1 = lzc.compress(b"Some data\n")
out2 = lzc.compress(b"Another piece of data\n")
out3 = lzc.compress(b"Even more data\n")
out4 = lzc.flush()
# Concatenate all the partial results:
result = b"".join([out1, out2, out3, out4])
Запис стислих даних у вже відкритий файл:
import lzma
with open("file.xz", "wb") as f:
f.write(b"This data will not be compressed\n")
with lzma.open(f, "w") as lzf:
lzf.write(b"This *will* be compressed\n")
f.write(b"Not compressed\n")
Створення стисненого файлу за допомогою спеціального ланцюжка фільтрів:
import lzma
my_filters = [
{"id": lzma.FILTER_DELTA, "dist": 5},
{"id": lzma.FILTER_LZMA2, "preset": 7 | lzma.PRESET_EXTREME},
]
with lzma.open("file.xz", "w", filters=my_filters) as f:
f.write(b"blah blah blah")