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

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

Распаковывает 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")