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 (объект 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.

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

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)

• Фильтр разности:

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