1328 lines
126 KiB
HTML
1328 lines
126 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<meta property="og:title" content="compression.zstd — Compression compatible with the Zstandard format" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="https://docs.python.org/3/library/compression.zstd.html" />
|
||
<meta property="og:site_name" content="Python documentation" />
|
||
<meta property="og:description" content="Source code: Lib/compression/zstd/__init__.py This module provides classes and functions for compressing and decompressing data using the Zstandard (or zstd) compression algorithm. The zstd manual ..." />
|
||
<meta property="og:image" content="_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<meta name="description" content="Source code: Lib/compression/zstd/__init__.py This module provides classes and functions for compressing and decompressing data using the Zstandard (or zstd) compression algorithm. The zstd manual ..." />
|
||
<meta name="theme-color" content="#3776ab">
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
|
||
<title>compression.zstd — Compression compatible with the Zstandard format — Python 3.15.0 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=48df1187" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
|
||
|
||
<script src="../_static/documentation_options.js?v=0fe728b1"></script>
|
||
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.15.0 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="zlib — Compression compatible with gzip" href="zlib.html" />
|
||
<link rel="prev" title="The compression package" href="compression.html" />
|
||
|
||
|
||
<link rel="canonical" href="https://docs.python.org/3/library/compression.zstd.html">
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
<script type="text/javascript" src="../_static/search-focus.js"></script>
|
||
<script type="text/javascript" src="../_static/themetoggle.js"></script>
|
||
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
|
||
<meta name="readthedocs-addons-api-version" content="1">
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
|
||
<nav class="nav-content" role="navigation">
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<span class="nav-items-wrapper">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Python logo">
|
||
</a>
|
||
<span class="version_switcher_placeholder"></span>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
|
||
</svg>
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
|
||
<input type="submit" value="Go">
|
||
</form>
|
||
</span>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label>
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">compression.zstd</span></code> — Compression compatible with the Zstandard format</a><ul>
|
||
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
|
||
<li><a class="reference internal" href="#reading-and-writing-compressed-files">Reading and writing compressed files</a></li>
|
||
<li><a class="reference internal" href="#compressing-and-decompressing-data-in-memory">Compressing and decompressing data in memory</a></li>
|
||
<li><a class="reference internal" href="#zstandard-dictionaries">Zstandard dictionaries</a></li>
|
||
<li><a class="reference internal" href="#advanced-parameter-control">Advanced parameter control</a></li>
|
||
<li><a class="reference internal" href="#miscellaneous">Miscellaneous</a></li>
|
||
<li><a class="reference internal" href="#examples">Examples</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="compression.html"
|
||
title="previous chapter">The <code class="xref py py-mod docutils literal notranslate"><span class="pre">compression</span></code> package</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="zlib.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zlib</span></code> — Compression compatible with <strong class="program">gzip</strong></a></p>
|
||
</div>
|
||
<script>
|
||
document.addEventListener('DOMContentLoaded', () => {
|
||
const title = document.querySelector('meta[property="og:title"]').content;
|
||
const elements = document.querySelectorAll('.improvepage');
|
||
const pageurl = window.location.href.split('?')[0];
|
||
elements.forEach(element => {
|
||
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
|
||
url.searchParams.set('pagetitle', title);
|
||
url.searchParams.set('pageurl', pageurl);
|
||
url.searchParams.set('pagesource', "library/compression.zstd.rst");
|
||
element.href = url.toString();
|
||
});
|
||
});
|
||
</script>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a bug</a></li>
|
||
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.15/Doc/library/compression.zstd.rst?plain=1"
|
||
rel="nofollow">Show source
|
||
</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="zlib.html" title="zlib — Compression compatible with gzip"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="compression.html" title="The compression package"
|
||
accesskey="P">previous</a> |</li>
|
||
|
||
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.15.0 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python standard library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="archiving.html" accesskey="U">Data Compression and Archiving</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">compression.zstd</span></code> — Compression compatible with the Zstandard format</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
|
||
<input type="submit" value="Go">
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="module-compression.zstd">
|
||
<span id="compression-zstd-compression-compatible-with-the-zstandard-format"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">compression.zstd</span></code> — Compression compatible with the Zstandard format<a class="headerlink" href="#module-compression.zstd" title="Link to this heading">¶</a></h1>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.14.</span></p>
|
||
</div>
|
||
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.15/Lib/compression/zstd/__init__.py">Lib/compression/zstd/__init__.py</a></p>
|
||
<hr class="docutils" />
|
||
<p>This module provides classes and functions for compressing and decompressing
|
||
data using the Zstandard (or <em>zstd</em>) compression algorithm. The
|
||
<a class="reference external" href="https://facebook.github.io/zstd/doc/api_manual_latest.html">zstd manual</a>
|
||
describes Zstandard as “a fast lossless compression algorithm, targeting
|
||
real-time compression scenarios at zlib-level and better compression ratios.”
|
||
Also included is a file interface that supports reading and writing the
|
||
contents of <code class="docutils literal notranslate"><span class="pre">.zst</span></code> files created by the <strong class="program">zstd</strong> utility, as well as
|
||
raw zstd compressed streams.</p>
|
||
<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">compression.zstd</span></code> module contains:</p>
|
||
<ul class="simple">
|
||
<li><p>The <a class="reference internal" href="#compression.zstd.open" title="compression.zstd.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function and <a class="reference internal" href="#compression.zstd.ZstdFile" title="compression.zstd.ZstdFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdFile</span></code></a> class for reading and
|
||
writing compressed files.</p></li>
|
||
<li><p>The <a class="reference internal" href="#compression.zstd.ZstdCompressor" title="compression.zstd.ZstdCompressor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdCompressor</span></code></a> and <a class="reference internal" href="#compression.zstd.ZstdDecompressor" title="compression.zstd.ZstdDecompressor"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDecompressor</span></code></a> classes for
|
||
incremental (de)compression.</p></li>
|
||
<li><p>The <a class="reference internal" href="#compression.zstd.compress" title="compression.zstd.compress"><code class="xref py py-func docutils literal notranslate"><span class="pre">compress()</span></code></a> and <a class="reference internal" href="#compression.zstd.decompress" title="compression.zstd.decompress"><code class="xref py py-func docutils literal notranslate"><span class="pre">decompress()</span></code></a> functions for one-shot
|
||
(de)compression.</p></li>
|
||
<li><p>The <a class="reference internal" href="#compression.zstd.train_dict" title="compression.zstd.train_dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">train_dict()</span></code></a> and <a class="reference internal" href="#compression.zstd.finalize_dict" title="compression.zstd.finalize_dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">finalize_dict()</span></code></a> functions and the
|
||
<a class="reference internal" href="#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a> class to train and manage Zstandard dictionaries.</p></li>
|
||
<li><p>The <a class="reference internal" href="#compression.zstd.CompressionParameter" title="compression.zstd.CompressionParameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">CompressionParameter</span></code></a>, <a class="reference internal" href="#compression.zstd.DecompressionParameter" title="compression.zstd.DecompressionParameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DecompressionParameter</span></code></a>, and
|
||
<a class="reference internal" href="#compression.zstd.Strategy" title="compression.zstd.Strategy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Strategy</span></code></a> classes for setting advanced (de)compression parameters.</p></li>
|
||
</ul>
|
||
<p>This is an <a class="reference internal" href="../glossary.html#term-optional-module"><span class="xref std std-term">optional module</span></a>.
|
||
If it is missing from your copy of CPython,
|
||
look for documentation from your distributor (that is,
|
||
whoever provided Python to you).
|
||
If you are the distributor, see <a class="reference internal" href="../using/configure.html#optional-module-requirements"><span class="std std-ref">Requirements for optional modules</span></a>.</p>
|
||
<section id="exceptions">
|
||
<h2>Exceptions<a class="headerlink" href="#exceptions" title="Link to this heading">¶</a></h2>
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdError">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">ZstdError</span></span><a class="headerlink" href="#compression.zstd.ZstdError" title="Link to this definition">¶</a></dt>
|
||
<dd><p>This exception is raised when an error occurs during compression or
|
||
decompression, or while initializing the (de)compressor state.</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="reading-and-writing-compressed-files">
|
||
<h2>Reading and writing compressed files<a class="headerlink" href="#reading-and-writing-compressed-files" title="Link to this heading">¶</a></h2>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="compression.zstd.open">
|
||
<span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">open</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">file</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'rb'</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">level</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">zstd_dict</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">newline</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.open" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Open a Zstandard-compressed file in binary or text mode, returning a
|
||
<a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>.</p>
|
||
<p>The <em>file</em> argument can be either a file name (given as a
|
||
<a class="reference internal" href="../builtins/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, <a class="reference internal" href="../builtins/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> or <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like</span></a>
|
||
object), in which case the named file is opened, or it can be an existing
|
||
file object to read from or write to.</p>
|
||
<p>The mode argument can be either <code class="docutils literal notranslate"><span class="pre">'rb'</span></code> for reading (default), <code class="docutils literal notranslate"><span class="pre">'wb'</span></code> for
|
||
overwriting, <code class="docutils literal notranslate"><span class="pre">'ab'</span></code> for appending, or <code class="docutils literal notranslate"><span class="pre">'xb'</span></code> for exclusive creation.
|
||
These can equivalently be given as <code class="docutils literal notranslate"><span class="pre">'r'</span></code>, <code class="docutils literal notranslate"><span class="pre">'w'</span></code>, <code class="docutils literal notranslate"><span class="pre">'a'</span></code>, and <code class="docutils literal notranslate"><span class="pre">'x'</span></code>
|
||
respectively. You may also open in text mode with <code class="docutils literal notranslate"><span class="pre">'rt'</span></code>, <code class="docutils literal notranslate"><span class="pre">'wt'</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">'at'</span></code>, and <code class="docutils literal notranslate"><span class="pre">'xt'</span></code> respectively.</p>
|
||
<p>When reading, the <em>options</em> argument can be a dictionary providing advanced
|
||
decompression parameters; see <a class="reference internal" href="#compression.zstd.DecompressionParameter" title="compression.zstd.DecompressionParameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DecompressionParameter</span></code></a> for detailed
|
||
information about supported
|
||
parameters. The <em>zstd_dict</em> argument is a <a class="reference internal" href="#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a> instance to be
|
||
used during decompression. When reading, if the <em>level</em>
|
||
argument is not None, a <code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code> will be raised.</p>
|
||
<p>When writing, the <em>options</em> argument can be a dictionary
|
||
providing advanced compression parameters; see
|
||
<a class="reference internal" href="#compression.zstd.CompressionParameter" title="compression.zstd.CompressionParameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">CompressionParameter</span></code></a> for detailed information about supported
|
||
parameters. The <em>level</em> argument is the compression level to use when
|
||
writing compressed data. Only one of <em>level</em> or <em>options</em> may be non-None.
|
||
The <em>zstd_dict</em> argument is a <a class="reference internal" href="#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a> instance to be used during
|
||
compression.</p>
|
||
<p>In binary mode, this function is equivalent to the <a class="reference internal" href="#compression.zstd.ZstdFile" title="compression.zstd.ZstdFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdFile</span></code></a>
|
||
constructor: <code class="docutils literal notranslate"><span class="pre">ZstdFile(file,</span> <span class="pre">mode,</span> <span class="pre">...)</span></code>. In this case, the
|
||
<em>encoding</em>, <em>errors</em>, and <em>newline</em> parameters must not be provided.</p>
|
||
<p>In text mode, a <a class="reference internal" href="#compression.zstd.ZstdFile" title="compression.zstd.ZstdFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdFile</span></code></a> object is created, and wrapped in an
|
||
<a class="reference internal" href="io.html#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.TextIOWrapper</span></code></a> instance with the specified encoding, error
|
||
handling behavior, and line endings.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdFile">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">ZstdFile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">file</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'rb'</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">level</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">zstd_dict</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.ZstdFile" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Open a Zstandard-compressed file in binary mode.</p>
|
||
<p>A <code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdFile</span></code> can wrap an already-open <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>, or operate
|
||
directly on a named file. The <em>file</em> argument specifies either the file
|
||
object to wrap, or the name of the file to open (as a <a class="reference internal" href="../builtins/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>,
|
||
<a class="reference internal" href="../builtins/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> or <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like</span></a> object). If
|
||
wrapping an existing file object, the wrapped file will not be closed when
|
||
the <code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdFile</span></code> is closed.</p>
|
||
<p>The <em>mode</em> argument can be either <code class="docutils literal notranslate"><span class="pre">'rb'</span></code> for reading (default), <code class="docutils literal notranslate"><span class="pre">'wb'</span></code>
|
||
for overwriting, <code class="docutils literal notranslate"><span class="pre">'xb'</span></code> for exclusive creation, or <code class="docutils literal notranslate"><span class="pre">'ab'</span></code> for appending.
|
||
These can equivalently be given as <code class="docutils literal notranslate"><span class="pre">'r'</span></code>, <code class="docutils literal notranslate"><span class="pre">'w'</span></code>, <code class="docutils literal notranslate"><span class="pre">'x'</span></code> and <code class="docutils literal notranslate"><span class="pre">'a'</span></code>
|
||
respectively.</p>
|
||
<p>If <em>file</em> is a file object (rather than an actual file name), a mode of
|
||
<code class="docutils literal notranslate"><span class="pre">'w'</span></code> does not truncate the file, and is instead equivalent to <code class="docutils literal notranslate"><span class="pre">'a'</span></code>.</p>
|
||
<p>When reading, the <em>options</em> argument can be a dictionary
|
||
providing advanced decompression parameters; see
|
||
<a class="reference internal" href="#compression.zstd.DecompressionParameter" title="compression.zstd.DecompressionParameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DecompressionParameter</span></code></a> for detailed information about supported
|
||
parameters. The <em>zstd_dict</em> argument is a <a class="reference internal" href="#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a> instance to be
|
||
used during decompression. When reading, if the <em>level</em>
|
||
argument is not None, a <code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code> will be raised.</p>
|
||
<p>When writing, the <em>options</em> argument can be a dictionary
|
||
providing advanced compression parameters; see
|
||
<a class="reference internal" href="#compression.zstd.CompressionParameter" title="compression.zstd.CompressionParameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">CompressionParameter</span></code></a> for detailed information about supported
|
||
parameters. The <em>level</em> argument is the compression level to use when
|
||
writing compressed data. Only one of <em>level</em> or <em>options</em> may be passed. The
|
||
<em>zstd_dict</em> argument is a <a class="reference internal" href="#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a> instance to be used during
|
||
compression.</p>
|
||
<p><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdFile</span></code> supports all the members specified by
|
||
<a class="reference internal" href="io.html#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.BufferedIOBase</span></code></a>, except for <a class="reference internal" href="io.html#io.BufferedIOBase.detach" title="io.BufferedIOBase.detach"><code class="xref py py-meth docutils literal notranslate"><span class="pre">detach()</span></code></a>
|
||
and <a class="reference internal" href="io.html#io.IOBase.truncate" title="io.IOBase.truncate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">truncate()</span></code></a>.
|
||
Iteration and the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement are supported.</p>
|
||
<p>The following method and attributes are also provided:</p>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdFile.peek">
|
||
<span class="sig-name descname"><span class="pre">peek</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.ZstdFile.peek" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return buffered data without advancing the file position. At least one
|
||
byte of data will be returned, unless EOF has been reached. The exact
|
||
number of bytes returned is unspecified (the <em>size</em> argument is ignored).</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>While calling <code class="xref py py-meth docutils literal notranslate"><span class="pre">peek()</span></code> does not change the file position of
|
||
the <code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdFile</span></code>, it may change the position of the underlying
|
||
file object (for example, if the <code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdFile</span></code> was constructed by
|
||
passing a file object for <em>file</em>).</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdFile.mode">
|
||
<span class="sig-name descname"><span class="pre">mode</span></span><a class="headerlink" href="#compression.zstd.ZstdFile.mode" title="Link to this definition">¶</a></dt>
|
||
<dd><p><code class="docutils literal notranslate"><span class="pre">'rb'</span></code> for reading and <code class="docutils literal notranslate"><span class="pre">'wb'</span></code> for writing.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdFile.name">
|
||
<span class="sig-name descname"><span class="pre">name</span></span><a class="headerlink" href="#compression.zstd.ZstdFile.name" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The name of the Zstandard file. Equivalent to the <a class="reference internal" href="io.html#io.FileIO.name" title="io.FileIO.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a>
|
||
attribute of the underlying <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="compressing-and-decompressing-data-in-memory">
|
||
<h2>Compressing and decompressing data in memory<a class="headerlink" href="#compressing-and-decompressing-data-in-memory" title="Link to this heading">¶</a></h2>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="compression.zstd.compress">
|
||
<span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">compress</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">level</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">zstd_dict</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.compress" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Compress <em>data</em> (a <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>), returning the compressed
|
||
data as a <a class="reference internal" href="../builtins/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object.</p>
|
||
<p>The <em>level</em> argument is an integer controlling the level of
|
||
compression. <em>level</em> is an alternative to setting
|
||
<a class="reference internal" href="#compression.zstd.CompressionParameter.compression_level" title="compression.zstd.CompressionParameter.compression_level"><code class="xref py py-attr docutils literal notranslate"><span class="pre">CompressionParameter.compression_level</span></code></a> in <em>options</em>. Use
|
||
<a class="reference internal" href="#compression.zstd.CompressionParameter.bounds" title="compression.zstd.CompressionParameter.bounds"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bounds()</span></code></a> on
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">compression_level</span></code> to get the values that can
|
||
be passed for <em>level</em>. If advanced compression options are needed, the
|
||
<em>level</em> argument must be omitted and in the <em>options</em> dictionary the
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">CompressionParameter.compression_level</span></code> parameter should be set.</p>
|
||
<p>The <em>options</em> argument is a Python dictionary containing advanced
|
||
compression parameters. The valid keys and values for compression parameters
|
||
are documented as part of the <a class="reference internal" href="#compression.zstd.CompressionParameter" title="compression.zstd.CompressionParameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">CompressionParameter</span></code></a> documentation.</p>
|
||
<p>The <em>zstd_dict</em> argument is an instance of <a class="reference internal" href="#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a>
|
||
containing trained data to improve compression efficiency. The
|
||
function <a class="reference internal" href="#compression.zstd.train_dict" title="compression.zstd.train_dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">train_dict()</span></code></a> can be used to generate a Zstandard dictionary.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="compression.zstd.decompress">
|
||
<span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">decompress</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">zstd_dict</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.decompress" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Decompress <em>data</em> (a <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>), returning the uncompressed
|
||
data as a <a class="reference internal" href="../builtins/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object.</p>
|
||
<p>The <em>options</em> argument is a Python dictionary containing advanced
|
||
decompression parameters. The valid keys and values for compression
|
||
parameters are documented as part of the <a class="reference internal" href="#compression.zstd.DecompressionParameter" title="compression.zstd.DecompressionParameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DecompressionParameter</span></code></a>
|
||
documentation.</p>
|
||
<p>The <em>zstd_dict</em> argument is an instance of <a class="reference internal" href="#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a>
|
||
containing trained data used during compression. This must be
|
||
the same Zstandard dictionary used during compression.</p>
|
||
<p>If <em>data</em> is the concatenation of multiple distinct compressed frames,
|
||
decompress all of these frames, and return the concatenation of the results.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdCompressor">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">ZstdCompressor</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">level</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">zstd_dict</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.ZstdCompressor" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Create a compressor object, which can be used to compress data
|
||
incrementally.</p>
|
||
<p>For a more convenient way of compressing a single chunk of data, see the
|
||
module-level function <a class="reference internal" href="#compression.zstd.compress" title="compression.zstd.compress"><code class="xref py py-func docutils literal notranslate"><span class="pre">compress()</span></code></a>.</p>
|
||
<p>The <em>level</em> argument is an integer controlling the level of
|
||
compression. <em>level</em> is an alternative to setting
|
||
<a class="reference internal" href="#compression.zstd.CompressionParameter.compression_level" title="compression.zstd.CompressionParameter.compression_level"><code class="xref py py-attr docutils literal notranslate"><span class="pre">CompressionParameter.compression_level</span></code></a> in <em>options</em>. Use
|
||
<a class="reference internal" href="#compression.zstd.CompressionParameter.bounds" title="compression.zstd.CompressionParameter.bounds"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bounds()</span></code></a> on
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">compression_level</span></code> to get the values that can
|
||
be passed for <em>level</em>. If advanced compression options are needed, the
|
||
<em>level</em> argument must be omitted and in the <em>options</em> dictionary the
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">CompressionParameter.compression_level</span></code> parameter should be set.</p>
|
||
<p>The <em>options</em> argument is a Python dictionary containing advanced
|
||
compression parameters. The valid keys and values for compression parameters
|
||
are documented as part of the <a class="reference internal" href="#compression.zstd.CompressionParameter" title="compression.zstd.CompressionParameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">CompressionParameter</span></code></a> documentation.</p>
|
||
<p>The <em>zstd_dict</em> argument is an optional instance of <a class="reference internal" href="#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a>
|
||
containing trained data to improve compression efficiency. The
|
||
function <a class="reference internal" href="#compression.zstd.train_dict" title="compression.zstd.train_dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">train_dict()</span></code></a> can be used to generate a Zstandard dictionary.</p>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdCompressor.compress">
|
||
<span class="sig-name descname"><span class="pre">compress</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">ZstdCompressor.CONTINUE</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.ZstdCompressor.compress" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Compress <em>data</em> (a <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>), returning a <a class="reference internal" href="../builtins/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>
|
||
object with compressed data if possible, or otherwise an empty
|
||
<code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code> object. Some of <em>data</em> may be buffered internally, for
|
||
use in later calls to <code class="xref py py-meth docutils literal notranslate"><span class="pre">compress()</span></code> and <a class="reference internal" href="#compression.zstd.ZstdCompressor.flush" title="compression.zstd.ZstdCompressor.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code></a>. The returned
|
||
data should be concatenated with the output of any previous calls to
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">compress()</span></code>.</p>
|
||
<p>The <em>mode</em> argument is a <code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdCompressor</span></code> attribute, either
|
||
<a class="reference internal" href="#compression.zstd.ZstdCompressor.CONTINUE" title="compression.zstd.ZstdCompressor.CONTINUE"><code class="xref py py-attr docutils literal notranslate"><span class="pre">CONTINUE</span></code></a>, <a class="reference internal" href="#compression.zstd.ZstdCompressor.FLUSH_BLOCK" title="compression.zstd.ZstdCompressor.FLUSH_BLOCK"><code class="xref py py-attr docutils literal notranslate"><span class="pre">FLUSH_BLOCK</span></code></a>,
|
||
or <a class="reference internal" href="#compression.zstd.ZstdCompressor.FLUSH_FRAME" title="compression.zstd.ZstdCompressor.FLUSH_FRAME"><code class="xref py py-attr docutils literal notranslate"><span class="pre">FLUSH_FRAME</span></code></a>.</p>
|
||
<p>When all data has been provided to the compressor, call the
|
||
<a class="reference internal" href="#compression.zstd.ZstdCompressor.flush" title="compression.zstd.ZstdCompressor.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code></a> method to finish the compression process. If
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">compress()</span></code> is called with <em>mode</em> set to <a class="reference internal" href="#compression.zstd.ZstdCompressor.FLUSH_FRAME" title="compression.zstd.ZstdCompressor.FLUSH_FRAME"><code class="xref py py-attr docutils literal notranslate"><span class="pre">FLUSH_FRAME</span></code></a>,
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code> should not be called, as it would write out a new empty
|
||
frame.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdCompressor.flush">
|
||
<span class="sig-name descname"><span class="pre">flush</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">ZstdCompressor.FLUSH_FRAME</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.ZstdCompressor.flush" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Finish the compression process, returning a <a class="reference internal" href="../builtins/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object
|
||
containing any data stored in the compressor’s internal buffers.</p>
|
||
<p>The <em>mode</em> argument is a <code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdCompressor</span></code> attribute, either
|
||
<a class="reference internal" href="#compression.zstd.ZstdCompressor.FLUSH_BLOCK" title="compression.zstd.ZstdCompressor.FLUSH_BLOCK"><code class="xref py py-attr docutils literal notranslate"><span class="pre">FLUSH_BLOCK</span></code></a>, or <a class="reference internal" href="#compression.zstd.ZstdCompressor.FLUSH_FRAME" title="compression.zstd.ZstdCompressor.FLUSH_FRAME"><code class="xref py py-attr docutils literal notranslate"><span class="pre">FLUSH_FRAME</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdCompressor.set_pledged_input_size">
|
||
<span class="sig-name descname"><span class="pre">set_pledged_input_size</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.ZstdCompressor.set_pledged_input_size" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Specify the amount of uncompressed data <em>size</em> that will be provided for
|
||
the next frame. <em>size</em> will be written into the frame header of the next
|
||
frame unless <a class="reference internal" href="#compression.zstd.CompressionParameter.content_size_flag" title="compression.zstd.CompressionParameter.content_size_flag"><code class="xref py py-attr docutils literal notranslate"><span class="pre">CompressionParameter.content_size_flag</span></code></a> is <code class="docutils literal notranslate"><span class="pre">False</span></code>
|
||
or <code class="docutils literal notranslate"><span class="pre">0</span></code>. A size of <code class="docutils literal notranslate"><span class="pre">0</span></code> means that the frame is empty. If <em>size</em> is
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code>, the frame header will omit the frame size. Frames that include
|
||
the uncompressed data size require less memory to decompress, especially
|
||
at higher compression levels.</p>
|
||
<p>If <a class="reference internal" href="#compression.zstd.ZstdCompressor.last_mode" title="compression.zstd.ZstdCompressor.last_mode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">last_mode</span></code></a> is not <a class="reference internal" href="#compression.zstd.ZstdCompressor.FLUSH_FRAME" title="compression.zstd.ZstdCompressor.FLUSH_FRAME"><code class="xref py py-attr docutils literal notranslate"><span class="pre">FLUSH_FRAME</span></code></a>, a
|
||
<a class="reference internal" href="../builtins/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised as the compressor is not at the start of
|
||
a frame. If the pledged size does not match the actual size of data
|
||
provided to <a class="reference internal" href="#compression.zstd.ZstdCompressor.compress" title="compression.zstd.ZstdCompressor.compress"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compress()</span></code></a>, future calls to <code class="xref py py-meth docutils literal notranslate"><span class="pre">compress()</span></code> or
|
||
<a class="reference internal" href="#compression.zstd.ZstdCompressor.flush" title="compression.zstd.ZstdCompressor.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code></a> may raise <a class="reference internal" href="#compression.zstd.ZstdError" title="compression.zstd.ZstdError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ZstdError</span></code></a> and the last chunk of data may
|
||
be lost.</p>
|
||
<p>After <a class="reference internal" href="#compression.zstd.ZstdCompressor.flush" title="compression.zstd.ZstdCompressor.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code></a> or <a class="reference internal" href="#compression.zstd.ZstdCompressor.compress" title="compression.zstd.ZstdCompressor.compress"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compress()</span></code></a> are called with mode
|
||
<a class="reference internal" href="#compression.zstd.ZstdCompressor.FLUSH_FRAME" title="compression.zstd.ZstdCompressor.FLUSH_FRAME"><code class="xref py py-attr docutils literal notranslate"><span class="pre">FLUSH_FRAME</span></code></a>, the next frame will not include the frame size into
|
||
the header unless <code class="xref py py-meth docutils literal notranslate"><span class="pre">set_pledged_input_size()</span></code> is called again.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdCompressor.CONTINUE">
|
||
<span class="sig-name descname"><span class="pre">CONTINUE</span></span><a class="headerlink" href="#compression.zstd.ZstdCompressor.CONTINUE" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Collect more data for compression, which may or may not generate output
|
||
immediately. This mode optimizes the compression ratio by maximizing the
|
||
amount of data per block and frame.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdCompressor.FLUSH_BLOCK">
|
||
<span class="sig-name descname"><span class="pre">FLUSH_BLOCK</span></span><a class="headerlink" href="#compression.zstd.ZstdCompressor.FLUSH_BLOCK" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Complete and write a block to the data stream. The data returned so far
|
||
can be immediately decompressed. Past data can still be referenced in
|
||
future blocks generated by calls to <a class="reference internal" href="#compression.zstd.ZstdCompressor.compress" title="compression.zstd.ZstdCompressor.compress"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compress()</span></code></a>,
|
||
improving compression.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdCompressor.FLUSH_FRAME">
|
||
<span class="sig-name descname"><span class="pre">FLUSH_FRAME</span></span><a class="headerlink" href="#compression.zstd.ZstdCompressor.FLUSH_FRAME" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Complete and write out a frame. Future data provided to
|
||
<a class="reference internal" href="#compression.zstd.ZstdCompressor.compress" title="compression.zstd.ZstdCompressor.compress"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compress()</span></code></a> will be written into a new frame and
|
||
<em>cannot</em> reference past data.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdCompressor.last_mode">
|
||
<span class="sig-name descname"><span class="pre">last_mode</span></span><a class="headerlink" href="#compression.zstd.ZstdCompressor.last_mode" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The last mode passed to either <a class="reference internal" href="#compression.zstd.ZstdCompressor.compress" title="compression.zstd.ZstdCompressor.compress"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compress()</span></code></a> or <a class="reference internal" href="#compression.zstd.ZstdCompressor.flush" title="compression.zstd.ZstdCompressor.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code></a>.
|
||
The value can be one of <a class="reference internal" href="#compression.zstd.ZstdCompressor.CONTINUE" title="compression.zstd.ZstdCompressor.CONTINUE"><code class="xref py py-attr docutils literal notranslate"><span class="pre">CONTINUE</span></code></a>, <a class="reference internal" href="#compression.zstd.ZstdCompressor.FLUSH_BLOCK" title="compression.zstd.ZstdCompressor.FLUSH_BLOCK"><code class="xref py py-attr docutils literal notranslate"><span class="pre">FLUSH_BLOCK</span></code></a>, or
|
||
<a class="reference internal" href="#compression.zstd.ZstdCompressor.FLUSH_FRAME" title="compression.zstd.ZstdCompressor.FLUSH_FRAME"><code class="xref py py-attr docutils literal notranslate"><span class="pre">FLUSH_FRAME</span></code></a>. The initial value is <code class="xref py py-attr docutils literal notranslate"><span class="pre">FLUSH_FRAME</span></code>,
|
||
signifying that the compressor is at the start of a new frame.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdDecompressor">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">ZstdDecompressor</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">zstd_dict</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.ZstdDecompressor" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Create a decompressor object, which can be used to decompress data
|
||
incrementally.</p>
|
||
<p>For a more convenient way of decompressing an entire compressed stream at
|
||
once, see the module-level function <a class="reference internal" href="#compression.zstd.decompress" title="compression.zstd.decompress"><code class="xref py py-func docutils literal notranslate"><span class="pre">decompress()</span></code></a>.</p>
|
||
<p>The <em>options</em> argument is a Python dictionary containing advanced
|
||
decompression parameters. The valid keys and values for compression
|
||
parameters are documented as part of the <a class="reference internal" href="#compression.zstd.DecompressionParameter" title="compression.zstd.DecompressionParameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DecompressionParameter</span></code></a>
|
||
documentation.</p>
|
||
<p>The <em>zstd_dict</em> argument is an instance of <a class="reference internal" href="#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a>
|
||
containing trained data used during compression. This must be
|
||
the same Zstandard dictionary used during compression.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This class does not transparently handle inputs containing multiple
|
||
compressed frames, unlike the <a class="reference internal" href="#compression.zstd.decompress" title="compression.zstd.decompress"><code class="xref py py-func docutils literal notranslate"><span class="pre">decompress()</span></code></a> function and
|
||
<a class="reference internal" href="#compression.zstd.ZstdFile" title="compression.zstd.ZstdFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdFile</span></code></a> class. To decompress a multi-frame input, you should
|
||
use <code class="xref py py-func docutils literal notranslate"><span class="pre">decompress()</span></code>, <code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdFile</span></code> if working with a
|
||
<a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>, or multiple <code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDecompressor</span></code> instances.</p>
|
||
</div>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdDecompressor.decompress">
|
||
<span class="sig-name descname"><span class="pre">decompress</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">max_length</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.ZstdDecompressor.decompress" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Decompress <em>data</em> (a <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>), returning
|
||
uncompressed data as bytes. Some of <em>data</em> may be buffered
|
||
internally, for use in later calls to <code class="xref py py-meth docutils literal notranslate"><span class="pre">decompress()</span></code>.
|
||
The returned data should be concatenated with the output of any previous
|
||
calls to <code class="xref py py-meth docutils literal notranslate"><span class="pre">decompress()</span></code>.</p>
|
||
<p>If <em>max_length</em> is non-negative, the method returns at most <em>max_length</em>
|
||
bytes of decompressed data. If this limit is reached and further
|
||
output can be produced (or EOF is reached), the <a class="reference internal" href="#compression.zstd.ZstdDecompressor.needs_input" title="compression.zstd.ZstdDecompressor.needs_input"><code class="xref py py-attr docutils literal notranslate"><span class="pre">needs_input</span></code></a>
|
||
attribute will be set to <code class="docutils literal notranslate"><span class="pre">False</span></code>. In this case, the next call to
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">decompress()</span></code> may provide <em>data</em> as <code class="docutils literal notranslate"><span class="pre">b''</span></code> to obtain
|
||
more of the output. The full content can thus be read like:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">process_output</span><span class="p">(</span><span class="n">d</span><span class="o">.</span><span class="n">decompress</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">max_length</span><span class="p">))</span>
|
||
<span class="k">while</span> <span class="ow">not</span> <span class="n">d</span><span class="o">.</span><span class="n">eof</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">d</span><span class="o">.</span><span class="n">needs_input</span><span class="p">:</span>
|
||
<span class="n">process_output</span><span class="p">(</span><span class="n">d</span><span class="o">.</span><span class="n">decompress</span><span class="p">(</span><span class="sa">b</span><span class="s2">""</span><span class="p">,</span> <span class="n">max_length</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If all of the input data was decompressed and returned (either
|
||
because this was less than <em>max_length</em> bytes, or because
|
||
<em>max_length</em> was negative), the <a class="reference internal" href="#compression.zstd.ZstdDecompressor.needs_input" title="compression.zstd.ZstdDecompressor.needs_input"><code class="xref py py-attr docutils literal notranslate"><span class="pre">needs_input</span></code></a> attribute
|
||
will be set to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>
|
||
<p>Attempting to decompress data after the end of a frame will raise a
|
||
<a class="reference internal" href="../builtins/exceptions.html#EOFError" title="EOFError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">EOFError</span></code></a>. Any data found after the end of the frame is ignored
|
||
and saved in the <a class="reference internal" href="#compression.zstd.ZstdDecompressor.unused_data" title="compression.zstd.ZstdDecompressor.unused_data"><code class="xref py py-attr docutils literal notranslate"><span class="pre">unused_data</span></code></a> attribute.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdDecompressor.eof">
|
||
<span class="sig-name descname"><span class="pre">eof</span></span><a class="headerlink" href="#compression.zstd.ZstdDecompressor.eof" title="Link to this definition">¶</a></dt>
|
||
<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the end-of-stream marker has been reached.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdDecompressor.unused_data">
|
||
<span class="sig-name descname"><span class="pre">unused_data</span></span><a class="headerlink" href="#compression.zstd.ZstdDecompressor.unused_data" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Data found after the end of the compressed stream.</p>
|
||
<p>Before the end of the stream is reached, this will be <code class="docutils literal notranslate"><span class="pre">b''</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdDecompressor.needs_input">
|
||
<span class="sig-name descname"><span class="pre">needs_input</span></span><a class="headerlink" href="#compression.zstd.ZstdDecompressor.needs_input" title="Link to this definition">¶</a></dt>
|
||
<dd><p><code class="docutils literal notranslate"><span class="pre">False</span></code> if the <a class="reference internal" href="#compression.zstd.ZstdDecompressor.decompress" title="compression.zstd.ZstdDecompressor.decompress"><code class="xref py py-meth docutils literal notranslate"><span class="pre">decompress()</span></code></a> method can provide more
|
||
decompressed data before requiring new compressed input.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="zstandard-dictionaries">
|
||
<h2>Zstandard dictionaries<a class="headerlink" href="#zstandard-dictionaries" title="Link to this heading">¶</a></h2>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="compression.zstd.train_dict">
|
||
<span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">train_dict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">samples</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dict_size</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.train_dict" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Train a Zstandard dictionary, returning a <a class="reference internal" href="#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a> instance.
|
||
Zstandard dictionaries enable more efficient compression of smaller sizes
|
||
of data, which is traditionally difficult to compress due to less
|
||
repetition. If you are compressing multiple similar groups of data (such as
|
||
similar files), Zstandard dictionaries can improve compression ratios and
|
||
speed significantly.</p>
|
||
<p>The <em>samples</em> argument (an iterable of <a class="reference internal" href="../builtins/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> objects), is the
|
||
population of samples used to train the Zstandard dictionary.</p>
|
||
<p>The <em>dict_size</em> argument, an integer, is the maximum size (in bytes) the
|
||
Zstandard dictionary should be. The Zstandard documentation suggests an
|
||
absolute maximum of no more than 100 KB, but the maximum can often be smaller
|
||
depending on the data. Larger dictionaries generally slow down compression,
|
||
but improve compression ratios. Smaller dictionaries lead to faster
|
||
compression, but reduce the compression ratio.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="compression.zstd.finalize_dict">
|
||
<span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">finalize_dict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">zstd_dict</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">samples</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dict_size</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">level</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.finalize_dict" title="Link to this definition">¶</a></dt>
|
||
<dd><p>An advanced function for converting a “raw content” Zstandard dictionary into
|
||
a regular Zstandard dictionary. “Raw content” dictionaries are a sequence of
|
||
bytes that do not need to follow the structure of a normal Zstandard
|
||
dictionary.</p>
|
||
<p>The <em>zstd_dict</em> argument is a <a class="reference internal" href="#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a> instance with
|
||
the <a class="reference internal" href="#compression.zstd.ZstdDict.dict_content" title="compression.zstd.ZstdDict.dict_content"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dict_content</span></code></a> containing the raw dictionary contents.</p>
|
||
<p>The <em>samples</em> argument (an iterable of <a class="reference internal" href="../builtins/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> objects), contains
|
||
sample data for generating the Zstandard dictionary.</p>
|
||
<p>The <em>dict_size</em> argument, an integer, is the maximum size (in bytes) the
|
||
Zstandard dictionary should be. See <a class="reference internal" href="#compression.zstd.train_dict" title="compression.zstd.train_dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">train_dict()</span></code></a> for
|
||
suggestions on the maximum dictionary size.</p>
|
||
<p>The <em>level</em> argument (an integer) is the compression level expected to be
|
||
passed to the compressors using this dictionary. The dictionary information
|
||
varies for each compression level, so tuning for the proper compression
|
||
level can make compression more efficient.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdDict">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">ZstdDict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dict_content</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">is_raw</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.ZstdDict" title="Link to this definition">¶</a></dt>
|
||
<dd><p>A wrapper around Zstandard dictionaries. Dictionaries can be used to improve
|
||
the compression of many small chunks of data. Use <a class="reference internal" href="#compression.zstd.train_dict" title="compression.zstd.train_dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">train_dict()</span></code></a> if you
|
||
need to train a new dictionary from sample data.</p>
|
||
<p>The <em>dict_content</em> argument (a <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>), is the already
|
||
trained dictionary information.</p>
|
||
<p>The <em>is_raw</em> argument, a boolean, is an advanced parameter controlling the
|
||
meaning of <em>dict_content</em>. <code class="docutils literal notranslate"><span class="pre">True</span></code> means <em>dict_content</em> is a “raw content”
|
||
dictionary, without any format restrictions. <code class="docutils literal notranslate"><span class="pre">False</span></code> means <em>dict_content</em>
|
||
is an ordinary Zstandard dictionary, created from Zstandard functions,
|
||
for example, <a class="reference internal" href="#compression.zstd.train_dict" title="compression.zstd.train_dict"><code class="xref py py-func docutils literal notranslate"><span class="pre">train_dict()</span></code></a> or the external <strong class="program">zstd</strong> CLI.</p>
|
||
<p>When passing a <code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code> to a function, the
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">as_digested_dict</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">as_undigested_dict</span></code> attributes can
|
||
control how the dictionary is loaded by passing them as the <code class="docutils literal notranslate"><span class="pre">zstd_dict</span></code>
|
||
argument, for example, <code class="docutils literal notranslate"><span class="pre">compress(data,</span> <span class="pre">zstd_dict=zd.as_digested_dict)</span></code>.
|
||
Digesting a dictionary is a costly operation that occurs when loading a
|
||
Zstandard dictionary. When making multiple calls to compression or
|
||
decompression, passing a digested dictionary will reduce the overhead of
|
||
loading the dictionary.</p>
|
||
<blockquote>
|
||
<div><table class="docutils align-default" id="id1">
|
||
<caption><span class="caption-text">Difference for compression</span><a class="headerlink" href="#id1" title="Link to this table">¶</a></caption>
|
||
<colgroup>
|
||
<col style="width: 29.4%" />
|
||
<col style="width: 41.2%" />
|
||
<col style="width: 29.4%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"></th>
|
||
<th class="head"><p>Digested dictionary</p></th>
|
||
<th class="head"><p>Undigested dictionary</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>Advanced parameters of the compressor which may be overridden by
|
||
the dictionary’s parameters</p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">window_log</span></code>, <code class="docutils literal notranslate"><span class="pre">hash_log</span></code>, <code class="docutils literal notranslate"><span class="pre">chain_log</span></code>, <code class="docutils literal notranslate"><span class="pre">search_log</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">min_match</span></code>, <code class="docutils literal notranslate"><span class="pre">target_length</span></code>, <code class="docutils literal notranslate"><span class="pre">strategy</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">enable_long_distance_matching</span></code>, <code class="docutils literal notranslate"><span class="pre">ldm_hash_log</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">ldm_min_match</span></code>, <code class="docutils literal notranslate"><span class="pre">ldm_bucket_size_log</span></code>, <code class="docutils literal notranslate"><span class="pre">ldm_hash_rate_log</span></code>,
|
||
and some non-public parameters.</p></td>
|
||
<td><p>None</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code> internally caches the dictionary</p></td>
|
||
<td><p>Yes. It’s faster when loading a digested dictionary again with the
|
||
same compression level.</p></td>
|
||
<td><p>No. If you wish to load an undigested dictionary multiple times,
|
||
consider reusing a compressor object.</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div></blockquote>
|
||
<p>If passing a <code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code> without any attribute, an undigested
|
||
dictionary is passed by default when compressing and a digested dictionary
|
||
is generated if necessary and passed by default when decompressing.</p>
|
||
<blockquote>
|
||
<div><dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdDict.dict_content">
|
||
<span class="sig-name descname"><span class="pre">dict_content</span></span><a class="headerlink" href="#compression.zstd.ZstdDict.dict_content" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The content of the Zstandard dictionary, a <code class="docutils literal notranslate"><span class="pre">bytes</span></code> object. It’s the
|
||
same as the <em>dict_content</em> argument in the <code class="docutils literal notranslate"><span class="pre">__init__</span></code> method. It can
|
||
be used with other programs, such as the <code class="docutils literal notranslate"><span class="pre">zstd</span></code> CLI program.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdDict.dict_id">
|
||
<span class="sig-name descname"><span class="pre">dict_id</span></span><a class="headerlink" href="#compression.zstd.ZstdDict.dict_id" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Identifier of the Zstandard dictionary, a non-negative int value.</p>
|
||
<p>Non-zero means the dictionary is ordinary, created by Zstandard
|
||
functions and following the Zstandard format.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">0</span></code> means a “raw content” dictionary, free of any format restriction,
|
||
used for advanced users.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The meaning of <code class="docutils literal notranslate"><span class="pre">0</span></code> for <code class="xref py py-attr docutils literal notranslate"><span class="pre">ZstdDict.dict_id</span></code> is different
|
||
from the <code class="docutils literal notranslate"><span class="pre">dictionary_id</span></code> attribute to the <a class="reference internal" href="#compression.zstd.get_frame_info" title="compression.zstd.get_frame_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_frame_info()</span></code></a>
|
||
function.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdDict.as_digested_dict">
|
||
<span class="sig-name descname"><span class="pre">as_digested_dict</span></span><a class="headerlink" href="#compression.zstd.ZstdDict.as_digested_dict" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Load as a digested dictionary.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.ZstdDict.as_undigested_dict">
|
||
<span class="sig-name descname"><span class="pre">as_undigested_dict</span></span><a class="headerlink" href="#compression.zstd.ZstdDict.as_undigested_dict" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Load as an undigested dictionary.</p>
|
||
</dd></dl>
|
||
|
||
</div></blockquote>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="advanced-parameter-control">
|
||
<h2>Advanced parameter control<a class="headerlink" href="#advanced-parameter-control" title="Link to this heading">¶</a></h2>
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">CompressionParameter</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter" title="Link to this definition">¶</a></dt>
|
||
<dd><p>An <a class="reference internal" href="enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a> containing the advanced compression parameter
|
||
keys that can be used when compressing data.</p>
|
||
<p>The <a class="reference internal" href="#compression.zstd.CompressionParameter.bounds" title="compression.zstd.CompressionParameter.bounds"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bounds()</span></code></a> method can be used on any attribute to get the valid
|
||
values for that parameter.</p>
|
||
<p>Parameters are optional; any omitted parameter will have its value selected
|
||
automatically.</p>
|
||
<p>Example getting the lower and upper bound of <a class="reference internal" href="#compression.zstd.CompressionParameter.compression_level" title="compression.zstd.CompressionParameter.compression_level"><code class="xref py py-attr docutils literal notranslate"><span class="pre">compression_level</span></code></a>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">lower</span><span class="p">,</span> <span class="n">upper</span> <span class="o">=</span> <span class="n">CompressionParameter</span><span class="o">.</span><span class="n">compression_level</span><span class="o">.</span><span class="n">bounds</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Example setting the <a class="reference internal" href="#compression.zstd.CompressionParameter.window_log" title="compression.zstd.CompressionParameter.window_log"><code class="xref py py-attr docutils literal notranslate"><span class="pre">window_log</span></code></a> to the maximum size:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">_lower</span><span class="p">,</span> <span class="n">upper</span> <span class="o">=</span> <span class="n">CompressionParameter</span><span class="o">.</span><span class="n">window_log</span><span class="o">.</span><span class="n">bounds</span><span class="p">()</span>
|
||
<span class="n">options</span> <span class="o">=</span> <span class="p">{</span><span class="n">CompressionParameter</span><span class="o">.</span><span class="n">window_log</span><span class="p">:</span> <span class="n">upper</span><span class="p">}</span>
|
||
<span class="n">compress</span><span class="p">(</span><span class="sa">b</span><span class="s1">'venezuelan beaver cheese'</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="n">options</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.bounds">
|
||
<span class="sig-name descname"><span class="pre">bounds</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.CompressionParameter.bounds" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the tuple of int bounds, <code class="docutils literal notranslate"><span class="pre">(lower,</span> <span class="pre">upper)</span></code>, of a compression
|
||
parameter. This method should be called on the attribute you wish to
|
||
retrieve the bounds of. For example, to get the valid values for
|
||
<a class="reference internal" href="#compression.zstd.CompressionParameter.compression_level" title="compression.zstd.CompressionParameter.compression_level"><code class="xref py py-attr docutils literal notranslate"><span class="pre">compression_level</span></code></a>, one may check the result of
|
||
<code class="docutils literal notranslate"><span class="pre">CompressionParameter.compression_level.bounds()</span></code>.</p>
|
||
<p>Both the lower and upper bounds are inclusive.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.compression_level">
|
||
<span class="sig-name descname"><span class="pre">compression_level</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.compression_level" title="Link to this definition">¶</a></dt>
|
||
<dd><p>A high-level means of setting other compression parameters that affect
|
||
the speed and ratio of compressing data.</p>
|
||
<p>Regular compression levels are greater than <code class="docutils literal notranslate"><span class="pre">0</span></code>. Values greater than
|
||
<code class="docutils literal notranslate"><span class="pre">20</span></code> are considered “ultra” compression and require more memory than
|
||
other levels. Negative values can be used to trade off faster compression
|
||
for worse compression ratios.</p>
|
||
<p>Setting the level to zero uses <a class="reference internal" href="#compression.zstd.COMPRESSION_LEVEL_DEFAULT" title="compression.zstd.COMPRESSION_LEVEL_DEFAULT"><code class="xref py py-attr docutils literal notranslate"><span class="pre">COMPRESSION_LEVEL_DEFAULT</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.window_log">
|
||
<span class="sig-name descname"><span class="pre">window_log</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.window_log" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Maximum allowed back-reference distance the compressor can use when
|
||
compressing data, expressed as power of two, <code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre"><<</span> <span class="pre">window_log</span></code> bytes.
|
||
This parameter greatly influences the memory usage of compression. Higher
|
||
values require more memory but gain better compression values.</p>
|
||
<p>A value of zero causes the value to be selected automatically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.hash_log">
|
||
<span class="sig-name descname"><span class="pre">hash_log</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.hash_log" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Size of the initial probe table, as a power of two. The resulting memory
|
||
usage is <code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre"><<</span> <span class="pre">(hash_log+2)</span></code> bytes. Larger tables improve compression
|
||
ratio of strategies <= <a class="reference internal" href="#compression.zstd.Strategy.dfast" title="compression.zstd.Strategy.dfast"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dfast</span></code></a>, and improve compression
|
||
speed of strategies > <code class="xref py py-attr docutils literal notranslate"><span class="pre">dfast</span></code>.</p>
|
||
<p>A value of zero causes the value to be selected automatically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.chain_log">
|
||
<span class="sig-name descname"><span class="pre">chain_log</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.chain_log" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Size of the multi-probe search table, as a power of two. The resulting
|
||
memory usage is <code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre"><<</span> <span class="pre">(chain_log+2)</span></code> bytes. Larger tables result in
|
||
better and slower compression. This parameter has no effect for the
|
||
<a class="reference internal" href="#compression.zstd.Strategy.fast" title="compression.zstd.Strategy.fast"><code class="xref py py-attr docutils literal notranslate"><span class="pre">fast</span></code></a> strategy. It’s still useful when using
|
||
<a class="reference internal" href="#compression.zstd.Strategy.dfast" title="compression.zstd.Strategy.dfast"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dfast</span></code></a> strategy, in which case it defines a secondary
|
||
probe table.</p>
|
||
<p>A value of zero causes the value to be selected automatically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.search_log">
|
||
<span class="sig-name descname"><span class="pre">search_log</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.search_log" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Number of search attempts, as a power of two. More attempts result in
|
||
better and slower compression. This parameter is useless for
|
||
<a class="reference internal" href="#compression.zstd.Strategy.fast" title="compression.zstd.Strategy.fast"><code class="xref py py-attr docutils literal notranslate"><span class="pre">fast</span></code></a> and <a class="reference internal" href="#compression.zstd.Strategy.dfast" title="compression.zstd.Strategy.dfast"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dfast</span></code></a> strategies.</p>
|
||
<p>A value of zero causes the value to be selected automatically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.min_match">
|
||
<span class="sig-name descname"><span class="pre">min_match</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.min_match" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Minimum size of searched matches. Larger values increase compression and
|
||
decompression speed, but decrease ratio. Note that Zstandard can still
|
||
find matches of smaller size, it just tweaks its search algorithm to look
|
||
for this size and larger. For all strategies < <a class="reference internal" href="#compression.zstd.Strategy.btopt" title="compression.zstd.Strategy.btopt"><code class="xref py py-attr docutils literal notranslate"><span class="pre">btopt</span></code></a>,
|
||
the effective minimum is <code class="docutils literal notranslate"><span class="pre">4</span></code>; for all strategies
|
||
> <a class="reference internal" href="#compression.zstd.Strategy.fast" title="compression.zstd.Strategy.fast"><code class="xref py py-attr docutils literal notranslate"><span class="pre">fast</span></code></a>, the effective maximum is <code class="docutils literal notranslate"><span class="pre">6</span></code>.</p>
|
||
<p>A value of zero causes the value to be selected automatically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.target_length">
|
||
<span class="sig-name descname"><span class="pre">target_length</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.target_length" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The impact of this field depends on the selected <a class="reference internal" href="#compression.zstd.Strategy" title="compression.zstd.Strategy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Strategy</span></code></a>.</p>
|
||
<p>For strategies <a class="reference internal" href="#compression.zstd.Strategy.btopt" title="compression.zstd.Strategy.btopt"><code class="xref py py-attr docutils literal notranslate"><span class="pre">btopt</span></code></a>, <a class="reference internal" href="#compression.zstd.Strategy.btultra" title="compression.zstd.Strategy.btultra"><code class="xref py py-attr docutils literal notranslate"><span class="pre">btultra</span></code></a> and
|
||
<a class="reference internal" href="#compression.zstd.Strategy.btultra2" title="compression.zstd.Strategy.btultra2"><code class="xref py py-attr docutils literal notranslate"><span class="pre">btultra2</span></code></a>, the value is the length of a match
|
||
considered “good enough” to stop searching. Larger values make
|
||
compression ratios better, but compresses slower.</p>
|
||
<p>For strategy <a class="reference internal" href="#compression.zstd.Strategy.fast" title="compression.zstd.Strategy.fast"><code class="xref py py-attr docutils literal notranslate"><span class="pre">fast</span></code></a>, it is the distance between match
|
||
sampling. Larger values make compression faster, but with a worse
|
||
compression ratio.</p>
|
||
<p>A value of zero causes the value to be selected automatically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.strategy">
|
||
<span class="sig-name descname"><span class="pre">strategy</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.strategy" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The higher the value of selected strategy, the more complex the
|
||
compression technique used by zstd, resulting in higher compression
|
||
ratios but slower compression.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p><a class="reference internal" href="#compression.zstd.Strategy" title="compression.zstd.Strategy"><code class="xref py py-class docutils literal notranslate"><span class="pre">Strategy</span></code></a></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.enable_long_distance_matching">
|
||
<span class="sig-name descname"><span class="pre">enable_long_distance_matching</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.enable_long_distance_matching" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Long distance matching can be used to improve compression for large
|
||
inputs by finding large matches at greater distances. It increases memory
|
||
usage and window size.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">1</span></code> enable long distance matching while <code class="docutils literal notranslate"><span class="pre">False</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code>
|
||
disable it.</p>
|
||
<p>Enabling this parameter increases default
|
||
<a class="reference internal" href="#compression.zstd.CompressionParameter.window_log" title="compression.zstd.CompressionParameter.window_log"><code class="xref py py-attr docutils literal notranslate"><span class="pre">window_log</span></code></a> to 128 MiB except when expressly
|
||
set to a different value. This setting is enabled by default if
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">window_log</span></code> >= 128 MiB and the compression
|
||
strategy >= <a class="reference internal" href="#compression.zstd.Strategy.btopt" title="compression.zstd.Strategy.btopt"><code class="xref py py-attr docutils literal notranslate"><span class="pre">btopt</span></code></a> (compression level 16+).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.ldm_hash_log">
|
||
<span class="sig-name descname"><span class="pre">ldm_hash_log</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.ldm_hash_log" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Size of the table for long distance matching, as a power of two. Larger
|
||
values increase memory usage and compression ratio, but decrease
|
||
compression speed.</p>
|
||
<p>A value of zero causes the value to be selected automatically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.ldm_min_match">
|
||
<span class="sig-name descname"><span class="pre">ldm_min_match</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.ldm_min_match" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Minimum match size for long distance matcher. Larger or too small values
|
||
can often decrease the compression ratio.</p>
|
||
<p>A value of zero causes the value to be selected automatically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.ldm_bucket_size_log">
|
||
<span class="sig-name descname"><span class="pre">ldm_bucket_size_log</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.ldm_bucket_size_log" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Log size of each bucket in the long distance matcher hash table for
|
||
collision resolution. Larger values improve collision resolution but
|
||
decrease compression speed.</p>
|
||
<p>A value of zero causes the value to be selected automatically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.ldm_hash_rate_log">
|
||
<span class="sig-name descname"><span class="pre">ldm_hash_rate_log</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.ldm_hash_rate_log" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Frequency of inserting/looking up entries into the long distance matcher
|
||
hash table. Larger values improve compression speed. Deviating far from
|
||
the default value will likely result in a compression ratio decrease.</p>
|
||
<p>A value of zero causes the value to be selected automatically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.content_size_flag">
|
||
<span class="sig-name descname"><span class="pre">content_size_flag</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.content_size_flag" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Write the size of the data to be compressed into the Zstandard frame
|
||
header when known prior to compressing.</p>
|
||
<p>This flag only takes effect under the following scenarios:</p>
|
||
<ul class="simple">
|
||
<li><p>Calling <a class="reference internal" href="#compression.zstd.compress" title="compression.zstd.compress"><code class="xref py py-func docutils literal notranslate"><span class="pre">compress()</span></code></a> for one-shot compression</p></li>
|
||
<li><p>Providing all of the data to be compressed in the frame in a single
|
||
<a class="reference internal" href="#compression.zstd.ZstdCompressor.compress" title="compression.zstd.ZstdCompressor.compress"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ZstdCompressor.compress()</span></code></a> call, with the
|
||
<a class="reference internal" href="#compression.zstd.ZstdCompressor.FLUSH_FRAME" title="compression.zstd.ZstdCompressor.FLUSH_FRAME"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ZstdCompressor.FLUSH_FRAME</span></code></a> mode.</p></li>
|
||
<li><p>Calling <a class="reference internal" href="#compression.zstd.ZstdCompressor.set_pledged_input_size" title="compression.zstd.ZstdCompressor.set_pledged_input_size"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ZstdCompressor.set_pledged_input_size()</span></code></a> with the exact
|
||
amount of data that will be provided to the compressor prior to any
|
||
calls to <a class="reference internal" href="#compression.zstd.ZstdCompressor.compress" title="compression.zstd.ZstdCompressor.compress"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ZstdCompressor.compress()</span></code></a> for the current frame.
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">ZstdCompressor.set_pledged_input_size()</span></code> must be called for each
|
||
new frame.</p></li>
|
||
</ul>
|
||
<p>All other compression calls may not write the size information into the
|
||
frame header.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">1</span></code> enable the content size flag while <code class="docutils literal notranslate"><span class="pre">False</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code>
|
||
disable it.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.checksum_flag">
|
||
<span class="sig-name descname"><span class="pre">checksum_flag</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.checksum_flag" title="Link to this definition">¶</a></dt>
|
||
<dd><p>A four-byte checksum using XXHash64 of the uncompressed content is
|
||
written at the end of each frame. Zstandard’s decompression code verifies
|
||
the checksum. If there is a mismatch a <a class="reference internal" href="#compression.zstd.ZstdError" title="compression.zstd.ZstdError"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdError</span></code></a> exception is
|
||
raised.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">1</span></code> enable checksum generation while <code class="docutils literal notranslate"><span class="pre">False</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code>
|
||
disable it.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.dict_id_flag">
|
||
<span class="sig-name descname"><span class="pre">dict_id_flag</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.dict_id_flag" title="Link to this definition">¶</a></dt>
|
||
<dd><p>When compressing with a <a class="reference internal" href="#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a>, the dictionary’s ID is written
|
||
into the frame header.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">1</span></code> enable storing the dictionary ID while <code class="docutils literal notranslate"><span class="pre">False</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">0</span></code> disable it.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.nb_workers">
|
||
<span class="sig-name descname"><span class="pre">nb_workers</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.nb_workers" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Select how many threads will be spawned to compress in parallel. When
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_workers</span></code> > 0, enables multi-threaded compression, a value of
|
||
<code class="docutils literal notranslate"><span class="pre">1</span></code> means “one-thread multi-threaded mode”. More workers improve speed,
|
||
but also increase memory usage and slightly reduce compression ratio.</p>
|
||
<p>A value of zero disables multi-threading.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.job_size">
|
||
<span class="sig-name descname"><span class="pre">job_size</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.job_size" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Size of a compression job, in bytes. This value is enforced only when
|
||
<a class="reference internal" href="#compression.zstd.CompressionParameter.nb_workers" title="compression.zstd.CompressionParameter.nb_workers"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_workers</span></code></a> >= 1. Each compression job is
|
||
completed in parallel, so this value can indirectly impact the number of
|
||
active threads.</p>
|
||
<p>A value of zero causes the value to be selected automatically.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.CompressionParameter.overlap_log">
|
||
<span class="sig-name descname"><span class="pre">overlap_log</span></span><a class="headerlink" href="#compression.zstd.CompressionParameter.overlap_log" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Sets how much data is reloaded from previous jobs (threads) for new jobs
|
||
to be used by the look behind window during compression. This value is
|
||
only used when <a class="reference internal" href="#compression.zstd.CompressionParameter.nb_workers" title="compression.zstd.CompressionParameter.nb_workers"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_workers</span></code></a> >= 1. Acceptable
|
||
values vary from 0 to 9.</p>
|
||
<blockquote>
|
||
<div><ul class="simple">
|
||
<li><p>0 means dynamically set the overlap amount</p></li>
|
||
<li><p>1 means no overlap</p></li>
|
||
<li><p>9 means use a full window size from the previous job</p></li>
|
||
</ul>
|
||
</div></blockquote>
|
||
<p>Each increment halves/doubles the overlap size. “8” means an overlap of
|
||
<code class="docutils literal notranslate"><span class="pre">window_size/2</span></code>, “7” means an overlap of <code class="docutils literal notranslate"><span class="pre">window_size/4</span></code>, etc.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="compression.zstd.DecompressionParameter">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">DecompressionParameter</span></span><a class="headerlink" href="#compression.zstd.DecompressionParameter" title="Link to this definition">¶</a></dt>
|
||
<dd><p>An <a class="reference internal" href="enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a> containing the advanced decompression parameter
|
||
keys that can be used when decompressing data. Parameters are optional; any
|
||
omitted parameter will have its value selected automatically.</p>
|
||
<p>The <a class="reference internal" href="#compression.zstd.DecompressionParameter.bounds" title="compression.zstd.DecompressionParameter.bounds"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bounds()</span></code></a> method can be used on any attribute to get the valid
|
||
values for that parameter.</p>
|
||
<p>Example setting the <a class="reference internal" href="#compression.zstd.DecompressionParameter.window_log_max" title="compression.zstd.DecompressionParameter.window_log_max"><code class="xref py py-attr docutils literal notranslate"><span class="pre">window_log_max</span></code></a> to the maximum size:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">data</span> <span class="o">=</span> <span class="n">compress</span><span class="p">(</span><span class="sa">b</span><span class="s1">'Some very long buffer of bytes...'</span><span class="p">)</span>
|
||
|
||
<span class="n">_lower</span><span class="p">,</span> <span class="n">upper</span> <span class="o">=</span> <span class="n">DecompressionParameter</span><span class="o">.</span><span class="n">window_log_max</span><span class="o">.</span><span class="n">bounds</span><span class="p">()</span>
|
||
|
||
<span class="n">options</span> <span class="o">=</span> <span class="p">{</span><span class="n">DecompressionParameter</span><span class="o">.</span><span class="n">window_log_max</span><span class="p">:</span> <span class="n">upper</span><span class="p">}</span>
|
||
<span class="n">decompress</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="n">options</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="compression.zstd.DecompressionParameter.bounds">
|
||
<span class="sig-name descname"><span class="pre">bounds</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.DecompressionParameter.bounds" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the tuple of int bounds, <code class="docutils literal notranslate"><span class="pre">(lower,</span> <span class="pre">upper)</span></code>, of a decompression
|
||
parameter. This method should be called on the attribute you wish to
|
||
retrieve the bounds of.</p>
|
||
<p>Both the lower and upper bounds are inclusive.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.DecompressionParameter.window_log_max">
|
||
<span class="sig-name descname"><span class="pre">window_log_max</span></span><a class="headerlink" href="#compression.zstd.DecompressionParameter.window_log_max" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The base-two logarithm of the maximum size of the window used during
|
||
decompression. This can be useful to limit the amount of memory used when
|
||
decompressing data. A larger maximum window size leads to faster
|
||
decompression.</p>
|
||
<p>A value of zero causes the value to be selected automatically.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="compression.zstd.Strategy">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">Strategy</span></span><a class="headerlink" href="#compression.zstd.Strategy" title="Link to this definition">¶</a></dt>
|
||
<dd><p>An <a class="reference internal" href="enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a> containing strategies for compression.
|
||
Higher-numbered strategies correspond to more complex and slower
|
||
compression.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The values of attributes of <code class="xref py py-class docutils literal notranslate"><span class="pre">Strategy</span></code> are not necessarily stable
|
||
across zstd versions. Only the ordering of the attributes may be relied
|
||
upon. The attributes are listed below in order.</p>
|
||
</div>
|
||
<p>The following strategies are available:</p>
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.Strategy.fast">
|
||
<span class="sig-name descname"><span class="pre">fast</span></span><a class="headerlink" href="#compression.zstd.Strategy.fast" title="Link to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.Strategy.dfast">
|
||
<span class="sig-name descname"><span class="pre">dfast</span></span><a class="headerlink" href="#compression.zstd.Strategy.dfast" title="Link to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.Strategy.greedy">
|
||
<span class="sig-name descname"><span class="pre">greedy</span></span><a class="headerlink" href="#compression.zstd.Strategy.greedy" title="Link to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.Strategy.lazy">
|
||
<span class="sig-name descname"><span class="pre">lazy</span></span><a class="headerlink" href="#compression.zstd.Strategy.lazy" title="Link to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.Strategy.lazy2">
|
||
<span class="sig-name descname"><span class="pre">lazy2</span></span><a class="headerlink" href="#compression.zstd.Strategy.lazy2" title="Link to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.Strategy.btlazy2">
|
||
<span class="sig-name descname"><span class="pre">btlazy2</span></span><a class="headerlink" href="#compression.zstd.Strategy.btlazy2" title="Link to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.Strategy.btopt">
|
||
<span class="sig-name descname"><span class="pre">btopt</span></span><a class="headerlink" href="#compression.zstd.Strategy.btopt" title="Link to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.Strategy.btultra">
|
||
<span class="sig-name descname"><span class="pre">btultra</span></span><a class="headerlink" href="#compression.zstd.Strategy.btultra" title="Link to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.Strategy.btultra2">
|
||
<span class="sig-name descname"><span class="pre">btultra2</span></span><a class="headerlink" href="#compression.zstd.Strategy.btultra2" title="Link to this definition">¶</a></dt>
|
||
<dd></dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="miscellaneous">
|
||
<h2>Miscellaneous<a class="headerlink" href="#miscellaneous" title="Link to this heading">¶</a></h2>
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="compression.zstd.get_frame_info">
|
||
<span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">get_frame_info</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">frame_buffer</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#compression.zstd.get_frame_info" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Retrieve a <a class="reference internal" href="#compression.zstd.FrameInfo" title="compression.zstd.FrameInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">FrameInfo</span></code></a> object containing metadata about a Zstandard
|
||
frame. Frames contain metadata related to the compressed data they hold.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="compression.zstd.FrameInfo">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">FrameInfo</span></span><a class="headerlink" href="#compression.zstd.FrameInfo" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Metadata related to a Zstandard frame.</p>
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.FrameInfo.decompressed_size">
|
||
<span class="sig-name descname"><span class="pre">decompressed_size</span></span><a class="headerlink" href="#compression.zstd.FrameInfo.decompressed_size" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The size of the decompressed contents of the frame.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.FrameInfo.dictionary_id">
|
||
<span class="sig-name descname"><span class="pre">dictionary_id</span></span><a class="headerlink" href="#compression.zstd.FrameInfo.dictionary_id" title="Link to this definition">¶</a></dt>
|
||
<dd><p>An integer representing the Zstandard dictionary ID needed for
|
||
decompressing the frame. <code class="docutils literal notranslate"><span class="pre">0</span></code> means the dictionary ID was not
|
||
recorded in the frame header. This may mean that a Zstandard dictionary
|
||
is not needed, or that the ID of a required dictionary was not recorded.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.COMPRESSION_LEVEL_DEFAULT">
|
||
<span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">COMPRESSION_LEVEL_DEFAULT</span></span><a class="headerlink" href="#compression.zstd.COMPRESSION_LEVEL_DEFAULT" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The default compression level for Zstandard: <code class="docutils literal notranslate"><span class="pre">3</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="compression.zstd.zstd_version_info">
|
||
<span class="sig-prename descclassname"><span class="pre">compression.zstd.</span></span><span class="sig-name descname"><span class="pre">zstd_version_info</span></span><a class="headerlink" href="#compression.zstd.zstd_version_info" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Version number of the runtime zstd library as a tuple of integers
|
||
(major, minor, release).</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="examples">
|
||
<h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h2>
|
||
<p>Reading in a compressed file:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">compression</span><span class="w"> </span><span class="kn">import</span> <span class="n">zstd</span>
|
||
|
||
<span class="k">with</span> <span class="n">zstd</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"file.zst"</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="n">file_content</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Creating a compressed file:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">compression</span><span class="w"> </span><span class="kn">import</span> <span class="n">zstd</span>
|
||
|
||
<span class="n">data</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">"Insert Data Here"</span>
|
||
<span class="k">with</span> <span class="n">zstd</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"file.zst"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Compressing data in memory:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">compression</span><span class="w"> </span><span class="kn">import</span> <span class="n">zstd</span>
|
||
|
||
<span class="n">data_in</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">"Insert Data Here"</span>
|
||
<span class="n">data_out</span> <span class="o">=</span> <span class="n">zstd</span><span class="o">.</span><span class="n">compress</span><span class="p">(</span><span class="n">data_in</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Incremental compression:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">compression</span><span class="w"> </span><span class="kn">import</span> <span class="n">zstd</span>
|
||
|
||
<span class="n">comp</span> <span class="o">=</span> <span class="n">zstd</span><span class="o">.</span><span class="n">ZstdCompressor</span><span class="p">()</span>
|
||
<span class="n">out1</span> <span class="o">=</span> <span class="n">comp</span><span class="o">.</span><span class="n">compress</span><span class="p">(</span><span class="sa">b</span><span class="s2">"Some data</span><span class="se">\n</span><span class="s2">"</span><span class="p">)</span>
|
||
<span class="n">out2</span> <span class="o">=</span> <span class="n">comp</span><span class="o">.</span><span class="n">compress</span><span class="p">(</span><span class="sa">b</span><span class="s2">"Another piece of data</span><span class="se">\n</span><span class="s2">"</span><span class="p">)</span>
|
||
<span class="n">out3</span> <span class="o">=</span> <span class="n">comp</span><span class="o">.</span><span class="n">compress</span><span class="p">(</span><span class="sa">b</span><span class="s2">"Even more data</span><span class="se">\n</span><span class="s2">"</span><span class="p">)</span>
|
||
<span class="n">out4</span> <span class="o">=</span> <span class="n">comp</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
|
||
<span class="c1"># Concatenate all the partial results:</span>
|
||
<span class="n">result</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">""</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">out1</span><span class="p">,</span> <span class="n">out2</span><span class="p">,</span> <span class="n">out3</span><span class="p">,</span> <span class="n">out4</span><span class="p">])</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Writing compressed data to an already-open file:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">compression</span><span class="w"> </span><span class="kn">import</span> <span class="n">zstd</span>
|
||
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"myfile"</span><span class="p">,</span> <span class="s2">"wb"</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="sa">b</span><span class="s2">"This data will not be compressed</span><span class="se">\n</span><span class="s2">"</span><span class="p">)</span>
|
||
<span class="k">with</span> <span class="n">zstd</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">)</span> <span class="k">as</span> <span class="n">zstf</span><span class="p">:</span>
|
||
<span class="n">zstf</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="sa">b</span><span class="s2">"This *will* be compressed</span><span class="se">\n</span><span class="s2">"</span><span class="p">)</span>
|
||
<span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="sa">b</span><span class="s2">"Not compressed</span><span class="se">\n</span><span class="s2">"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Creating a compressed file using compression parameters:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">compression</span><span class="w"> </span><span class="kn">import</span> <span class="n">zstd</span>
|
||
|
||
<span class="n">options</span> <span class="o">=</span> <span class="p">{</span>
|
||
<span class="n">zstd</span><span class="o">.</span><span class="n">CompressionParameter</span><span class="o">.</span><span class="n">checksum_flag</span><span class="p">:</span> <span class="mi">1</span>
|
||
<span class="p">}</span>
|
||
<span class="k">with</span> <span class="n">zstd</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s2">"file.zst"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="n">options</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="sa">b</span><span class="s2">"Mind if I squeeze in?"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">compression.zstd</span></code> — Compression compatible with the Zstandard format</a><ul>
|
||
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
|
||
<li><a class="reference internal" href="#reading-and-writing-compressed-files">Reading and writing compressed files</a></li>
|
||
<li><a class="reference internal" href="#compressing-and-decompressing-data-in-memory">Compressing and decompressing data in memory</a></li>
|
||
<li><a class="reference internal" href="#zstandard-dictionaries">Zstandard dictionaries</a></li>
|
||
<li><a class="reference internal" href="#advanced-parameter-control">Advanced parameter control</a></li>
|
||
<li><a class="reference internal" href="#miscellaneous">Miscellaneous</a></li>
|
||
<li><a class="reference internal" href="#examples">Examples</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="compression.html"
|
||
title="previous chapter">The <code class="xref py py-mod docutils literal notranslate"><span class="pre">compression</span></code> package</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="zlib.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zlib</span></code> — Compression compatible with <strong class="program">gzip</strong></a></p>
|
||
</div>
|
||
<script>
|
||
document.addEventListener('DOMContentLoaded', () => {
|
||
const title = document.querySelector('meta[property="og:title"]').content;
|
||
const elements = document.querySelectorAll('.improvepage');
|
||
const pageurl = window.location.href.split('?')[0];
|
||
elements.forEach(element => {
|
||
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
|
||
url.searchParams.set('pagetitle', title);
|
||
url.searchParams.set('pageurl', pageurl);
|
||
url.searchParams.set('pagesource', "library/compression.zstd.rst");
|
||
element.href = url.toString();
|
||
});
|
||
});
|
||
</script>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a bug</a></li>
|
||
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.15/Doc/library/compression.zstd.rst?plain=1"
|
||
rel="nofollow">Show source
|
||
</a>
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="sidebarbutton" title="Collapse sidebar">
|
||
<span>«</span>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="zlib.html" title="zlib — Compression compatible with gzip"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="compression.html" title="The compression package"
|
||
>previous</a> |</li>
|
||
|
||
<li class="root-icon"><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.15.0 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python standard library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="archiving.html" >Data Compression and Archiving</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">compression.zstd</span></code> — Compression compatible with the Zstandard format</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
|
||
<input type="submit" value="Go">
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
|
||
<br>
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br>
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br>
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br>
|
||
|
||
|
||
<br>
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br>
|
||
<br>
|
||
Last updated on Oct 09, 2026 (11:35 UTC).
|
||
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
|
||
<br>
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |