> **Источник:** https://python-all.ru/3/library/compression.zstd.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# `compression.zstd` – Сжатие, совместимое с форматом Zstandard

Добавлено в версии 3.14.

**Исходный код:** [Lib/compression/zstd/\_\_init\_\_.py](https://python-all.ru/src/3.14/Lib/compression/zstd/__init__.py)

---

Этот модуль предоставляет классы и функции для сжатия и декомпрессии данных с использованием алгоритма сжатия Zstandard (или *zstd*). [Руководство по zstd](https://python-all.ru/3/library/compression.zstd.html) описывает Zstandard как «быстрый алгоритм сжатия без потерь, предназначенный для сценариев сжатия в реальном времени на уровне zlib и с лучшим коэффициентом сжатия». Также включён файловый интерфейс, поддерживающий чтение и запись содержимого файлов `.zst`, созданных утилитой **zstd**, а также сырых сжатых потоков zstd.

Модуль `compression.zstd` содержит:

- Функция [`open()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.open) и класс [`ZstdFile`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdFile) для чтения и записи сжатых файлов.
- Классы [`ZstdCompressor`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor) и [`ZstdDecompressor`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDecompressor) для инкрементального сжатия и распаковки.
- Функции [`compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.compress) и [`decompress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.decompress) для одноразового сжатия и распаковки.
- Функции [`train_dict()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.train_dict) и [`finalize_dict()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.finalize_dict), а также класс [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict) для обучения и управления словарями Zstandard.
- Классы [`CompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter), [`DecompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.DecompressionParameter) и [`Strategy`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy) для задания расширенных параметров (де)компрессии.

Это [опциональный модуль](https://python-all.ru/3/glossary.html#term-optional-module). Если его нет в вашей копии CPython, обратитесь к документации от вашего дистрибьютора (то есть того, кто предоставил вам Python). Если вы дистрибьютор, обратитесь к [требованиям к опциональным модулям](https://python-all.ru/3/using/configure.html#optional-module-requirements).

## Исключения

#### `exception compression.zstd.ZstdError`

Это исключение возбуждается, когда во время сжатия или декомпрессии, либо при инициализации состояния (де)компрессора происходит ошибка.

## Чтение и запись сжатых файлов

#### `compression.zstd.open(file, /, mode='rb', *, level=None, options=None, zstd_dict=None, encoding=None, errors=None, newline=None)`

Открывает файл, сжатый Zstandard, в двоичном или текстовом режиме и возвращает [файловый объект](https://python-all.ru/3/glossary.html#term-file-object).

Аргумент *file* может быть либо именем файла (заданным как объект [`str`](https://python-all.ru/3/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes) или [путеподобный](https://python-all.ru/3/glossary.html#term-path-like-object)), в этом случае открывается указанный файл, либо существующим файловым объектом для чтения или записи.

Аргумент mode может быть `'rb'` для чтения (по умолчанию), `'wb'` для перезаписи, `'ab'` для добавления или `'xb'` для исключительного создания. Эквивалентно их можно задать как `'r'`, `'w'`, `'a'` и `'x'` соответственно. Также можно открыть в текстовом режиме с помощью `'rt'`, `'wt'`, `'at'` и `'xt'` соответственно.

При чтении аргумент *options* может быть словарём с расширенными параметрами декомпрессии; подробнее о поддерживаемых параметрах см. [`DecompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.DecompressionParameter). Аргумент *zstd\_dict* – это экземпляр [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict), используемый при декомпрессии. При чтении, если аргумент *level* не равен None, будет возбуждено `TypeError`.

При записи аргумент *options* может быть словарём с расширенными параметрами сжатия; подробнее о поддерживаемых параметрах см. [`CompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter). Аргумент *level* – уровень сжатия, используемый при записи сжатых данных. Только один из *level* или *options* может быть не равен None. Аргумент *zstd\_dict* – экземпляр [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict), используемый при сжатии.

В двоичном режиме эта функция эквивалентна конструктору [`ZstdFile`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdFile): `ZstdFile(file, mode, ...)`. В этом случае параметры *encoding*, *errors* и *newline* не должны указываться.

В текстовом режиме создаётся объект [`ZstdFile`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdFile), обёрнутый в экземпляр [`io.TextIOWrapper`](https://python-all.ru/3/library/io.html#io.TextIOWrapper) с указанными кодировкой, поведением обработки ошибок и символами конца строки.

#### `class compression.zstd.ZstdFile(file, /, mode='rb', *, level=None, options=None, zstd_dict=None)`

Открывает файл, сжатый Zstandard, в двоичном режиме.

`ZstdFile` может обёртывать уже открытый [файловый объект](https://python-all.ru/3/glossary.html#term-file-object) или работать напрямую с именованным файлом. Аргумент *file* задаёт либо обёртываемый файловый объект, либо имя открываемого файла (как объект [`str`](https://python-all.ru/3/library/stdtypes.html#str), [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes) или [путеподобный](https://python-all.ru/3/glossary.html#term-path-like-object)). При обёртывании существующего файлового объекта обёрнутый файл не будет закрыт при закрытии `ZstdFile`.

Аргумент *mode* может быть `'rb'` для чтения (по умолчанию), `'wb'` для перезаписи, `'xb'` для исключительного создания или `'ab'` для добавления. Эквивалентно их можно задать как `'r'`, `'w'`, `'x'` и `'a'` соответственно.

Если *file* – файловый объект (а не собственно имя файла), то режим `'w'` не усекает файл, а эквивалентен `'a'`.

При чтении аргумент *options* может быть словарём с расширенными параметрами декомпрессии; подробнее о поддерживаемых параметрах см. [`DecompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.DecompressionParameter). Аргумент *zstd\_dict* – экземпляр [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict), используемый при декомпрессии. При чтении, если аргумент *level* не None, будет возбуждено `TypeError`.

При записи аргумент *options* может быть словарём с расширенными параметрами сжатия; подробнее о поддерживаемых параметрах см. [`CompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter). Аргумент *level* – уровень сжатия, используемый при записи сжатых данных. Можно передать только один из *level* или *options*. Аргумент *zstd\_dict* – экземпляр [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict), используемый при сжатии.

`ZstdFile` поддерживает все члены, указанные в [`io.BufferedIOBase`](https://python-all.ru/3/library/io.html#io.BufferedIOBase), за исключением [`detach()`](https://python-all.ru/3/library/io.html#io.BufferedIOBase.detach) и [`truncate()`](https://python-all.ru/3/library/io.html#io.IOBase.truncate). Поддерживаются итерация и оператор [`with`](https://python-all.ru/3/reference/compound_stmts.html#with).

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

#### `peek(size=-1)`

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

> **Примечание**
>
> Хотя вызов `peek()` не изменяет позицию файла в `ZstdFile`, он может изменить позицию нижележащего файлового объекта (например, если `ZstdFile` был создан путём передачи файлового объекта в *file*).

#### `mode`

`'rb'` для чтения и `'wb'` для записи.

#### `name`

Имя файла Zstandard. Эквивалентно атрибуту [`name`](https://python-all.ru/3/library/io.html#io.FileIO.name) нижележащего [файлового объекта](https://python-all.ru/3/glossary.html#term-file-object).

## Сжатие и распаковка данных в памяти

#### `compression.zstd.compress(data, level=None, options=None, zstd_dict=None)`

Сжимает *data* ([объект, подобный байтам](https://python-all.ru/3/glossary.html#term-bytes-like-object)) и возвращает сжатые данные в виде объекта [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes).

Аргумент *level* – целое число, управляющее степенью сжатия. *level* – альтернатива установке [`CompressionParameter.compression_level`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.compression_level) в *options*. Используйте [`bounds()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.bounds) на `compression_level`, чтобы получить значения, которые можно передать для *level*. Если требуются дополнительные параметры сжатия, аргумент *level* должен быть опущен, а в словаре *options* следует задать параметр `CompressionParameter.compression_level`.

Аргумент *options* – это словарь Python, содержащий дополнительные параметры сжатия. Допустимые ключи и значения для параметров сжатия описаны в документации [`CompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter).

Аргумент *zstd\_dict* – это экземпляр [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict), содержащий обученные данные для повышения эффективности сжатия. Для генерации словаря Zstandard можно использовать функцию [`train_dict()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.train_dict).

#### `compression.zstd.decompress(data, zstd_dict=None, options=None)`

Распаковывает *data* ([объект, подобный байтам](https://python-all.ru/3/glossary.html#term-bytes-like-object)) и возвращает распакованные данные в виде объекта [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes).

Аргумент *options* – это словарь Python, содержащий дополнительные параметры распаковки. Допустимые ключи и значения для параметров сжатия описаны в документации [`DecompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.DecompressionParameter).

Аргумент *zstd\_dict* – это экземпляр [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict), содержащий обученные данные, использовавшиеся при сжатии. Это должен быть тот же самый словарь Zstandard, который использовался при сжатии.

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

#### `class compression.zstd.ZstdCompressor(level=None, options=None, zstd_dict=None)`

Создаёт объект компрессора, который можно использовать для инкрементального сжатия данных.

Для более удобного сжатия одного фрагмента данных обратитесь к функции уровня модуля [`compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.compress).

Аргумент *level* – целое число, управляющее степенью сжатия. *level* – альтернатива установке [`CompressionParameter.compression_level`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.compression_level) в *options*. Используйте [`bounds()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.bounds) на `compression_level`, чтобы получить значения, которые можно передать для *level*. Если требуются дополнительные параметры сжатия, аргумент *level* должен быть опущен, а в словаре *options* следует задать параметр `CompressionParameter.compression_level`.

Аргумент *options* – это словарь Python, содержащий дополнительные параметры сжатия. Допустимые ключи и значения для параметров сжатия описаны в документации [`CompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter).

Аргумент *zstd\_dict* – необязательный экземпляр [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict), содержащий обученные данные для повышения эффективности сжатия. Для генерации словаря Zstandard можно использовать функцию [`train_dict()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.train_dict).

#### `compress(data, mode=ZstdCompressor.CONTINUE)`

Сжимает *data* ([объект, подобный байтам](https://python-all.ru/3/glossary.html#term-bytes-like-object)) и возвращает объект [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes) со сжатыми данными, если возможно, или пустой объект `bytes` в противном случае. Часть *data* может быть помещена во внутренний буфер для использования в последующих вызовах `compress()` и [`flush()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.flush). Возвращаемые данные следует объединять с выводом всех предыдущих вызовов `compress()`.

Аргумент *mode* – это атрибут `ZstdCompressor`: [`CONTINUE`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.CONTINUE), [`FLUSH_BLOCK`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_BLOCK) или [`FLUSH_FRAME`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME).

Когда все данные переданы компрессору, вызовите метод [`flush()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.flush) для завершения процесса сжатия. Если `compress()` вызывается с *mode*, установленным в [`FLUSH_FRAME`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME), не следует вызывать `flush()`, так как это запишет новый пустой фрейм.

#### `flush(mode=ZstdCompressor.FLUSH_FRAME)`

Завершает процесс сжатия, возвращая объект [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes), содержащий данные, хранящиеся во внутренних буферах компрессора.

Аргумент *mode* – это атрибут `ZstdCompressor`: [`FLUSH_BLOCK`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_BLOCK) или [`FLUSH_FRAME`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME).

#### `set_pledged_input_size(size)`

Задаёт объём несжатых данных *size*, которые будут предоставлены для следующего фрейма. *size* будет записан в заголовок следующего фрейма, если только [`CompressionParameter.content_size_flag`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.content_size_flag) не равен `False` или `0`. Размер `0` означает, что фрейм пуст. Если *size* равен `None`, заголовок фрейма будет без указания размера. Фреймы, включающие размер несжатых данных, требуют меньше памяти для распаковки, особенно при высоких степенях сжатия.

Если [`last_mode`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.last_mode) не равен [`FLUSH_FRAME`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME), возникает исключение [`ValueError`](https://python-all.ru/3/library/exceptions.html#ValueError), так как компрессор находится не в начале фрейма. Если указанный размер не соответствует фактическому размеру данных, переданных в [`compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress), будущие вызовы `compress()` или [`flush()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.flush) могут вызвать [`ZstdError`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdError), и последний фрагмент данных может быть потерян.

После вызова [`flush()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.flush) или [`compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress) с режимом [`FLUSH_FRAME`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME) следующий фрейм не будет включать размер фрейма в заголовок, если только повторно не вызвать `set_pledged_input_size()`.

#### `CONTINUE`

Собирает больше данных для сжатия, что может генерировать выходные данные немедленно или нет. Этот режим оптимизирует степень сжатия, максимизируя объём данных на блок и фрейм.

#### `FLUSH_BLOCK`

Завершает и записывает блок в поток данных. Возвращённые на данный момент данные могут быть немедленно распакованы. Предыдущие данные всё ещё могут использоваться в будущих блоках, создаваемых вызовами [`compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress), что улучшает сжатие.

#### `FLUSH_FRAME`

Завершает и записывает кадр. Последующие данные, переданные в [`compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress), будут записаны в новый кадр и *не могут* ссылаться на предыдущие данные.

#### `last_mode`

Последний режим, переданный в [`compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress) или [`flush()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.flush). Значение может быть [`CONTINUE`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.CONTINUE), [`FLUSH_BLOCK`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_BLOCK) или [`FLUSH_FRAME`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME). Начальное значение – `FLUSH_FRAME`, что означает, что компрессор находится в начале нового кадра.

#### `class compression.zstd.ZstdDecompressor(zstd_dict=None, options=None)`

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

Для более удобного способа декомпрессии целого сжатого потока за один раз обратитесь к функции уровня модуля [`decompress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.decompress).

Аргумент *options* – это словарь Python, содержащий расширенные параметры декомпрессии. Допустимые ключи и значения для параметров сжатия документированы в [`DecompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.DecompressionParameter).

Аргумент *zstd\_dict* – это экземпляр [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict), содержащий обученные данные, использованные при сжатии. Он должен быть тем же самым словарём Zstandard, который использовался при сжатии.

> **Примечание**
>
> Этот класс не обрабатывает прозрачно входные данные, содержащие несколько сжатых кадров, в отличие от функции [`decompress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.decompress) и класса [`ZstdFile`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdFile). Чтобы декомпрессировать многофреймовый ввод, следует использовать `decompress()`, `ZstdFile` при работе с [файловым объектом](https://python-all.ru/3/glossary.html#term-file-object) или несколько экземпляров `ZstdDecompressor`.

#### `decompress(data, max_length=-1)`

Декомпрессирует *data* ([байтоподобный объект](https://python-all.ru/3/glossary.html#term-bytes-like-object)), возвращая несжатые данные в виде байтов. Часть *data* может быть буферизована внутренне для использования в последующих вызовах `decompress()`. Возвращаемые данные следует объединить с выводом всех предыдущих вызовов `decompress()`.

Если *max\_length* неотрицателен, метод возвращает не более *max\_length* байт декомпрессированных данных. Если этот лимит достигнут и можно сгенерировать больше данных, атрибут [`needs_input`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDecompressor.needs_input) будет установлен в `False`. В этом случае следующий вызов `decompress()` может передать *data* как `b''` для получения дополнительного вывода.

Если все входные данные были декомпрессированы и возвращены (либо потому что это было меньше *max\_length* байтов, либо потому что *max\_length* было отрицательным), атрибут [`needs_input`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDecompressor.needs_input) будет установлен в `True`.

Попытка декомпрессии данных после конца кадра вызовет исключение [`ZstdError`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdError). Любые данные, обнаруженные после конца кадра, игнорируются и сохраняются в атрибуте [`unused_data`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDecompressor.unused_data).

#### `eof`

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

#### `unused_data`

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

До достижения конца потока это будет `b''`.

#### `needs_input`

`False`, если метод [`decompress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDecompressor.decompress) может предоставить больше декомпрессированных данных до запроса нового сжатого ввода.

## Словари Zstandard

#### `compression.zstd.train_dict(samples, dict_size)`

Обучает словарь Zstandard, возвращая экземпляр [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict). Словари Zstandard обеспечивают более эффективное сжатие небольших объёмов данных, которые традиционно трудно сжимать из-за меньшей повторяемости. Если сжимаются несколько похожих групп данных (например, похожие файлы), словари Zstandard могут значительно улучшить степень сжатия и скорость.

Аргумент *samples* (итерируемый объект из [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes)) – это набор образцов, используемый для обучения словаря Zstandard.

Аргумент *dict\_size*, целое число, задаёт максимальный размер (в байтах) словаря Zstandard. В документации Zstandard рекомендуется абсолютный максимум не более 100 КБ, но часто можно использовать меньший размер в зависимости от данных. Более крупные словари обычно замедляют сжатие, но улучшают степень сжатия. Меньшие словари ускоряют сжатие, но снижают степень сжатия.

#### `compression.zstd.finalize_dict(zstd_dict, /, samples, dict_size, level)`

Расширенная функция для преобразования словаря Zstandard с «сырым содержимым» в обычный словарь Zstandard. Словари с «сырым содержимым» – это последовательность байтов, которая не обязана следовать структуре обычного словаря Zstandard.

Аргумент *zstd\_dict* – это экземпляр [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict) с [`dict_content`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict.dict_content), содержащим сырое содержимое словаря.

Аргумент *samples* (итерируемый объект из [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes)) содержит образцы данных для генерации словаря Zstandard.

Аргумент *dict\_size*, целое число, задаёт максимальный размер (в байтах) словаря Zstandard. См. [`train_dict()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.train_dict) для рекомендаций по максимальному размеру словаря.

Аргумент *level* (целое число) – это уровень сжатия, который ожидается для передачи компрессорам, использующим этот словарь. Информация словаря меняется для каждого уровня сжатия, поэтому настройка на правильный уровень сжатия может сделать сжатие более эффективным.

#### `class compression.zstd.ZstdDict(dict_content, /, *, is_raw=False)`

Обёртка вокруг словарей Zstandard. Словари можно использовать для улучшения сжатия множества небольших фрагментов данных. Используйте [`train_dict()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.train_dict), если нужно обучить новый словарь на основе образцов данных.

Аргумент *dict\_content* ([байтоподобный объект](https://python-all.ru/3/glossary.html#term-bytes-like-object)) – это информация уже обученного словаря.

Аргумент *is\_raw*, логическое значение, – это расширенный параметр, управляющий значением *dict\_content*. `True` означает, что *dict\_content* является словарём в формате «сырое содержимое» без каких-либо ограничений по формату. `False` означает, что *dict\_content* – это обычный словарь Zstandard, созданный с помощью функций Zstandard, например, [`train_dict()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.train_dict) или внешней утилиты командной строки **zstd**.

При передаче `ZstdDict` в функцию атрибуты `as_digested_dict` и `as_undigested_dict` могут управлять тем, как загружается словарь, если передать их в качестве аргумента `zstd_dict`, например, `compress(data, zstd_dict=zd.as_digested_dict)`. Подготовка словаря – это затратная операция, выполняемая при загрузке словаря Zstandard. Если при многократных вызовах сжатия или разжатия передавать подготовленный словарь, это снизит накладные расходы на загрузку словаря.

> |  | Подготовленный словарь | Неподготовленный словарь |
> | --- | --- | --- |
> | Расширенные параметры компрессора, которые могут быть переопределены параметрами словаря | `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 |
> | `ZstdDict` внутренне кэширует словарь | Да. Это быстрее при повторной загрузке подготовленного словаря с тем же уровнем сжатия. | Нет. Если требуется загрузить неподготовленный словарь несколько раз, рассмотрите возможность повторного использования объекта компрессора. |

Если передаётся `ZstdDict` без каких-либо атрибутов, по умолчанию при сжатии передаётся неподготовленный словарь, а при разжатии при необходимости создаётся и по умолчанию передаётся подготовленный словарь.

> #### `dict_content`
>
> Содержимое словаря Zstandard, объект `bytes`. Оно совпадает с аргументом *dict\_content* в методе `__init__`. Его можно использовать с другими программами, например, с программой командной строки `zstd`.
>
> #### `dict_id`
>
> Идентификатор словаря Zstandard, неотрицательное целое значение.
>
> Ненулевое значение означает, что словарь является обычным, созданным функциями Zstandard и следующим формату Zstandard.
>
> `0` означает словарь в формате «сырое содержимое», свободный от каких-либо ограничений формата, используемый продвинутыми пользователями.
>
> > **Примечание**
> >
> > Значение `0` для `ZstdDict.dict_id` отличается от атрибута `dictionary_id` функции [`get_frame_info()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.get_frame_info).
>
> #### `as_digested_dict`
>
> Загрузить как подготовленный словарь.
>
> #### `as_undigested_dict`
>
> Загрузить как неподготовленный словарь.

## Управление расширенными параметрами

#### `class compression.zstd.CompressionParameter`

[`IntEnum`](https://python-all.ru/3/library/enum.html#enum.IntEnum), содержащий ключи расширенных параметров сжатия, которые можно использовать при сжатии данных.

Метод [`bounds()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.bounds) можно использовать для любого атрибута, чтобы получить допустимые значения для этого параметра.

Параметры необязательны; для любого пропущенного параметра значение будет выбрано автоматически.

Пример получения нижней и верхней границы [`compression_level`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.compression_level):

```python
lower, upper = CompressionParameter.compression_level.bounds()
```

Пример установки [`window_log`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.window_log) на максимальный размер:

```python
_lower, upper = CompressionParameter.window_log.bounds()
options = {CompressionParameter.window_log: upper}
compress(b'venezuelan beaver cheese', options=options)
```

#### `bounds()`

Возвращает кортеж границ типа int, `(lower, upper)`, для параметра сжатия. Этот метод следует вызывать для атрибута, границы которого необходимо получить. Например, чтобы узнать допустимые значения для [`compression_level`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.compression_level), можно проверить результат `CompressionParameter.compression_level.bounds()`.

Нижняя и верхняя границы включены.

#### `compression_level`

Высокоуровневое средство настройки других параметров сжатия, влияющих на скорость и степень сжатия данных.

Обычные уровни сжатия больше `0`. Значения больше `20` считаются «ультра»-сжатием и требуют больше памяти, чем другие уровни. Отрицательные значения можно использовать для ускорения сжатия ценой ухудшения степени сжатия.

Установка уровня в ноль использует [`COMPRESSION_LEVEL_DEFAULT`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.COMPRESSION_LEVEL_DEFAULT).

#### `window_log`

Максимально допустимое расстояние обратной ссылки, которое может использовать компрессор при сжатии данных, выражается как степень двойки: `1 << window_log` байт. Этот параметр сильно влияет на использование памяти при сжатии. Большие значения требуют больше памяти, но обеспечивают лучшую степень сжатия.

Значение ноль означает автоматический выбор.

#### `hash_log`

Размер начальной таблицы поиска (probe table) в виде степени двойки. Результирующее использование памяти составляет `1 << (hash_log+2)` байт. Более крупные таблицы улучшают степень сжатия для стратегий \<= [`dfast`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.dfast) и увеличивают скорость сжатия для стратегий \> `dfast`.

Значение ноль означает автоматический выбор.

#### `chain_log`

Размер таблицы множественного поиска (multi-probe search table) в виде степени двойки. Результирующее использование памяти составляет `1 << (chain_log+2)` байт. Более крупные таблицы приводят к лучшему, но более медленному сжатию. Этот параметр не влияет на стратегию [`fast`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.fast). Он всё ещё полезен при использовании стратегии [`dfast`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.dfast), в этом случае он определяет вторичную таблицу поиска.

Значение ноль означает автоматический выбор.

#### `search_log`

Количество попыток поиска в виде степени двойки. Большее количество попыток даёт лучшее, но более медленное сжатие. Этот параметр бесполезен для стратегий [`fast`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.fast) и [`dfast`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.dfast).

Значение ноль означает автоматический выбор.

#### `min_match`

Минимальный размер искомых совпадений. Большие значения увеличивают скорость сжатия и распаковки, но уменьшают степень сжатия. Обратите внимание, что Zstandard всё ещё может находить совпадения меньшего размера – алгоритм просто настраивается на поиск совпадений этого размера и больше. Для всех стратегий \< [`btopt`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.btopt) эффективный минимум равен `4`; для всех стратегий \> [`fast`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.fast) эффективный максимум равен `6`.

Значение ноль означает автоматический выбор.

#### `target_length`

Влияние этого поля зависит от выбранного [`Strategy`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy).

Для стратегий [`btopt`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.btopt), [`btultra`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.btultra) и [`btultra2`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.btultra2) значение – это длина совпадения, считающегося «достаточно хорошим» для прекращения поиска. Большие значения улучшают степень сжатия, но замедляют сжатие.

Для стратегии [`fast`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.fast) это расстояние между выборками совпадений. Большие значения ускоряют сжатие, но ухудшают степень сжатия.

Значение ноль означает автоматический выбор.

#### `strategy`

Чем выше значение выбранной стратегии, тем более сложную технику сжатия использует zstd, что приводит к более высокой степени сжатия, но замедляет сжатие.

> **См. также**
>
> [`Strategy`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy)

#### `enable_long_distance_matching`

Сопоставление на больших расстояниях (long distance matching) может использоваться для улучшения сжатия больших входных данных за счёт нахождения больших совпадений на больших расстояниях. Это увеличивает использование памяти и размер окна.

`True` или `1` включают сопоставление на больших расстояниях, а `False` или `0` отключают его.

Включение этого параметра увеличивает значение по умолчанию [`window_log`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.window_log) до 128 МиБ, если только явно не задано другое значение. Этот параметр включён по умолчанию, если `window_log` \>= 128 МиБ и стратегия сжатия \>= [`btopt`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.btopt) (уровень сжатия 16+).

#### `ldm_hash_log`

Размер таблицы для поиска совпадений на больших расстояниях, задаваемый как степень двойки. Большие значения увеличивают использование памяти и степень сжатия, но снижают скорость сжатия.

Нулевое значение приводит к автоматическому выбору значения.

#### `ldm_min_match`

Минимальный размер совпадения для средства поиска на больших расстояниях. Слишком большие или слишком маленькие значения часто могут снижать степень сжатия.

Нулевое значение приводит к автоматическому выбору значения.

#### `ldm_bucket_size_log`

Логарифмический размер каждой корзины в хеш-таблице средства поиска на больших расстояниях для разрешения коллизий. Большие значения улучшают разрешение коллизий, но снижают скорость сжатия.

Нулевое значение приводит к автоматическому выбору значения.

#### `ldm_hash_rate_log`

Частота вставки/поиска записей в хеш-таблице средства поиска на больших расстояниях. Большие значения улучшают скорость сжатия. Сильное отклонение от значения по умолчанию, скорее всего, приведет к снижению степени сжатия.

Нулевое значение приводит к автоматическому выбору значения.

#### `content_size_flag`

Записывать размер сжимаемых данных в заголовок фрейма Zstandard, если он известен до начала сжатия.

Этот флаг действует только в следующих сценариях:

- Вызов [`compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.compress) для одноразового сжатия
- Передача всех сжимаемых данных во фрейме одним вызовом [`ZstdCompressor.compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress) в режиме [`ZstdCompressor.FLUSH_FRAME`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.FLUSH_FRAME).
- Вызов [`ZstdCompressor.set_pledged_input_size()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.set_pledged_input_size) с точным объемом данных, который будет передан компрессору до любых вызовов [`ZstdCompressor.compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress) для текущего фрейма. `ZstdCompressor.set_pledged_input_size()` должен вызываться для каждого нового фрейма.

Все остальные вызовы сжатия могут не записывать информацию о размере в заголовок фрейма.

`True` или `1` включают флаг размера содержимого, а `False` или `0` отключают его.

#### `checksum_flag`

Четырехбайтовая контрольная сумма по алгоритму XXHash64 от несжатого содержимого записывается в конце каждого фрейма. Код декомпрессии Zstandard проверяет контрольную сумму. При несовпадении возбуждается исключение [`ZstdError`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdError).

`True` или `1` включают генерацию контрольной суммы, а `False` или `0` отключают её.

#### `dict_id_flag`

При сжатии с использованием [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict) идентификатор словаря записывается в заголовок фрейма.

`True` или `1` включают сохранение идентификатора словаря, а `False` или `0` отключают его.

#### `nb_workers`

Выбор количества потоков, которые будут порождены для параллельного сжатия. Когда `nb_workers` \> 0, включает многопоточное сжатие; значение `1` означает «однопоточный многопоточный режим». Больше рабочих потоков повышает скорость, но также увеличивает использование памяти и незначительно снижает степень сжатия.

Нулевое значение отключает многопоточность.

#### `job_size`

Размер задания на сжатие в байтах. Это значение применяется только при [`nb_workers`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.nb_workers) \>= 1. Каждое задание на сжатие выполняется параллельно, поэтому это значение может косвенно влиять на количество активных потоков.

Нулевое значение приводит к автоматическому выбору значения.

#### `overlap_log`

Определяет, сколько данных загружается повторно из предыдущих задач (потоков) для новых задач, чтобы они использовались окном просмотра назад при сжатии. Это значение применяется только при [`nb_workers`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.nb_workers) \>= 1. Допустимые значения – от 0 до 9.

> - 0 – динамически устанавливать величину перекрытия
> - 1 – без перекрытия
> - 9 – использовать полный размер окна из предыдущего задания

Каждое приращение уменьшает или увеличивает размер перекрытия вдвое. «8» означает перекрытие `window_size/2`, «7» – перекрытие `window_size/4` и т.д.

#### `class compression.zstd.DecompressionParameter`

[`IntEnum`](https://python-all.ru/3/library/enum.html#enum.IntEnum), содержащий ключи расширенных параметров декомпрессии, которые можно использовать при декомпрессии данных. Параметры необязательны; для любого пропущенного параметра значение будет выбрано автоматически.

Метод [`bounds()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.DecompressionParameter.bounds) можно вызывать для любого атрибута, чтобы получить допустимые значения для этого параметра.

Пример установки [`window_log_max`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.DecompressionParameter.window_log_max) на максимальный размер:

```python
data = compress(b'Some very long buffer of bytes...')

_lower, upper = DecompressionParameter.window_log_max.bounds()

options = {DecompressionParameter.window_log_max: upper}
decompress(data, options=options)
```

#### `bounds()`

Возвращает кортеж целочисленных границ `(lower, upper)` параметра декомпрессии. Этот метод следует вызывать для того атрибута, границы которого требуется получить.

Верхняя и нижняя границы включены.

#### `window_log_max`

Двоичный логарифм максимального размера окна, используемого при декомпрессии. Это может быть полезно для ограничения объёма памяти, используемого при декомпрессии данных. Больший максимальный размер окна приводит к более быстрой декомпрессии.

Значение 0 приводит к автоматическому выбору значения.

#### `class compression.zstd.Strategy`

[`IntEnum`](https://python-all.ru/3/library/enum.html#enum.IntEnum), содержащий стратегии сжатия. Стратегии с бо́льшими номерами соответствуют более сложному и медленному сжатию.

> **Примечание**
>
> Значения атрибутов `Strategy` не обязательно стабильны в разных версиях zstd. Можно полагаться только на порядок атрибутов. Атрибуты перечислены ниже по порядку.

Доступны следующие стратегии:

#### `fast`

#### `dfast`

#### `greedy`

#### `lazy`

#### `lazy2`

#### `btlazy2`

#### `btopt`

#### `btultra`

#### `btultra2`

## Разное

#### `compression.zstd.get_frame_info(frame_buffer)`

Извлекает объект [`FrameInfo`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.FrameInfo), содержащий метаданные о фрейме Zstandard. Фреймы содержат метаданные, связанные с хранящимися в них сжатыми данными.

#### `class compression.zstd.FrameInfo`

Метаданные, относящиеся к фрейму Zstandard.

#### `decompressed_size`

Размер распакованных данных фрейма.

#### `dictionary_id`

Целое число, представляющее идентификатор словаря Zstandard, необходимый для распаковки фрейма. Значение `0` означает, что идентификатор словаря не был записан в заголовке фрейма. Это может означать, что словарь Zstandard не требуется, или что идентификатор необходимого словаря не был записан.

#### `compression.zstd.COMPRESSION_LEVEL_DEFAULT`

Уровень сжатия по умолчанию для Zstandard: `3`.

#### `compression.zstd.zstd_version_info`

Номер версии библиотеки zstd времени выполнения в виде кортежа целых чисел (major, minor, release).

## Примеры

Чтение сжатого файла:

```python
from compression import zstd

with zstd.open("file.zst") as f:
    file_content = f.read()
```

Создание сжатого файла:

```python
from compression import zstd

data = b"Insert Data Here"
with zstd.open("file.zst", "w") as f:
    f.write(data)
```

Сжатие данных в памяти:

```python
from compression import zstd

data_in = b"Insert Data Here"
data_out = zstd.compress(data_in)
```

Инкрементальное сжатие:

```python
from compression import zstd

comp = zstd.ZstdCompressor()
out1 = comp.compress(b"Some data\n")
out2 = comp.compress(b"Another piece of data\n")
out3 = comp.compress(b"Even more data\n")
out4 = comp.flush()
# Объединить все частичные результаты:
result = b"".join([out1, out2, out3, out4])
```

Запись сжатых данных в уже открытый файл:

```python
from compression import zstd

with open("myfile", "wb") as f:
    f.write(b"This data will not be compressed\n")
    with zstd.open(f, "w") as zstf:
        zstf.write(b"This *will* be compressed\n")
    f.write(b"Not compressed\n")
```

Создание сжатого файла с использованием параметров сжатия:

```python
from compression import zstd

options = {
   zstd.CompressionParameter.checksum_flag: 1
}
with zstd.open("file.zst", "w", options=options) as f:
    f.write(b"Mind if I squeeze in?")
```