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

mode

'rb' для чтения и 'wb' для записи.

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

name

Имя файла lzma. Эквивалентно атрибуту name базового файлового объекта.

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

Изменено в версии 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 включительно, при необходимости объединённым оператором OR с константой 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) и возвращает распакованные данные в виде байтов. Часть 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")