lzma – Сжатие с использованием алгоритма LZMA¶lzma – Compression using the LZMA algorithm

Чтение и запись сжатых файлов¶Reading and writing compressed files

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

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

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

Аргумент 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 или path-like объекта). При обёртывании существующего файлового объекта обёрнутый файл не будет закрыт при закрытии 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).

mode¶

'rb' для чтения и 'wb' для записи.

Добавлено в версии 3.13.

name¶

Имя lzma-файла. Эквивалентно атрибуту name нижележащего файлового объекта.

Добавлено в версии 3.13.

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

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

Изменено в версии 3.6: Принимает объект, подобный пути.

Сжатие и распаковка данных в памяти¶Compressing and decompressing data in memory

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 определяет тип проверки целостности, включаемой в сжатые данные. Эта проверка используется при распаковке для контроля целостности данных. Возможные значения:

• CHECK_NONE: без проверки целостности. Это значение по умолчанию (и единственное допустимое) для FORMAT_ALONE и FORMAT_RAW.

• CHECK_CRC32: 32-битный CRC (циклическая проверка избыточности).

• CHECK_CRC64: 64-битный CRC (циклическая проверка избыточности). Это значение по умолчанию для FORMAT_XZ.

• CHECK_SHA256: 256-битный алгоритм безопасного хеширования (SHA-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 (байтоподобный объект), возвращая несжатые данные в виде байтов. Часть 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)¶

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

Если данные представляют собой объединение нескольких разных сжатых потоков, распакуйте все эти потоки и верните объединённый результат.

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

Разное¶Miscellaneous

lzma.is_check_supported(check)¶

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

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

Указание пользовательских цепочек фильтров¶Specifying custom filter chains

Спецификатор цепочки фильтров – это последовательность словарей, где каждый словарь содержит идентификатор и параметры одного фильтра. Каждый словарь должен содержать ключ "id" и может содержать дополнительные ключи для указания опций, зависящих от фильтра. Допустимые идентификаторы фильтров:

• Фильтры сжатия:

  • FILTER_LZMA1 (для использования с FORMAT_ALONE)

  • FILTER_LZMA2 (для использования с FORMAT_XZ и FORMAT_RAW)

• Дельта-фильтр:

  • FILTER_DELTA

• Фильтры ветвления-вызова-перехода (BCJ):

  • FILTER_X86

  • FILTER_IA64

  • FILTER_ARM

  • FILTER_ARMTHUMB

  • FILTER_POWERPC

  • FILTER_SPARC

    Приведённые выше функции работают во всех версиях библиотеки времени выполнения lzma.

  • FILTER_ARM64

    Работает только если версия lzma 5.4.0 или новее.

    Добавлено в версии 3.16.0a0 (не выпущено).

  • FILTER_RISCV

    Работает только если версия lzma 5.6.0 или новее.

    Добавлено в версии 3.16.0a0 (не выпущено).

Цепочка фильтров может содержать до 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.

Примеры¶Examples

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

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