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_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_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_AUTO, который может распаковывать файлы как .xz так и .lzma. Другие возможные значения – FORMAT_XZ, FORMAT_ALONE, и FORMAT_RAW.

Аргумент memlimit указывает ограничение (в байтах) на объем памяти, который может использовать распаковщик. При использовании этого аргумента распаковка завершится ошибкой LZMAError, если распаковку невозможно выполнить в рамках данного ограничения по памяти.

Аргумент filters указывает цепочку фильтров, которая использовалась для создания потока, подлежащего распаковке. Этот аргумент обязателен, если формат равен FORMAT_RAW, но не должен использоваться для других форматов. Подробнее о цепочках фильтров см. в разделе Указание пользовательских цепочек фильтров.

Примечание

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

decompress(data, max_length=- 1)

Распаковывает data (объект bytes-like object), возвращая распакованные данные как байты. Некоторые данные из 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 выше для описания аргументов формат, проверка, preset и filters.

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

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

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

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

Разное

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