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 и filters имеют те же значения, что и для 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: Принимает путеподобный объект.

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

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

Создать объект компрессора, который может быть используемый, чтобы сжать данные с приращением.

Более удобный способ сжатия одного чанка данных см. в разделе compress().

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

  • FORMAT_XZ: формат контейнера .xz. Это формат по умолчанию.
  • FORMAT_ALONE: наследование формат контейнера .lzma. Этот формат более ограничен, чем .xz - он не поддерживает проверки целостности или несколько фильтров.
  • FORMAT_RAW: поток необработанных данных, не использующий формат контейнера. Этот спецификатор формата не поддерживает проверки целостности и требует, чтобы всегда указывалась пользовательская цепочка фильтров (как для сжатия, так и для распаковки). Кроме того, данные, сжатые таким образом, не могут быть распакованы с использованием FORMAT_AUTO (см. LZMADecompressor).

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

  • 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 MiB. По этой причине обычно лучше придерживаться предустановки по умолчанию.

Аргумент 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 (байтоподобный объект), возвращая несжатые данные в байтах. Некоторые из 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.

См. LZMACompressor выше для описания format, check, preset и аргументов filters.

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

Распакуйте data (объект bytes), возвращая несжатые данные как объект bytes.

Если data является конкатенацией множества различных сжатых потоков, распакуйте все эти потоки и возвращает конкатенацию результатов.

См. LZMADecompressor выше для описания format, memlimit и аргументов filters.

Разное

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)
  • Фильтр Delta:
    • FILTER_DELTA
  • Фильтры Branch-Call-Jump (BCJ):
    • FILTER_IA64
    • FILTER_ARM
    • FILTER_ARMTHUMB
    • FILTER_POWERPC
    • FILTER_SPARC

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

Фильтры сжатия поддерживают следующие параметры (указанные как дополнительные статьи в словаре, представляющем фильтр):

  • preset: стиль сжатия, используемый в качестве источника значения по умолчанию для параметров, которые не указаны явно.
  • dict_size: размер словаря в байтах. Это должно быть между 4 KiB и 1,5 GiB (включительно).
  • 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()
# Объединить все частичные результаты:
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")