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 (по умолчанию), FORMAT_ALONE и FORMAT_RAW.

Аргумент check задаёт тип проверки целостности, включаемой в сжатые данные. Эта проверка используется при распаковке, чтобы убедиться, что данные не были повреждены. Возможные значения: CHECK_NONE, CHECK_CRC32, CHECK_CRC64 (по умолчанию для FORMAT_XZ) и CHECK_SHA256.

Если указанная проверка не поддерживается, возникает исключение 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.

Константы

Следующие константы уровня модуля предназначены для использования в качестве аргументов format, check, preset и filters классов и функций, описанных выше.

Форматы контейнеров:

lzma.FORMAT_XZ

Формат контейнера .xz.

lzma.FORMAT_ALONE

Устаревший формат контейнера .lzma. Этот формат более ограничен, чем .xz: он не поддерживает проверки целостности и несколько фильтров.

lzma.FORMAT_RAW

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

lzma.FORMAT_AUTO

Используется только для распаковки. Формат контейнера определяется автоматически, поэтому можно распаковывать файлы как .xz, так и .lzma.

Проверки целостности:

lzma.CHECK_NONE

Без проверки целостности. Это значение используется по умолчанию (и является единственным допустимым) для FORMAT_ALONE и FORMAT_RAW.

lzma.CHECK_CRC32

32-разрядная циклическая проверка избыточности.

lzma.CHECK_CRC64

64-разрядная циклическая проверка избыточности. Используется по умолчанию для FORMAT_XZ.

lzma.CHECK_SHA256

256-разрядный алгоритм безопасного хеширования.

lzma.CHECK_UNKNOWN

Проверку целостности, используемую потоком, пока не удалось определить. Это значение может иметь атрибут LZMADecompressor.check, пока не будет декодировано достаточно данных.

lzma.CHECK_ID_MAX

Наибольший поддерживаемый идентификатор проверки целостности.

Предустановки сжатия:

lzma.PRESET_DEFAULT

Предустановка сжатия по умолчанию, эквивалентная уровню предустановки 6.

lzma.PRESET_EXTREME

Флаг, который можно объединить побитовой операцией ИЛИ с уровнем предустановки (от 0 до 9), чтобы выбрать более медленный, но более тщательный вариант этой предустановки.

Идентификаторы и параметры фильтров:

lzma.FILTER_LZMA1

lzma.FILTER_LZMA2

Фильтры сжатия LZMA1 и LZMA2. FILTER_LZMA1 используется с FORMAT_ALONE, а FILTER_LZMA2 — с FORMAT_XZ и FORMAT_RAW.

lzma.FILTER_DELTA

Дельта-фильтр.

lzma.MODE_FAST

lzma.MODE_NORMAL

Режимы сжатия, которые можно использовать в качестве параметра mode спецификатора фильтра (см. Указание пользовательских цепочек фильтров).

lzma.MF_HC3

lzma.MF_HC4

lzma.MF_BT2

lzma.MF_BT3

lzma.MF_BT4

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

Примеры

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

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