Содержание страницы

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

Новое в версии 3.3.

Этот модуль предоставляет классы и вспомогательные функции для сжатия и распаковки данных с использованием алгоритма сжатия LZMA. Также включён файловый интерфейс, поддерживающий форматы файлов .xz и устаревший .lzma, используемые утилитой xz, а также сырые сжатые потоки.

Интерфейс, предоставляемый этим модулем, очень похож на интерфейс модуля bz2. Однако обратите внимание, что LZMAFile не является потокобезопасным, в отличие от bz2.BZ2File, поэтому если требуется использовать один экземпляр LZMAFile из нескольких потоков, необходимо защищать его блокировкой.

exception lzma.LZMAError¶: Это исключение возникает при ошибке во время сжатия или распаковки, а также при инициализации состояния компрессора/декодера.

13.4.1. Чтение и запись сжатых файлов¶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), и в этом случае именованный файл открывается, либо существующим файловым объектом для чтения или записи.

Аргумент 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".

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, check, preset и filters имеют тот же смысл, что и для LZMACompressor.

LZMAFile поддерживает все члены, указанные в io.BufferedIOBase, за исключением detach() и truncate(). Поддерживаются итерация и инструкция with.

Также предоставляется следующий метод:

peek(size=-1)¶: Возвращает буферизованные данные, не сдвигая позицию в файле. Будет возвращён как минимум один байт данных, если не достигнут EOF. Точное количество возвращаемых байт не определено (аргумент size игнорируется).

Примечание

Хотя вызов peek() не изменяет файловую позицию LZMAFile, он может изменить позицию нижележащего файлового объекта (например, если LZMAFile был создан передачей файлового объекта в filename).

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

13.4.2. Сжатие и распаковка данных в памяти¶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-битная циклическая избыточная проверка (CRC32).
CHECK_CRC64: 64-битная циклическая избыточная проверка (CRC). Значение по умолчанию для FORMAT_XZ.
CHECK_SHA256: 256-битный алгоритм безопасного хеширования (SHA).

Если указанный тип проверки не поддерживается, возбуждается исключение LZMAError.

Настройки сжатия можно задать либо как предустановленный уровень сжатия (с помощью аргумента preset), либо детально, как собственную цепочку фильтров (с помощью аргумента filters).

Аргумент preset (если указан) должен быть целым числом от 0 до 9 включительно, возможно, с побитовым OR с константой 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, но его не следует использовать для других форматов. Подробнее о цепочках фильтров см. Specifying custom filter chains.

Примечание

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

decompress(data)¶: Распаковывает data (объект bytes) и возвращает объект bytes, содержащий распакованные данные как минимум для части входных данных. Некоторые данные из data могут буферизироваться внутри для последующих вызовов decompress(). Возвращаемые данные следует дополнять выходными данными из всех предыдущих вызовов decompress().

check¶: Идентификатор проверки целостности, используемый входным потоком. Может быть равен CHECK_UNKNOWN, пока не декодировано достаточно входных данных, чтобы определить, какая проверка целостности используется.

eof¶: True, если достигнут маркер конца потока.

unused_data¶

Данные, обнаруженные после конца сжатого потока.

До достижения конца потока значением будет b"".

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.

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

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

13.4.3. Разное¶Miscellaneous

lzma.is_check_supported(check)¶

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

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

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

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

Фильтры сжатия:
- FILTER_LZMA1 (для использования с FORMAT_ALONE)
- FILTER_LZMA2 (for use with FORMAT_XZ and FORMAT_RAW)
Дельта-фильтр:
- FILTER_DELTA
Фильтры ветвления-вызова-перехода (BCJ):
- 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.

13.4.5. Примеры¶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")