`lzma.md`

298 строк · 28.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.11/library/lzma.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`lzma`](https://python-all.ru/3.11/library/lzma.html#module-lzma) – Сжатие с использованием алгоритма LZMA89Новое в версии 3.3.1011**Исходный код:** [Lib/lzma.py](https://python-all.ru/src/3.11/Lib/lzma.py)1213---1415Этот модуль предоставляет классы и вспомогательные функции для сжатия и распаковки данных с помощью алгоритма сжатия LZMA. Также включен файловый интерфейс, поддерживающий форматы файлов `.xz` и устаревший `.lzma`, используемые утилитой **xz**, а также сырые сжатые потоки.1617Интерфейс, предоставляемый этим модулем, очень похож на интерфейс модуля [`bz2`](https://python-all.ru/3.11/library/bz2.html#module-bz2). Обратите внимание, что [`LZMAFile`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAFile) и [`bz2.BZ2File`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2File) *не* являются потокобезопасными, поэтому, если требуется использовать один экземпляр [`LZMAFile`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAFile) из нескольких потоков, необходимо защищать его блокировкой.1819#### `exception lzma.LZMAError`2021Это исключение возникает при ошибке во время сжатия или распаковки, а также при инициализации состояния компрессора/декодера.2223## Чтение и запись сжатых файлов2425#### `lzma.open(filename, mode='rb', *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)`2627Открывает LZMA-сжатый файл в двоичном или текстовом режиме и возвращает [файловый объект](https://python-all.ru/3.11/glossary.html#term-file-object).2829Аргумент *filename* может быть как именем файла (в виде [`str`](https://python-all.ru/3.11/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes) или [path-like](https://python-all.ru/3.11/glossary.html#term-path-like-object) объекта), в этом случае открывается указанный файл, так и существующим файловым объектом для чтения или записи.3031Аргумент *mode* может быть любым из `"r"`, `"rb"`, `"w"`, `"wb"`, `"x"`, `"xb"`, `"a"` или `"ab"` для бинарного режима, или `"rt"`, `"wt"`, `"xt"` или `"at"` для текстового режима. По умолчанию `"rb"`.3233При открытии файла для чтения аргументы *format* и *filters* имеют то же значение, что и для [`LZMADecompressor`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMADecompressor). В этом случае аргументы *check* и *preset* не должны использоваться.3435При открытии файла для записи аргументы *format*, *check*, *preset* и *filters* имеют то же значение, что и для [`LZMACompressor`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMACompressor).3637В двоичном режиме эта функция эквивалентна конструктору [`LZMAFile`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAFile): `LZMAFile(filename, mode, ...)`. В этом случае аргументы *encoding*, *errors* и *newline* указывать нельзя.3839Для текстового режима создаётся объект [`LZMAFile`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAFile), обёрнутый в экземпляр [`io.TextIOWrapper`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper) с указанными кодировкой, поведением при ошибках и символами конца строки.4041Изменено в версии 3.4: Добавлена поддержка режимов `"x"`, `"xb"` и `"xt"`.4243Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.11/glossary.html#term-path-like-object).4445#### `class lzma.LZMAFile(filename=None, mode='r', *, format=None, check=-1, preset=None, filters=None)`4647Открывает LZMA-сжатый файл в двоичном режиме.4849[`LZMAFile`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAFile) может обернуть уже открытый [файловый объект](https://python-all.ru/3.11/glossary.html#term-file-object) или работать напрямую с именованным файлом. Аргумент *filename* указывает либо оборачиваемый файловый объект, либо имя открываемого файла (в виде [`str`](https://python-all.ru/3.11/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes) или [path-like](https://python-all.ru/3.11/glossary.html#term-path-like-object) объекта). При обёртывании существующего файлового объекта обёрнутый файл не будет закрыт при закрытии [`LZMAFile`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAFile).5051Аргумент *mode* может быть `"r"` для чтения (по умолчанию), `"w"` для перезаписи, `"x"` для исключительного создания или `"a"` для добавления. Им эквивалентно соответствуют `"rb"`, `"wb"`, `"xb"` и `"ab"` соответственно.5253Если *filename* – файловый объект (а не фактическое имя файла), режим `"w"` не усекает файл, а вместо этого эквивалентен `"a"`.5455При открытии файла для чтения входной файл может быть объединением нескольких отдельных сжатых потоков. Они прозрачно декодируются как единый логический поток.5657При открытии файла для чтения аргументы *format* и *filters* имеют то же значение, что и для [`LZMADecompressor`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMADecompressor). В этом случае аргументы *check* и *preset* не должны использоваться.5859При открытии файла для записи аргументы *format*, *check*, *preset* и *filters* имеют то же значение, что и для [`LZMACompressor`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMACompressor).6061[`LZMAFile`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAFile) поддерживает все члены, указанные в [`io.BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase), за исключением [`detach()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.detach) и [`truncate()`](https://python-all.ru/3.11/library/io.html#io.IOBase.truncate). Поддерживаются итерация и оператор [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with).6263Также предоставляется следующий метод:6465#### `peek(size=-1)`6667Возвращает буферизованные данные, не сдвигая позицию в файле. Будет возвращён как минимум один байт данных, если не достигнут EOF. Точное количество возвращаемых байт не определено (аргумент *size* игнорируется).6869> **Примечание**70>71> Хотя вызов [`peek()`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAFile.peek) не изменяет позицию файла в [`LZMAFile`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAFile), он может изменить позицию нижележащего файлового объекта (например, если [`LZMAFile`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAFile) был создан путём передачи файлового объекта в качестве *filename*).7273Изменено в версии 3.4: Добавлена поддержка режимов `"x"` и `"xb"`.7475Изменено в версии 3.5: Метод [`read()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.read) теперь принимает аргумент типа `None`.7677Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.11/glossary.html#term-path-like-object).7879## Сжатие и распаковка данных в памяти8081#### `class lzma.LZMACompressor(format=FORMAT_XZ, check=-1, preset=None, filters=None)`8283Создаёт объект компрессора, который можно использовать для пошагового сжатия данных.8485Более удобный способ сжатия одного блока данных – [`compress()`](https://python-all.ru/3.11/library/lzma.html#lzma.compress).8687Аргумент *format* указывает, какой формат контейнера следует использовать. Возможные значения:8889- **`FORMAT_XZ`: формат контейнера `.xz`.**9091  Это формат по умолчанию.92- **`FORMAT_ALONE`: устаревший формат контейнера `.lzma`.**9394  Этот формат более ограничен по сравнению с `.xz` – он не поддерживает проверки целостности и несколько фильтров.95- **`FORMAT_RAW`: необработанный поток данных без использования контейнерного формата.**9697  Этот спецификатор формата не поддерживает проверку целостности и требует всегда указывать собственную цепочку фильтров (как для сжатия, так и для распаковки). Кроме того, данные, сжатые таким образом, невозможно распаковать с помощью `FORMAT_AUTO` (см. [`LZMADecompressor`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMADecompressor)).9899Аргумент *check* определяет тип проверки целостности, включаемой в сжатые данные. Эта проверка используется при распаковке для контроля целостности данных. Возможные значения:100101- `CHECK_NONE`: без проверки целостности. Это значение по умолчанию (и единственное допустимое) для `FORMAT_ALONE` и `FORMAT_RAW`.102- `CHECK_CRC32`: 32-битный CRC (циклическая проверка избыточности).103- `CHECK_CRC64`: 64-битный CRC (циклическая проверка избыточности). Это значение по умолчанию для `FORMAT_XZ`.104- `CHECK_SHA256`: 256-битный алгоритм безопасного хеширования (SHA-256).105106Если указанная проверка не поддерживается, вызывается исключение [`LZMAError`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAError).107108Настройки сжатия можно задать либо как предустановленный уровень сжатия (с помощью аргумента *preset*), либо детально, как собственную цепочку фильтров (с помощью аргумента *filters*).109110Аргумент *preset* (если указан) должен быть целым числом от `0` до `9` включительно, возможно, с побитовым ИЛИ с константой `PRESET_EXTREME`. Если не заданы ни *preset*, ни *filters*, поведение по умолчанию – использовать `PRESET_DEFAULT` (уровень предустановки `6`). Более высокие уровни дают меньший выходной объём, но замедляют процесс сжатия.111112> **Примечание**113>114> Помимо большей нагрузки на процессор, сжатие с более высокими уровнями предустановок также требует значительно больше памяти (и выдаёт выходные данные, которым для распаковки требуется больше памяти). Например, для уровня `9` накладные расходы для объекта [`LZMACompressor`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMACompressor) могут достигать 800 МиБ. По этой причине обычно лучше придерживаться уровня по умолчанию.115116Аргумент *filters* (если указан) должен задавать цепочку фильтров. Подробнее см. [Задание собственных цепочек фильтров](https://python-all.ru/3.11/library/lzma.html#filter-chain-specs).117118#### `compress(data)`119120Сжимает *data* (объект [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes)) и возвращает объект [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes), содержащий сжатые данные хотя бы для части входных данных. Часть *data* может быть буферизована внутри для использования в последующих вызовах [`compress()`](https://python-all.ru/3.11/library/lzma.html#lzma.compress) и [`flush()`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMACompressor.flush). Возвращённые данные следует объединять с результатом всех предыдущих вызовов [`compress()`](https://python-all.ru/3.11/library/lzma.html#lzma.compress).121122#### `flush()`123124Завершает процесс сжатия, возвращая объект [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes), содержащий данные, хранящиеся во внутренних буферах компрессора.125126Компрессор нельзя использовать после вызова этого метода.127128#### `class lzma.LZMADecompressor(format=FORMAT_AUTO, memlimit=None, filters=None)`129130Создаёт объект декомпрессора, который можно использовать для инкрементальной декомпрессии данных.131132Более удобный способ распаковки всего сжатого потока за один раз см. в [`decompress()`](https://python-all.ru/3.11/library/lzma.html#lzma.decompress).133134Аргумент *format* задаёт используемый контейнерный формат. Значение по умолчанию – `FORMAT_AUTO`, которое позволяет распаковывать файлы как `.xz`, так и `.lzma`. Другие возможные значения: `FORMAT_XZ`, `FORMAT_ALONE`, `FORMAT_RAW`.135136Аргумент *memlimit* задаёт ограничение (в байтах) на объём памяти, который может использовать распаковщик. При использовании этого аргумента распаковка завершится с исключением [`LZMAError`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAError), если входные данные невозможно распаковать в пределах заданного лимита памяти.137138Аргумент *filters* задаёт цепочку фильтров, использованную при создании распаковываемого потока. Этот аргумент обязателен, если *format* равен `FORMAT_RAW`, но не должен использоваться для других форматов. Дополнительную информацию о цепочках фильтров см. в [Задание собственных цепочек фильтров](https://python-all.ru/3.11/library/lzma.html#filter-chain-specs).139140> **Примечание**141>142> В отличие от [`decompress()`](https://python-all.ru/3.11/library/lzma.html#lzma.decompress) и [`LZMAFile`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMAFile), этот класс не обрабатывает прозрачно входные данные, содержащие несколько сжатых потоков. Чтобы распаковать многопоточный вход с помощью [`LZMADecompressor`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMADecompressor), необходимо создавать новый распаковщик для каждого потока.143144#### `decompress(data, max_length=-1)`145146Декомпрессирует *data* ([байтоподобный объект](https://python-all.ru/3.11/glossary.html#term-bytes-like-object)), возвращая несжатые данные в виде байтов. Часть *data* может буферизироваться внутренне для использования в последующих вызовах [`decompress()`](https://python-all.ru/3.11/library/lzma.html#lzma.decompress). Возвращаемые данные следует объединять с результатом любых предыдущих вызовов [`decompress()`](https://python-all.ru/3.11/library/lzma.html#lzma.decompress).147148Если *max\_length* неотрицательно, возвращает не более *max\_length* байтов декомпрессированных данных. Если этот лимит достигнут и может быть сгенерирован дальнейший вывод, атрибут [`needs_input`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMADecompressor.needs_input) будет установлен в `False`. В этом случае следующий вызов [`decompress()`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMADecompressor.decompress) может передать *data* как `b''` для получения ещё вывода.149150Если все входные данные были декомпрессированы и возвращены (либо потому что это было меньше *max\_length* байтов, либо потому что *max\_length* было отрицательным), атрибут [`needs_input`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMADecompressor.needs_input) будет установлен в `True`.151152Попытка декомпрессировать данные после достижения конца потока вызывает [`EOFError`](https://python-all.ru/3.11/library/exceptions.html#EOFError). Любые данные, обнаруженные после конца потока, игнорируются и сохраняются в атрибуте [`unused_data`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMADecompressor.unused_data).153154Изменено в версии 3.5: Добавлен параметр *max\_length*.155156#### `check`157158Идентификатор проверки целостности, используемой входным потоком. Может быть `CHECK_UNKNOWN`, пока не будет декодировано достаточно входных данных, чтобы определить, какая проверка целостности используется.159160#### `eof`161162`True`, если достигнут маркер конца потока.163164#### `unused_data`165166Данные, обнаруженные после конца сжатого потока.167168До достижения конца потока это будет `b""`.169170#### `needs_input`171172`False`, если метод [`decompress()`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMADecompressor.decompress) может предоставить больше декомпрессированных данных до запроса нового несжатого входа.173174Новое в версии 3.5.175176#### `lzma.compress(data, format=FORMAT_XZ, check=-1, preset=None, filters=None)`177178Сжимает *data* (объект [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes)) и возвращает сжатые данные в виде объекта [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes).179180Описание аргументов *format*, *check*, *preset* и *filters* см. выше в [`LZMACompressor`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMACompressor).181182#### `lzma.decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None)`183184Распаковывает *данные* (объект [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes)), возвращая распакованные данные в виде объекта [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes).185186Если *данные* представляют собой объединение нескольких разных сжатых потоков, распакуйте все эти потоки и верните объединённый результат.187188Описание аргументов *format*, *memlimit* и *filters* см. выше в [`LZMADecompressor`](https://python-all.ru/3.11/library/lzma.html#lzma.LZMADecompressor).189190## Разное191192#### `lzma.is_check_supported(check)`193194Возвращает `True`, если указанная проверка целостности поддерживается в этой системе.195196`CHECK_NONE` и `CHECK_CRC32` поддерживаются всегда. `CHECK_CRC64` и `CHECK_SHA256` могут быть недоступны, если используется версия **liblzma**, скомпилированная с ограниченным набором функций.197198## Указание пользовательских цепочек фильтров199200Спецификатор цепочки фильтров – это последовательность словарей, где каждый словарь содержит идентификатор и параметры одного фильтра. Каждый словарь должен содержать ключ `"id"` и может содержать дополнительные ключи для указания опций, зависящих от фильтра. Допустимые идентификаторы фильтров:201202- Фильтры сжатия:203204  - `FILTER_LZMA1` (для использования с `FORMAT_ALONE`)205  - `FILTER_LZMA2` (для использования с `FORMAT_XZ` и `FORMAT_RAW`)206- Дельта-фильтр:207208  - `FILTER_DELTA`209- Фильтры ветвления-вызова-перехода (BCJ):210211  - `FILTER_X86`212  - `FILTER_IA64`213  - `FILTER_ARM`214  - `FILTER_ARMTHUMB`215  - `FILTER_POWERPC`216  - `FILTER_SPARC`217218Цепочка фильтров может содержать до 4 фильтров и не может быть пустой. Последний фильтр в цепочке должен быть фильтром сжатия, а все остальные – дельта-фильтрами или фильтрами BCJ.219220Фильтры сжатия поддерживают следующие опции (указываются как дополнительные записи в словаре, представляющем фильтр):221222- `preset`: Предустановка сжатия, используемая как источник значений по умолчанию для параметров, которые не заданы явно.223- `dict_size`: Размер словаря в байтах. Должен быть в диапазоне от 4 КиБ до 1,5 ГиБ (включительно).224- `lc`: Количество бит контекста литералов.225- `lp`: Количество бит позиции литералов. Сумма `lc + lp` не должна превышать 4.226- `pb`: Количество бит позиции; должно быть не более 4.227- `mode`: `MODE_FAST` или `MODE_NORMAL`.228- `nice_len`: Что считать «подходящей длиной» для совпадения. Должно быть 273 или меньше.229- `mf`: Какой поисковик совпадений использовать – `MF_HC3`, `MF_HC4`, `MF_BT2`, `MF_BT3` или `MF_BT4`.230- `depth`: Максимальная глубина поиска, используемая искателем совпадений. 0 (по умолчанию) означает автоматический выбор на основе других параметров фильтра.231232Дельта-фильтр хранит разности между байтами, создавая в некоторых случаях более повторяющиеся входные данные для компрессора. Он поддерживает один параметр, `dist`. Он указывает расстояние между вычитаемыми байтами. Значение по умолчанию – 1, то есть вычисляются разности между соседними байтами.233234Фильтры BCJ предназначены для применения к машинному коду. Они преобразуют относительные переходы, вызовы и прыжки в коде в абсолютную адресацию с целью повышения избыточности, которую может использовать компрессор. Эти фильтры поддерживают один параметр, `start_offset`. Он задаёт адрес, который должен соответствовать началу входных данных. По умолчанию – 0.235236## Примеры237238Чтение сжатого файла:239240```python241import lzma242with lzma.open("file.xz") as f:243    file_content = f.read()244```245246Создание сжатого файла:247248```python249import lzma250data = b"Insert Data Here"251with lzma.open("file.xz", "w") as f:252    f.write(data)253```254255Сжатие данных в памяти:256257```python258import lzma259data_in = b"Insert Data Here"260data_out = lzma.compress(data_in)261```262263Инкрементальное сжатие:264265```python266import lzma267lzc = lzma.LZMACompressor()268out1 = lzc.compress(b"Some data\n")269out2 = lzc.compress(b"Another piece of data\n")270out3 = lzc.compress(b"Even more data\n")271out4 = lzc.flush()272# Объединить все частичные результаты:273result = b"".join([out1, out2, out3, out4])274```275276Запись сжатых данных в уже открытый файл:277278```python279import lzma280with open("file.xz", "wb") as f:281    f.write(b"This data will not be compressed\n")282    with lzma.open(f, "w") as lzf:283        lzf.write(b"This *will* be compressed\n")284    f.write(b"Not compressed\n")285```286287Создание сжатого файла с использованием пользовательской цепочки фильтров:288289```python290import lzma291my_filters = [292    {"id": lzma.FILTER_DELTA, "dist": 5},293    {"id": lzma.FILTER_LZMA2, "preset": 7 | lzma.PRESET_EXTREME},294]295with lzma.open("file.xz", "w", filters=my_filters) as f:296    f.write(b"blah blah blah")297```298