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-битный алгоритм хэширования 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), возвращая необработанные данные в формате 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")