`compression.zstd.md`

574 строк · 60.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3/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/3.14/Lib/compression/zstd/__init__.py)1213---1415Этот модуль предоставляет классы и функции для сжатия и декомпрессии данных с использованием алгоритма сжатия Zstandard (или *zstd*). [Руководство по zstd](https://python-all.ru/3/library/compression.zstd.html) описывает Zstandard как «быстрый алгоритм сжатия без потерь, предназначенный для сценариев сжатия в реальном времени на уровне zlib и с лучшим коэффициентом сжатия». Также включён файловый интерфейс, поддерживающий чтение и запись содержимого файлов `.zst`, созданных утилитой **zstd**, а также сырых сжатых потоков zstd.1617Модуль `compression.zstd` содержит:1819- Функция [`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) для чтения и записи сжатых файлов.20- Классы [`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) для инкрементального сжатия и распаковки.21- Функции [`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) для одноразового сжатия и распаковки.22- Функции [`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.23- Классы [`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) для задания расширенных параметров (де)компрессии.2425Это [опциональный модуль](https://python-all.ru/3/glossary.html#term-optional-module). Если его нет в вашей копии CPython, обратитесь к документации от вашего дистрибьютора (то есть того, кто предоставил вам Python). Если вы дистрибьютор, обратитесь к [требованиям к опциональным модулям](https://python-all.ru/3/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/glossary.html#term-file-object).3839Аргумент *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)), в этом случае открывается указанный файл, либо существующим файловым объектом для чтения или записи.4041Аргумент mode может быть `'rb'` для чтения (по умолчанию), `'wb'` для перезаписи, `'ab'` для добавления или `'xb'` для исключительного создания. Эквивалентно их можно задать как `'r'`, `'w'`, `'a'` и `'x'` соответственно. Также можно открыть в текстовом режиме с помощью `'rt'`, `'wt'`, `'at'` и `'xt'` соответственно.4243При чтении аргумент *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`.4445При записи аргумент *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), используемый при сжатии.4647В двоичном режиме эта функция эквивалентна конструктору [`ZstdFile`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdFile): `ZstdFile(file, mode, ...)`. В этом случае параметры *encoding*, *errors* и *newline* не должны указываться.4849В текстовом режиме создаётся объект [`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) с указанными кодировкой, поведением обработки ошибок и символами конца строки.5051#### `class compression.zstd.ZstdFile(file, /, mode='rb', *, level=None, options=None, zstd_dict=None)`5253Открывает файл, сжатый Zstandard, в двоичном режиме.5455`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`.5657Аргумент *mode* может быть `'rb'` для чтения (по умолчанию), `'wb'` для перезаписи, `'xb'` для исключительного создания или `'ab'` для добавления. Эквивалентно их можно задать как `'r'`, `'w'`, `'x'` и `'a'` соответственно.5859Если *file* – файловый объект (а не собственно имя файла), то режим `'w'` не усекает файл, а эквивалентен `'a'`.6061При чтении аргумент *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`.6263При записи аргумент *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), используемый при сжатии.6465`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).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/library/io.html#io.FileIO.name) нижележащего [файлового объекта](https://python-all.ru/3/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/glossary.html#term-bytes-like-object)) и возвращает сжатые данные в виде объекта [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes).9091Аргумент *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`.9293Аргумент *options* – это словарь Python, содержащий дополнительные параметры сжатия. Допустимые ключи и значения для параметров сжатия описаны в документации [`CompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter).9495Аргумент *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).9697#### `compression.zstd.decompress(data, zstd_dict=None, options=None)`9899Распаковывает *data* ([объект, подобный байтам](https://python-all.ru/3/glossary.html#term-bytes-like-object)) и возвращает распакованные данные в виде объекта [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes).100101Аргумент *options* – это словарь Python, содержащий дополнительные параметры распаковки. Допустимые ключи и значения для параметров сжатия описаны в документации [`DecompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.DecompressionParameter).102103Аргумент *zstd\_dict* – это экземпляр [`ZstdDict`](https://python-all.ru/3/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/library/compression.zstd.html#compression.zstd.compress).112113Аргумент *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`.114115Аргумент *options* – это словарь Python, содержащий дополнительные параметры сжатия. Допустимые ключи и значения для параметров сжатия описаны в документации [`CompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter).116117Аргумент *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).118119#### `compress(data, mode=ZstdCompressor.CONTINUE)`120121Сжимает *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()`.122123Аргумент *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).124125Когда все данные переданы компрессору, вызовите метод [`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()`, так как это запишет новый пустой фрейм.126127#### `flush(mode=ZstdCompressor.FLUSH_FRAME)`128129Завершает процесс сжатия, возвращая объект [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes), содержащий данные, хранящиеся во внутренних буферах компрессора.130131Аргумент *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).132133#### `set_pledged_input_size(size)`134135Задаёт объём несжатых данных *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`, заголовок фрейма будет без указания размера. Фреймы, включающие размер несжатых данных, требуют меньше памяти для распаковки, особенно при высоких степенях сжатия.136137Если [`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), и последний фрагмент данных может быть потерян.138139После вызова [`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()`.140141#### `CONTINUE`142143Собирает больше данных для сжатия, что может генерировать выходные данные немедленно или нет. Этот режим оптимизирует степень сжатия, максимизируя объём данных на блок и фрейм.144145#### `FLUSH_BLOCK`146147Завершает и записывает блок в поток данных. Возвращённые на данный момент данные могут быть немедленно распакованы. Предыдущие данные всё ещё могут использоваться в будущих блоках, создаваемых вызовами [`compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress), что улучшает сжатие.148149#### `FLUSH_FRAME`150151Завершает и записывает кадр. Последующие данные, переданные в [`compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdCompressor.compress), будут записаны в новый кадр и *не могут* ссылаться на предыдущие данные.152153#### `last_mode`154155Последний режим, переданный в [`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`, что означает, что компрессор находится в начале нового кадра.156157#### `class compression.zstd.ZstdDecompressor(zstd_dict=None, options=None)`158159Создаёт объект декомпрессора, который можно использовать для инкрементальной декомпрессии данных.160161Для более удобного способа декомпрессии целого сжатого потока за один раз обратитесь к функции уровня модуля [`decompress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.decompress).162163Аргумент *options* – это словарь Python, содержащий расширенные параметры декомпрессии. Допустимые ключи и значения для параметров сжатия документированы в [`DecompressionParameter`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.DecompressionParameter).164165Аргумент *zstd\_dict* – это экземпляр [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict), содержащий обученные данные, использованные при сжатии. Он должен быть тем же самым словарём Zstandard, который использовался при сжатии.166167> **Примечание**168>169> Этот класс не обрабатывает прозрачно входные данные, содержащие несколько сжатых кадров, в отличие от функции [`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`.170171#### `decompress(data, max_length=-1)`172173Декомпрессирует *data* ([байтоподобный объект](https://python-all.ru/3/glossary.html#term-bytes-like-object)), возвращая несжатые данные в виде байтов. Часть *data* может быть буферизована внутренне для использования в последующих вызовах `decompress()`. Возвращаемые данные следует объединить с выводом всех предыдущих вызовов `decompress()`.174175Если *max\_length* неотрицателен, метод возвращает не более *max\_length* байт декомпрессированных данных. Если этот лимит достигнут и можно сгенерировать больше данных, атрибут [`needs_input`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDecompressor.needs_input) будет установлен в `False`. В этом случае следующий вызов `decompress()` может передать *data* как `b''` для получения дополнительного вывода.176177Если все входные данные были декомпрессированы и возвращены (либо потому что это было меньше *max\_length* байтов, либо потому что *max\_length* было отрицательным), атрибут [`needs_input`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDecompressor.needs_input) будет установлен в `True`.178179Попытка декомпрессии данных после конца кадра вызовет исключение [`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).180181#### `eof`182183`True`, если достигнут маркер конца потока.184185#### `unused_data`186187Данные, обнаруженные после конца сжатого потока.188189До достижения конца потока это будет `b''`.190191#### `needs_input`192193`False`, если метод [`decompress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDecompressor.decompress) может предоставить больше декомпрессированных данных до запроса нового сжатого ввода.194195## Словари Zstandard196197#### `compression.zstd.train_dict(samples, dict_size)`198199Обучает словарь Zstandard, возвращая экземпляр [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict). Словари Zstandard обеспечивают более эффективное сжатие небольших объёмов данных, которые традиционно трудно сжимать из-за меньшей повторяемости. Если сжимаются несколько похожих групп данных (например, похожие файлы), словари Zstandard могут значительно улучшить степень сжатия и скорость.200201Аргумент *samples* (итерируемый объект из [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes)) – это набор образцов, используемый для обучения словаря Zstandard.202203Аргумент *dict\_size*, целое число, задаёт максимальный размер (в байтах) словаря Zstandard. В документации Zstandard рекомендуется абсолютный максимум не более 100 КБ, но часто можно использовать меньший размер в зависимости от данных. Более крупные словари обычно замедляют сжатие, но улучшают степень сжатия. Меньшие словари ускоряют сжатие, но снижают степень сжатия.204205#### `compression.zstd.finalize_dict(zstd_dict, /, samples, dict_size, level)`206207Расширенная функция для преобразования словаря Zstandard с «сырым содержимым» в обычный словарь Zstandard. Словари с «сырым содержимым» – это последовательность байтов, которая не обязана следовать структуре обычного словаря Zstandard.208209Аргумент *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), содержащим сырое содержимое словаря.210211Аргумент *samples* (итерируемый объект из [`bytes`](https://python-all.ru/3/library/stdtypes.html#bytes)) содержит образцы данных для генерации словаря Zstandard.212213Аргумент *dict\_size*, целое число, задаёт максимальный размер (в байтах) словаря Zstandard. См. [`train_dict()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.train_dict) для рекомендаций по максимальному размеру словаря.214215Аргумент *level* (целое число) – это уровень сжатия, который ожидается для передачи компрессорам, использующим этот словарь. Информация словаря меняется для каждого уровня сжатия, поэтому настройка на правильный уровень сжатия может сделать сжатие более эффективным.216217#### `class compression.zstd.ZstdDict(dict_content, /, *, is_raw=False)`218219Обёртка вокруг словарей Zstandard. Словари можно использовать для улучшения сжатия множества небольших фрагментов данных. Используйте [`train_dict()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.train_dict), если нужно обучить новый словарь на основе образцов данных.220221Аргумент *dict\_content* ([байтоподобный объект](https://python-all.ru/3/glossary.html#term-bytes-like-object)) – это информация уже обученного словаря.222223Аргумент *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**.224225При передаче `ZstdDict` в функцию атрибуты `as_digested_dict` и `as_undigested_dict` могут управлять тем, как загружается словарь, если передать их в качестве аргумента `zstd_dict`, например, `compress(data, zstd_dict=zd.as_digested_dict)`. Подготовка словаря – это затратная операция, выполняемая при загрузке словаря Zstandard. Если при многократных вызовах сжатия или разжатия передавать подготовленный словарь, это снизит накладные расходы на загрузку словаря.226227> |  | Подготовленный словарь | Неподготовленный словарь |228> | --- | --- | --- |229> | Расширенные параметры компрессора, которые могут быть переопределены параметрами словаря | `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 |230> | `ZstdDict` внутренне кэширует словарь | Да. Это быстрее при повторной загрузке подготовленного словаря с тем же уровнем сжатия. | Нет. Если требуется загрузить неподготовленный словарь несколько раз, рассмотрите возможность повторного использования объекта компрессора. |231232Если передаётся `ZstdDict` без каких-либо атрибутов, по умолчанию при сжатии передаётся неподготовленный словарь, а при разжатии при необходимости создаётся и по умолчанию передаётся подготовленный словарь.233234> #### `dict_content`235>236> Содержимое словаря Zstandard, объект `bytes`. Оно совпадает с аргументом *dict\_content* в методе `__init__`. Его можно использовать с другими программами, например, с программой командной строки `zstd`.237>238> #### `dict_id`239>240> Идентификатор словаря Zstandard, неотрицательное целое значение.241>242> Ненулевое значение означает, что словарь является обычным, созданным функциями Zstandard и следующим формату Zstandard.243>244> `0` означает словарь в формате «сырое содержимое», свободный от каких-либо ограничений формата, используемый продвинутыми пользователями.245>246> > **Примечание**247> >248> > Значение `0` для `ZstdDict.dict_id` отличается от атрибута `dictionary_id` функции [`get_frame_info()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.get_frame_info).249>250> #### `as_digested_dict`251>252> Загрузить как подготовленный словарь.253>254> #### `as_undigested_dict`255>256> Загрузить как неподготовленный словарь.257258## Управление расширенными параметрами259260#### `class compression.zstd.CompressionParameter`261262[`IntEnum`](https://python-all.ru/3/library/enum.html#enum.IntEnum), содержащий ключи расширенных параметров сжатия, которые можно использовать при сжатии данных.263264Метод [`bounds()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.bounds) можно использовать для любого атрибута, чтобы получить допустимые значения для этого параметра.265266Параметры необязательны; для любого пропущенного параметра значение будет выбрано автоматически.267268Пример получения нижней и верхней границы [`compression_level`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.compression_level):269270```python271lower, upper = CompressionParameter.compression_level.bounds()272```273274Пример установки [`window_log`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.window_log) на максимальный размер:275276```python277_lower, upper = CompressionParameter.window_log.bounds()278options = {CompressionParameter.window_log: upper}279compress(b'venezuelan beaver cheese', options=options)280```281282#### `bounds()`283284Возвращает кортеж границ типа int, `(lower, upper)`, для параметра сжатия. Этот метод следует вызывать для атрибута, границы которого необходимо получить. Например, чтобы узнать допустимые значения для [`compression_level`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.compression_level), можно проверить результат `CompressionParameter.compression_level.bounds()`.285286Нижняя и верхняя границы включены.287288#### `compression_level`289290Высокоуровневое средство настройки других параметров сжатия, влияющих на скорость и степень сжатия данных.291292Обычные уровни сжатия больше `0`. Значения больше `20` считаются «ультра»-сжатием и требуют больше памяти, чем другие уровни. Отрицательные значения можно использовать для ускорения сжатия ценой ухудшения степени сжатия.293294Установка уровня в ноль использует [`COMPRESSION_LEVEL_DEFAULT`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.COMPRESSION_LEVEL_DEFAULT).295296#### `window_log`297298Максимально допустимое расстояние обратной ссылки, которое может использовать компрессор при сжатии данных, выражается как степень двойки: `1 << window_log` байт. Этот параметр сильно влияет на использование памяти при сжатии. Большие значения требуют больше памяти, но обеспечивают лучшую степень сжатия.299300Значение ноль означает автоматический выбор.301302#### `hash_log`303304Размер начальной таблицы поиска (probe table) в виде степени двойки. Результирующее использование памяти составляет `1 << (hash_log+2)` байт. Более крупные таблицы улучшают степень сжатия для стратегий \<= [`dfast`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.dfast) и увеличивают скорость сжатия для стратегий \> `dfast`.305306Значение ноль означает автоматический выбор.307308#### `chain_log`309310Размер таблицы множественного поиска (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), в этом случае он определяет вторичную таблицу поиска.311312Значение ноль означает автоматический выбор.313314#### `search_log`315316Количество попыток поиска в виде степени двойки. Большее количество попыток даёт лучшее, но более медленное сжатие. Этот параметр бесполезен для стратегий [`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).317318Значение ноль означает автоматический выбор.319320#### `min_match`321322Минимальный размер искомых совпадений. Большие значения увеличивают скорость сжатия и распаковки, но уменьшают степень сжатия. Обратите внимание, что 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`.323324Значение ноль означает автоматический выбор.325326#### `target_length`327328Влияние этого поля зависит от выбранного [`Strategy`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy).329330Для стратегий [`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) значение – это длина совпадения, считающегося «достаточно хорошим» для прекращения поиска. Большие значения улучшают степень сжатия, но замедляют сжатие.331332Для стратегии [`fast`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy.fast) это расстояние между выборками совпадений. Большие значения ускоряют сжатие, но ухудшают степень сжатия.333334Значение ноль означает автоматический выбор.335336#### `strategy`337338Чем выше значение выбранной стратегии, тем более сложную технику сжатия использует zstd, что приводит к более высокой степени сжатия, но замедляет сжатие.339340> **См. также**341>342> [`Strategy`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.Strategy)343344#### `enable_long_distance_matching`345346Сопоставление на больших расстояниях (long distance matching) может использоваться для улучшения сжатия больших входных данных за счёт нахождения больших совпадений на больших расстояниях. Это увеличивает использование памяти и размер окна.347348`True` или `1` включают сопоставление на больших расстояниях, а `False` или `0` отключают его.349350Включение этого параметра увеличивает значение по умолчанию [`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+).351352#### `ldm_hash_log`353354Размер таблицы для поиска совпадений на больших расстояниях, задаваемый как степень двойки. Большие значения увеличивают использование памяти и степень сжатия, но снижают скорость сжатия.355356Нулевое значение приводит к автоматическому выбору значения.357358#### `ldm_min_match`359360Минимальный размер совпадения для средства поиска на больших расстояниях. Слишком большие или слишком маленькие значения часто могут снижать степень сжатия.361362Нулевое значение приводит к автоматическому выбору значения.363364#### `ldm_bucket_size_log`365366Логарифмический размер каждой корзины в хеш-таблице средства поиска на больших расстояниях для разрешения коллизий. Большие значения улучшают разрешение коллизий, но снижают скорость сжатия.367368Нулевое значение приводит к автоматическому выбору значения.369370#### `ldm_hash_rate_log`371372Частота вставки/поиска записей в хеш-таблице средства поиска на больших расстояниях. Большие значения улучшают скорость сжатия. Сильное отклонение от значения по умолчанию, скорее всего, приведет к снижению степени сжатия.373374Нулевое значение приводит к автоматическому выбору значения.375376#### `content_size_flag`377378Записывать размер сжимаемых данных в заголовок фрейма Zstandard, если он известен до начала сжатия.379380Этот флаг действует только в следующих сценариях:381382- Вызов [`compress()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.compress) для одноразового сжатия383- Передача всех сжимаемых данных во фрейме одним вызовом [`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).384- Вызов [`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()` должен вызываться для каждого нового фрейма.385386Все остальные вызовы сжатия могут не записывать информацию о размере в заголовок фрейма.387388`True` или `1` включают флаг размера содержимого, а `False` или `0` отключают его.389390#### `checksum_flag`391392Четырехбайтовая контрольная сумма по алгоритму XXHash64 от несжатого содержимого записывается в конце каждого фрейма. Код декомпрессии Zstandard проверяет контрольную сумму. При несовпадении возбуждается исключение [`ZstdError`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdError).393394`True` или `1` включают генерацию контрольной суммы, а `False` или `0` отключают её.395396#### `dict_id_flag`397398При сжатии с использованием [`ZstdDict`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.ZstdDict) идентификатор словаря записывается в заголовок фрейма.399400`True` или `1` включают сохранение идентификатора словаря, а `False` или `0` отключают его.401402#### `nb_workers`403404Выбор количества потоков, которые будут порождены для параллельного сжатия. Когда `nb_workers` \> 0, включает многопоточное сжатие; значение `1` означает «однопоточный многопоточный режим». Больше рабочих потоков повышает скорость, но также увеличивает использование памяти и незначительно снижает степень сжатия.405406Нулевое значение отключает многопоточность.407408#### `job_size`409410Размер задания на сжатие в байтах. Это значение применяется только при [`nb_workers`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.nb_workers) \>= 1. Каждое задание на сжатие выполняется параллельно, поэтому это значение может косвенно влиять на количество активных потоков.411412Нулевое значение приводит к автоматическому выбору значения.413414#### `overlap_log`415416Определяет, сколько данных загружается повторно из предыдущих задач (потоков) для новых задач, чтобы они использовались окном просмотра назад при сжатии. Это значение применяется только при [`nb_workers`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.CompressionParameter.nb_workers) \>= 1. Допустимые значения – от 0 до 9.417418> - 0 – динамически устанавливать величину перекрытия419> - 1 – без перекрытия420> - 9 – использовать полный размер окна из предыдущего задания421422Каждое приращение уменьшает или увеличивает размер перекрытия вдвое. «8» означает перекрытие `window_size/2`, «7» – перекрытие `window_size/4` и т.д.423424#### `class compression.zstd.DecompressionParameter`425426[`IntEnum`](https://python-all.ru/3/library/enum.html#enum.IntEnum), содержащий ключи расширенных параметров декомпрессии, которые можно использовать при декомпрессии данных. Параметры необязательны; для любого пропущенного параметра значение будет выбрано автоматически.427428Метод [`bounds()`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.DecompressionParameter.bounds) можно вызывать для любого атрибута, чтобы получить допустимые значения для этого параметра.429430Пример установки [`window_log_max`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.DecompressionParameter.window_log_max) на максимальный размер:431432```python433data = compress(b'Some very long buffer of bytes...')434435_lower, upper = DecompressionParameter.window_log_max.bounds()436437options = {DecompressionParameter.window_log_max: upper}438decompress(data, options=options)439```440441#### `bounds()`442443Возвращает кортеж целочисленных границ `(lower, upper)` параметра декомпрессии. Этот метод следует вызывать для того атрибута, границы которого требуется получить.444445Верхняя и нижняя границы включены.446447#### `window_log_max`448449Двоичный логарифм максимального размера окна, используемого при декомпрессии. Это может быть полезно для ограничения объёма памяти, используемого при декомпрессии данных. Больший максимальный размер окна приводит к более быстрой декомпрессии.450451Значение 0 приводит к автоматическому выбору значения.452453#### `class compression.zstd.Strategy`454455[`IntEnum`](https://python-all.ru/3/library/enum.html#enum.IntEnum), содержащий стратегии сжатия. Стратегии с бо́льшими номерами соответствуют более сложному и медленному сжатию.456457> **Примечание**458>459> Значения атрибутов `Strategy` не обязательно стабильны в разных версиях zstd. Можно полагаться только на порядок атрибутов. Атрибуты перечислены ниже по порядку.460461Доступны следующие стратегии:462463#### `fast`464465#### `dfast`466467#### `greedy`468469#### `lazy`470471#### `lazy2`472473#### `btlazy2`474475#### `btopt`476477#### `btultra`478479#### `btultra2`480481## Разное482483#### `compression.zstd.get_frame_info(frame_buffer)`484485Извлекает объект [`FrameInfo`](https://python-all.ru/3/library/compression.zstd.html#compression.zstd.FrameInfo), содержащий метаданные о фрейме Zstandard. Фреймы содержат метаданные, связанные с хранящимися в них сжатыми данными.486487#### `class compression.zstd.FrameInfo`488489Метаданные, относящиеся к фрейму Zstandard.490491#### `decompressed_size`492493Размер распакованных данных фрейма.494495#### `dictionary_id`496497Целое число, представляющее идентификатор словаря Zstandard, необходимый для распаковки фрейма. Значение `0` означает, что идентификатор словаря не был записан в заголовке фрейма. Это может означать, что словарь Zstandard не требуется, или что идентификатор необходимого словаря не был записан.498499#### `compression.zstd.COMPRESSION_LEVEL_DEFAULT`500501Уровень сжатия по умолчанию для Zstandard: `3`.502503#### `compression.zstd.zstd_version_info`504505Номер версии библиотеки zstd времени выполнения в виде кортежа целых чисел (major, minor, release).506507## Примеры508509Чтение сжатого файла:510511```python512from compression import zstd513514with zstd.open("file.zst") as f:515    file_content = f.read()516```517518Создание сжатого файла:519520```python521from compression import zstd522523data = b"Insert Data Here"524with zstd.open("file.zst", "w") as f:525    f.write(data)526```527528Сжатие данных в памяти:529530```python531from compression import zstd532533data_in = b"Insert Data Here"534data_out = zstd.compress(data_in)535```536537Инкрементальное сжатие:538539```python540from compression import zstd541542comp = zstd.ZstdCompressor()543out1 = comp.compress(b"Some data\n")544out2 = comp.compress(b"Another piece of data\n")545out3 = comp.compress(b"Even more data\n")546out4 = comp.flush()547# Объединить все частичные результаты:548result = b"".join([out1, out2, out3, out4])549```550551Запись сжатых данных в уже открытый файл:552553```python554from compression import zstd555556with open("myfile", "wb") as f:557    f.write(b"This data will not be compressed\n")558    with zstd.open(f, "w") as zstf:559        zstf.write(b"This *will* be compressed\n")560    f.write(b"Not compressed\n")561```562563Создание сжатого файла с использованием параметров сжатия:564565```python566from compression import zstd567568options = {569   zstd.CompressionParameter.checksum_flag: 1570}571with zstd.open("file.zst", "w", options=options) as f:572    f.write(b"Mind if I squeeze in?")573```574