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

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

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 и filters имеют те же значения, что и для LZMADecompressor. В этом случае аргументы check и preset использовать не следует.

При открытии файла для записи аргументы 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: Принимает объект, подобный пути.

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

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-разрядный алгоритм безопасного хеширования.

Если указанная проверка не поддерживается, возникает исключение 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 (объект типа bytes-like) и возвращает распакованные данные в виде байтов. Часть 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.

Разное

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.

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

• 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.

Примеры

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

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