compression.zstd — сжатие, совместимое с форматом Zstandard

Исключения

exception compression.zstd.ZstdError

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

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

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

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

Аргумент file может быть именем файла (заданным в виде объекта str, bytes или объекта, подобного пути), в этом случае открывается указанный файл, либо существующим файловым объектом для чтения или записи.

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

При чтении аргумент options может быть словарём с дополнительными параметрами распаковки; подробную информацию о поддерживаемых параметрах см. в разделе DecompressionParameter. Аргумент zstd_dict — это экземпляр ZstdDict, используемый при распаковке. При чтении, если аргумент level не равен None, будет вызвано исключение TypeError.

При записи аргумент options может быть словарём с дополнительными параметрами сжатия; подробную информацию о поддерживаемых параметрах см. в разделе CompressionParameter. Аргумент level задаёт уровень сжатия при записи сжатых данных. Только один из аргументов level или options может иметь значение, отличное от None. Аргумент zstd_dict — это экземпляр ZstdDict, используемый при сжатии.

В двоичном режиме эта функция эквивалентна конструктору ZstdFile: ZstdFile(file, mode, ...). В этом случае параметры encoding, errors и newline указывать нельзя.

В текстовом режиме создаётся объект ZstdFile и оборачивается в экземпляр io.TextIOWrapper с указанными кодировкой, поведением при обработке ошибок и символами окончания строк.

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

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

Объект ZstdFile может оборачивать уже открытый файловый объект или работать непосредственно с файлом, указанным по имени. Аргумент file задаёт файловый объект для обёртывания или имя открываемого файла (в виде объекта str, bytes или объекта, подобного пути). При обёртывании существующего файлового объекта он не будет закрыт при закрытии объекта ZstdFile.

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

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

При чтении аргумент options может быть словарём с дополнительными параметрами распаковки; подробную информацию о поддерживаемых параметрах см. в разделе DecompressionParameter. Аргумент zstd_dict — это экземпляр ZstdDict, используемый при распаковке. При чтении, если аргумент level не равен None, будет вызвано исключение TypeError.

При записи аргумент options может быть словарём с дополнительными параметрами сжатия; подробную информацию о поддерживаемых параметрах см. в разделе CompressionParameter. Аргумент level задаёт уровень сжатия при записи сжатых данных. Можно указать только один из аргументов level или options. Аргумент zstd_dict — это экземпляр ZstdDict, используемый при сжатии.

Объект ZstdFile поддерживает все методы и атрибуты, определённые в io.BufferedIOBase, за исключением detach() и truncate(). Поддерживаются итерация и инструкция with.

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

peek(size=-1)

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

Примечание

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

mode

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

name

Имя файла Zstandard. Эквивалентно атрибуту name базового файлового объекта.

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

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

Сжимает data (объект, подобный байтам) и возвращает сжатые данные в виде объекта bytes.

Аргумент level — целое число, задающее уровень сжатия. level является альтернативой заданию CompressionParameter.compression_level в options. Вызовите bounds() для compression_level, чтобы получить допустимые значения level. Если требуются дополнительные параметры сжатия, аргумент level нужно опустить, а в словаре options задать параметр CompressionParameter.compression_level.

Аргумент options — это словарь Python, содержащий дополнительные параметры сжатия. Допустимые ключи и значения параметров сжатия описаны в документации CompressionParameter.

Аргумент zstd_dict — это экземпляр ZstdDict, содержащий обученные данные для повышения эффективности сжатия. Для создания словаря Zstandard можно использовать функцию train_dict().

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

Распаковывает data (объект, подобный байтам) и возвращает распакованные данные в виде объекта bytes.

Аргумент options — это словарь Python, содержащий дополнительные параметры распаковки. Допустимые ключи и значения параметров распаковки описаны в документации DecompressionParameter.

Аргумент zstd_dict — это экземпляр ZstdDict, содержащий обученные данные, использованные при сжатии. Это должен быть тот же словарь Zstandard, который использовался при сжатии.

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

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

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

Для более удобного сжатия одного блока данных см. функцию уровня модуля compress().

Аргумент level — целое число, задающее уровень сжатия. level является альтернативой заданию CompressionParameter.compression_level в options. Вызовите bounds() для compression_level, чтобы получить допустимые значения level. Если требуются дополнительные параметры сжатия, аргумент level нужно опустить, а в словаре options задать параметр CompressionParameter.compression_level.

Аргумент options — это словарь Python, содержащий дополнительные параметры сжатия. Допустимые ключи и значения параметров сжатия описаны в документации CompressionParameter.

Аргумент zstd_dict — это необязательный экземпляр ZstdDict, содержащий обученные данные для повышения эффективности сжатия. Для создания словаря Zstandard можно использовать функцию train_dict().

compress(data, mode=ZstdCompressor.CONTINUE)

Сжимает data (объект, подобный байтам) и, если это возможно, возвращает объект bytes со сжатыми данными, а в противном случае — пустой объект bytes. Часть data может быть сохранена во внутреннем буфере для последующих вызовов compress() и flush(). Возвращённые данные следует объединить с результатами всех предыдущих вызовов compress().

Аргумент mode — это атрибут ZstdCompressor со значением CONTINUE, FLUSH_BLOCK или FLUSH_FRAME.

После передачи компрессору всех данных вызовите метод flush(), чтобы завершить процесс сжатия. Если compress() вызывается с аргументом mode, равным FLUSH_FRAME, вызывать flush() не следует, так как это приведёт к записи нового пустого кадра.

flush(mode=ZstdCompressor.FLUSH_FRAME)

Завершает процесс сжатия и возвращает объект bytes, содержащий все данные из внутренних буферов компрессора.

Аргумент mode — это атрибут ZstdCompressor со значением FLUSH_BLOCK или FLUSH_FRAME.

set_pledged_input_size(size)

Указывает размер несжатых данных size, которые будут переданы для следующего кадра. Значение size записывается в заголовок следующего кадра, если только параметр CompressionParameter.content_size_flag не равен False или 0. Значение 0 означает, что кадр пуст. Если size равен None, размер кадра не будет указан в его заголовке. Для распаковки кадров, содержащих размер несжатых данных, требуется меньше памяти, особенно при высоких уровнях сжатия.

Если значение last_mode не равно FLUSH_FRAME, вызывается исключение ValueError, поскольку компрессор не находится в начале кадра. Если заявленный размер не совпадает с фактическим размером данных, переданных в compress(), последующие вызовы compress() или flush() могут вызвать ZstdError, а последний блок данных может быть потерян.

После вызова flush() или compress() с режимом FLUSH_FRAME в заголовок следующего кадра не будет включён его размер, если только set_pledged_input_size() не будет вызван снова.

CONTINUE

Продолжает накапливать данные для сжатия; при этом вывод может формироваться сразу или позднее. Этот режим оптимизирует коэффициент сжатия, увеличивая объём данных в каждом блоке и кадре.

FLUSH_BLOCK

Завершает блок и записывает его в поток данных. Уже возвращённые данные можно немедленно распаковать. Данные из предыдущих блоков по-прежнему могут использоваться в последующих блоках, созданных вызовами compress(), что повышает степень сжатия.

FLUSH_FRAME

Завершает кадр и записывает его. Последующие данные, переданные в compress(), будут записаны в новый кадр и не смогут ссылаться на предыдущие данные.

last_mode

Последний режим, переданный в compress() или flush(). Значение может быть одним из следующих: CONTINUE, FLUSH_BLOCK или FLUSH_FRAME. Начальное значение — FLUSH_FRAME, означающее, что компрессор находится в начале нового кадра.

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

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

Для более удобной однократной распаковки целого сжатого потока см. функцию уровня модуля decompress().

Аргумент options — это словарь Python, содержащий дополнительные параметры распаковки. Допустимые ключи и значения параметров распаковки описаны в документации DecompressionParameter.

Аргумент zstd_dict — это экземпляр ZstdDict, содержащий обученные данные, использованные при сжатии. Это должен быть тот же словарь Zstandard, который использовался при сжатии.

Примечание

Этот класс не обрабатывает прозрачно входные данные, содержащие несколько сжатых кадров, в отличие от функции decompress() и класса ZstdFile. Для распаковки входных данных с несколькими кадрами следует использовать decompress(), ZstdFile при работе с файловым объектом или несколько экземпляров ZstdDecompressor.

decompress(data, max_length=-1)

Распаковывает data (объект, подобный байтам) и возвращает распакованные данные в виде байтов. Часть data может быть сохранена во внутреннем буфере для последующих вызовов decompress(). Возвращённые данные следует объединить с результатами всех предыдущих вызовов decompress().

Если значение max_length неотрицательно, метод возвращает не более max_length байтов распакованных данных. Если достигнут этот предел и можно получить дополнительные данные, атрибут needs_input будет установлен в False. В этом случае следующий вызов decompress() может получить в аргументе data значение b'', чтобы вернуть больше данных.

Если все входные данные были распакованы и возвращены (поскольку их размер был меньше max_length байтов или значение max_length было отрицательным), атрибут needs_input будет установлен в True.

Попытка распаковать данные после конца кадра вызовет исключение EOFError. Все данные после конца кадра игнорируются и сохраняются в атрибуте unused_data.

eof

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

unused_data

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

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

needs_input

False, если метод decompress() может предоставить дополнительные распакованные данные до того, как потребуются новые сжатые данные.

Словари Zstandard

compression.zstd.train_dict(samples, dict_size)

Обучает словарь Zstandard и возвращает экземпляр ZstdDict. Словари Zstandard обеспечивают более эффективное сжатие небольших объемов данных, которые традиционно сложно сжимать из-за меньшего количества повторений. Если вы сжимаете несколько похожих групп данных (например, похожие файлы), словари Zstandard могут значительно улучшить степень и скорость сжатия.

Аргумент samples (итерируемый объект из объектов bytes) — это набор образцов, используемых для обучения словаря Zstandard.

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

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

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

Аргумент zstd_dict — экземпляр ZstdDict, у которого атрибут dict_content содержит необработанное содержимое словаря.

Аргумент samples (итерируемый объект из объектов bytes) содержит образцы данных для создания словаря Zstandard.

Аргумент dict_size — целое число, обозначающее максимальный размер (в байтах) словаря Zstandard. Рекомендации по максимальному размеру словаря см. в описании train_dict().

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

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

Обертка для словарей Zstandard. Словари можно использовать для улучшения сжатия множества небольших фрагментов данных. Если вам нужно обучить новый словарь на основе образцов данных, используйте train_dict().

Аргумент dict_content (объект, похожий на объект bytes) — это уже обученная информация словаря.

Аргумент is_raw — логический параметр расширенной настройки, определяющий смысл dict_content. True означает, что dict_content — это словарь с «необработанным содержимым», не имеющий ограничений на формат. False означает, что dict_content — обычный словарь Zstandard, созданный функциями Zstandard, например train_dict(), или внешней программой zstd CLI.

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

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

dict_content

Содержимое словаря Zstandard — объект bytes. Оно совпадает с аргументом dict_content метода __init__. Его можно использовать с другими программами, например с программой CLI zstd.

dict_id

Идентификатор словаря Zstandard — неотрицательное целое число.

Ненулевое значение означает, что словарь является обычным, созданным функциями Zstandard и соответствующим формату Zstandard.

0 означает словарь с «необработанным содержимым», не имеющий ограничений на формат и предназначенный для опытных пользователей.

Примечание

Значение 0 для ZstdDict.dict_id отличается от значения атрибута dictionary_id функции get_frame_info().

as_digested_dict

Загрузить как подготовленный словарь.

as_undigested_dict

Загрузить как неподготовленный словарь.

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

class compression.zstd.CompressionParameter

IntEnum, содержащий ключи расширенных параметров сжатия, которые можно использовать при сжатии данных.

Метод bounds() можно использовать для любого атрибута, чтобы получить допустимые значения этого параметра.

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

Пример получения нижней и верхней границ для compression_level:

lower, upper = CompressionParameter.compression_level.bounds()

Пример установки для window_log максимального значения:

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

bounds()

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

Нижняя и верхняя границы включаются в диапазон.

compression_level

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

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

При установке уровня, равного нулю, используется COMPRESSION_LEVEL_DEFAULT.

window_log

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

При значении ноль параметр выбирается автоматически.

hash_log

Размер начальной таблицы поиска, выраженный как степень двойки. Получившийся объем используемой памяти составляет 1 << (hash_log+2) байт. Более крупные таблицы повышают степень сжатия стратегий <= dfast и увеличивают скорость сжатия стратегий > dfast.

При значении ноль параметр выбирается автоматически.

chain_log

Размер таблицы поиска с несколькими пробами, выраженный как степень двойки. Получившийся объем используемой памяти составляет 1 << (chain_log+2) байт. Более крупные таблицы обеспечивают лучшее, но более медленное сжатие. Этот параметр не влияет на стратегию fast. Он по-прежнему полезен при использовании стратегии dfast, для которой он задает вторичную таблицу поиска.

При значении ноль параметр выбирается автоматически.

search_log

Количество попыток поиска, выраженное как степень двойки. Большее количество попыток повышает степень сжатия, но замедляет его. Этот параметр не имеет значения для стратегий fast и dfast.

При значении ноль параметр выбирается автоматически.

min_match

Минимальный размер совпадений, которые ищутся. Более высокие значения повышают скорость сжатия и распаковки, но снижают степень сжатия. Обратите внимание: Zstandard по-прежнему может находить совпадения меньшего размера; алгоритм поиска лишь настраивается на поиск совпадений заданного размера и больше. Для всех стратегий < btopt эффективный минимум равен 4; для всех стратегий > fast эффективный максимум равен 6.

При значении ноль параметр выбирается автоматически.

target_length

Влияние этого поля зависит от выбранной Strategy.

Для стратегий btopt, btultra и btultra2 это значение задает длину совпадения, считающегося «достаточно хорошим» для прекращения поиска. Более высокие значения повышают степень сжатия, но замедляют его.

Для стратегии fast это расстояние между выборками совпадений. Более высокие значения ускоряют сжатие, но снижают его степень.

При значении ноль параметр выбирается автоматически.

strategy

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

См. также

Strategy

enable_long_distance_matching

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

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

Включение этого параметра увеличивает значение window_log по умолчанию до 128 МиБ, если явно не задано другое значение. Этот параметр включен по умолчанию, если window_log >= 128 МиБ, а стратегия сжатия >= btopt (уровень сжатия 16+).

ldm_hash_log

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

При значении ноль параметр выбирается автоматически.

ldm_min_match

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

При значении ноль параметр выбирается автоматически.

ldm_bucket_size_log

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

При значении ноль параметр выбирается автоматически.

ldm_hash_rate_log

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

При значении ноль параметр выбирается автоматически.

content_size_flag

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

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

• Вызов compress() для однократного сжатия
• Передача всех сжимаемых данных кадра за один вызов ZstdCompressor.compress() в режиме ZstdCompressor.FLUSH_FRAME.
• Вызов ZstdCompressor.set_pledged_input_size() с точным объемом данных, который будет передан компрессору до вызова ZstdCompressor.compress() для текущего кадра. ZstdCompressor.set_pledged_input_size() необходимо вызывать для каждого нового кадра.

При всех остальных вызовах сжатия информация о размере может не записываться в заголовок кадра.

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

checksum_flag

В конце каждого кадра записывается четырехбайтовая контрольная сумма XXHash64 несжатого содержимого. Код распаковки Zstandard проверяет контрольную сумму. При несовпадении вызывается исключение ZstdError.

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

dict_id_flag

При сжатии с использованием ZstdDict идентификатор словаря записывается в заголовок кадра.

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

nb_workers

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

Значение ноль отключает многопоточность.

job_size

Размер задания на сжатие в байтах. Это значение применяется только при условии, что nb_workers >= 1. Каждое задание на сжатие выполняется параллельно, поэтому это значение может косвенно влиять на количество активных потоков.

При значении ноль параметр выбирается автоматически.

overlap_log

Задает объем данных из предыдущих заданий (потоков), повторно загружаемых для новых заданий и используемых окном просмотра назад при сжатии. Это значение используется только при условии, что nb_workers >= 1. Допустимые значения находятся в диапазоне от 0 до 9.

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

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

class compression.zstd.DecompressionParameter

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

Метод bounds() можно использовать для любого атрибута, чтобы получить допустимые значения этого параметра.

Пример установки максимального значения для window_log_max:

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

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

При значении ноль параметр выбирается автоматически.

class compression.zstd.Strategy

IntEnum, содержащий стратегии сжатия. Стратегии с более высокими номерами соответствуют более сложному и медленному сжатию.

Примечание

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

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

fast

dfast

greedy

lazy

lazy2

btlazy2

btopt

btultra

btultra2

Разное

compression.zstd.get_frame_info(frame_buffer)

Получает объект 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 во время выполнения в виде кортежа целых чисел (основная версия, дополнительная версия, выпуск).

Примеры

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

from compression import zstd

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

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

from compression import zstd

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

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

from compression import zstd

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

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

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()
# Concatenate all the partial results:
result = b"".join([out1, out2, out3, out4])

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

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")

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

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?")