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), возвращая распакованные данные как 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)

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

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

См. LZMADecompressor выше для описания аргументов формат, 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 (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.

Примеры

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

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