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 (включительно), необязательно побитово ИЛИ с константой 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 object), возвращая распакованные данные в виде байтов. Часть 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 и фильтры.

Разное

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