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

Новое в версии 3.3.

Исходный код: Lib/lzma.py

Этот модуль предоставляет классы и вспомогательные функции для сжатия и распаковки данных с использованием алгоритма сжатия LZMA. Также включён интерфейс для файлов, поддерживающий форматы .xz и устаревший .lzma форматы, используемые утилитой xz, а также сырые сжатые потоки.

Интерфейс, предоставляемый этим модулем, очень похож на интерфейс модуля bz2. Однако обратите внимание, что LZMAFile не является потокобезопасным, в отличие от bz2.BZ2File, поэтому, если вам нужно использовать один экземпляр LZMAFile из нескольких потоков, необходимо защитить его с помощью блокировки.

exception lzma.LZMAError: Это исключение возникает, когда во время сжатия или распаковки, или при инициализации состояния сжатия/распаковки произошла ошибка.

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

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, 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 object), возвращая данные без сжатия как 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
Фильтры 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")