compression.zstd.md

1> **Источник:** https://python-all.ru/3.16/library/compression.zstd.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `compression.zstd` – Сжатие, совместимое с форматом Zstandard89Добавлено в версии 3.14.1011**Исходный код:** [Lib/compression/zstd/\_\_init\_\_.py](https://python-all.ru/src/main/Lib/compression/zstd/__init__.py)1213---1415Этот модуль предоставляет классы и функции для сжатия и декомпрессии данных с использованием алгоритма сжатия Zstandard (или *zstd*). [Руководство по zstd](https://python-all.ru/3.16/library/compression.zstd.html) описывает Zstandard как «быстрый алгоритм сжатия без потерь, предназначенный для сценариев сжатия в реальном времени на уровне zlib и с лучшим коэффициентом сжатия». Также включён файловый интерфейс, поддерживающий чтение и запись содержимого файлов `.zst`, созданных утилитой **zstd**, а также сырых сжатых потоков zstd.1617Модуль `compression.zstd` содержит:1819- Функция [`open()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.open) и класс [`ZstdFile`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdFile) для чтения и записи сжатых файлов.20- Классы [`ZstdCompressor`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor) и [`ZstdDecompressor`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDecompressor) для инкрементального сжатия и распаковки.21- Функции [`compress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.compress) и [`decompress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.decompress) для одноразового сжатия и распаковки.22- Функции [`train_dict()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.train_dict) и [`finalize_dict()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.finalize_dict), а также класс [`ZstdDict`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict) для обучения и управления словарями Zstandard.23- Классы [`CompressionParameter`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter), [`DecompressionParameter`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.DecompressionParameter) и [`Strategy`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy) для задания расширенных параметров (де)компрессии.2425Это [опциональный модуль](https://python-all.ru/3.16/glossary.html#term-optional-module). Если его нет в вашей копии CPython, обратитесь к документации от вашего дистрибьютора (то есть того, кто предоставил вам Python). Если вы дистрибьютор, обратитесь к [требованиям к опциональным модулям](https://python-all.ru/3.16/using/configure.html#optional-module-requirements).2627## Исключения2829#### `exception compression.zstd.ZstdError`3031Это исключение возбуждается, когда во время сжатия или декомпрессии, либо при инициализации состояния (де)компрессора происходит ошибка.3233## Чтение и запись сжатых файлов3435#### `compression.zstd.open(file, /, mode='rb', *, level=None, options=None, zstd_dict=None, encoding=None, errors=None, newline=None)`3637Открывает файл, сжатый Zstandard, в двоичном или текстовом режиме и возвращает [файловый объект](https://python-all.ru/3.16/glossary.html#term-file-object).3839Аргумент *file* может быть либо именем файла (заданным как объект [`str`](https://python-all.ru/3.16/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes) или [путеподобный](https://python-all.ru/3.16/glossary.html#term-path-like-object)), в этом случае открывается указанный файл, либо существующим файловым объектом для чтения или записи.4041Аргумент mode может быть `'rb'` для чтения (по умолчанию), `'wb'` для перезаписи, `'ab'` для добавления или `'xb'` для исключительного создания. Эквивалентно их можно задать как `'r'`, `'w'`, `'a'` и `'x'` соответственно. Также можно открыть в текстовом режиме с помощью `'rt'`, `'wt'`, `'at'` и `'xt'` соответственно.4243При чтении аргумент *options* может быть словарём с расширенными параметрами декомпрессии; подробнее о поддерживаемых параметрах см. [`DecompressionParameter`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.DecompressionParameter). Аргумент *zstd\_dict* – это экземпляр [`ZstdDict`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict), используемый при декомпрессии. При чтении, если аргумент *level* не равен None, будет возбуждено `TypeError`.4445При записи аргумент *options* может быть словарём с расширенными параметрами сжатия; подробнее о поддерживаемых параметрах см. [`CompressionParameter`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter). Аргумент *level* – уровень сжатия, используемый при записи сжатых данных. Только один из *level* или *options* может быть не равен None. Аргумент *zstd\_dict* – экземпляр [`ZstdDict`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict), используемый при сжатии.4647В двоичном режиме эта функция эквивалентна конструктору [`ZstdFile`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdFile): `ZstdFile(file, mode, ...)`. В этом случае параметры *encoding*, *errors* и *newline* не должны указываться.4849В текстовом режиме создаётся объект [`ZstdFile`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdFile), обёрнутый в экземпляр [`io.TextIOWrapper`](https://python-all.ru/3.16/library/io.html#io.TextIOWrapper) с указанными кодировкой, поведением обработки ошибок и символами конца строки.5051#### `class compression.zstd.ZstdFile(file, /, mode='rb', *, level=None, options=None, zstd_dict=None)`5253Открывает файл, сжатый Zstandard, в двоичном режиме.5455`ZstdFile` может обёртывать уже открытый [файловый объект](https://python-all.ru/3.16/glossary.html#term-file-object) или работать напрямую с именованным файлом. Аргумент *file* задаёт либо обёртываемый файловый объект, либо имя открываемого файла (как объект [`str`](https://python-all.ru/3.16/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes) или [путеподобный](https://python-all.ru/3.16/glossary.html#term-path-like-object)). При обёртывании существующего файлового объекта обёрнутый файл не будет закрыт при закрытии `ZstdFile`.5657Аргумент *mode* может быть `'rb'` для чтения (по умолчанию), `'wb'` для перезаписи, `'xb'` для исключительного создания или `'ab'` для добавления. Эквивалентно их можно задать как `'r'`, `'w'`, `'x'` и `'a'` соответственно.5859Если *file* – файловый объект (а не собственно имя файла), то режим `'w'` не усекает файл, а эквивалентен `'a'`.6061При чтении аргумент *options* может быть словарём с расширенными параметрами декомпрессии; подробнее о поддерживаемых параметрах см. [`DecompressionParameter`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.DecompressionParameter). Аргумент *zstd\_dict* – экземпляр [`ZstdDict`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict), используемый при декомпрессии. При чтении, если аргумент *level* не None, будет возбуждено `TypeError`.6263При записи аргумент *options* может быть словарём с расширенными параметрами сжатия; подробнее о поддерживаемых параметрах см. [`CompressionParameter`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter). Аргумент *level* – уровень сжатия, используемый при записи сжатых данных. Можно передать только один из *level* или *options*. Аргумент *zstd\_dict* – экземпляр [`ZstdDict`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict), используемый при сжатии.6465`ZstdFile` поддерживает все члены, указанные в [`io.BufferedIOBase`](https://python-all.ru/3.16/library/io.html#io.BufferedIOBase), за исключением [`detach()`](https://python-all.ru/3.16/library/io.html#io.BufferedIOBase.detach) и [`truncate()`](https://python-all.ru/3.16/library/io.html#io.IOBase.truncate). Поддерживаются итерация и оператор [`with`](https://python-all.ru/3.16/reference/compound_stmts.html#with).6667Также предоставляются следующие методы и атрибуты:6869#### `peek(size=-1)`7071Возвращает буферизованные данные, не сдвигая позицию в файле. Будет возвращён как минимум один байт данных, если не достигнут EOF. Точное количество возвращаемых байт не определено (аргумент *size* игнорируется).7273> **Примечание**74>75> Хотя вызов `peek()` не изменяет позицию файла в `ZstdFile`, он может изменить позицию нижележащего файлового объекта (например, если `ZstdFile` был создан путём передачи файлового объекта в *file*).7677#### `mode`7879`'rb'` для чтения и `'wb'` для записи.8081#### `name`8283Имя файла Zstandard. Эквивалентно атрибуту [`name`](https://python-all.ru/3.16/library/io.html#io.FileIO.name) нижележащего [файлового объекта](https://python-all.ru/3.16/glossary.html#term-file-object).8485## Сжатие и распаковка данных в памяти8687#### `compression.zstd.compress(data, level=None, options=None, zstd_dict=None)`8889Сжимает *data* ([объект, подобный байтам](https://python-all.ru/3.16/glossary.html#term-bytes-like-object)) и возвращает сжатые данные в виде объекта [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes).9091Аргумент *level* – целое число, управляющее степенью сжатия. *level* – альтернатива установке [`CompressionParameter.compression_level`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter.compression_level) в *options*. Используйте [`bounds()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter.bounds) на `compression_level`, чтобы получить значения, которые можно передать для *level*. Если требуются дополнительные параметры сжатия, аргумент *level* должен быть опущен, а в словаре *options* следует задать параметр `CompressionParameter.compression_level`.9293Аргумент *options* – это словарь Python, содержащий дополнительные параметры сжатия. Допустимые ключи и значения для параметров сжатия описаны в документации [`CompressionParameter`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter).9495Аргумент *zstd\_dict* – это экземпляр [`ZstdDict`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict), содержащий обученные данные для повышения эффективности сжатия. Для генерации словаря Zstandard можно использовать функцию [`train_dict()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.train_dict).9697#### `compression.zstd.decompress(data, zstd_dict=None, options=None)`9899Распаковывает *data* ([объект, подобный байтам](https://python-all.ru/3.16/glossary.html#term-bytes-like-object)) и возвращает распакованные данные в виде объекта [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes).100101Аргумент *options* – это словарь Python, содержащий расширенные параметры декомпрессии. Допустимые ключи и значения для параметров сжатия документированы в [`DecompressionParameter`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.DecompressionParameter).102103Аргумент *zstd\_dict* – это экземпляр [`ZstdDict`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict), содержащий обученные данные, использованные при сжатии. Он должен быть тем же самым словарём Zstandard, который использовался при сжатии.104105Если *data* представляет собой объединение нескольких отдельных сжатых фреймов, распакуйте все эти фреймы и верните объединение результатов.106107#### `class compression.zstd.ZstdCompressor(level=None, options=None, zstd_dict=None)`108109Создаёт объект компрессора, который можно использовать для инкрементального сжатия данных.110111Для более удобного сжатия одного фрагмента данных обратитесь к функции уровня модуля [`compress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.compress).112113Аргумент *level* – целое число, управляющее степенью сжатия. *level* – альтернатива установке [`CompressionParameter.compression_level`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter.compression_level) в *options*. Используйте [`bounds()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter.bounds) на `compression_level`, чтобы получить значения, которые можно передать для *level*. Если требуются дополнительные параметры сжатия, аргумент *level* должен быть опущен, а в словаре *options* следует задать параметр `CompressionParameter.compression_level`.114115Аргумент *options* – это словарь Python, содержащий дополнительные параметры сжатия. Допустимые ключи и значения для параметров сжатия описаны в документации [`CompressionParameter`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter).116117Аргумент *zstd\_dict* – необязательный экземпляр [`ZstdDict`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict), содержащий обученные данные для повышения эффективности сжатия. Для генерации словаря Zstandard можно использовать функцию [`train_dict()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.train_dict).118119#### `compress(data, mode=ZstdCompressor.CONTINUE)`120121Сжимает *data* ([объект, подобный байтам](https://python-all.ru/3.16/glossary.html#term-bytes-like-object)) и возвращает объект [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes) со сжатыми данными, если возможно, или пустой объект `bytes` в противном случае. Часть *data* может быть помещена во внутренний буфер для использования в последующих вызовах `compress()` и [`flush()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.flush). Возвращаемые данные следует объединять с выводом всех предыдущих вызовов `compress()`.122123Аргумент *mode* – это атрибут `ZstdCompressor`: [`CONTINUE`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.CONTINUE), [`FLUSH_BLOCK`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_BLOCK) или [`FLUSH_FRAME`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME).124125Когда все данные переданы компрессору, вызовите метод [`flush()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.flush) для завершения процесса сжатия. Если `compress()` вызывается с *mode*, установленным в [`FLUSH_FRAME`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME), не следует вызывать `flush()`, так как это запишет новый пустой фрейм.126127#### `flush(mode=ZstdCompressor.FLUSH_FRAME)`128129Завершает процесс сжатия, возвращая объект [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes), содержащий данные, хранящиеся во внутренних буферах компрессора.130131Аргумент *mode* – это атрибут `ZstdCompressor`: [`FLUSH_BLOCK`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_BLOCK) или [`FLUSH_FRAME`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME).132133#### `set_pledged_input_size(size)`134135Задаёт объём несжатых данных *size*, которые будут предоставлены для следующего фрейма. *size* будет записан в заголовок следующего фрейма, если только [`CompressionParameter.content_size_flag`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter.content_size_flag) не равен `False` или `0`. Размер `0` означает, что фрейм пуст. Если *size* равен `None`, заголовок фрейма будет без указания размера. Фреймы, включающие размер несжатых данных, требуют меньше памяти для распаковки, особенно при высоких степенях сжатия.136137Если [`last_mode`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.last_mode) не равен [`FLUSH_FRAME`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME), возникает исключение [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError), так как компрессор находится не в начале фрейма. Если указанный размер не соответствует фактическому размеру данных, переданных в [`compress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress), будущие вызовы `compress()` или [`flush()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.flush) могут вызвать [`ZstdError`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdError), и последний фрагмент данных может быть потерян.138139После вызова [`flush()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.flush) или [`compress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress) с режимом [`FLUSH_FRAME`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME) следующий фрейм не будет включать размер фрейма в заголовок, если только повторно не вызвать `set_pledged_input_size()`.140141#### `CONTINUE`142143Собирает больше данных для сжатия, что может генерировать выходные данные немедленно или нет. Этот режим оптимизирует степень сжатия, максимизируя объём данных на блок и фрейм.144145#### `FLUSH_BLOCK`146147Завершает и записывает блок в поток данных. Возвращённые на данный момент данные могут быть немедленно распакованы. Предыдущие данные всё ещё могут использоваться в будущих блоках, создаваемых вызовами [`compress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress), что улучшает сжатие.148149#### `FLUSH_FRAME`150151Завершает и записывает кадр. Последующие данные, переданные в [`compress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress), будут записаны в новый кадр и *не могут* ссылаться на предыдущие данные.152153#### `last_mode`154155Последний режим, переданный в [`compress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress) или [`flush()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.flush). Значение может быть [`CONTINUE`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.CONTINUE), [`FLUSH_BLOCK`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_BLOCK) или [`FLUSH_FRAME`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME). Начальное значение – `FLUSH_FRAME`, что означает, что компрессор находится в начале нового кадра.156157#### `class compression.zstd.ZstdDecompressor(zstd_dict=None, options=None)`158159Создаёт объект декомпрессора, который можно использовать для инкрементальной декомпрессии данных.160161Для более удобного способа декомпрессии целого сжатого потока за один раз обратитесь к функции уровня модуля [`decompress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.decompress).162163Аргумент *options* – это словарь Python, содержащий расширенные параметры декомпрессии. Допустимые ключи и значения для параметров сжатия документированы в [`DecompressionParameter`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.DecompressionParameter).164165Аргумент *zstd\_dict* – это экземпляр [`ZstdDict`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict), содержащий обученные данные, использованные при сжатии. Он должен быть тем же самым словарём Zstandard, который использовался при сжатии.166167> **Примечание**168>169> Этот класс не обрабатывает прозрачно входные данные, содержащие несколько сжатых кадров, в отличие от функции [`decompress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.decompress) и класса [`ZstdFile`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdFile). Чтобы декомпрессировать многофреймовый ввод, следует использовать `decompress()`, `ZstdFile` при работе с [файловым объектом](https://python-all.ru/3.16/glossary.html#term-file-object) или несколько экземпляров `ZstdDecompressor`.170171#### `decompress(data, max_length=-1)`172173Декомпрессирует *data* ([байтоподобный объект](https://python-all.ru/3.16/glossary.html#term-bytes-like-object)), возвращая несжатые данные в виде байтов. Часть *data* может быть буферизована внутренне для использования в последующих вызовах `decompress()`. Возвращаемые данные следует объединить с выводом всех предыдущих вызовов `decompress()`.174175Если *max\_length* неотрицателен, метод возвращает не более *max\_length* байт распакованных данных. Если этот предел достигнут и может быть получен дальнейший вывод (или достигнут конец файла), атрибут [`needs_input`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDecompressor.needs_input) будет установлен в `False`. В этом случае следующий вызов `decompress()` может передать *data* как `b''`, чтобы получить ещё порцию вывода. Таким образом, полное содержимое можно прочитать следующим образом:176177```python178process_output(d.decompress(data, max_length))179while not d.eof and not d.needs_input:180    process_output(d.decompress(b"", max_length))181```182183Если все входные данные были декомпрессированы и возвращены (либо потому что это было меньше *max\_length* байтов, либо потому что *max\_length* было отрицательным), атрибут [`needs_input`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDecompressor.needs_input) будет установлен в `True`.184185Попытка декомпрессии данных после конца кадра вызовет исключение [`ZstdError`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdError). Любые данные, обнаруженные после конца кадра, игнорируются и сохраняются в атрибуте [`unused_data`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDecompressor.unused_data).186187#### `eof`188189`True`, если достигнут маркер конца потока.190191#### `unused_data`192193Данные, обнаруженные после конца сжатого потока.194195До достижения конца потока это будет `b''`.196197#### `needs_input`198199`False`, если метод [`decompress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDecompressor.decompress) может предоставить больше декомпрессированных данных до запроса нового сжатого ввода.200201## Словари Zstandard202203#### `compression.zstd.train_dict(samples, dict_size)`204205Обучает словарь Zstandard, возвращая экземпляр [`ZstdDict`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict). Словари Zstandard обеспечивают более эффективное сжатие небольших объёмов данных, которые традиционно трудно сжимать из-за меньшей повторяемости. Если сжимаются несколько похожих групп данных (например, похожие файлы), словари Zstandard могут значительно улучшить степень сжатия и скорость.206207Аргумент *samples* (итерируемый объект из [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes)) – это набор образцов, используемый для обучения словаря Zstandard.208209Аргумент *dict\_size*, целое число, задаёт максимальный размер (в байтах) словаря Zstandard. В документации Zstandard рекомендуется абсолютный максимум не более 100 КБ, но часто можно использовать меньший размер в зависимости от данных. Более крупные словари обычно замедляют сжатие, но улучшают степень сжатия. Меньшие словари ускоряют сжатие, но снижают степень сжатия.210211#### `compression.zstd.finalize_dict(zstd_dict, /, samples, dict_size, level)`212213Расширенная функция для преобразования словаря Zstandard с «сырым содержимым» в обычный словарь Zstandard. Словари с «сырым содержимым» – это последовательность байтов, которая не обязана следовать структуре обычного словаря Zstandard.214215Аргумент *zstd\_dict* – это экземпляр [`ZstdDict`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict) с [`dict_content`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict.dict_content), содержащим сырое содержимое словаря.216217Аргумент *samples* (итерируемый объект из [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes)) содержит образцы данных для генерации словаря Zstandard.218219Аргумент *dict\_size*, целое число, задаёт максимальный размер (в байтах) словаря Zstandard. См. [`train_dict()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.train_dict) для рекомендаций по максимальному размеру словаря.220221Аргумент *level* (целое число) – это уровень сжатия, который ожидается для передачи компрессорам, использующим этот словарь. Информация словаря меняется для каждого уровня сжатия, поэтому настройка на правильный уровень сжатия может сделать сжатие более эффективным.222223#### `class compression.zstd.ZstdDict(dict_content, /, *, is_raw=False)`224225Обёртка вокруг словарей Zstandard. Словари можно использовать для улучшения сжатия множества небольших фрагментов данных. Используйте [`train_dict()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.train_dict), если нужно обучить новый словарь на основе образцов данных.226227Аргумент *dict\_content* ([байтоподобный объект](https://python-all.ru/3.16/glossary.html#term-bytes-like-object)) – это информация уже обученного словаря.228229Аргумент *is\_raw*, логическое значение, – это расширенный параметр, управляющий значением *dict\_content*. `True` означает, что *dict\_content* является словарём в формате «сырое содержимое» без каких-либо ограничений по формату. `False` означает, что *dict\_content* – это обычный словарь Zstandard, созданный с помощью функций Zstandard, например, [`train_dict()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.train_dict) или внешней утилиты командной строки **zstd**.230231При передаче `ZstdDict` в функцию атрибуты `as_digested_dict` и `as_undigested_dict` могут управлять тем, как загружается словарь, если передать их в качестве аргумента `zstd_dict`, например, `compress(data, zstd_dict=zd.as_digested_dict)`. Подготовка словаря – это затратная операция, выполняемая при загрузке словаря Zstandard. Если при многократных вызовах сжатия или разжатия передавать подготовленный словарь, это снизит накладные расходы на загрузку словаря.232233> |  | Подготовленный словарь | Неподготовленный словарь |234> | --- | --- | --- |235> | Расширенные параметры компрессора, которые могут быть переопределены параметрами словаря | `window_log`, `hash_log`, `chain_log`, `search_log`, `min_match`, `target_length`, `strategy`, `enable_long_distance_matching`, `ldm_hash_log`, `ldm_min_match`, `ldm_bucket_size_log`, `ldm_hash_rate_log` и некоторые непубличные параметры. | None |236> | `ZstdDict` внутренне кэширует словарь | Да. Это быстрее при повторной загрузке подготовленного словаря с тем же уровнем сжатия. | Нет. Если требуется загрузить неподготовленный словарь несколько раз, рассмотрите возможность повторного использования объекта компрессора. |237238Если передаётся `ZstdDict` без каких-либо атрибутов, по умолчанию при сжатии передаётся неподготовленный словарь, а при разжатии при необходимости создаётся и по умолчанию передаётся подготовленный словарь.239240> #### `dict_content`241>242> Содержимое словаря Zstandard, объект `bytes`. Оно совпадает с аргументом *dict\_content* в методе `__init__`. Его можно использовать с другими программами, например, с программой командной строки `zstd`.243>244> #### `dict_id`245>246> Идентификатор словаря Zstandard, неотрицательное целое значение.247>248> Ненулевое значение означает, что словарь является обычным, созданным функциями Zstandard и следующим формату Zstandard.249>250> `0` означает словарь в формате «сырое содержимое», свободный от каких-либо ограничений формата, используемый продвинутыми пользователями.251>252> > **Примечание**253> >254> > Значение `0` для `ZstdDict.dict_id` отличается от атрибута `dictionary_id` функции [`get_frame_info()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.get_frame_info).255>256> #### `as_digested_dict`257>258> Загрузить как подготовленный словарь.259>260> #### `as_undigested_dict`261>262> Загрузить как неподготовленный словарь.263264## Управление расширенными параметрами265266#### `class compression.zstd.CompressionParameter`267268[`IntEnum`](https://python-all.ru/3.16/library/enum.html#enum.IntEnum), содержащий ключи расширенных параметров сжатия, которые можно использовать при сжатии данных.269270Метод [`bounds()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter.bounds) можно вызывать для любого атрибута, чтобы получить допустимые значения для этого параметра.271272Параметры необязательны; для любого пропущенного параметра значение будет выбрано автоматически.273274Пример получения нижней и верхней границы [`compression_level`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter.compression_level):275276```python277lower, upper = CompressionParameter.compression_level.bounds()278```279280Пример установки [`window_log`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter.window_log) на максимальный размер:281282```python283_lower, upper = CompressionParameter.window_log.bounds()284options = {CompressionParameter.window_log: upper}285compress(b'venezuelan beaver cheese', options=options)286```287288#### `bounds()`289290Возвращает кортеж границ типа int, `(lower, upper)`, для параметра сжатия. Этот метод следует вызывать для атрибута, границы которого необходимо получить. Например, чтобы узнать допустимые значения для [`compression_level`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter.compression_level), можно проверить результат `CompressionParameter.compression_level.bounds()`.291292Верхняя и нижняя границы включены.293294#### `compression_level`295296Высокоуровневое средство настройки других параметров сжатия, влияющих на скорость и степень сжатия данных.297298Обычные уровни сжатия больше `0`. Значения больше `20` считаются «ультра»-сжатием и требуют больше памяти, чем другие уровни. Отрицательные значения можно использовать для ускорения сжатия ценой ухудшения степени сжатия.299300Установка уровня в ноль использует [`COMPRESSION_LEVEL_DEFAULT`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.COMPRESSION_LEVEL_DEFAULT).301302#### `window_log`303304Максимально допустимое расстояние обратной ссылки, которое может использовать компрессор при сжатии данных, выражается как степень двойки: `1 << window_log` байт. Этот параметр сильно влияет на использование памяти при сжатии. Большие значения требуют больше памяти, но обеспечивают лучшую степень сжатия.305306Значение 0 приводит к автоматическому выбору значения.307308#### `hash_log`309310Размер начальной таблицы поиска (probe table) в виде степени двойки. Результирующее использование памяти составляет `1 << (hash_log+2)` байт. Более крупные таблицы улучшают степень сжатия для стратегий \<= [`dfast`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy.dfast) и увеличивают скорость сжатия для стратегий \> `dfast`.311312Значение 0 приводит к автоматическому выбору значения.313314#### `chain_log`315316Размер таблицы множественного поиска (multi-probe search table) в виде степени двойки. Результирующее использование памяти составляет `1 << (chain_log+2)` байт. Более крупные таблицы приводят к лучшему, но более медленному сжатию. Этот параметр не влияет на стратегию [`fast`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy.fast). Он всё ещё полезен при использовании стратегии [`dfast`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy.dfast), в этом случае он определяет вторичную таблицу поиска.317318Значение 0 приводит к автоматическому выбору значения.319320#### `search_log`321322Количество попыток поиска в виде степени двойки. Большее количество попыток даёт лучшее, но более медленное сжатие. Этот параметр бесполезен для стратегий [`fast`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy.fast) и [`dfast`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy.dfast).323324Значение 0 приводит к автоматическому выбору значения.325326#### `min_match`327328Минимальный размер искомых совпадений. Большие значения увеличивают скорость сжатия и распаковки, но уменьшают степень сжатия. Обратите внимание, что Zstandard всё ещё может находить совпадения меньшего размера – алгоритм просто настраивается на поиск совпадений этого размера и больше. Для всех стратегий \< [`btopt`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy.btopt) эффективный минимум равен `4`; для всех стратегий \> [`fast`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy.fast) эффективный максимум равен `6`.329330Значение 0 приводит к автоматическому выбору значения.331332#### `target_length`333334Влияние этого поля зависит от выбранного [`Strategy`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy).335336Для стратегий [`btopt`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy.btopt), [`btultra`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy.btultra) и [`btultra2`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy.btultra2) значение – это длина совпадения, считающегося «достаточно хорошим» для прекращения поиска. Большие значения улучшают степень сжатия, но замедляют сжатие.337338Для стратегии [`fast`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy.fast) это расстояние между выборками совпадений. Большие значения ускоряют сжатие, но ухудшают степень сжатия.339340Значение 0 приводит к автоматическому выбору значения.341342#### `strategy`343344Чем выше значение выбранной стратегии, тем более сложную технику сжатия использует zstd, что приводит к более высокой степени сжатия, но замедляет сжатие.345346> **См. также**347>348> [`Strategy`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy)349350#### `enable_long_distance_matching`351352Сопоставление на больших расстояниях (long distance matching) может использоваться для улучшения сжатия больших входных данных за счёт нахождения больших совпадений на больших расстояниях. Это увеличивает использование памяти и размер окна.353354`True` или `1` включают сопоставление на больших расстояниях, а `False` или `0` отключают его.355356Включение этого параметра увеличивает значение по умолчанию [`window_log`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter.window_log) до 128 МиБ, если только явно не задано другое значение. Этот параметр включён по умолчанию, если `window_log` \>= 128 МиБ и стратегия сжатия \>= [`btopt`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.Strategy.btopt) (уровень сжатия 16+).357358#### `ldm_hash_log`359360Размер таблицы для поиска совпадений на больших расстояниях, задаваемый как степень двойки. Большие значения увеличивают использование памяти и степень сжатия, но снижают скорость сжатия.361362Значение 0 приводит к автоматическому выбору значения.363364#### `ldm_min_match`365366Минимальный размер совпадения для средства поиска на больших расстояниях. Слишком большие или слишком маленькие значения часто могут снижать степень сжатия.367368Значение 0 приводит к автоматическому выбору значения.369370#### `ldm_bucket_size_log`371372Логарифмический размер каждой корзины в хеш-таблице средства поиска на больших расстояниях для разрешения коллизий. Большие значения улучшают разрешение коллизий, но снижают скорость сжатия.373374Значение 0 приводит к автоматическому выбору значения.375376#### `ldm_hash_rate_log`377378Частота вставки/поиска записей в хеш-таблице средства поиска на больших расстояниях. Большие значения улучшают скорость сжатия. Сильное отклонение от значения по умолчанию, скорее всего, приведет к снижению степени сжатия.379380Значение 0 приводит к автоматическому выбору значения.381382#### `content_size_flag`383384Записывать размер сжимаемых данных в заголовок фрейма Zstandard, если он известен до начала сжатия.385386Этот флаг действует только в следующих сценариях:387388- Вызов [`compress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.compress) для одноразового сжатия389- Передача всех сжимаемых данных во фрейме одним вызовом [`ZstdCompressor.compress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress) в режиме [`ZstdCompressor.FLUSH_FRAME`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME).390- Вызов [`ZstdCompressor.set_pledged_input_size()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.set_pledged_input_size) с точным объемом данных, который будет передан компрессору до любых вызовов [`ZstdCompressor.compress()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress) для текущего фрейма. `ZstdCompressor.set_pledged_input_size()` должен вызываться для каждого нового фрейма.391392Все остальные вызовы сжатия могут не записывать информацию о размере в заголовок фрейма.393394`True` или `1` включают флаг размера содержимого, а `False` или `0` отключают его.395396#### `checksum_flag`397398Четырехбайтовая контрольная сумма по алгоритму XXHash64 от несжатого содержимого записывается в конце каждого фрейма. Код декомпрессии Zstandard проверяет контрольную сумму. При несовпадении возбуждается исключение [`ZstdError`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdError).399400`True` или `1` включают генерацию контрольной суммы, а `False` или `0` отключают её.401402#### `dict_id_flag`403404При сжатии с использованием [`ZstdDict`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.ZstdDict) идентификатор словаря записывается в заголовок фрейма.405406`True` или `1` включают сохранение идентификатора словаря, а `False` или `0` отключают его.407408#### `nb_workers`409410Выбор количества потоков, которые будут порождены для параллельного сжатия. Когда `nb_workers` \> 0, включает многопоточное сжатие; значение `1` означает «однопоточный многопоточный режим». Больше рабочих потоков повышает скорость, но также увеличивает использование памяти и незначительно снижает степень сжатия.411412Нулевое значение отключает многопоточность.413414#### `job_size`415416Размер задания на сжатие в байтах. Это значение применяется только при [`nb_workers`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter.nb_workers) \>= 1. Каждое задание на сжатие выполняется параллельно, поэтому это значение может косвенно влиять на количество активных потоков.417418Значение 0 приводит к автоматическому выбору значения.419420#### `overlap_log`421422Определяет, сколько данных загружается повторно из предыдущих задач (потоков) для новых задач, чтобы они использовались окном просмотра назад при сжатии. Это значение применяется только при [`nb_workers`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.CompressionParameter.nb_workers) \>= 1. Допустимые значения – от 0 до 9.423424> - 0 – динамически устанавливать величину перекрытия425> - 1 – без перекрытия426> - 9 – использовать полный размер окна из предыдущего задания427428Каждое приращение уменьшает или увеличивает размер перекрытия вдвое. «8» означает перекрытие `window_size/2`, «7» – перекрытие `window_size/4` и т.д.429430#### `class compression.zstd.DecompressionParameter`431432[`IntEnum`](https://python-all.ru/3.16/library/enum.html#enum.IntEnum), содержащий ключи расширенных параметров декомпрессии, которые можно использовать при декомпрессии данных. Параметры необязательны; для любого пропущенного параметра значение будет выбрано автоматически.433434Метод [`bounds()`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.DecompressionParameter.bounds) можно вызывать для любого атрибута, чтобы получить допустимые значения для этого параметра.435436Пример установки [`window_log_max`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.DecompressionParameter.window_log_max) на максимальный размер:437438```python439data = compress(b'Some very long buffer of bytes...')440441_lower, upper = DecompressionParameter.window_log_max.bounds()442443options = {DecompressionParameter.window_log_max: upper}444decompress(data, options=options)445```446447#### `bounds()`448449Возвращает кортеж целочисленных границ `(lower, upper)` параметра декомпрессии. Этот метод следует вызывать для того атрибута, границы которого требуется получить.450451Верхняя и нижняя границы включены.452453#### `window_log_max`454455Двоичный логарифм максимального размера окна, используемого при декомпрессии. Это может быть полезно для ограничения объёма памяти, используемого при декомпрессии данных. Больший максимальный размер окна приводит к более быстрой декомпрессии.456457Значение 0 приводит к автоматическому выбору значения.458459#### `class compression.zstd.Strategy`460461[`IntEnum`](https://python-all.ru/3.16/library/enum.html#enum.IntEnum), содержащий стратегии сжатия. Стратегии с бо́льшими номерами соответствуют более сложному и медленному сжатию.462463> **Примечание**464>465> Значения атрибутов `Strategy` не обязательно стабильны в разных версиях zstd. Можно полагаться только на порядок атрибутов. Атрибуты перечислены ниже по порядку.466467Доступны следующие стратегии:468469#### `fast`470471#### `dfast`472473#### `greedy`474475#### `lazy`476477#### `lazy2`478479#### `btlazy2`480481#### `btopt`482483#### `btultra`484485#### `btultra2`486487## Разное488489#### `compression.zstd.get_frame_info(frame_buffer)`490491Извлекает объект [`FrameInfo`](https://python-all.ru/3.16/library/compression.zstd.html#compression.zstd.FrameInfo), содержащий метаданные о фрейме Zstandard. Фреймы содержат метаданные, связанные с хранящимися в них сжатыми данными.492493#### `class compression.zstd.FrameInfo`494495Метаданные, относящиеся к фрейму Zstandard.496497#### `decompressed_size`498499Размер распакованных данных фрейма.500501#### `dictionary_id`502503Целое число, представляющее идентификатор словаря Zstandard, необходимый для распаковки фрейма. Значение `0` означает, что идентификатор словаря не был записан в заголовке фрейма. Это может означать, что словарь Zstandard не требуется, или что идентификатор необходимого словаря не был записан.504505#### `compression.zstd.COMPRESSION_LEVEL_DEFAULT`506507Уровень сжатия по умолчанию для Zstandard: `3`.508509#### `compression.zstd.zstd_version_info`510511Номер версии библиотеки zstd времени выполнения в виде кортежа целых чисел (major, minor, release).512513## Примеры514515Чтение сжатого файла:516517```python518from compression import zstd519520with zstd.open("file.zst") as f:521    file_content = f.read()522```523524Создание сжатого файла:525526```python527from compression import zstd528529data = b"Insert Data Here"530with zstd.open("file.zst", "w") as f:531    f.write(data)532```533534Сжатие данных в памяти:535536```python537from compression import zstd538539data_in = b"Insert Data Here"540data_out = zstd.compress(data_in)541```542543Инкрементальное сжатие:544545```python546from compression import zstd547548comp = zstd.ZstdCompressor()549out1 = comp.compress(b"Some data\n")550out2 = comp.compress(b"Another piece of data\n")551out3 = comp.compress(b"Even more data\n")552out4 = comp.flush()553# Объединить все частичные результаты:554result = b"".join([out1, out2, out3, out4])555```556557Запись сжатых данных в уже открытый файл:558559```python560from compression import zstd561562with open("myfile", "wb") as f:563    f.write(b"This data will not be compressed\n")564    with zstd.open(f, "w") as zstf:565        zstf.write(b"This *will* be compressed\n")566    f.write(b"Not compressed\n")567```568569Создание сжатого файла с использованием параметров сжатия:570571```python572from compression import zstd573574options = {575   zstd.CompressionParameter.checksum_flag: 1576}577with zstd.open("file.zst", "w", options=options) as f:578    f.write(b"Mind if I squeeze in?")579```580