lzma — Сжатие с помощью алгоритма LZMA

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

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

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

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

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

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

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

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.

2. Сжатие и распаковку данных в памяти

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-битный алгоритм хеширования Secure Hash.

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

3. Разное

lzma.is_check_supported(check)

Возвращает true, если указанная проверка целостности поддерживается в этой системе.

CHECK_NONE и CHECK_CRC32 всегда поддерживаются. CHECK_CRC64 и CHECK_SHA256 могут быть недоступны, если вы используете версию liblzma, скомпилированную с ограниченным набором функций.

4. Указание пользовательских цепочек фильтров

Указатель цепочки фильтров представляет собой последовательность словарей, где каждый словарь содержит идентификатор и параметры для одного фильтра. Каждый словарь должен содержать ключ "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.

5. Примеры

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

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