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

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

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 поддерживает все элементы, указанные в io.BufferedIOBase, за исключением detach() и truncate(). Поддерживаются итерация и оператор with.

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

peek(size=-1)¶

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

Примечание

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

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

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

Более удобный способ сжатия отдельного фрагмента данных приведен в разделе 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().

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

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

Если значение max_length неотрицательно, возвращается не более max_length байт распакованных данных. Если этот предел достигнут и возможен дальнейший вывод, атрибуту needs_input будет присвоено значение False. В этом случае следующий вызов decompress() может предоставить данные в виде 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)¶

Сжимает данные (объект bytes), возвращая сжатые данные в виде объекта bytes.

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

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

Распакуйте данные (объект 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

• Фильтры перехода от одного вызова к другому (BCJ):

  • FILTER_X86

  • FILTER_IA64

  • FILTER_ARM

  • FILTER_ARMTHUMB

  • FILTER_POWERPC

  • FILTER_SPARC

Цепочка фильтров может состоять максимум из 4 фильтров и не может быть пустой. Последним фильтром в цепочке должен быть компрессионный фильтр, а все остальные фильтры должны быть фильтрами типа delta или 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")