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

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

lzma.open(filename, mode='rb', *, format=None, check=- 1, preset=None, filters=None, encoding=None, errors=None, newline=None)¶

Открыть LZMA-сжатый файл в двоичном или текстовом режиме, возвращая file object.

Аргумент filename может быть либо фактическим именем файла (заданным как объект str, bytes или path-like), в этом случае именованный файл открывается, либо существующим объектом файла для чтения или записи.

Аргумент mode может быть любым из "r", "rb", "w", "wb", "x", "xb", "a" или "ab" для двоичного режима, или "rt", "wt", "xt" или "at" для текстового режима. По умолчанию используется значение "rb".

При открытии файла для чтения аргументы формат и фильтры имеют те же значения, что и для 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: Принимает path-like object.

class lzma.LZMAFile(filename=None, mode='r', *, format=None, check=- 1, preset=None, filters=None)¶

Открытие LZMA-сжатого файла в двоичном режиме.

LZMAFile может обернуть уже открытый file object или работать непосредственно с именованным файлом. Аргумент filename указывает либо объект файла, который нужно обернуть, либо имя файла, который нужно открыть (как объект str, bytes или path-like). При обертывании существующего объекта файла, обернутый файл не будет закрыт при закрытии LZMAFile.

Аргумент mode может быть либо "r" для чтения (по умолчанию), "w" для перезаписи, "x" для эксклюзивного создания, либо "a" для добавления. Эквивалентно они могут быть заданы как "rb", "wb", "xb" и "ab" соответственно.

Если filename является объектом файла (а не реальным именем файла), режим "w" не усекает файл, а эквивалентен "a".

При открытии файла для чтения входной файл может быть конкатенацией нескольких отдельных сжатых потоков. Они прозрачно декодируются как единый логический поток.

При открытии файла для чтения аргументы формат и фильтры имеют те же значения, что и для LZMADecompressor. В этом случае аргументы check и preset не должны использоваться.

При открытии файла для записи аргументы format, check, preset и filters имеют те же значения, что и для LZMACompressor.

LZMAFile поддерживает все члены, указанные в io.BufferedIOBase, кроме detach() и truncate(). Поддерживается итерация и оператор with.

Также предлагается следующий метод:

peek(size=- 1)¶

Возврат буферизованных данных без продвижения позиции файла. Будет возвращен как минимум один байт данных, если не было достигнуто EOF. Точное количество возвращаемых байтов не определено (аргумент size игнорируется).

Примечание

Хотя вызов peek() не изменяет позицию файла LZMAFile, он может изменить позицию базового объекта файла (например, если LZMAFile был построен путем передачи объекта файла для filename).

Изменено в версии 3.4: Добавлена поддержка режимов "x" и "xb".

Изменено в версии 3.5: Метод read() теперь принимает аргумент None.

Изменено в версии 3.6: Принимает path-like object.

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

class lzma.LZMACompressor(format=FORMAT_XZ, check=- 1, preset=None, filters=None)¶

Создайте объект компрессора, который можно использовать для инкрементного сжатия данных.

Для более удобного способа сжатия одного фрагмента данных смотрите compress().

Аргумент формат указывает, какой формат контейнера должен быть использован. Возможными значениями являются:

• FORMAT_XZ: Формат контейнера .xz.

  Это формат по умолчанию.

• FORMAT_ALONE: Устаревший формат контейнера .lzma.

  Этот формат более ограничен, чем .xz - он не поддерживает проверку целостности или множественные фильтры.

• FORMAT_RAW: Необработанный поток данных, не использующий никакого контейнерного формата.

  Этот спецификатор формата не поддерживает проверку целостности и требует, чтобы вы всегда указывали пользовательскую цепочку фильтров (как для сжатия, так и для распаковки). Кроме того, данные, сжатые таким образом, нельзя распаковать с помощью 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_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_RAW, но не должен использоваться для других форматов. Дополнительную информацию о цепочках фильтров смотрите в Указание пользовательских цепочек фильтров.

Примечание

В отличие от decompress() и LZMAFile, этот класс не обрабатывает прозрачно входные данные, содержащие несколько сжатых потоков. Для декомпрессии многопотокового ввода с помощью LZMADecompressor необходимо создать новый декомпрессор для каждого потока.

decompress(data, max_length=- 1)¶

Декомпрессия data (a bytes-like object), возвращая несжатые данные в виде байтов. Часть данных может быть буферизована внутри, для использования в последующих вызовах decompress(). Возвращенные данные должны быть конкатенированы с результатами предыдущих вызовов decompress().

Если max_length неотрицательна, возвращается не более max_length байт распакованных данных. Если этот предел достигнут и дальнейший вывод может быть произведен, атрибут needs_input будет установлен в False. В этом случае следующий вызов decompress() может предоставить данные в качестве 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)¶

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

Описание аргументов формат, проверка, пресет и фильтры см. выше LZMACompressor.

lzma.decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None)¶

Декомпрессия данных (объект 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

• Фильтры Branch-Call-Jump (BCJ):

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