lzma.md
1> **Источник:** https://python-all.ru/3.4/library/lzma.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 13.4. [`lzma`](https://python-all.ru/3.4/library/lzma.html#module-lzma) – Сжатие с использованием алгоритма LZMA89Новое в версии 3.3.1011Этот модуль предоставляет классы и вспомогательные функции для сжатия и распаковки данных с использованием алгоритма сжатия LZMA. Также включён файловый интерфейс, поддерживающий форматы файлов `.xz` и устаревший `.lzma`, используемые утилитой **xz**, а также сырые сжатые потоки.1213Интерфейс, предоставляемый этим модулем, очень похож на интерфейс модуля [`bz2`](https://python-all.ru/3.4/library/bz2.html#module-bz2). Однако обратите внимание, что [`LZMAFile`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAFile) *не* является потокобезопасным, в отличие от [`bz2.BZ2File`](https://python-all.ru/3.4/library/bz2.html#bz2.BZ2File), поэтому если требуется использовать один экземпляр [`LZMAFile`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAFile) из нескольких потоков, необходимо защищать его блокировкой.1415#### `exception lzma.LZMAError`1617Это исключение возникает при ошибке во время сжатия или распаковки, а также при инициализации состояния компрессора/декодера.1819## 13.4.1. Чтение и запись сжатых файлов2021#### `lzma.open(filename, mode="rb", *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)`2223Открывает LZMA-сжатый файл в двоичном или текстовом режиме и возвращает [*файловый объект*](https://python-all.ru/3.4/glossary.html#term-file-object).2425Аргумент *filename* может быть либо фактическим именем файла (заданным как объект [`str`](https://python-all.ru/3.4/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes)), и в этом случае именованный файл открывается, либо существующим файловым объектом для чтения или записи.2627Аргумент *mode* может быть любым из следующих: `"r"`, `"rb"`, `"w"`, `"wb"`, `"x"`, `"xb"`, `"a"` или `"ab"` для двоичного режима, или `"rt"`, `"wt"`, `"xt"`, или `"at"` для текстового режима. По умолчанию – `"rb"`.2829При открытии файла для чтения аргументы *format* и *filters* имеют тот же смысл, что и для [`LZMADecompressor`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMADecompressor). В этом случае аргументы *check* и *preset* использовать не следует.3031При открытии файла для записи аргументы *format*, *check*, *preset* и *filters* имеют тот же смысл, что и для [`LZMACompressor`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMACompressor).3233Для двоичного режима эта функция эквивалентна конструктору [`LZMAFile`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAFile): `LZMAFile(filename, mode, ...)`. В этом случае аргументы *encoding*, *errors* и *newline* указывать нельзя.3435Для текстового режима создаётся объект [`LZMAFile`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAFile), который обёртывается в экземпляр [`io.TextIOWrapper`](https://python-all.ru/3.4/library/io.html#io.TextIOWrapper) с указанными кодировкой, стратегией обработки ошибок и разделителями строк.3637Изменено в версии 3.4: Добавлена поддержка режимов `"x"`, `"xb"` и `"xt"`.3839#### `class lzma.LZMAFile(filename=None, mode="r", *, format=None, check=-1, preset=None, filters=None)`4041Открывает LZMA-сжатый файл в двоичном режиме.4243Объект [`LZMAFile`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAFile) может обёртывать уже открытый [*файловый объект*](https://python-all.ru/3.4/glossary.html#term-file-object) или работать напрямую с именованным файлом. Аргумент *filename* указывает либо файловый объект для обёртывания, либо имя открываемого файла (как объект [`str`](https://python-all.ru/3.4/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes)). При обёртывании существующего файлового объекта обёрнутый файл не будет закрыт при закрытии [`LZMAFile`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAFile).4445Аргумент *mode* может быть `"r"` для чтения (по умолчанию), `"w"` для перезаписи, `"x"` для эксклюзивного создания или `"a"` для добавления. Эквивалентно их можно задать как `"rb"`, `"wb"`, `"xb"` и `"ab"` соответственно.4647Если *filename* является файловым объектом (а не фактическим именем файла), режим `"w"` не усекает файл, а вместо этого эквивалентен `"a"`.4849При открытии файла для чтения входной файл может быть объединением нескольких отдельных сжатых потоков. Они прозрачно декодируются как единый логический поток.5051При открытии файла для чтения аргументы *format* и *filters* имеют тот же смысл, что и для [`LZMADecompressor`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMADecompressor). В этом случае аргументы *check* и *preset* использовать не следует.5253При открытии файла для записи аргументы *format*, *check*, *preset* и *filters* имеют тот же смысл, что и для [`LZMACompressor`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMACompressor).5455[`LZMAFile`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAFile) поддерживает все члены, указанные в [`io.BufferedIOBase`](https://python-all.ru/3.4/library/io.html#io.BufferedIOBase), за исключением `detach()` и `truncate()`. Поддерживаются итерация и инструкция [`with`](https://python-all.ru/3.4/reference/compound_stmts.html#with).5657Также предоставляется следующий метод:5859#### `peek(size=-1)`6061Возвращает буферизованные данные, не сдвигая позицию в файле. Будет возвращён как минимум один байт данных, если не достигнут EOF. Точное количество возвращаемых байт не определено (аргумент *size* игнорируется).6263> **Примечание**64>65> Хотя вызов [`peek()`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAFile.peek) не изменяет файловую позицию [`LZMAFile`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAFile), он может изменить позицию нижележащего файлового объекта (например, если [`LZMAFile`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAFile) был создан передачей файлового объекта в *filename*).6667Изменено в версии 3.4: Добавлена поддержка режимов `"x"` и `"xb"`.6869## 13.4.2. Сжатие и распаковка данных в памяти7071#### `class lzma.LZMACompressor(format=FORMAT_XZ, check=-1, preset=None, filters=None)`7273Создаёт объект компрессора, который можно использовать для пошагового сжатия данных.7475Для более удобного сжатия одного блока данных см. [`compress()`](https://python-all.ru/3.4/library/lzma.html#lzma.compress).7677Аргумент *format* указывает, какой формат контейнера следует использовать. Возможные значения:7879- **`FORMAT_XZ`: Формат контейнера `.xz`.**8081 Это формат по умолчанию.82- **`FORMAT_ALONE`: Устаревший формат контейнера `.lzma`.**8384 Этот формат более ограничен по сравнению с8586 `.xz`8788 – он не поддерживает проверки целостности или несколько фильтров.89- **`FORMAT_RAW`: Сырой поток данных, не использующий никакого формата контейнера.**9091 Этот спецификатор формата не поддерживает проверки целостности и требует всегда указывать пользовательскую цепочку фильтров (как для сжатия, так и для распаковки). Кроме того, данные, сжатые таким образом, нельзя распаковать с помощью9293 `FORMAT_AUTO`9495 (см.9697 [`LZMADecompressor`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMADecompressor)9899 ).100101Аргумент *check* определяет тип проверки целостности, включаемой в сжатые данные. Эта проверка используется при распаковке для контроля целостности данных. Возможные значения:102103- `CHECK_NONE`: Без проверки целостности. Это значение по умолчанию (и единственное допустимое) для `FORMAT_ALONE` и `FORMAT_RAW`.104- `CHECK_CRC32`: 32-битная циклическая избыточная проверка (CRC32).105- `CHECK_CRC64`: 64-битная циклическая избыточная проверка (CRC). Значение по умолчанию для `FORMAT_XZ`.106- `CHECK_SHA256`: 256-битный алгоритм безопасного хеширования (SHA).107108Если указанный тип проверки не поддерживается, возбуждается исключение [`LZMAError`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAError).109110Настройки сжатия можно задать либо как предустановленный уровень сжатия (с помощью аргумента *preset*), либо детально, как собственную цепочку фильтров (с помощью аргумента *filters*).111112Аргумент *preset* (если указан) должен быть целым числом от `0` до `9` включительно, возможно, с побитовым OR с константой `PRESET_EXTREME`. Если не заданы ни *preset*, ни *filters*, по умолчанию используется `PRESET_DEFAULT` (уровень `6`). Чем выше уровень, тем меньше выходной файл, но процесс сжатия замедляется.113114> **Примечание**115>116> Помимо большей нагрузки на процессор, сжатие с более высокими уровнями требует значительно больше памяти (и выдаёт результат, который для распаковки требует больше памяти). Например, для уровня `9` накладные расходы для объекта [`LZMACompressor`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMACompressor) могут достигать 800 МиБ. Поэтому обычно лучше придерживаться уровня по умолчанию.117118Аргумент *filters* (если указан) должен задавать цепочку фильтров. Подробнее см. [*Задание собственных цепочек фильтров*](https://python-all.ru/3.4/library/lzma.html#filter-chain-specs).119120#### `compress(data)`121122Сжимает *data* (объект [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes)) и возвращает объект [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes), содержащий сжатые данные как минимум для части входных данных. Некоторые данные из *data* могут буферизироваться внутри для последующих вызовов [`compress()`](https://python-all.ru/3.4/library/lzma.html#lzma.compress) и [`flush()`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMACompressor.flush). Возвращаемые данные следует дополнять выходными данными из всех предыдущих вызовов [`compress()`](https://python-all.ru/3.4/library/lzma.html#lzma.compress).123124#### `flush()`125126Завершает процесс сжатия, возвращая объект [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes), содержащий все данные, сохранённые во внутренних буферах компрессора.127128Компрессор нельзя использовать после вызова этого метода.129130#### `class lzma.LZMADecompressor(format=FORMAT_AUTO, memlimit=None, filters=None)`131132Создаёт объект декомпрессора, который можно использовать для инкрементальной декомпрессии данных.133134Для более удобной распаковки всего сжатого потока за один раз см. [`decompress()`](https://python-all.ru/3.4/library/lzma.html#lzma.decompress).135136Аргумент *format* задаёт формат контейнера. По умолчанию используется `FORMAT_AUTO`, который может распаковывать файлы как `.xz`, так и `.lzma`. Другие возможные значения: `FORMAT_XZ`, `FORMAT_ALONE` и `FORMAT_RAW`.137138Аргумент *memlimit* задаёт ограничение (в байтах) на объём памяти, который может использовать распаковщик. При использовании этого аргумента распаковка завершится ошибкой с исключением [`LZMAError`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAError), если её невозможно выполнить в пределах заданного ограничения.139140Аргумент *filters* задаёт цепочку фильтров, с помощью которой был создан распаковываемый поток. Этот аргумент обязателен, если *format* равен `FORMAT_RAW`, но его не следует использовать для других форматов. Подробнее о цепочках фильтров см. [*Specifying custom filter chains*](https://python-all.ru/3.4/library/lzma.html#filter-chain-specs).141142> **Примечание**143>144> В отличие от [`decompress()`](https://python-all.ru/3.4/library/lzma.html#lzma.decompress) и [`LZMAFile`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMAFile), этот класс не обрабатывает прозрачно входные данные, содержащие несколько сжатых потоков. Чтобы распаковать многопоточный вход с помощью [`LZMADecompressor`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMADecompressor), для каждого потока нужно создавать отдельный распаковщик.145146#### `decompress(data)`147148Распаковывает *data* (объект [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes)) и возвращает объект [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes), содержащий распакованные данные как минимум для части входных данных. Некоторые данные из *data* могут буферизироваться внутри для последующих вызовов [`decompress()`](https://python-all.ru/3.4/library/lzma.html#lzma.decompress). Возвращаемые данные следует дополнять выходными данными из всех предыдущих вызовов [`decompress()`](https://python-all.ru/3.4/library/lzma.html#lzma.decompress).149150#### `check`151152Идентификатор проверки целостности, используемый входным потоком. Может быть равен `CHECK_UNKNOWN`, пока не декодировано достаточно входных данных, чтобы определить, какая проверка целостности используется.153154#### `eof`155156`True`, если достигнут маркер конца потока.157158#### `unused_data`159160Данные, обнаруженные после конца сжатого потока.161162До достижения конца потока значением будет `b""`.163164#### `lzma.compress(data, format=FORMAT_XZ, check=-1, preset=None, filters=None)`165166Сжимает *data* (объект [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes)) и возвращает сжатые данные в виде объекта [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes).167168Описание аргументов *format*, *check*, *preset* и *filters* см. выше в описании [`LZMACompressor`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMACompressor).169170#### `lzma.decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None)`171172Распаковывает *data* (объект [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes)) и возвращает распакованные данные в виде объекта [`bytes`](https://python-all.ru/3.4/library/functions.html#bytes).173174Если *данные* представляют собой объединение нескольких разных сжатых потоков, распакуйте все эти потоки и верните объединённый результат.175176Описание аргументов *format*, *memlimit* и *filters* см. выше в описании [`LZMADecompressor`](https://python-all.ru/3.4/library/lzma.html#lzma.LZMADecompressor).177178## 13.4.3. Разное179180#### `lzma.is_check_supported(check)`181182Возвращает True, если указанная проверка целостности поддерживается в этой системе.183184`CHECK_NONE` и `CHECK_CRC32` поддерживаются всегда. `CHECK_CRC64` и `CHECK_SHA256` могут быть недоступны, если используется версия **liblzma**, собранная с ограниченным набором функций.185186## 13.4.4. Задание пользовательских цепочек фильтров187188Спецификация цепочки фильтров – это последовательность словарей, каждый из которых содержит идентификатор и параметры одного фильтра. Каждый словарь обязательно должен содержать ключ `"id"` и может содержать дополнительные ключи с параметрами, зависящими от фильтра. Допустимые идентификаторы фильтров:189190- **Фильтры сжатия:**191192 - `FILTER_LZMA1` (для использования с `FORMAT_ALONE`)193 - `FILTER_LZMA2` (for use with `FORMAT_XZ` and `FORMAT_RAW`)194- **Дельта-фильтр:**195196 - `FILTER_DELTA`197- **Фильтры ветвления-вызова-перехода (BCJ):**198199 - `FILTER_X86`200 - `FILTER_IA64`201 - `FILTER_ARM`202 - `FILTER_ARMTHUMB`203 - `FILTER_POWERPC`204 - `FILTER_SPARC`205206Цепочка фильтров может содержать до 4 фильтров и не может быть пустой. Последний фильтр в цепочке должен быть фильтром сжатия, а все остальные – дельта-фильтрами или фильтрами BCJ.207208Фильтры сжатия поддерживают следующие опции (указываются как дополнительные записи в словаре, представляющем фильтр):209210> - `preset`: Предустановка сжатия, используемая как источник значений по умолчанию для параметров, которые не заданы явно.211> - `dict_size`: Размер словаря в байтах. Должен быть от 4 КиБ до 1,5 ГиБ включительно.212> - `lc`: Количество битов контекста литерала.213> - `lp`: Количество битов позиции литерала. Сумма `lc + lp` не должна превышать 4.214> - `pb`: Количество битов позиции; не более 4.215> - `mode`: `MODE_FAST` или `MODE_NORMAL`.216> - `nice_len`: Какая длина считается «хорошей» для совпадения. Должно быть не больше 273.217> - `mf`: Какой поисковик совпадений использовать – `MF_HC3`, `MF_HC4`, `MF_BT2`, `MF_BT3` или `MF_BT4`.218> - `depth`: Максимальная глубина поиска, используемая поисковиком совпадений. Значение 0 (по умолчанию) означает автоматический выбор на основе остальных параметров фильтра.219220Дельта-фильтр хранит разности между байтами, создавая в определенных условиях более повторяющиеся входные данные для компрессора. Он поддерживает только один Дельта-фильтр поддерживает только один параметр, `dist`. Он указывает расстояние между вычитаемыми байтами. По умолчанию 1, т.е. берутся разности между соседними байтами.221222Фильтры BCJ предназначены для применения к машинному коду. Они преобразуют относительные ветвления, вызовы и переходы в коде в абсолютные адреса с целью увеличения избыточности, которая может быть использована компрессором. Эти фильтры поддерживают один параметр, `start_offset`. Он задает адрес, который должен соответствовать началу входных данных. По умолчанию 0.223224## 13.4.5. Примеры225226Чтение сжатого файла:227228```python229import lzma230with lzma.open("file.xz") as f:231 file_content = f.read()232```233234Создание сжатого файла:235236```python237import lzma238data = b"Insert Data Here"239with lzma.open("file.xz", "w") as f:240 f.write(data)241```242243Сжатие данных в памяти:244245```python246import lzma247data_in = b"Insert Data Here"248data_out = lzma.compress(data_in)249```250251Инкрементальное сжатие:252253```python254import lzma255lzc = lzma.LZMACompressor()256out1 = lzc.compress(b"Some data\n")257out2 = lzc.compress(b"Another piece of data\n")258out3 = lzc.compress(b"Even more data\n")259out4 = lzc.flush()260# Объединить все частичные результаты:261result = b"".join([out1, out2, out3, out4])262```263264Запись сжатых данных в уже открытый файл:265266```python267import lzma268with open("file.xz", "wb") as f:269 f.write(b"This data will not be compressed\n")270 with lzma.open(f, "w") as lzf:271 lzf.write(b"This *will* be compressed\n")272 f.write(b"Not compressed\n")273```274275Создание сжатого файла с использованием пользовательской цепочки фильтров:276277```python278import lzma279my_filters = [280 {"id": lzma.FILTER_DELTA, "dist": 5},281 {"id": lzma.FILTER_LZMA2, "preset": 7 | lzma.PRESET_EXTREME},282]283with lzma.open("file.xz", "w", filters=my_filters) as f:284 f.write(b"blah blah blah")285```286