lzma — Сжатие с использованием алгоритма LZMA

Добавлена в версии 3.3.

Исходный код: Lib/lzma.py

Этот модуль предоставляет классы и удобные функции для сжатия и распаковки данных с использованием алгоритма сжатия LZMA. Также включен интерфейс для работы с файлами, поддерживающий форматы файлов .xz и устаревший .lzma используемые утилитой xz, а также сырые сжатые потоки.

Интерфейс, предоставляемый этим модулем, очень похож на интерфейс модуля bz2. Однако обратите внимание, что LZMAFile не является потокобезопасным, в отличие от bz2.BZ2File, поэтому если вам нужно использовать один экземпляр LZMAFile из нескольких потоков, необходимо защитить его с помощью блокировки.

exception lzma.LZMAError: Это исключение возникает при возникновении ошибки во время сжатия или распаковки или при инициализации состояния сжимающего/распаковывающего модуля.

13.4.1. Чтение и запись сжатых файлов

lzma.open(filename, mode="rb", *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)

Открыть LZMA-сжатый файл в двоичном или текстовом режиме, возвращая объект файла.

Аргумент filename может быть либо именем файла (переданным как str, bytes или объект-путь), в этом случае открывается указанный файл, или это может быть существующий объект файла для чтения или записи.

Аргумент 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: Принимает объект-путь.

class lzma.LZMAFile(filename=None, mode="r", *, format=None, check=-1, preset=None, filters=None)

Открыть LZMA-сжатый файл в двоичном режиме.

Объект LZMAFile может обернуть уже открытый объект файла, или работать напрямую с файлом. Аргумент filename указывает либо объект файла для обертывания, либо имя файла для открытия (как str, bytes или объект-путь). При обертывании существующего объекта файла, обернутый файл не будет закрыт при закрытии LZMAFile.

Аргумент mode может принимать значения "r" для чтения (по умолчанию), "w" для перезаписи, "x" для эксклюзивного создания или "a" для добавления. Эти значения могут быть заданы эквивалентно как "rb", "wb", "xb" и "ab" соответственно.

Если filename является объектом файла (а не фактическим именем файла), режим "w" не обрезает файл и вместо этого эквивалентен режиму "a".

При открытии файла для чтения, входной файл может быть конкатенацией нескольких отдельных сжатых потоков. Они прозрачно декодируются как один логический поток.

При открытии файла для записи, аргументы format, check, preset и filters имеют то же значение, что и для LZMACompressor.

LZMAFile поддерживает все члены, указанные в io.BufferedIOBase, за исключением detach() и truncate(). Поддерживаются итерация и оператор with.

Также предоставляется следующий метод:

peek(size=-1): Возвращает буферизованные данные без продвижения позиции файла. Будет возвращено как минимум один байт данных, если не достигнут конец файла. Точное количество возвращённых байтов не определено (аргумент size игнорируется).

Примечание

Хотя вызов peek() не изменяет позицию файла объекта LZMAFile, он может изменить позицию базового объекта файла (например, если LZMAFile был создан путём передачи объекта файла для filename).

Изменено в версии 3.4: Добавлена поддержка режимов "x" и "xb".

Изменено в версии 3.5: Метод read() теперь принимает аргумент None.

Изменено в версии 3.6: Принимает объект-путь.

13.4.2. Сжатие и распаковка данных в памяти

class lzma.LZMACompressor(format=FORMAT_XZ, check=-1, preset=None, filters=None)

Создайте объект сжатия, который можно использовать для поэтапного сжатия данных.

Для более удобного способа сжатия одного блока данных см. compress().

Аргумент format указывает, какой формат контейнера следует использовать. Возможные значения:

FORMAT_XZ: The .xz container format.

Это формат по умолчанию.
FORMAT_ALONE: The legacy .lzma container format.

Этот формат ограничен по сравнению с .xz — он не поддерживает проверки целостности или несколько фильтров.
FORMAT_RAW: A raw data stream, not using any container format.

Этот формат не поддерживает проверки целостности и требует, чтобы вы всегда указывали пользовательскую цепочку фильтров (как для сжатия, так и для разархивирования). Кроме того, данные, сжатые таким образом, не могут быть разархивированы с помощью FORMAT_AUTO (см. LZMADecompressor).

Аргумент check указывает тип проверки целостности, который следует включить в сжатые данные. Эта проверка используется при разархивировании, чтобы убедиться, что данные не повреждены. Возможные значения:

CHECK_NONE: Нет проверки целостности. Это значение по умолчанию (и единственное допустимое значение) для FORMAT_ALONE и FORMAT_RAW.
CHECK_CRC32: 32-битная проверка циклического избыточного кода.
CHECK_CRC64: 64-битная проверка циклического избыточного кода. Это значение по умолчанию для FORMAT_XZ.
CHECK_SHA256: 256-битный алгоритм хэширования Secure Hash.

Если указанная проверка не поддерживается, возникает LZMAError.

Настройки сжатия можно указать либо как предопределенный уровень сжатия (с аргументом preset), либо подробно, как пользовательскую цепочку фильтров (с аргументом filters).

Аргумент preset (если указан) должен быть целым числом от 0 до 9 (включительно), необязательно с использованием константы PRESET_EXTREME. Если ни preset, ни filters не указаны, используется поведение по умолчанию с использованием PRESET_DEFAULT (уровень предварительной настройки 6). Более высокие уровни предварительной настройки дают меньший выходной объем, но замедляют процесс сжатия.

Примечание

Помимо большей интенсивности использования ЦП, сжатие с более высокими уровнями предварительной настройки также требует больше памяти (и производит выходные данные, для разархивирования которых требуется больше памяти). Например, с предварительной настройкой 9 издержки объекта LZMACompressor могут достигать 800 МБ. По этой причине обычно лучше придерживаться значения по умолчанию.

Аргумент filters (если указан) должен быть указателем на цепочку фильтров. Подробности см. в Указание пользовательских цепочек фильтров.

compress(data): Сжимает data (объект bytes), возвращая объект bytes со сжатыми данными, по крайней мере, для части входных данных. Часть data может буферизоваться внутри, для использования в последующих вызовах compress() и flush(). Возвращаемые данные должны быть объединены с результатами предыдущих вызовов compress().

flush()

Завершает процесс сжатия, возвращая объект bytes с любыми данными, хранящимися в буферах внутри сжимающего объекта.

После вызова этого метода сжимающий объект использовать нельзя.

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)

Разархивирует data (объект объект-подобный байтам), возвращая разархивированные данные в виде байтов. Часть data может буферизоваться внутри, для использования в последующих вызовах decompress(). Возвращаемые данные должны быть объединены с результатами предыдущих вызовов decompress().

Если max_length неотрицательно, возвращает не более max_length байтов разархивированных данных. Если этот лимит достигнут, а дальнейший вывод возможен, атрибут needs_input будет установлен в False. В этом случае следующий вызов decompress() может принять data в качестве b'' для получения большего количества вывода.

Если все входные данные были разархивированы и возвращены (либо потому, что это было меньше max_length байтов, либо потому, что max_length было отрицательным), атрибут needs_input будет установлен в True.

Попытка разархивировать данные после достижения конца потока приводит к EOFError. Любые данные, обнаруженные после конца потока, игнорируются и сохраняются в атрибуте unused_data.

Изменено в версии 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.

Описание аргументов format, check, preset и filters см. выше в LZMACompressor.

lzma.decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None)

Разархивирует data (объект bytes), возвращая разархивированные данные в виде объекта bytes.

Если data представляет собой конкатенацию нескольких отдельных сжатых потоков, разархивируются все потоки, и возвращается конкатенация результатов.

Описание аргументов format, memlimit и filters см. выше в LZMADecompressor.

13.4.3. Разное

lzma.is_check_supported(check)

Возвращает true, если данный контроль целостности поддерживается в данной системе.

CHECK_NONE и CHECK_CRC32 всегда поддерживаются. CHECK_CRC64 и CHECK_SHA256 могут быть недоступны, если вы используете версию liblzma, скомпилированную с ограниченным набором функций.

13.4.4. Определение пользовательских цепочек фильтров

Спецификатор цепочки фильтров представляет собой последовательность словарей, где каждый словарь содержит идентификатор и параметры для одного фильтра. Каждый словарь должен содержать ключ "id", и может содержать дополнительные ключи для указания параметров, зависящих от фильтра. Допустимые идентификаторы фильтров следующие:

Фильтры сжатия:
- FILTER_LZMA1 (для использования с FORMAT_ALONE)
- FILTER_LZMA2 (для использования с FORMAT_XZ и FORMAT_RAW)
Фильтр разности:
- FILTER_DELTA
Фильтры BCJ (Branch-Call-Jump):
- FILTER_X86
- FILTER_IA64
- FILTER_ARM
- FILTER_ARMTHUMB
- FILTER_POWERPC
- FILTER_SPARC

Цепочка фильтров может состоять из не более чем 4 фильтров и не может быть пустой. Последний фильтр в цепочке должен быть фильтром сжатия, а все остальные — фильтрами разности или BCJ.

Фильтры сжатия поддерживают следующие параметры (указанные как дополнительные записи в словаре, представляющем фильтр):

preset: Набор параметров сжатия для использования в качестве источника значений по умолчанию для параметров, которые не указаны явно.
dict_size: Размер словаря в байтах. Он должен быть между 4 КБ и 1,5 ГБ (включительно).
lc: Количество битов контекста литералов.
lp: Количество битов позиции литералов. Сумма lc + lp должна быть не более 4.
pb: Количество битов позиции; должно быть не более 4.
mode: 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.

13.4.5. Примеры

Чтение сжатого файла:

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