Deploy documentation from 1efdd4c091 1efdd4c091

This commit is contained in:
github-actions[bot] committed 2026-08-18 03:30:05 +00:00
commit 89feb571a2
102 files changed
+18140

No files matched your search

+4
View File
@@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
config: fba96becba878414a2a6dc74e49e11a4
tags: 645f666f9bcd5a90fca523b33c5a78b7
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
View File
Whitespace-only changes.
+280
View File
@@ -0,0 +1,280 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta content="Page not found - tzst documentation. Return to the main documentation or search for what you're looking for." name="description" />
<meta content="404, page not found, tzst documentation, error" name="keywords" />
<meta content="Page Not Found - tzst Documentation" name="og:title" />
<meta content="The requested page could not be found. Visit the tzst documentation homepage or use the search feature." name="og:description" />
<meta content="Page Not Found - tzst Documentation" name="twitter:title" />
<meta content="The requested page could not be found. Visit the tzst documentation homepage or use the search feature." name="twitter:description" />
<meta content="website" name="og:type" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="og:image" />
<meta content="https://tzst.xi-xu.me/" name="og:url" />
<meta content="summary_large_image" name="twitter:card" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="twitter:image" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>404 - Page Not Found &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/404.html" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=3b3401d5"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="_static/opensearch.xml"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Documentation" href="README.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "404 - Page Not Found",
"item": "https://tzst.xi-xu.me/404.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/404.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="index.html" class="icon icon-home">
tzst
<img src="_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">404 - Page Not Found</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/404.md" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="page-not-found">
<h1>404 - Page Not Found<a class="headerlink" href="#page-not-found" title="Link to this heading"></a></h1>
<section id="oops-the-page-youre-looking-for-doesnt-exist">
<h2>Oops! The page you’re looking for doesn’t exist<a class="headerlink" href="#oops-the-page-youre-looking-for-doesnt-exist" title="Link to this heading"></a></h2>
<p>The URL you requested could not be found in the tzst documentation. This might happen if:</p>
<ul class="simple">
<li><p>The page has been moved or renamed</p></li>
<li><p>You followed a broken link</p></li>
<li><p>There’s a typo in the URL</p></li>
<li><p>The page has been removed</p></li>
</ul>
</section>
<section id="where-would-you-like-to-go">
<h2>Where would you like to go?<a class="headerlink" href="#where-would-you-like-to-go" title="Link to this heading"></a></h2>
<section id="popular-pages">
<h3>Popular Pages<a class="headerlink" href="#popular-pages" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong><a class="reference internal" href="index.html"><span class="doc">tzst Documentation</span></a></strong> - Documentation homepage</p></li>
<li><p><strong><a class="reference internal" href="quickstart.html"><span class="doc">Quick Start Guide</span></a></strong> - Get started with tzst</p></li>
<li><p><strong><a class="reference internal" href="performance.html"><span class="doc">Performance Guide</span></a></strong> - Learn about performance optimizations</p></li>
<li><p><strong><a class="reference internal" href="examples.html"><span class="doc">Examples</span></a></strong> - Practical examples and use cases</p></li>
<li><p><strong><a class="reference internal" href="api/index.html"><span class="doc">API Reference</span></a></strong> - Complete API reference</p></li>
<li><p><strong><a class="reference internal" href="development.html"><span class="doc">Development Guide</span></a></strong> - Contributing to tzst</p></li>
<li><p><strong><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></strong> - Index of all documented items</p></li>
</ul>
</section>
<section id="quick-navigation">
<h3>Quick Navigation<a class="headerlink" href="#quick-navigation" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Installation Guide</strong> - <a class="reference internal" href="quickstart.html#installation"><span class="std std-ref">Installation</span></a></p></li>
<li><p><strong>Basic Usage</strong> - <a class="reference internal" href="quickstart.html#basic-usage"><span class="std std-ref">Basic Usage</span></a></p></li>
<li><p><strong>Security Features</strong> - <a class="reference internal" href="examples.html#security-and-filtering"><span class="std std-ref">Security and Filtering</span></a></p></li>
<li><p><strong>Error Handling</strong> - <a class="reference internal" href="examples.html#error-handling"><span class="std std-ref">Error Handling</span></a></p></li>
</ul>
</section>
</section>
<section id="search-documentation">
<h2>Search Documentation<a class="headerlink" href="#search-documentation" title="Link to this heading"></a></h2>
<p>Use the search box in the top navigation to find what you’re looking for, or browse through these sections:</p>
<section id="core-features">
<h3>Core Features<a class="headerlink" href="#core-features" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong><a class="reference internal" href="api/core.html"><span class="doc">Core API</span></a></strong> - Core TzstArchive class and functions</p></li>
<li><p><strong><a class="reference internal" href="api/cli.html"><span class="doc">CLI API</span></a></strong> - Command-line interface</p></li>
<li><p><strong><a class="reference internal" href="api/exceptions.html"><span class="doc">Exceptions API</span></a></strong> - Exception handling</p></li>
</ul>
</section>
<section id="examples-tutorials">
<h3>Examples &amp; Tutorials<a class="headerlink" href="#examples-tutorials" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Archive Creation</strong> - <a class="reference internal" href="examples.html#basic-archive-operations"><span class="std std-ref">Creating Your First Archive</span></a></p></li>
<li><p><strong>Security Best Practices</strong> - <a class="reference internal" href="examples.html#security-and-filtering"><span class="std std-ref">Security and Filtering</span></a></p></li>
<li><p><strong>Integration Examples</strong> - <a class="reference internal" href="examples.html#integration-examples"><span class="std std-ref">Integration Examples</span></a></p></li>
<li><p><strong>Performance Optimization</strong> - <a class="reference internal" href="examples.html#performance-optimization"><span class="std std-ref">Performance Optimization</span></a></p></li>
</ul>
</section>
</section>
<section id="additional-resources">
<h2>Additional Resources<a class="headerlink" href="#additional-resources" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/xixu-me/tzst">GitHub Repository</a> - Source code and issue tracker</p></li>
<li><p><a class="reference external" href="https://pypi.org/project/tzst/">PyPI Package</a> - Download and installation</p></li>
<li><p><a class="reference external" href="https://github.com/xixu-me/tzst/releases">Release Notes</a> - Latest updates and changes</p></li>
</ul>
</section>
<section id="report-an-issue">
<h2>Report an Issue<a class="headerlink" href="#report-an-issue" title="Link to this heading"></a></h2>
<p>If you believe this is a broken link within our documentation, please <a class="reference external" href="https://github.com/xixu-me/tzst/issues">report it on GitHub</a>.</p>
<hr class="docutils" />
<p><strong>Need help?</strong> Check our <a class="reference internal" href="quickstart.html"><span class="doc">Quick Start Guide</span></a> guide or browse the <a class="reference internal" href="examples.html"><span class="doc">Examples</span></a> for common use cases.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="README.html" class="btn btn-neutral float-right" title="Documentation" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
+1
View File
@@ -0,0 +1 @@
tzst.xi-xu.me
+378
View File
@@ -0,0 +1,378 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Documentation &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/README.html" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=3b3401d5"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="_static/opensearch.xml"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="prev" title="404 - Page Not Found" href="404.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Documentation",
"item": "https://tzst.xi-xu.me/README.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/README.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="index.html" class="icon icon-home">
tzst
<img src="_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Documentation</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/README.md" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="documentation">
<h1>Documentation<a class="headerlink" href="#documentation" title="Link to this heading"></a></h1>
<p>This directory contains the Sphinx documentation for the tzst library.</p>
<section id="setup">
<h2>Setup<a class="headerlink" href="#setup" title="Link to this heading"></a></h2>
<ol class="arabic">
<li><p>Install documentation dependencies:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>requirements.txt
</pre></div>
</div>
</li>
<li><p>Install the tzst package in development mode (required for autodoc):</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>..
</pre></div>
</div>
</li>
</ol>
</section>
<section id="building-documentation">
<h2>Building Documentation<a class="headerlink" href="#building-documentation" title="Link to this heading"></a></h2>
<section id="local-development">
<h3>Local Development<a class="headerlink" href="#local-development" title="Link to this heading"></a></h3>
<p>Build the documentation locally:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># On Unix/macOS</span>
make<span class="w"> </span>html
<span class="c1"># On Windows</span>
make.bat<span class="w"> </span>html
</pre></div>
</div>
<p>The built documentation will be in <code class="docutils literal notranslate"><span class="pre">_build/html/</span></code>. Open <code class="docutils literal notranslate"><span class="pre">_build/html/index.html</span></code> in your browser.</p>
</section>
<section id="live-reload-recommended-for-development">
<h3>Live Reload (Recommended for Development)<a class="headerlink" href="#live-reload-recommended-for-development" title="Link to this heading"></a></h3>
<p>For automatic rebuilding when files change:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install sphinx-autobuild if not already installed</span>
pip<span class="w"> </span>install<span class="w"> </span>sphinx-autobuild
<span class="c1"># Start live reload server</span>
make<span class="w"> </span>livehtml
<span class="c1"># or</span>
sphinx-autobuild<span class="w"> </span>.<span class="w"> </span>_build/html
</pre></div>
</div>
<p>This will start a local server (usually at <a class="reference external" href="http://localhost:8000">http://localhost:8000</a>) that automatically rebuilds and refreshes when you save changes.</p>
</section>
<section id="other-build-targets">
<h3>Other Build Targets<a class="headerlink" href="#other-build-targets" title="Link to this heading"></a></h3>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Check documentation coverage</span>
make<span class="w"> </span>coverage
<span class="c1"># Check for broken links</span>
make<span class="w"> </span>linkcheck
<span class="c1"># Build PDF (requires LaTeX)</span>
make<span class="w"> </span>latexpdf
<span class="c1"># Clean build directory</span>
make<span class="w"> </span>clean
</pre></div>
</div>
</section>
</section>
<section id="documentation-structure">
<h2>Documentation Structure<a class="headerlink" href="#documentation-structure" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">index.md</span></code> - Main documentation homepage</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">quickstart.md</span></code> - Quick start guide for new users</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">examples.md</span></code> - Practical examples and use cases</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">api/</span></code> - API reference documentation</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">index.md</span></code> - API overview</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">core.md</span></code> - Core functionality documentation</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cli.md</span></code> - CLI documentation</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">exceptions.md</span></code> - Exception classes documentation</p></li>
</ul>
</li>
</ul>
</section>
<section id="writing-documentation">
<h2>Writing Documentation<a class="headerlink" href="#writing-documentation" title="Link to this heading"></a></h2>
<section id="markdown-vs-restructuredtext">
<h3>Markdown vs reStructuredText<a class="headerlink" href="#markdown-vs-restructuredtext" title="Link to this heading"></a></h3>
<p>This documentation uses MyST parser, which allows you to write in Markdown with some reStructuredText features. You can use either <code class="docutils literal notranslate"><span class="pre">.md</span></code> or <code class="docutils literal notranslate"><span class="pre">.rst</span></code> files.</p>
</section>
<section id="adding-new-pages">
<h3>Adding New Pages<a class="headerlink" href="#adding-new-pages" title="Link to this heading"></a></h3>
<ol class="arabic simple">
<li><p>Create a new <code class="docutils literal notranslate"><span class="pre">.md</span></code> file in the appropriate directory</p></li>
<li><p>Add it to the relevant <code class="docutils literal notranslate"><span class="pre">toctree</span></code> directive in the parent index file</p></li>
<li><p>Use proper Markdown headers and cross-references</p></li>
</ol>
</section>
<section id="api-documentation">
<h3>API Documentation<a class="headerlink" href="#api-documentation" title="Link to this heading"></a></h3>
<p>API documentation is automatically generated from docstrings using Sphinx autodoc. To document a new module:</p>
<ol class="arabic simple">
<li><p>Add the module to the appropriate API file (e.g., <code class="docutils literal notranslate"><span class="pre">api/core.md</span></code>)</p></li>
<li><p>Use autodoc directives like <code class="docutils literal notranslate"><span class="pre">automodule</span></code>, <code class="docutils literal notranslate"><span class="pre">autoclass</span></code>, <code class="docutils literal notranslate"><span class="pre">autofunction</span></code></p></li>
</ol>
</section>
<section id="code-examples">
<h3>Code Examples<a class="headerlink" href="#code-examples" title="Link to this heading"></a></h3>
<p>Use fenced code blocks with language specification:</p>
<div class="highlight-markdown notranslate"><div class="highlight"><pre><span></span><span class="sb">```python</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">TzstArchive</span>
<span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"example.tzst"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="n">archive</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"file.txt"</span><span class="p">)</span>
<span class="sb">```</span>
</pre></div>
</div>
</section>
<section id="cross-references">
<h3>Cross-References<a class="headerlink" href="#cross-references" title="Link to this heading"></a></h3>
<p>Link to other documentation pages:</p>
<div class="highlight-markdown notranslate"><div class="highlight"><pre><span></span>See the {doc}`quickstart` guide for more information.
</pre></div>
</div>
<p>Link to API documentation:</p>
<div class="highlight-markdown notranslate"><div class="highlight"><pre><span></span>Use the {class}`tzst.TzstArchive` class.
</pre></div>
</div>
</section>
</section>
<section id="automated-deployment">
<h2>Automated Deployment<a class="headerlink" href="#automated-deployment" title="Link to this heading"></a></h2>
<p>Documentation is automatically built and deployed to GitHub Pages when changes are pushed to the main branch. The workflow is defined in <code class="docutils literal notranslate"><span class="pre">.github/workflows/publish_docs.yml</span></code>.</p>
<section id="local-testing-of-deployment">
<h3>Local Testing of Deployment<a class="headerlink" href="#local-testing-of-deployment" title="Link to this heading"></a></h3>
<p>To test the deployment process locally:</p>
<ol class="arabic simple">
<li><p>Build the documentation: <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code></p></li>
<li><p>Serve the built files: <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">http.server</span> <span class="pre">8000</span> <span class="pre">-d</span> <span class="pre">_build/html</span></code></p></li>
<li><p>Visit <a class="reference external" href="http://localhost:8000">http://localhost:8000</a></p></li>
</ol>
</section>
</section>
<section id="troubleshooting">
<h2>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Link to this heading"></a></h2>
<section id="import-errors">
<h3>Import Errors<a class="headerlink" href="#import-errors" title="Link to this heading"></a></h3>
<p>If you get import errors when building documentation:</p>
<ol class="arabic simple">
<li><p>Make sure the tzst package is installed: <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-e</span> <span class="pre">..</span></code></p></li>
<li><p>Check that all dependencies are installed: <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-r</span> <span class="pre">requirements.txt</span></code></p></li>
<li><p>Verify your Python path includes the src directory</p></li>
</ol>
</section>
<section id="theme-issues">
<h3>Theme Issues<a class="headerlink" href="#theme-issues" title="Link to this heading"></a></h3>
<p>If the RTD theme isn’t working:</p>
<ol class="arabic simple">
<li><p>Install the theme: <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">sphinx-rtd-theme</span></code></p></li>
<li><p>Check that it’s listed in <code class="docutils literal notranslate"><span class="pre">requirements.txt</span></code></p></li>
<li><p>Verify the theme configuration in <code class="docutils literal notranslate"><span class="pre">conf.py</span></code></p></li>
</ol>
</section>
<section id="build-warnings">
<h3>Build Warnings<a class="headerlink" href="#build-warnings" title="Link to this heading"></a></h3>
<p>Address all Sphinx warnings to ensure high-quality documentation:</p>
<ul class="simple">
<li><p>Fix broken cross-references</p></li>
<li><p>Add missing docstrings</p></li>
<li><p>Resolve autodoc import issues</p></li>
<li><p>Fix malformed markup</p></li>
</ul>
</section>
</section>
<section id="contributing">
<h2>Contributing<a class="headerlink" href="#contributing" title="Link to this heading"></a></h2>
<p>When contributing to documentation:</p>
<ol class="arabic simple">
<li><p>Follow the existing style and structure</p></li>
<li><p>Test your changes locally before submitting</p></li>
<li><p>Add examples for new features</p></li>
<li><p>Update the changelog if appropriate</p></li>
<li><p>Ensure all links work correctly</p></li>
</ol>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="404.html" class="btn btn-neutral float-left" title="404 - Page Not Found" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
+196
View File
@@ -0,0 +1,196 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Overview: module code &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/_modules/index.html" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=3b3401d5"></script>
<script src="../_static/doctools.js?v=fd6eb6e6"></script>
<script src="../_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="../_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="../_static/opensearch.xml"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Overview: module code",
"item": "https://tzst.xi-xu.me/_modules/index.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/_modules/index.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="../index.html" class="icon icon-home">
tzst
<img src="../_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="../api/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Overview: module code</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<h1>All modules for which code is available</h1>
<ul><li><a href="tzst/cli.html">tzst.cli</a></li>
<li><a href="tzst/core.html">tzst.core</a></li>
<li><a href="tzst/exceptions.html">tzst.exceptions</a></li>
</ul>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+276
View File
@@ -0,0 +1,276 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>tzst.exceptions &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="../../_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/_modules/tzst/exceptions.html" />
<script src="../../_static/jquery.js?v=5d32c60e"></script>
<script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../../_static/documentation_options.js?v=3b3401d5"></script>
<script src="../../_static/doctools.js?v=fd6eb6e6"></script>
<script src="../../_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="../../_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="../../_static/opensearch.xml"/>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "tzst.exceptions",
"item": "https://tzst.xi-xu.me/_modules/tzst/exceptions.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/_modules/tzst/exceptions.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="../../index.html" class="icon icon-home">
tzst
<img src="../../_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../api/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../index.html">Module code</a></li>
<li class="breadcrumb-item active">tzst.exceptions</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<h1>Source code for tzst.exceptions</h1><div class="highlight"><pre>
<span></span><span class="sd">"""Exception classes for tzst."""</span>
<div class="viewcode-block" id="TzstError">
<a class="viewcode-back" href="../../api/exceptions.html#tzst.exceptions.TzstError">[docs]</a>
<span class="k">class</span><span class="w"> </span><span class="nc">TzstError</span><span class="p">(</span><span class="ne">Exception</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""Base exception for all tzst operations.</span>
<span class="sd"> This is the parent class for all tzst-specific exceptions.</span>
<span class="sd"> Catch this to handle any tzst-related error.</span>
<span class="sd"> """</span>
<span class="k">pass</span></div>
<div class="viewcode-block" id="TzstCompressionError">
<a class="viewcode-back" href="../../api/exceptions.html#tzst.exceptions.TzstCompressionError">[docs]</a>
<span class="k">class</span><span class="w"> </span><span class="nc">TzstCompressionError</span><span class="p">(</span><span class="n">TzstError</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""Exception raised when compression operations fail.</span>
<span class="sd"> This can occur when:</span>
<span class="sd"> - Invalid compression level is specified</span>
<span class="sd"> - Disk space is insufficient during compression</span>
<span class="sd"> - Input data cannot be compressed due to corruption</span>
<span class="sd"> - Zstandard compression encounters an internal error</span>
<span class="sd"> """</span>
<span class="k">pass</span></div>
<div class="viewcode-block" id="TzstDecompressionError">
<a class="viewcode-back" href="../../api/exceptions.html#tzst.exceptions.TzstDecompressionError">[docs]</a>
<span class="k">class</span><span class="w"> </span><span class="nc">TzstDecompressionError</span><span class="p">(</span><span class="n">TzstError</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""Exception raised when decompression operations fail.</span>
<span class="sd"> This can occur when:</span>
<span class="sd"> - Archive file is corrupted or incomplete</span>
<span class="sd"> - Archive was not created with zstandard compression</span>
<span class="sd"> - Decompression buffer overflows or underflows</span>
<span class="sd"> - Archive format is invalid or unsupported</span>
<span class="sd"> """</span>
<span class="k">pass</span></div>
<div class="viewcode-block" id="TzstArchiveError">
<a class="viewcode-back" href="../../api/exceptions.html#tzst.exceptions.TzstArchiveError">[docs]</a>
<span class="k">class</span><span class="w"> </span><span class="nc">TzstArchiveError</span><span class="p">(</span><span class="n">TzstError</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""Exception raised when archive operations fail.</span>
<span class="sd"> This can occur when:</span>
<span class="sd"> - Archive file cannot be opened or created</span>
<span class="sd"> - File permissions prevent archive access</span>
<span class="sd"> - Archive structure is malformed</span>
<span class="sd"> - Tar operations fail within the archive</span>
<span class="sd"> - Atomic file operations fail during creation</span>
<span class="sd"> """</span>
<span class="k">pass</span></div>
<div class="viewcode-block" id="TzstFileNotFoundError">
<a class="viewcode-back" href="../../api/exceptions.html#tzst.exceptions.TzstFileNotFoundError">[docs]</a>
<span class="k">class</span><span class="w"> </span><span class="nc">TzstFileNotFoundError</span><span class="p">(</span><span class="n">TzstError</span><span class="p">,</span> <span class="ne">FileNotFoundError</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""Exception raised when a required file is not found.</span>
<span class="sd"> This can occur when:</span>
<span class="sd"> - Archive file does not exist for reading operations</span>
<span class="sd"> - Input files for archiving do not exist</span>
<span class="sd"> - Output directory cannot be created for extraction</span>
<span class="sd"> - Temporary files cannot be created during atomic operations</span>
<span class="sd"> Inherits from both TzstError and FileNotFoundError for compatibility</span>
<span class="sd"> with standard Python exception handling patterns.</span>
<span class="sd"> """</span>
<span class="k">pass</span></div>
</pre></div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
@@ -0,0 +1,123 @@
/* Compatability shim for jQuery and underscores.js.
*
* Copyright Sphinx contributors
* Released under the two clause BSD licence
*/
/**
* small helper function to urldecode strings
*
* See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
*/
jQuery.urldecode = function(x) {
if (!x) {
return x
}
return decodeURIComponent(x.replace(/\+/g, ' '));
};
/**
* small helper function to urlencode strings
*/
jQuery.urlencode = encodeURIComponent;
/**
* This function returns the parsed url parameters of the
* current request. Multiple values per key are supported,
* it will always return arrays of strings for the value parts.
*/
jQuery.getQueryParameters = function(s) {
if (typeof s === 'undefined')
s = document.location.search;
var parts = s.substr(s.indexOf('?') + 1).split('&');
var result = {};
for (var i = 0; i < parts.length; i++) {
var tmp = parts[i].split('=', 2);
var key = jQuery.urldecode(tmp[0]);
var value = jQuery.urldecode(tmp[1]);
if (key in result)
result[key].push(value);
else
result[key] = [value];
}
return result;
};
/**
* highlight a given string on a jquery object by wrapping it in
* span elements with the given class name.
*/
jQuery.fn.highlightText = function(text, className) {
function highlight(node, addItems) {
if (node.nodeType === 3) {
var val = node.nodeValue;
var pos = val.toLowerCase().indexOf(text);
if (pos >= 0 &&
!jQuery(node.parentNode).hasClass(className) &&
!jQuery(node.parentNode).hasClass("nohighlight")) {
var span;
var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
if (isInSVG) {
span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
} else {
span = document.createElement("span");
span.className = className;
}
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
node.parentNode.insertBefore(span, node.parentNode.insertBefore(
document.createTextNode(val.substr(pos + text.length)),
node.nextSibling));
node.nodeValue = val.substr(0, pos);
if (isInSVG) {
var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
var bbox = node.parentElement.getBBox();
rect.x.baseVal.value = bbox.x;
rect.y.baseVal.value = bbox.y;
rect.width.baseVal.value = bbox.width;
rect.height.baseVal.value = bbox.height;
rect.setAttribute('class', className);
addItems.push({
"parent": node.parentNode,
"target": rect});
}
}
}
else if (!jQuery(node).is("button, select, textarea")) {
jQuery.each(node.childNodes, function() {
highlight(this, addItems);
});
}
}
var addItems = [];
var result = this.each(function() {
highlight(this, addItems);
});
for (var i = 0; i < addItems.length; ++i) {
jQuery(addItems[i].parent).before(addItems[i].target);
}
return result;
};
/*
* backward compatibility for jQuery.browser
* This will be supported until firefox bug is fixed.
*/
if (!jQuery.browser) {
jQuery.uaMatch = function(ua) {
ua = ua.toLowerCase();
var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
/(webkit)[ \/]([\w.]+)/.exec(ua) ||
/(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
/(msie) ([\w.]+)/.exec(ua) ||
ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
[];
return {
browser: match[ 1 ] || "",
version: match[ 2 ] || "0"
};
};
jQuery.browser = {};
jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
}
+476
View File
@@ -0,0 +1,476 @@
// @ts-check
/**@constructor*/
BaseStemmer = function() {
/** @protected */
this.current = '';
this.cursor = 0;
this.limit = 0;
this.limit_backward = 0;
this.bra = 0;
this.ket = 0;
/**
* @param {string} value
*/
this.setCurrent = function(value) {
this.current = value;
this.cursor = 0;
this.limit = this.current.length;
this.limit_backward = 0;
this.bra = this.cursor;
this.ket = this.limit;
};
/**
* @return {string}
*/
this.getCurrent = function() {
return this.current;
};
/**
* @param {BaseStemmer} other
*/
this.copy_from = function(other) {
/** @protected */
this.current = other.current;
this.cursor = other.cursor;
this.limit = other.limit;
this.limit_backward = other.limit_backward;
this.bra = other.bra;
this.ket = other.ket;
};
/**
* @param {number[]} s
* @param {number} min
* @param {number} max
* @return {boolean}
*/
this.in_grouping = function(s, min, max) {
/** @protected */
if (this.cursor >= this.limit) return false;
var ch = this.current.charCodeAt(this.cursor);
if (ch > max || ch < min) return false;
ch -= min;
if ((s[ch >>> 3] & (0x1 << (ch & 0x7))) == 0) return false;
this.cursor++;
return true;
};
/**
* @param {number[]} s
* @param {number} min
* @param {number} max
* @return {boolean}
*/
this.go_in_grouping = function(s, min, max) {
/** @protected */
while (this.cursor < this.limit) {
var ch = this.current.charCodeAt(this.cursor);
if (ch > max || ch < min)
return true;
ch -= min;
if ((s[ch >>> 3] & (0x1 << (ch & 0x7))) == 0)
return true;
this.cursor++;
}
return false;
};
/**
* @param {number[]} s
* @param {number} min
* @param {number} max
* @return {boolean}
*/
this.in_grouping_b = function(s, min, max) {
/** @protected */
if (this.cursor <= this.limit_backward) return false;
var ch = this.current.charCodeAt(this.cursor - 1);
if (ch > max || ch < min) return false;
ch -= min;
if ((s[ch >>> 3] & (0x1 << (ch & 0x7))) == 0) return false;
this.cursor--;
return true;
};
/**
* @param {number[]} s
* @param {number} min
* @param {number} max
* @return {boolean}
*/
this.go_in_grouping_b = function(s, min, max) {
/** @protected */
while (this.cursor > this.limit_backward) {
var ch = this.current.charCodeAt(this.cursor - 1);
if (ch > max || ch < min) return true;
ch -= min;
if ((s[ch >>> 3] & (0x1 << (ch & 0x7))) == 0) return true;
this.cursor--;
}
return false;
};
/**
* @param {number[]} s
* @param {number} min
* @param {number} max
* @return {boolean}
*/
this.out_grouping = function(s, min, max) {
/** @protected */
if (this.cursor >= this.limit) return false;
var ch = this.current.charCodeAt(this.cursor);
if (ch > max || ch < min) {
this.cursor++;
return true;
}
ch -= min;
if ((s[ch >>> 3] & (0X1 << (ch & 0x7))) == 0) {
this.cursor++;
return true;
}
return false;
};
/**
* @param {number[]} s
* @param {number} min
* @param {number} max
* @return {boolean}
*/
this.go_out_grouping = function(s, min, max) {
/** @protected */
while (this.cursor < this.limit) {
var ch = this.current.charCodeAt(this.cursor);
if (ch <= max && ch >= min) {
ch -= min;
if ((s[ch >>> 3] & (0X1 << (ch & 0x7))) != 0) {
return true;
}
}
this.cursor++;
}
return false;
};
/**
* @param {number[]} s
* @param {number} min
* @param {number} max
* @return {boolean}
*/
this.out_grouping_b = function(s, min, max) {
/** @protected */
if (this.cursor <= this.limit_backward) return false;
var ch = this.current.charCodeAt(this.cursor - 1);
if (ch > max || ch < min) {
this.cursor--;
return true;
}
ch -= min;
if ((s[ch >>> 3] & (0x1 << (ch & 0x7))) == 0) {
this.cursor--;
return true;
}
return false;
};
/**
* @param {number[]} s
* @param {number} min
* @param {number} max
* @return {boolean}
*/
this.go_out_grouping_b = function(s, min, max) {
/** @protected */
while (this.cursor > this.limit_backward) {
var ch = this.current.charCodeAt(this.cursor - 1);
if (ch <= max && ch >= min) {
ch -= min;
if ((s[ch >>> 3] & (0x1 << (ch & 0x7))) != 0) {
return true;
}
}
this.cursor--;
}
return false;
};
/**
* @param {string} s
* @return {boolean}
*/
this.eq_s = function(s)
{
/** @protected */
if (this.limit - this.cursor < s.length) return false;
if (this.current.slice(this.cursor, this.cursor + s.length) != s)
{
return false;
}
this.cursor += s.length;
return true;
};
/**
* @param {string} s
* @return {boolean}
*/
this.eq_s_b = function(s)
{
/** @protected */
if (this.cursor - this.limit_backward < s.length) return false;
if (this.current.slice(this.cursor - s.length, this.cursor) != s)
{
return false;
}
this.cursor -= s.length;
return true;
};
/**
* @param {Among[]} v
* @return {number}
*/
this.find_among = function(v)
{
/** @protected */
var i = 0;
var j = v.length;
var c = this.cursor;
var l = this.limit;
var common_i = 0;
var common_j = 0;
var first_key_inspected = false;
while (true)
{
var k = i + ((j - i) >>> 1);
var diff = 0;
var common = common_i < common_j ? common_i : common_j; // smaller
// w[0]: string, w[1]: substring_i, w[2]: result, w[3]: function (optional)
var w = v[k];
var i2;
for (i2 = common; i2 < w[0].length; i2++)
{
if (c + common == l)
{
diff = -1;
break;
}
diff = this.current.charCodeAt(c + common) - w[0].charCodeAt(i2);
if (diff != 0) break;
common++;
}
if (diff < 0)
{
j = k;
common_j = common;
}
else
{
i = k;
common_i = common;
}
if (j - i <= 1)
{
if (i > 0) break; // v->s has been inspected
if (j == i) break; // only one item in v
// - but now we need to go round once more to get
// v->s inspected. This looks messy, but is actually
// the optimal approach.
if (first_key_inspected) break;
first_key_inspected = true;
}
}
do {
var w = v[i];
if (common_i >= w[0].length)
{
this.cursor = c + w[0].length;
if (w.length < 4) return w[2];
var res = w[3](this);
this.cursor = c + w[0].length;
if (res) return w[2];
}
i = w[1];
} while (i >= 0);
return 0;
};
// find_among_b is for backwards processing. Same comments apply
/**
* @param {Among[]} v
* @return {number}
*/
this.find_among_b = function(v)
{
/** @protected */
var i = 0;
var j = v.length
var c = this.cursor;
var lb = this.limit_backward;
var common_i = 0;
var common_j = 0;
var first_key_inspected = false;
while (true)
{
var k = i + ((j - i) >> 1);
var diff = 0;
var common = common_i < common_j ? common_i : common_j;
var w = v[k];
var i2;
for (i2 = w[0].length - 1 - common; i2 >= 0; i2--)
{
if (c - common == lb)
{
diff = -1;
break;
}
diff = this.current.charCodeAt(c - 1 - common) - w[0].charCodeAt(i2);
if (diff != 0) break;
common++;
}
if (diff < 0)
{
j = k;
common_j = common;
}
else
{
i = k;
common_i = common;
}
if (j - i <= 1)
{
if (i > 0) break;
if (j == i) break;
if (first_key_inspected) break;
first_key_inspected = true;
}
}
do {
var w = v[i];
if (common_i >= w[0].length)
{
this.cursor = c - w[0].length;
if (w.length < 4) return w[2];
var res = w[3](this);
this.cursor = c - w[0].length;
if (res) return w[2];
}
i = w[1];
} while (i >= 0);
return 0;
};
/* to replace chars between c_bra and c_ket in this.current by the
* chars in s.
*/
/**
* @param {number} c_bra
* @param {number} c_ket
* @param {string} s
* @return {number}
*/
this.replace_s = function(c_bra, c_ket, s)
{
/** @protected */
var adjustment = s.length - (c_ket - c_bra);
this.current = this.current.slice(0, c_bra) + s + this.current.slice(c_ket);
this.limit += adjustment;
if (this.cursor >= c_ket) this.cursor += adjustment;
else if (this.cursor > c_bra) this.cursor = c_bra;
return adjustment;
};
/**
* @return {boolean}
*/
this.slice_check = function()
{
/** @protected */
if (this.bra < 0 ||
this.bra > this.ket ||
this.ket > this.limit ||
this.limit > this.current.length)
{
return false;
}
return true;
};
/**
* @param {number} c_bra
* @return {boolean}
*/
this.slice_from = function(s)
{
/** @protected */
var result = false;
if (this.slice_check())
{
this.replace_s(this.bra, this.ket, s);
result = true;
}
return result;
};
/**
* @return {boolean}
*/
this.slice_del = function()
{
/** @protected */
return this.slice_from("");
};
/**
* @param {number} c_bra
* @param {number} c_ket
* @param {string} s
*/
this.insert = function(c_bra, c_ket, s)
{
/** @protected */
var adjustment = this.replace_s(c_bra, c_ket, s);
if (c_bra <= this.bra) this.bra += adjustment;
if (c_bra <= this.ket) this.ket += adjustment;
};
/**
* @return {string}
*/
this.slice_to = function()
{
/** @protected */
var result = '';
if (this.slice_check())
{
result = this.current.slice(this.bra, this.ket);
}
return result;
};
/**
* @return {string}
*/
this.assign_to = function()
{
/** @protected */
return this.current.slice(0, this.limit);
};
};
+906
View File
@@ -0,0 +1,906 @@
/*
* Sphinx stylesheet -- basic theme.
*/
/* -- main layout ----------------------------------------------------------- */
div.clearer {
clear: both;
}
div.section::after {
display: block;
content: '';
clear: left;
}
/* -- relbar ---------------------------------------------------------------- */
div.related {
width: 100%;
font-size: 90%;
}
div.related h3 {
display: none;
}
div.related ul {
margin: 0;
padding: 0 0 0 10px;
list-style: none;
}
div.related li {
display: inline;
}
div.related li.right {
float: right;
margin-right: 5px;
}
/* -- sidebar --------------------------------------------------------------- */
div.sphinxsidebarwrapper {
padding: 10px 5px 0 10px;
}
div.sphinxsidebar {
float: left;
width: 230px;
margin-left: -100%;
font-size: 90%;
word-wrap: break-word;
overflow-wrap : break-word;
}
div.sphinxsidebar ul {
list-style: none;
}
div.sphinxsidebar ul ul,
div.sphinxsidebar ul.want-points {
margin-left: 20px;
list-style: square;
}
div.sphinxsidebar ul ul {
margin-top: 0;
margin-bottom: 0;
}
div.sphinxsidebar form {
margin-top: 10px;
}
div.sphinxsidebar input {
border: 1px solid #98dbcc;
font-family: sans-serif;
font-size: 1em;
}
div.sphinxsidebar #searchbox form.search {
overflow: hidden;
}
div.sphinxsidebar #searchbox input[type="text"] {
float: left;
width: 80%;
padding: 0.25em;
box-sizing: border-box;
}
div.sphinxsidebar #searchbox input[type="submit"] {
float: left;
width: 20%;
border-left: none;
padding: 0.25em;
box-sizing: border-box;
}
img {
border: 0;
max-width: 100%;
}
/* -- search page ----------------------------------------------------------- */
ul.search {
margin-top: 10px;
}
ul.search li {
padding: 5px 0;
}
ul.search li a {
font-weight: bold;
}
ul.search li p.context {
color: #888;
margin: 2px 0 0 30px;
text-align: left;
}
ul.keywordmatches li.goodmatch a {
font-weight: bold;
}
/* -- index page ------------------------------------------------------------ */
table.contentstable {
width: 90%;
margin-left: auto;
margin-right: auto;
}
table.contentstable p.biglink {
line-height: 150%;
}
a.biglink {
font-size: 1.3em;
}
span.linkdescr {
font-style: italic;
padding-top: 5px;
font-size: 90%;
}
/* -- general index --------------------------------------------------------- */
table.indextable {
width: 100%;
}
table.indextable td {
text-align: left;
vertical-align: top;
}
table.indextable ul {
margin-top: 0;
margin-bottom: 0;
list-style-type: none;
}
table.indextable > tbody > tr > td > ul {
padding-left: 0em;
}
table.indextable tr.pcap {
height: 10px;
}
table.indextable tr.cap {
margin-top: 10px;
background-color: #f2f2f2;
}
img.toggler {
margin-right: 3px;
margin-top: 3px;
cursor: pointer;
}
div.modindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
div.genindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
/* -- domain module index --------------------------------------------------- */
table.modindextable td {
padding: 2px;
border-collapse: collapse;
}
/* -- general body styles --------------------------------------------------- */
div.body {
min-width: 360px;
max-width: 800px;
}
div.body p, div.body dd, div.body li, div.body blockquote {
-moz-hyphens: auto;
-ms-hyphens: auto;
-webkit-hyphens: auto;
hyphens: auto;
}
a.headerlink {
visibility: hidden;
}
a:visited {
color: #551A8B;
}
h1:hover > a.headerlink,
h2:hover > a.headerlink,
h3:hover > a.headerlink,
h4:hover > a.headerlink,
h5:hover > a.headerlink,
h6:hover > a.headerlink,
dt:hover > a.headerlink,
caption:hover > a.headerlink,
p.caption:hover > a.headerlink,
div.code-block-caption:hover > a.headerlink {
visibility: visible;
}
div.body p.caption {
text-align: inherit;
}
div.body td {
text-align: left;
}
.first {
margin-top: 0 !important;
}
p.rubric {
margin-top: 30px;
font-weight: bold;
}
img.align-left, figure.align-left, .figure.align-left, object.align-left {
clear: left;
float: left;
margin-right: 1em;
}
img.align-right, figure.align-right, .figure.align-right, object.align-right {
clear: right;
float: right;
margin-left: 1em;
}
img.align-center, figure.align-center, .figure.align-center, object.align-center {
display: block;
margin-left: auto;
margin-right: auto;
}
img.align-default, figure.align-default, .figure.align-default {
display: block;
margin-left: auto;
margin-right: auto;
}
.align-left {
text-align: left;
}
.align-center {
text-align: center;
}
.align-default {
text-align: center;
}
.align-right {
text-align: right;
}
/* -- sidebars -------------------------------------------------------------- */
div.sidebar,
aside.sidebar {
margin: 0 0 0.5em 1em;
border: 1px solid #ddb;
padding: 7px;
background-color: #ffe;
width: 40%;
float: right;
clear: right;
overflow-x: auto;
}
p.sidebar-title {
font-weight: bold;
}
nav.contents,
aside.topic,
div.admonition, div.topic, blockquote {
clear: left;
}
/* -- topics ---------------------------------------------------------------- */
nav.contents,
aside.topic,
div.topic {
border: 1px solid #ccc;
padding: 7px;
margin: 10px 0 10px 0;
}
p.topic-title {
font-size: 1.1em;
font-weight: bold;
margin-top: 10px;
}
/* -- admonitions ----------------------------------------------------------- */
div.admonition {
margin-top: 10px;
margin-bottom: 10px;
padding: 7px;
}
div.admonition dt {
font-weight: bold;
}
p.admonition-title {
margin: 0px 10px 5px 0px;
font-weight: bold;
}
div.body p.centered {
text-align: center;
margin-top: 25px;
}
/* -- content of sidebars/topics/admonitions -------------------------------- */
div.sidebar > :last-child,
aside.sidebar > :last-child,
nav.contents > :last-child,
aside.topic > :last-child,
div.topic > :last-child,
div.admonition > :last-child {
margin-bottom: 0;
}
div.sidebar::after,
aside.sidebar::after,
nav.contents::after,
aside.topic::after,
div.topic::after,
div.admonition::after,
blockquote::after {
display: block;
content: '';
clear: both;
}
/* -- tables ---------------------------------------------------------------- */
table.docutils {
margin-top: 10px;
margin-bottom: 10px;
border: 0;
border-collapse: collapse;
}
table.align-center {
margin-left: auto;
margin-right: auto;
}
table.align-default {
margin-left: auto;
margin-right: auto;
}
table caption span.caption-number {
font-style: italic;
}
table caption span.caption-text {
}
table.docutils td, table.docutils th {
padding: 1px 8px 1px 5px;
border-top: 0;
border-left: 0;
border-right: 0;
border-bottom: 1px solid #aaa;
}
th {
text-align: left;
padding-right: 5px;
}
table.citation {
border-left: solid 1px gray;
margin-left: 1px;
}
table.citation td {
border-bottom: none;
}
th > :first-child,
td > :first-child {
margin-top: 0px;
}
th > :last-child,
td > :last-child {
margin-bottom: 0px;
}
/* -- figures --------------------------------------------------------------- */
div.figure, figure {
margin: 0.5em;
padding: 0.5em;
}
div.figure p.caption, figcaption {
padding: 0.3em;
}
div.figure p.caption span.caption-number,
figcaption span.caption-number {
font-style: italic;
}
div.figure p.caption span.caption-text,
figcaption span.caption-text {
}
/* -- field list styles ----------------------------------------------------- */
table.field-list td, table.field-list th {
border: 0 !important;
}
.field-list ul {
margin: 0;
padding-left: 1em;
}
.field-list p {
margin: 0;
}
.field-name {
-moz-hyphens: manual;
-ms-hyphens: manual;
-webkit-hyphens: manual;
hyphens: manual;
}
/* -- hlist styles ---------------------------------------------------------- */
table.hlist {
margin: 1em 0;
}
table.hlist td {
vertical-align: top;
}
/* -- object description styles --------------------------------------------- */
.sig {
font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
}
.sig-name, code.descname {
background-color: transparent;
font-weight: bold;
}
.sig-name {
font-size: 1.1em;
}
code.descname {
font-size: 1.2em;
}
.sig-prename, code.descclassname {
background-color: transparent;
}
.optional {
font-size: 1.3em;
}
.sig-paren {
font-size: larger;
}
.sig-param.n {
font-style: italic;
}
/* C++ specific styling */
.sig-inline.c-texpr,
.sig-inline.cpp-texpr {
font-family: unset;
}
.sig.c .k, .sig.c .kt,
.sig.cpp .k, .sig.cpp .kt {
color: #0033B3;
}
.sig.c .m,
.sig.cpp .m {
color: #1750EB;
}
.sig.c .s, .sig.c .sc,
.sig.cpp .s, .sig.cpp .sc {
color: #067D17;
}
/* -- other body styles ----------------------------------------------------- */
ol.arabic {
list-style: decimal;
}
ol.loweralpha {
list-style: lower-alpha;
}
ol.upperalpha {
list-style: upper-alpha;
}
ol.lowerroman {
list-style: lower-roman;
}
ol.upperroman {
list-style: upper-roman;
}
:not(li) > ol > li:first-child > :first-child,
:not(li) > ul > li:first-child > :first-child {
margin-top: 0px;
}
:not(li) > ol > li:last-child > :last-child,
:not(li) > ul > li:last-child > :last-child {
margin-bottom: 0px;
}
ol.simple ol p,
ol.simple ul p,
ul.simple ol p,
ul.simple ul p {
margin-top: 0;
}
ol.simple > li:not(:first-child) > p,
ul.simple > li:not(:first-child) > p {
margin-top: 0;
}
ol.simple p,
ul.simple p {
margin-bottom: 0;
}
aside.footnote > span,
div.citation > span {
float: left;
}
aside.footnote > span:last-of-type,
div.citation > span:last-of-type {
padding-right: 0.5em;
}
aside.footnote > p {
margin-left: 2em;
}
div.citation > p {
margin-left: 4em;
}
aside.footnote > p:last-of-type,
div.citation > p:last-of-type {
margin-bottom: 0em;
}
aside.footnote > p:last-of-type:after,
div.citation > p:last-of-type:after {
content: "";
clear: both;
}
dl.field-list {
display: grid;
grid-template-columns: fit-content(30%) auto;
}
dl.field-list > dt {
font-weight: bold;
word-break: break-word;
padding-left: 0.5em;
padding-right: 5px;
}
dl.field-list > dd {
padding-left: 0.5em;
margin-top: 0em;
margin-left: 0em;
margin-bottom: 0em;
}
dl {
margin-bottom: 15px;
}
dd > :first-child {
margin-top: 0px;
}
dd ul, dd table {
margin-bottom: 10px;
}
dd {
margin-top: 3px;
margin-bottom: 10px;
margin-left: 30px;
}
.sig dd {
margin-top: 0px;
margin-bottom: 0px;
}
.sig dl {
margin-top: 0px;
margin-bottom: 0px;
}
dl > dd:last-child,
dl > dd:last-child > :last-child {
margin-bottom: 0;
}
dt:target, span.highlighted {
background-color: #fbe54e;
}
rect.highlighted {
fill: #fbe54e;
}
dl.glossary dt {
font-weight: bold;
font-size: 1.1em;
}
.versionmodified {
font-style: italic;
}
.system-message {
background-color: #fda;
padding: 5px;
border: 3px solid red;
}
.footnote:target {
background-color: #ffa;
}
.line-block {
display: block;
margin-top: 1em;
margin-bottom: 1em;
}
.line-block .line-block {
margin-top: 0;
margin-bottom: 0;
margin-left: 1.5em;
}
.guilabel, .menuselection {
font-family: sans-serif;
}
.accelerator {
text-decoration: underline;
}
.classifier {
font-style: oblique;
}
.classifier:before {
font-style: normal;
margin: 0 0.5em;
content: ":";
display: inline-block;
}
abbr, acronym {
border-bottom: dotted 1px;
cursor: help;
}
/* -- code displays --------------------------------------------------------- */
pre {
overflow: auto;
overflow-y: hidden; /* fixes display issues on Chrome browsers */
}
pre, div[class*="highlight-"] {
clear: both;
}
span.pre {
-moz-hyphens: none;
-ms-hyphens: none;
-webkit-hyphens: none;
hyphens: none;
white-space: nowrap;
}
div[class*="highlight-"] {
margin: 1em 0;
}
td.linenos pre {
border: 0;
background-color: transparent;
color: #aaa;
}
table.highlighttable {
display: block;
}
table.highlighttable tbody {
display: block;
}
table.highlighttable tr {
display: flex;
}
table.highlighttable td {
margin: 0;
padding: 0;
}
table.highlighttable td.linenos {
padding-right: 0.5em;
}
table.highlighttable td.code {
flex: 1;
overflow: hidden;
}
.highlight .hll {
display: block;
}
div.highlight pre,
table.highlighttable pre {
margin: 0;
}
div.code-block-caption + div {
margin-top: 0;
}
div.code-block-caption {
margin-top: 1em;
padding: 2px 5px;
font-size: small;
}
div.code-block-caption code {
background-color: transparent;
}
table.highlighttable td.linenos,
span.linenos,
div.highlight span.gp { /* gp: Generic.Prompt */
user-select: none;
-webkit-user-select: text; /* Safari fallback only */
-webkit-user-select: none; /* Chrome/Safari */
-moz-user-select: none; /* Firefox */
-ms-user-select: none; /* IE10+ */
}
div.code-block-caption span.caption-number {
padding: 0.1em 0.3em;
font-style: italic;
}
div.code-block-caption span.caption-text {
}
div.literal-block-wrapper {
margin: 1em 0;
}
code.xref, a code {
background-color: transparent;
font-weight: bold;
}
h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
background-color: transparent;
}
.viewcode-link {
float: right;
}
.viewcode-back {
float: right;
font-family: sans-serif;
}
div.viewcode-block:target {
margin: -1px -10px;
padding: 0 10px;
}
/* -- math display ---------------------------------------------------------- */
img.math {
vertical-align: middle;
}
div.body div.math p {
text-align: center;
}
span.eqno {
float: right;
}
span.eqno a.headerlink {
position: absolute;
z-index: 1;
}
div.math:hover a.headerlink {
visibility: visible;
}
/* -- printout stylesheet --------------------------------------------------- */
@media print {
div.document,
div.documentwrapper,
div.bodywrapper {
margin: 0 !important;
width: 100%;
}
div.sphinxsidebar,
div.related,
div.footer,
#top-link {
display: none;
}
}
+1
View File
@@ -0,0 +1 @@
.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px}
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
File diff suppressed because it is too large. Load diff

After

Width:  |  Height:  |  Size: 434 KiB

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
+4
View File
@@ -0,0 +1,4 @@
html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .eqno .headerlink:before,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*!
* Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome
* License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License)
*/@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-coLine truncated
+150
View File
@@ -0,0 +1,150 @@
/*
* Base JavaScript utilities for all Sphinx HTML documentation.
*/
"use strict";
const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
"TEXTAREA",
"INPUT",
"SELECT",
"BUTTON",
]);
const _ready = (callback) => {
if (document.readyState !== "loading") {
callback();
} else {
document.addEventListener("DOMContentLoaded", callback);
}
};
/**
* Small JavaScript module for the documentation.
*/
const Documentation = {
init: () => {
Documentation.initDomainIndexTable();
Documentation.initOnKeyListeners();
},
/**
* i18n support
*/
TRANSLATIONS: {},
PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
LOCALE: "unknown",
// gettext and ngettext don't access this so that the functions
// can safely bound to a different name (_ = Documentation.gettext)
gettext: (string) => {
const translated = Documentation.TRANSLATIONS[string];
switch (typeof translated) {
case "undefined":
return string; // no translation
case "string":
return translated; // translation exists
default:
return translated[0]; // (singular, plural) translation tuple exists
}
},
ngettext: (singular, plural, n) => {
const translated = Documentation.TRANSLATIONS[singular];
if (typeof translated !== "undefined")
return translated[Documentation.PLURAL_EXPR(n)];
return n === 1 ? singular : plural;
},
addTranslations: (catalog) => {
Object.assign(Documentation.TRANSLATIONS, catalog.messages);
Documentation.PLURAL_EXPR = new Function(
"n",
`return (${catalog.plural_expr})`,
);
Documentation.LOCALE = catalog.locale;
},
/**
* helper function to focus on search bar
*/
focusSearchBar: () => {
document.querySelectorAll("input[name=q]")[0]?.focus();
},
/**
* Initialise the domain index toggle buttons
*/
initDomainIndexTable: () => {
const toggler = (el) => {
const idNumber = el.id.substr(7);
const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
if (el.src.substr(-9) === "minus.png") {
el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
toggledRows.forEach((el) => (el.style.display = "none"));
} else {
el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
toggledRows.forEach((el) => (el.style.display = ""));
}
};
const togglerElements = document.querySelectorAll("img.toggler");
togglerElements.forEach((el) =>
el.addEventListener("click", (event) => toggler(event.currentTarget)),
);
togglerElements.forEach((el) => (el.style.display = ""));
if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
},
initOnKeyListeners: () => {
// only install a listener if it is really needed
if (
!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS
&& !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
)
return;
document.addEventListener("keydown", (event) => {
// bail for input elements
if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName))
return;
// bail with special keys
if (event.altKey || event.ctrlKey || event.metaKey) return;
if (!event.shiftKey) {
switch (event.key) {
case "ArrowLeft":
if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
const prevLink = document.querySelector('link[rel="prev"]');
if (prevLink && prevLink.href) {
window.location.href = prevLink.href;
event.preventDefault();
}
break;
case "ArrowRight":
if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
const nextLink = document.querySelector('link[rel="next"]');
if (nextLink && nextLink.href) {
window.location.href = nextLink.href;
event.preventDefault();
}
break;
}
}
// some keyboard layouts may need Shift to get /
switch (event.key) {
case "/":
if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
Documentation.focusSearchBar();
event.preventDefault();
}
});
},
};
// quick alias for translations
const _ = Documentation.gettext;
_ready(Documentation.init);
+13
View File
@@ -0,0 +1,13 @@
const DOCUMENTATION_OPTIONS = {
VERSION: '1.3.3',
LANGUAGE: 'en',
COLLAPSE_INDEX: false,
BUILDER: 'html',
FILE_SUFFIX: '.html',
LINK_SUFFIX: '.html',
HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt',
NAVIGATION_WITH_KEYS: false,
SHOW_SEARCH_SUMMARY: true,
ENABLE_SEARCH_SHORTCUTS: true,
};
File diff suppressed because it is too large. Load diff
Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 286 B

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
+2
View File
@@ -0,0 +1,2 @@
/*! jQuery v3.6.0 | (c) OpenJS Foundation and other contributors | jquery.org/license */
!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],r=Object.getPrototypeOf,s=t.slice,g=t.flat?function(e){return t.flat.call(e)}:function(e){return t.concat.apply([],e)},u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType&&"function"!=typeof e.item},x=function(e){return null!=e&&e===e.window},E=C.document,c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.6.0",S=function(e,t){return new S.fn.init(e,t)};function p(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0<t&&t-1 in e)}S.fn=S.prototype={jquery:f,constructor:S,length:0,toArray:function(){return s.call(this)},get:function(e){return null==e?s.call(this):e<0?this[e+this.length]:this[e]},pushStack:function(e){var t=S.merge(this.constructor(),e);return t.prevObject=this,t},each:function(e){return S.each(this,e)},map:function(n){return this.pushStack(S.map(this,function(e,t){return n.call(e,t,e)}))},slice:function(){return this.pushStack(s.apply(this,arguments))},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},even:function(){return this.pushStack(S.grep(this,function(e,t){return(t+1)%2}))},odd:function(){return this.pushStack(S.grep(this,function(e,t){return t%2}))},eq:function(e){var t=this.length,n=+e+(e<0?t:0);return this.pushStack(0<=n&&n<t?[this[n]]:[])},end:function(){return this.prevObject||this.constructor()},push:u,sort:t.sort,splice:t.splice},S.extend=S.fn.extend=function(){var e,t,n,r,i,o,a=arguments[0]||{},s=1,u=arguments.length,l=!1;for("boolean"==typeof a&&(l=a,a=arguments[s]||{},s++),"object"==typeof a||m(a)||(a={}),s===u&&(a=this,s--);s<u;s++)if(null!=(e=arguments[s]))for(t in e)r=e[t],"__proto__"!==t&&a!==r&&(l&&r&&(S.isPlainObject(r)||(i=Array.isArray(r)))?(n=a[t],o=i&&!Array.isArray(n)?[]:i||S.isPlainObject(n)?n:{},i=!1,a[t]=S.extend(l,o,r)):void 0!==r&&(a[t]=r));return a},S.extend({expando:"jQuery"+(f+Math.random()).replace(/\D/g,""),isReady:!0,error:function(e){throw new Error(e)},noop:function(){},isPlainObject:function(e){var t,n;return!(!e||"[object Object]"!==o.call(e))&&(!(t=r(e))||"function"==typeof(n=v.call(t,"constructor")&&t.constructor)&&a.call(n)===l)},isEmptyObject:function(e){var t;for(t in e)return!1;return!0},globalEval:function(e,t,n){b(e,{nonce:t&&t.nonce},n)},each:function(e,t){var n,r=0;if(p(e)){for(n=e.length;r<n;r++)if(!1===t.call(e[r],r,e[r]))break}else for(r in e)if(!1===t.call(e[r],r,e[r]))break;return e},makeArray:function(e,t){var n=t||[];return null!=e&&(p(Object(e))?S.merge(n,"string"==typeof e?[e]:e):u.call(n,e)),n},inArray:function(e,t,n){return null==t?-1:i.call(t,e,n)},merge:function(e,t){for(var n=+t.length,r=0,i=e.length;r<n;r++)e[i++]=t[r];return e.length=i,e},grep:function(e,t,n){for(var r=[],i=0,o=e.length,a=!n;i<o;i++)!t(e[i],i)!==a&&r.push(e[i]);return r},map:function(e,t,n){var r,i,o=0,a=[];if(p(e))for(r=e.length;o<r;o++)null!=(i=t(e[o],o,n))&&a.push(i);else for(o in e)null!=(i=t(e[o],o,n))&&a.push(i);return g(a)},guid:1,support:y}),"function"==typeof Symbol&&(S.fn[Symbol.iterator]=t[Symbol.iterator]),S.each("Boolean Number String Function Array Date RegExp Object Error Symbol".split(" "),function(e,t){n["[object "+t+"]"]=t.toLowerCase()});var d=function(n){var e,d,b,o,i,h,f,g,w,u,l,T,C,a,E,v,s,c,y,S="sizzle"+1*new Date,p=n.document,k=0,r=0,m=ue(),x=ue(),A=ue(),N=ue(),j=function(e,t){return e===t&&(l=!0),0},D={}.hasOwnProperty,t=[],q=t.pop,L=t.push,H=t.push,O=t.slice,P=function(e,t){for(var n=0,r=e.length;n<r;n++)if(e[n]===t)return n;return-1},R="checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|ismap|loop|multiple|open|readonly|required|scoped",M="[\\x20\\t\\r\\n\\f]",I="(?:\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\[^\\r\\n\\f]|[\\w-]|[^\0-\\x7f])+",W="\\["+M+"*("+I+")(?:"+M+"*([*^$|!~]?=)"+M+"*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|("+I+"))|)"+M+"*\\]",F=":("+I+")(?:\\((('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|((?:\\\\.|[^\\\\()[\\]]|"+W+")*)|.*)\\)|)",B=new RegExp(M+"+","g"),$=new RegExp("^"+M+"+|((?:^|[^\\\\])(?:\\\\.)*)"+M+"+$","g"),_=new RegExp("^"+M+"*,"+M+"*"),z=new RegExp("^"+M+"*([>+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp(F),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+F),CHILD:new RegExp("^Line truncated
+1
View File
@@ -0,0 +1 @@
!function(e){var t={};function r(n){if(t[n])return t[n].exports;var o=t[n]={i:n,l:!1,exports:{}};return e[n].call(o.exports,o,o.exports,r),o.l=!0,o.exports}r.m=e,r.c=t,r.d=function(e,t,n){r.o(e,t)||Object.defineProperty(e,t,{enumerable:!0,get:n})},r.r=function(e){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},r.t=function(e,t){if(1&t&&(e=r(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var n=Object.create(null);if(r.r(n),Object.defineProperty(n,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var o in e)r.d(n,o,function(t){return e[t]}.bind(null,o));return n},r.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return r.d(t,"a",t),t},r.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},r.p="",r(r.s=4)}({4:function(e,t,r){}});
+1
View File
@@ -0,0 +1 @@
!function(n){var e={};function t(i){if(e[i])return e[i].exports;var o=e[i]={i:i,l:!1,exports:{}};return n[i].call(o.exports,o,o.exports,t),o.l=!0,o.exports}t.m=n,t.c=e,t.d=function(n,e,i){t.o(n,e)||Object.defineProperty(n,e,{enumerable:!0,get:i})},t.r=function(n){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(n,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(n,"__esModule",{value:!0})},t.t=function(n,e){if(1&e&&(n=t(n)),8&e)return n;if(4&e&&"object"==typeof n&&n&&n.__esModule)return n;var i=Object.create(null);if(t.r(i),Object.defineProperty(i,"default",{enumerable:!0,value:n}),2&e&&"string"!=typeof n)for(var o in n)t.d(i,o,function(e){return n[e]}.bind(null,o));return i},t.n=function(n){var e=n&&n.__esModule?function(){return n.default}:function(){return n};return t.d(e,"a",e),e},t.o=function(n,e){return Object.prototype.hasOwnProperty.call(n,e)},t.p="",t(t.s=0)}([function(n,e,t){t(1),n.exports=t(3)},function(n,e,t){(function(){var e="undefined"!=typeof window?window.jQuery:t(2);n.exports.ThemeNav={navBar:null,win:null,winScroll:!1,winResize:!1,linkScroll:!1,winPosition:0,winHeight:null,docHeight:null,isRunning:!1,enable:function(n){var t=this;void 0===n&&(n=!0),t.isRunning||(t.isRunning=!0,e((function(e){t.init(e),t.reset(),t.win.on("hashchange",t.reset),n&&t.win.on("scroll",(function(){t.linkScroll||t.winScroll||(t.winScroll=!0,requestAnimationFrame((function(){t.onScroll()})))})),t.win.on("resize",(function(){t.winResize||(t.winResize=!0,requestAnimationFrame((function(){t.onResize()})))})),t.onResize()})))},enableSticky:function(){this.enable(!0)},init:function(n){n(document);var e=this;this.navBar=n("div.wy-side-scroll:first"),this.win=n(window),n(document).on("click","[data-toggle='wy-nav-top']",(function(){n("[data-toggle='wy-nav-shift']").toggleClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift")})).on("click",".wy-menu-vertical .current ul li a",(function(){var t=n(this);n("[data-toggle='wy-nav-shift']").removeClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift"),e.toggleCurrent(t),e.hashChange()})).on("click","[data-toggle='rst-current-version']",(function(){n("[data-toggle='rst-versions']").toggleClass("shift-up")})),n("table.docutils:not(.field-list,.footnote,.citation)").wrap("<div class='wy-table-responsive'></div>"),n("table.docutils.footnote").wrap("<div class='wy-table-responsive footnote'></div>"),n("table.docutils.citation").wrap("<div class='wy-table-responsive citation'></div>"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each((function(){var t=n(this);expand=n('<button class="toctree-expand" title="Open/close menu"></button>'),expand.on("click",(function(n){return e.toggleCurrent(t),n.stopPropagation(),!1})),t.prepend(expand)}))},reset:function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical"),t=e.find('[href="'+n+'"]');if(0===t.length){var i=$('.document [id="'+n.substring(1)+'"]').closest("div.section");0===(t=e.find('[href="#'+i.attr("id")+'"]')).length&&(t=e.find('[href="#"]'))}if(t.length>0){$(".wy-menu-vertical .current").removeClass("current").attr("aria-expanded","false"),t.addClass("current").attr("aria-expanded","true"),t.closest("li.toctree-l1").parent().addClass("current").attr("aria-expanded","true");for(let n=1;n<=10;n++)t.closest("li.toctree-l"+n).addClass("current").attr("aria-expanded","true");t[0].scrollIntoView()}}catch(n){console.log("Error expanding nav for anchor",n)}},onScroll:function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,t=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(t),this.winPosition=n)},onResize:function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},hashChange:function(){this.linkScroll=!0,this.win.one("hashchange",(function(){this.linkScroll=!1}))},toggleCurrent:function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current").attr("aria-expanded","false"),e.siblings().find("li.current").removeClass("current").attr("aria-expanded","false");var t=e.find("> ul li");t.length&&(t.removeClass("current").attr("aria-expanded","false"),e.toggleClass("current").attr("aria-expanded",(function(n,e){return"true"==e?"false":"true"})))}},"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:n.exports.ThemeNav,StickyNav:n.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],t=0;t<e.length&&!window.requestAnimationFrame;++t)window.requestAnimationFrame=window[e[t]+"RequestAnimationFrame"],window.cancelAnimationFrame=window[e[t]+"CancelAnimationFrame"]||window[e[t]+"CancelRequestAnimationFrame"];window.requestAnimationFrame||(window.requestAnimationFrame=function(e,t){var i=(new Date).getTime(),o=Math.max(0,16-(i-n)),r=window.setTimeout((function(){e(i+o)}),o);return n=i+o,r}),window.cancelAnimationFrame||(window.cancelAnimationFrame=function(n){clearTimeout(n)})}()}).call(window)},function(n,e){n.exports=jQueLine truncated
+228
View File
@@ -0,0 +1,228 @@
const themeFlyoutDisplay = "hidden";
const themeVersionSelector = true;
const themeLanguageSelector = true;
if (themeFlyoutDisplay === "attached") {
function renderLanguages(config) {
if (!config.projects.translations.length) {
return "";
}
// Insert the current language to the options on the selector
let languages = config.projects.translations.concat(config.projects.current);
languages = languages.sort((a, b) => a.language.name.localeCompare(b.language.name));
const languagesHTML = `
<dl>
<dt>Languages</dt>
${languages
.map(
(translation) => `
<dd ${translation.slug == config.projects.current.slug ? 'class="rtd-current-item"' : ""}>
<a href="${translation.urls.documentation}">${translation.language.code}</a>
</dd>
`,
)
.join("\n")}
</dl>
`;
return languagesHTML;
}
function renderVersions(config) {
if (!config.versions.active.length) {
return "";
}
const versionsHTML = `
<dl>
<dt>Versions</dt>
${config.versions.active
.map(
(version) => `
<dd ${version.slug === config.versions.current.slug ? 'class="rtd-current-item"' : ""}>
<a href="${version.urls.documentation}">${version.slug}</a>
</dd>
`,
)
.join("\n")}
</dl>
`;
return versionsHTML;
}
function renderDownloads(config) {
if (!Object.keys(config.versions.current.downloads).length) {
return "";
}
const downloadsNameDisplay = {
pdf: "PDF",
epub: "Epub",
htmlzip: "HTML",
};
const downloadsHTML = `
<dl>
<dt>Downloads</dt>
${Object.entries(config.versions.current.downloads)
.map(
([name, url]) => `
<dd>
<a href="${url}">${downloadsNameDisplay[name]}</a>
</dd>
`,
)
.join("\n")}
</dl>
`;
return downloadsHTML;
}
document.addEventListener("readthedocs-addons-data-ready", function (event) {
const config = event.detail.data();
const flyout = `
<div class="rst-versions" data-toggle="rst-versions" role="note">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book"> Read the Docs</span>
v: ${config.versions.current.slug}
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
<div class="injected">
${renderLanguages(config)}
${renderVersions(config)}
${renderDownloads(config)}
<dl>
<dt>On Read the Docs</dt>
<dd>
<a href="${config.projects.current.urls.home}">Project Home</a>
</dd>
<dd>
<a href="${config.projects.current.urls.builds}">Builds</a>
</dd>
<dd>
<a href="${config.projects.current.urls.downloads}">Downloads</a>
</dd>
</dl>
<dl>
<dt>Search</dt>
<dd>
<form id="flyout-search-form">
<input
class="wy-form"
type="text"
name="q"
aria-label="Search docs"
placeholder="Search docs"
/>
</form>
</dd>
</dl>
<hr />
<small>
<span>Hosted by <a href="https://about.readthedocs.org/?utm_source=&utm_content=flyout">Read the Docs</a></span>
</small>
</div>
</div>
`;
// Inject the generated flyout into the body HTML element.
document.body.insertAdjacentHTML("beforeend", flyout);
// Trigger the Read the Docs Addons Search modal when clicking on the "Search docs" input from inside the flyout.
document
.querySelector("#flyout-search-form")
.addEventListener("focusin", () => {
const event = new CustomEvent("readthedocs-search-show");
document.dispatchEvent(event);
});
})
}
if (themeLanguageSelector || themeVersionSelector) {
function onSelectorSwitch(event) {
const option = event.target.selectedIndex;
const item = event.target.options[option];
window.location.href = item.dataset.url;
}
document.addEventListener("readthedocs-addons-data-ready", function (event) {
const config = event.detail.data();
const versionSwitch = document.querySelector(
"div.switch-menus > div.version-switch",
);
if (themeVersionSelector) {
let versions = config.versions.active;
if (config.versions.current.hidden || config.versions.current.type === "external") {
versions.unshift(config.versions.current);
}
const versionSelect = `
<select>
${versions
.map(
(version) => `
<option
value="${version.slug}"
${config.versions.current.slug === version.slug ? 'selected="selected"' : ""}
data-url="${version.urls.documentation}">
${version.slug}
</option>`,
)
.join("\n")}
</select>
`;
versionSwitch.innerHTML = versionSelect;
versionSwitch.firstElementChild.addEventListener("change", onSelectorSwitch);
}
const languageSwitch = document.querySelector(
"div.switch-menus > div.language-switch",
);
if (themeLanguageSelector) {
if (config.projects.translations.length) {
// Add the current language to the options on the selector
let languages = config.projects.translations.concat(
config.projects.current,
);
languages = languages.sort((a, b) =>
a.language.name.localeCompare(b.language.name),
);
const languageSelect = `
<select>
${languages
.map(
(language) => `
<option
value="${language.language.code}"
${config.projects.current.slug === language.slug ? 'selected="selected"' : ""}
data-url="${language.urls.documentation}">
${language.language.name}
</option>`,
)
.join("\n")}
</select>
`;
languageSwitch.innerHTML = languageSelect;
languageSwitch.firstElementChild.addEventListener("change", onSelectorSwitch);
}
else {
languageSwitch.remove();
}
}
});
}
document.addEventListener("readthedocs-addons-data-ready", function (event) {
// Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav.
document
.querySelector("[role='search'] input")
.addEventListener("focusin", () => {
const event = new CustomEvent("readthedocs-search-show");
document.dispatchEvent(event);
});
});
+13
View File
@@ -0,0 +1,13 @@
/*
* This script contains the language-specific data used by searchtools.js,
* namely the set of stopwords, stemmer, scorer and splitter.
*/
const stopwords = new Set(["a", "about", "above", "after", "again", "against", "all", "am", "an", "and", "any", "are", "aren't", "as", "at", "be", "because", "been", "before", "being", "below", "between", "both", "but", "by", "can't", "cannot", "could", "couldn't", "did", "didn't", "do", "does", "doesn't", "doing", "don't", "down", "during", "each", "few", "for", "from", "further", "had", "hadn't", "has", "hasn't", "have", "haven't", "having", "he", "he'd", "he'll", "he's", "her", "here", "here's", "hers", "herself", "him", "himself", "his", "how", "how's", "i", "i'd", "i'll", "i'm", "i've", "if", "in", "into", "is", "isn't", "it", "it's", "its", "itself", "let's", "me", "more", "most", "mustn't", "my", "myself", "no", "nor", "not", "of", "off", "on", "once", "only", "or", "other", "ought", "our", "ours", "ourselves", "out", "over", "own", "same", "shan't", "she", "she'd", "she'll", "she's", "should", "shouldn't", "so", "some", "such", "than", "that", "that's", "the", "their", "theirs", "them", "themselves", "then", "there", "there's", "these", "they", "they'd", "they'll", "they're", "they've", "this", "those", "through", "to", "too", "under", "until", "up", "very", "was", "wasn't", "we", "we'd", "we'll", "we're", "we've", "were", "weren't", "what", "what's", "when", "when's", "where", "where's", "which", "while", "who", "who's", "whom", "why", "why's", "with", "won't", "would", "wouldn't", "you", "you'd", "you'll", "you're", "you've", "your", "yours", "yourself", "yourselves"]);
window.stopwords = stopwords; // Export to global scope
/* Non-minified versions are copied as separate JavaScript files, if available */
BaseStemmer=function(){this.current="",this.cursor=0,this.limit=0,this.limit_backward=0,this.bra=0,this.ket=0,this.setCurrent=function(t){this.current=t,this.cursor=0,this.limit=this.current.length,this.limit_backward=0,this.bra=this.cursor,this.ket=this.limit},this.getCurrent=function(){return this.current},this.copy_from=function(t){this.current=t.current,this.cursor=t.cursor,this.limit=t.limit,this.limit_backward=t.limit_backward,this.bra=t.bra,this.ket=t.ket},this.in_grouping=function(t,r,i){return!(this.cursor>=this.limit||i<(i=this.current.charCodeAt(this.cursor))||i<r||0==(t[(i-=r)>>>3]&1<<(7&i))||(this.cursor++,0))},this.go_in_grouping=function(t,r,i){for(;this.cursor<this.limit;){var s=this.current.charCodeAt(this.cursor);if(i<s||s<r)return!0;if(0==(t[(s-=r)>>>3]&1<<(7&s)))return!0;this.cursor++}return!1},this.in_grouping_b=function(t,r,i){return!(this.cursor<=this.limit_backward||i<(i=this.current.charCodeAt(this.cursor-1))||i<r||0==(t[(i-=r)>>>3]&1<<(7&i))||(this.cursor--,0))},this.go_in_grouping_b=function(t,r,i){for(;this.cursor>this.limit_backward;){var s=this.current.charCodeAt(this.cursor-1);if(i<s||s<r)return!0;if(0==(t[(s-=r)>>>3]&1<<(7&s)))return!0;this.cursor--}return!1},this.out_grouping=function(t,r,i){return!(this.cursor>=this.limit)&&(i<(i=this.current.charCodeAt(this.cursor))||i<r||0==(t[(i-=r)>>>3]&1<<(7&i)))&&(this.cursor++,!0)},this.go_out_grouping=function(t,r,i){for(;this.cursor<this.limit;){var s=this.current.charCodeAt(this.cursor);if(s<=i&&r<=s&&0!=(t[(s-=r)>>>3]&1<<(7&s)))return!0;this.cursor++}return!1},this.out_grouping_b=function(t,r,i){return!(this.cursor<=this.limit_backward)&&(i<(i=this.current.charCodeAt(this.cursor-1))||i<r||0==(t[(i-=r)>>>3]&1<<(7&i)))&&(this.cursor--,!0)},this.go_out_grouping_b=function(t,r,i){for(;this.cursor>this.limit_backward;){var s=this.current.charCodeAt(this.cursor-1);if(s<=i&&r<=s&&0!=(t[(s-=r)>>>3]&1<<(7&s)))return!0;this.cursor--}return!1},this.eq_s=function(t){return!(this.limit-this.cursor<t.length||this.current.slice(this.cursor,this.cursor+t.length)!=t||(this.cursor+=t.length,0))},this.eq_s_b=function(t){return!(this.cursor-this.limit_backward<t.length||this.current.slice(this.cursor-t.length,this.cursor)!=t||(this.cursor-=t.length,0))},this.find_among=function(t){for(var r=0,i=t.length,s=this.cursor,h=this.limit,e=0,n=0,c=!1;;){for(var u=r+(i-r>>>1),o=0,a=e<n?e:n,l=t[u],f=a;f<l[0].length;f++){if(s+a==h){o=-1;break}if(0!=(o=this.current.charCodeAt(s+a)-l[0].charCodeAt(f)))break;a++}if(o<0?(i=u,n=a):(r=u,e=a),i-r<=1){if(0<r)break;if(i==r)break;if(c)break;c=!0}}do{if(e>=(l=t[r])[0].length){if(this.cursor=s+l[0].length,l.length<4)return l[2];var g=l[3](this);if(this.cursor=s+l[0].length,g)return l[2]}}while(0<=(r=l[1]));return 0},this.find_among_b=function(t){for(var r=0,i=t.length,s=this.cursor,h=this.limit_backward,e=0,n=0,c=!1;;){for(var u,o=r+(i-r>>1),a=0,l=e<n?e:n,f=(u=t[o])[0].length-1-l;0<=f;f--){if(s-l==h){a=-1;break}if(0!=(a=this.current.charCodeAt(s-1-l)-u[0].charCodeAt(f)))break;l++}if(a<0?(i=o,n=l):(r=o,e=l),i-r<=1){if(0<r)break;if(i==r)break;if(c)break;c=!0}}do{if(e>=(u=t[r])[0].length){if(this.cursor=s-u[0].length,u.length<4)return u[2];var g=u[3](this);if(this.cursor=s-u[0].length,g)return u[2]}}while(0<=(r=u[1]));return 0},this.replace_s=function(t,r,i){var s=i.length-(r-t);return this.current=this.current.slice(0,t)+i+this.current.slice(r),this.limit+=s,this.cursor>=r?this.cursor+=s:this.cursor>t&&(this.cursor=t),s},this.slice_check=function(){return!(this.bra<0||this.bra>this.ket||this.ket>this.limit||this.limit>this.current.length)},this.slice_from=function(t){var r=!1;return this.slice_check()&&(this.replace_s(this.bra,this.ket,t),r=!0),r},this.slice_del=function(){return this.slice_from("")},this.insert=function(t,r,i){r=this.replace_s(t,r,i);t<=this.bra&&(this.bra+=r),t<=this.ket&&(this.ket+=r)},this.slice_to=function(){var t="";return t=this.slice_check()?this.current.slice(this.bra,this.ket):t},this.assign_to=function(){return this.current.slice(0,this.limit)}};
var EnglishStemmer=function(){var a=new BaseStemmer,c=[["arsen",-1,-1],["commun",-1,-1],["emerg",-1,-1],["gener",-1,-1],["later",-1,-1],["organ",-1,-1],["past",-1,-1],["univers",-1,-1]],o=[["'",-1,1],["'s'",0,1],["'s",-1,1]],u=[["ied",-1,2],["s",-1,3],["ies",1,2],["sses",1,1],["ss",1,-1],["us",1,-1]],t=[["succ",-1,1],["proc",-1,1],["exc",-1,1]],l=[["even",-1,2],["cann",-1,2],["inn",-1,2],["earr",-1,2],["herr",-1,2],["out",-1,2],["y",-1,1]],n=[["",-1,-1],["ed",0,2],["eed",1,1],["ing",0,3],["edly",0,2],["eedly",4,1],["ingly",0,2]],f=[["",-1,3],["bb",0,2],["dd",0,2],["ff",0,2],["gg",0,2],["bl",0,1],["mm",0,2],["nn",0,2],["pp",0,2],["rr",0,2],["at",0,1],["tt",0,2],["iz",0,1]],_=[["anci",-1,3],["enci",-1,2],["ogi",-1,14],["li",-1,16],["bli",3,12],["abli",4,4],["alli",3,8],["fulli",3,9],["lessli",3,15],["ousli",3,10],["entli",3,5],["aliti",-1,8],["biliti",-1,12],["iviti",-1,11],["tional",-1,1],["ational",14,7],["alism",-1,8],["ation",-1,7],["ization",17,6],["izer",-1,6],["ator",-1,7],["iveness",-1,11],["fulness",-1,9],["ousness",-1,10],["ogist",-1,13]],m=[["icate",-1,4],["ative",-1,6],["alize",-1,3],["iciti",-1,4],["ical",-1,4],["tional",-1,1],["ational",5,2],["ful",-1,5],["ness",-1,5]],b=[["ic",-1,1],["ance",-1,1],["ence",-1,1],["able",-1,1],["ible",-1,1],["ate",-1,1],["ive",-1,1],["ize",-1,1],["iti",-1,1],["al",-1,1],["ism",-1,1],["ion",-1,2],["er",-1,1],["ous",-1,1],["ant",-1,1],["ent",-1,1],["ment",15,1],["ement",16,1]],k=[["e",-1,1],["l",-1,2]],g=[["andes",-1,-1],["atlas",-1,-1],["bias",-1,-1],["cosmos",-1,-1],["early",-1,5],["gently",-1,3],["howe",-1,-1],["idly",-1,2],["news",-1,-1],["only",-1,6],["singly",-1,7],["skies",-1,1],["sky",-1,-1],["ugly",-1,4]],d=[17,64],v=[17,65,16,1],i=[1,17,65,208,1],w=[55,141,2],p=!1,y=0,h=0;function q(){var r=a.limit-a.cursor;return!!(a.out_grouping_b(i,89,121)&&a.in_grouping_b(v,97,121)&&a.out_grouping_b(v,97,121)||(a.cursor=a.limit-r,a.out_grouping_b(v,97,121)&&a.in_grouping_b(v,97,121)&&!(a.cursor>a.limit_backward))||(a.cursor=a.limit-r,a.eq_s_b("past")))}function z(){return h<=a.cursor}function Y(){return y<=a.cursor}this.stem=function(){var r=a.cursor;if(!(()=>{var r;if(a.bra=a.cursor,0!=(r=a.find_among(g))&&(a.ket=a.cursor,!(a.cursor<a.limit))){switch(r){case 1:if(a.slice_from("sky"))break;return;case 2:if(a.slice_from("idl"))break;return;case 3:if(a.slice_from("gentl"))break;return;case 4:if(a.slice_from("ugli"))break;return;case 5:if(a.slice_from("earli"))break;return;case 6:if(a.slice_from("onli"))break;return;case 7:if(a.slice_from("singl"))break;return}return 1}})()){a.cursor=r;var i=a.cursor,e=a.cursor+3;if(e>a.limit)a.cursor=i;else{a.cursor=e,a.cursor=r,(()=>{p=!1;var r=a.cursor;if(a.bra=a.cursor,!a.eq_s("'")||(a.ket=a.cursor,a.slice_del())){a.cursor=r;r=a.cursor;if(a.bra=a.cursor,a.eq_s("y")){if(a.ket=a.cursor,!a.slice_from("Y"))return;p=!0}a.cursor=r;for(r=a.cursor;;){var i=a.cursor;r:{for(;;){var e=a.cursor;if(a.in_grouping(v,97,121)&&(a.bra=a.cursor,a.eq_s("y"))){a.ket=a.cursor,a.cursor=e;break}if(a.cursor=e,a.cursor>=a.limit)break r;a.cursor++}if(!a.slice_from("Y"))return;p=!0;continue}a.cursor=i;break}a.cursor=r}})(),h=a.limit,y=a.limit;i=a.cursor;r:{var s=a.cursor;if(0==a.find_among(c)){if(a.cursor=s,!a.go_out_grouping(v,97,121))break r;if(a.cursor++,!a.go_in_grouping(v,97,121))break r;a.cursor++}h=a.cursor,a.go_out_grouping(v,97,121)&&(a.cursor++,a.go_in_grouping(v,97,121))&&(a.cursor++,y=a.cursor)}a.cursor=i,a.limit_backward=a.cursor,a.cursor=a.limit;var e=a.limit-a.cursor,r=((()=>{var r=a.limit-a.cursor;if(a.ket=a.cursor,0==a.find_among_b(o))a.cursor=a.limit-r;else if(a.bra=a.cursor,!a.slice_del())return;if(a.ket=a.cursor,0!=(r=a.find_among_b(u)))switch(a.bra=a.cursor,r){case 1:if(a.slice_from("ss"))break;return;case 2:r:{var i=a.limit-a.cursor,e=a.cursor-2;if(!(e<a.limit_backward)){if(a.cursor=e,a.slice_from("i"))break r;return}if(a.cursor=a.limit-i,!a.slice_from("ie"))return}break;case 3:if(a.cursor<=a.limit_backward)return;if(a.cursor--,!a.go_out_grouping_b(v,97,121))return;if(a.cursor--,a.slice_del())break}})(),a.cursor=a.limit-e,a.limit-a.cursor),i=((()=>{a.ket=a.cursor,o=a.find_among_b(n),a.bra=a.cursor;r:{var r=a.limit-a.cursor;i:{switch(o){case 1:var i=a.limit-a.cursor;e:{var e=a.limit-a.cursor;if(0==a.find_among_b(t)||a.cursor>a.limit_backward){if(a.cursor=a.limit-e,!z())break e;if(!a.slice_from("ee"))return}}a.cursor=a.limit-i;break;case 2:break i;case 3:if(0==(o=a.find_among_b(l)))break i;switch(o){case 1:var s=a.limit-a.cursor;if(!a.out_grouping_b(v,97,121))break i;if(a.cursor>a.limit_backward)break i;if(a.cursor=a.limit-s,a.bra=a.cursor,a.slice_from("ie"))break;return;case 2:if(a.cursor>a.limit_backward)break i}}break r}a.cursor=a.limit-r;var c=a.limit-a.cursor;if(!a.go_out_grouping_b(v,97,121))return;if(a.cursor--,a.cursor=a.limit-c,!a.slice_del())return;a.ket=a.cursor,a.bra=a.cursor;var o,c=a.limit-a.cursor;switch(o=a.find_among_b(f)){case 1:return a.slice_from("e");case 2:var u=a.limit-a.cursor;if(a.in_grouping_b(d,97,111)&&!(a.cursor>Line truncated
window.Stemmer = EnglishStemmer;
BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 90 B

+11
View File
@@ -0,0 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>tzst</ShortName>
<Description>Search tzst 1.3.3 Documentation</Description>
<InputEncoding>utf-8</InputEncoding>
<Url type="text/html" method="get"
template="https://tzst.xi-xu.me//search.html?q={searchTerms}"/>
<LongName>tzst 1.3.3 Documentation</LongName>
<Image height="16" width="16" type="image/x-icon">https://tzst.xi-xu.me//_static/favicon.ico</Image>
</OpenSearchDescription>
BIN
View File
Binary file not shown.

After

Width:  |  Height:  |  Size: 90 B

+75
View File
@@ -0,0 +1,75 @@
pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #ffffcc }
.highlight { background: #f8f8f8; }
.highlight .c { color: #3D7B7B; font-style: italic } /* Comment */
.highlight .err { border: 1px solid #F00 } /* Error */
.highlight .k { color: #008000; font-weight: bold } /* Keyword */
.highlight .o { color: #666 } /* Operator */
.highlight .ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */
.highlight .cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #9C6500 } /* Comment.Preproc */
.highlight .cpf { color: #3D7B7B; font-style: italic } /* Comment.PreprocFile */
.highlight .c1 { color: #3D7B7B; font-style: italic } /* Comment.Single */
.highlight .cs { color: #3D7B7B; font-style: italic } /* Comment.Special */
.highlight .gd { color: #A00000 } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */
.highlight .gr { color: #E40000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #008400 } /* Generic.Inserted */
.highlight .go { color: #717171 } /* Generic.Output */
.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.highlight .gt { color: #04D } /* Generic.Traceback */
.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
.highlight .kp { color: #008000 } /* Keyword.Pseudo */
.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #B00040 } /* Keyword.Type */
.highlight .m { color: #666 } /* Literal.Number */
.highlight .s { color: #BA2121 } /* Literal.String */
.highlight .na { color: #687822 } /* Name.Attribute */
.highlight .nb { color: #008000 } /* Name.Builtin */
.highlight .nc { color: #00F; font-weight: bold } /* Name.Class */
.highlight .no { color: #800 } /* Name.Constant */
.highlight .nd { color: #A2F } /* Name.Decorator */
.highlight .ni { color: #717171; font-weight: bold } /* Name.Entity */
.highlight .ne { color: #CB3F38; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #00F } /* Name.Function */
.highlight .nl { color: #767600 } /* Name.Label */
.highlight .nn { color: #00F; font-weight: bold } /* Name.Namespace */
.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #19177C } /* Name.Variable */
.highlight .ow { color: #A2F; font-weight: bold } /* Operator.Word */
.highlight .w { color: #BBB } /* Text.Whitespace */
.highlight .mb { color: #666 } /* Literal.Number.Bin */
.highlight .mf { color: #666 } /* Literal.Number.Float */
.highlight .mh { color: #666 } /* Literal.Number.Hex */
.highlight .mi { color: #666 } /* Literal.Number.Integer */
.highlight .mo { color: #666 } /* Literal.Number.Oct */
.highlight .sa { color: #BA2121 } /* Literal.String.Affix */
.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
.highlight .sc { color: #BA2121 } /* Literal.String.Char */
.highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */
.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
.highlight .s2 { color: #BA2121 } /* Literal.String.Double */
.highlight .se { color: #AA5D1F; font-weight: bold } /* Literal.String.Escape */
.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
.highlight .si { color: #A45A77; font-weight: bold } /* Literal.String.Interpol */
.highlight .sx { color: #008000 } /* Literal.String.Other */
.highlight .sr { color: #A45A77 } /* Literal.String.Regex */
.highlight .s1 { color: #BA2121 } /* Literal.String.Single */
.highlight .ss { color: #19177C } /* Literal.String.Symbol */
.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #00F } /* Name.Function.Magic */
.highlight .vc { color: #19177C } /* Name.Variable.Class */
.highlight .vg { color: #19177C } /* Name.Variable.Global */
.highlight .vi { color: #19177C } /* Name.Variable.Instance */
.highlight .vm { color: #19177C } /* Name.Variable.Magic */
.highlight .il { color: #666 } /* Literal.Number.Integer.Long */
+21
View File
@@ -0,0 +1,21 @@
# robots.txt for tzst documentation
User-agent: *
Allow: /
# Sitemap location
Sitemap: https://tzst.xi-xu.me/sitemap.xml
# Disallow build artifacts and internal directories
Disallow: /_sources/
Disallow: /_static/*.js$
Disallow: /_images/
# Allow static assets like CSS and images
Allow: /_static/*.css$
Allow: /_static/*.png$
Allow: /_static/*.jpg$
Allow: /_static/*.ico$
Allow: /_static/*.svg$
# Crawl delay (optional, considerate to search engines)
Crawl-delay: 1
+693
View File
@@ -0,0 +1,693 @@
/*
* Sphinx JavaScript utilities for the full-text search.
*/
"use strict";
/**
* Simple result scoring code.
*/
if (typeof Scorer === "undefined") {
var Scorer = {
// Implement the following function to further tweak the score for each result
// The function takes a result array [docname, title, anchor, descr, score, filename]
// and returns the new score.
/*
score: result => {
const [docname, title, anchor, descr, score, filename, kind] = result
return score
},
*/
// query matches the full name of an object
objNameMatch: 11,
// or matches in the last dotted part of the object name
objPartialMatch: 6,
// Additive scores depending on the priority of the object
objPrio: {
0: 15, // used to be importantResults
1: 5, // used to be objectResults
2: -5, // used to be unimportantResults
},
// Used when the priority is not in the mapping.
objPrioDefault: 0,
// query found in title
title: 15,
partialTitle: 7,
// query found in terms
term: 5,
partialTerm: 2,
};
}
// Global search result kind enum, used by themes to style search results.
// prettier-ignore
class SearchResultKind {
static get index() { return "index"; }
static get object() { return "object"; }
static get text() { return "text"; }
static get title() { return "title"; }
}
const _removeChildren = (element) => {
while (element && element.lastChild) element.removeChild(element.lastChild);
};
/**
* See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping
*/
const _escapeRegExp = (string) =>
string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
const _escapeHTML = (text) => {
return text
.replaceAll("&", "&amp;")
.replaceAll("<", "&lt;")
.replaceAll(">", "&gt;")
.replaceAll('"', "&quot;")
.replaceAll("'", "&apos;");
};
const _displayItem = (item, searchTerms, highlightTerms) => {
const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX;
const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX;
const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
const contentRoot = document.documentElement.dataset.content_root;
const [docName, title, anchor, descr, score, _filename, kind] = item;
let listItem = document.createElement("li");
// Add a class representing the item's type:
// can be used by a theme's CSS selector for styling
// See SearchResultKind for the class names.
listItem.classList.add(`kind-${kind}`);
let requestUrl;
let linkUrl;
if (docBuilder === "dirhtml") {
// dirhtml builder
let dirname = docName + "/";
if (dirname.match(/\/index\/$/))
dirname = dirname.substring(0, dirname.length - 6);
else if (dirname === "index/") dirname = "";
requestUrl = contentRoot + dirname;
linkUrl = requestUrl;
} else {
// normal html builders
requestUrl = contentRoot + docName + docFileSuffix;
linkUrl = docName + docLinkSuffix;
}
let linkEl = listItem.appendChild(document.createElement("a"));
linkEl.href = linkUrl + anchor;
linkEl.dataset.score = score;
linkEl.innerHTML = _escapeHTML(title);
if (descr) {
listItem.appendChild(document.createElement("span")).innerHTML =
` (${_escapeHTML(descr)})`;
// highlight search terms in the description
if (SPHINX_HIGHLIGHT_ENABLED)
// SPHINX_HIGHLIGHT_ENABLED is set in sphinx_highlight.js
highlightTerms.forEach((term) =>
_highlightText(listItem, term, "highlighted"),
);
} else if (showSearchSummary)
fetch(requestUrl)
.then((responseData) => responseData.text())
.then((data) => {
if (data)
listItem.appendChild(
Search.makeSearchSummary(data, searchTerms, anchor),
);
// highlight search terms in the summary
if (SPHINX_HIGHLIGHT_ENABLED)
// SPHINX_HIGHLIGHT_ENABLED is set in sphinx_highlight.js
highlightTerms.forEach((term) =>
_highlightText(listItem, term, "highlighted"),
);
});
Search.output.appendChild(listItem);
};
const _finishSearch = (resultCount) => {
Search.stopPulse();
Search.title.innerText = _("Search Results");
if (!resultCount)
Search.status.innerText = Documentation.gettext(
"Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.",
);
else
Search.status.innerText = Documentation.ngettext(
"Search finished, found one page matching the search query.",
"Search finished, found ${resultCount} pages matching the search query.",
resultCount,
).replace("${resultCount}", resultCount);
};
const _displayNextItem = (
results,
resultCount,
searchTerms,
highlightTerms,
) => {
// results left, load the summary and display it
// this is intended to be dynamic (don't sub resultsCount)
if (results.length) {
_displayItem(results.pop(), searchTerms, highlightTerms);
setTimeout(
() => _displayNextItem(results, resultCount, searchTerms, highlightTerms),
5,
);
}
// search finished, update title and status message
else _finishSearch(resultCount);
};
// Helper function used by query() to order search results.
// Each input is an array of [docname, title, anchor, descr, score, filename, kind].
// Order the results by score (in opposite order of appearance, since the
// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically.
const _orderResultsByScoreThenName = (a, b) => {
const leftScore = a[4];
const rightScore = b[4];
if (leftScore === rightScore) {
// same score: sort alphabetically
const leftTitle = a[1].toLowerCase();
const rightTitle = b[1].toLowerCase();
if (leftTitle === rightTitle) return 0;
return leftTitle > rightTitle ? -1 : 1; // inverted is intentional
}
return leftScore > rightScore ? 1 : -1;
};
/**
* Default splitQuery function. Can be overridden in ``sphinx.search`` with a
* custom function per language.
*
* The regular expression works by splitting the string on consecutive characters
* that are not Unicode letters, numbers, underscores, or emoji characters.
* This is the same as ``\W+`` in Python, preserving the surrogate pair area.
*/
if (typeof splitQuery === "undefined") {
var splitQuery = (query) =>
query
.split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu)
.filter((term) => term); // remove remaining empty strings
}
/**
* Search Module
*/
const Search = {
_index: null,
_queued_query: null,
_pulse_status: -1,
htmlToText: (htmlString, anchor) => {
const htmlElement = new DOMParser().parseFromString(
htmlString,
"text/html",
);
for (const removalQuery of [".headerlink", "script", "style"]) {
htmlElement.querySelectorAll(removalQuery).forEach((el) => {
el.remove();
});
}
if (anchor) {
const anchorContent = htmlElement.querySelector(
`[role="main"] ${anchor}`,
);
if (anchorContent) return anchorContent.textContent;
console.warn(
`Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.`,
);
}
// if anchor not specified or not found, fall back to main content
const docContent = htmlElement.querySelector('[role="main"]');
if (docContent) return docContent.textContent;
console.warn(
"Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template.",
);
return "";
},
init: () => {
const query = new URLSearchParams(window.location.search).get("q");
document
.querySelectorAll('input[name="q"]')
.forEach((el) => (el.value = query));
if (query) Search.performSearch(query);
},
loadIndex: (url) =>
(document.body.appendChild(document.createElement("script")).src = url),
setIndex: (index) => {
Search._index = index;
if (Search._queued_query !== null) {
const query = Search._queued_query;
Search._queued_query = null;
Search.query(query);
}
},
hasIndex: () => Search._index !== null,
deferQuery: (query) => (Search._queued_query = query),
stopPulse: () => (Search._pulse_status = -1),
startPulse: () => {
if (Search._pulse_status >= 0) return;
const pulse = () => {
Search._pulse_status = (Search._pulse_status + 1) % 4;
Search.dots.innerText = ".".repeat(Search._pulse_status);
if (Search._pulse_status >= 0) window.setTimeout(pulse, 500);
};
pulse();
},
/**
* perform a search for something (or wait until index is loaded)
*/
performSearch: (query) => {
// create the required interface elements
const searchText = document.createElement("h2");
searchText.textContent = _("Searching");
const searchSummary = document.createElement("p");
searchSummary.classList.add("search-summary");
searchSummary.innerText = "";
const searchList = document.createElement("ul");
searchList.setAttribute("role", "list");
searchList.classList.add("search");
const out = document.getElementById("search-results");
Search.title = out.appendChild(searchText);
Search.dots = Search.title.appendChild(document.createElement("span"));
Search.status = out.appendChild(searchSummary);
Search.output = out.appendChild(searchList);
const searchProgress = document.getElementById("search-progress");
// Some themes don't use the search progress node
if (searchProgress) {
searchProgress.innerText = _("Preparing search...");
}
Search.startPulse();
// index already loaded, the browser was quick!
if (Search.hasIndex()) Search.query(query);
else Search.deferQuery(query);
},
_parseQuery: (query) => {
// stem the search terms and add them to the correct list
const stemmer = new Stemmer();
const searchTerms = new Set();
const excludedTerms = new Set();
const highlightTerms = new Set();
const objectTerms = new Set(splitQuery(query.toLowerCase().trim()));
splitQuery(query.trim()).forEach((queryTerm) => {
const queryTermLower = queryTerm.toLowerCase();
// maybe skip this "word"
// stopwords set is from language_data.js
if (stopwords.has(queryTermLower) || queryTerm.match(/^\d+$/)) return;
// stem the word
let word = stemmer.stemWord(queryTermLower);
// select the correct list
if (word[0] === "-") excludedTerms.add(word.substr(1));
else {
searchTerms.add(word);
highlightTerms.add(queryTermLower);
}
});
if (SPHINX_HIGHLIGHT_ENABLED) {
// SPHINX_HIGHLIGHT_ENABLED is set in sphinx_highlight.js
localStorage.setItem(
"sphinx_highlight_terms",
[...highlightTerms].join(" "),
);
}
// console.debug("SEARCH: searching for:");
// console.info("required: ", [...searchTerms]);
// console.info("excluded: ", [...excludedTerms]);
return [query, searchTerms, excludedTerms, highlightTerms, objectTerms];
},
/**
* execute search (requires search index to be loaded)
*/
_performSearch: (
query,
searchTerms,
excludedTerms,
highlightTerms,
objectTerms,
) => {
const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const titles = Search._index.titles;
const allTitles = Search._index.alltitles;
const indexEntries = Search._index.indexentries;
// Collect multiple result groups to be sorted separately and then ordered.
// Each is an array of [docname, title, anchor, descr, score, filename, kind].
const normalResults = [];
const nonMainIndexResults = [];
_removeChildren(document.getElementById("search-progress"));
const queryLower = query.toLowerCase().trim();
for (const [title, foundTitles] of Object.entries(allTitles)) {
if (
title.toLowerCase().trim().includes(queryLower)
&& queryLower.length >= title.length / 2
) {
for (const [file, id] of foundTitles) {
const score = Math.round(
(Scorer.title * queryLower.length) / title.length,
);
const boost = titles[file] === title ? 1 : 0; // add a boost for document titles
normalResults.push([
docNames[file],
titles[file] !== title ? `${titles[file]} > ${title}` : title,
id !== null ? "#" + id : "",
null,
score + boost,
filenames[file],
SearchResultKind.title,
]);
}
}
}
// search for explicit entries in index directives
for (const [entry, foundEntries] of Object.entries(indexEntries)) {
if (entry.includes(queryLower) && queryLower.length >= entry.length / 2) {
for (const [file, id, isMain] of foundEntries) {
const score = Math.round((100 * queryLower.length) / entry.length);
const result = [
docNames[file],
titles[file],
id ? "#" + id : "",
null,
score,
filenames[file],
SearchResultKind.index,
];
if (isMain) {
normalResults.push(result);
} else {
nonMainIndexResults.push(result);
}
}
}
}
// lookup as object
objectTerms.forEach((term) =>
normalResults.push(...Search.performObjectSearch(term, objectTerms)),
);
// lookup as search terms in fulltext
normalResults.push(
...Search.performTermsSearch(searchTerms, excludedTerms),
);
// let the scorer override scores with a custom scoring function
if (Scorer.score) {
normalResults.forEach((item) => (item[4] = Scorer.score(item)));
nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item)));
}
// Sort each group of results by score and then alphabetically by name.
normalResults.sort(_orderResultsByScoreThenName);
nonMainIndexResults.sort(_orderResultsByScoreThenName);
// Combine the result groups in (reverse) order.
// Non-main index entries are typically arbitrary cross-references,
// so display them after other results.
let results = [...nonMainIndexResults, ...normalResults];
// remove duplicate search results
// note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept
let seen = new Set();
results = results.reverse().reduce((acc, result) => {
let resultStr = result
.slice(0, 4)
.concat([result[5]])
.map((v) => String(v))
.join(",");
if (!seen.has(resultStr)) {
acc.push(result);
seen.add(resultStr);
}
return acc;
}, []);
return results.reverse();
},
query: (query) => {
const [
searchQuery,
searchTerms,
excludedTerms,
highlightTerms,
objectTerms,
] = Search._parseQuery(query);
const results = Search._performSearch(
searchQuery,
searchTerms,
excludedTerms,
highlightTerms,
objectTerms,
);
// for debugging
//Search.lastresults = results.slice(); // a copy
// console.info("search results:", Search.lastresults);
// print the results
_displayNextItem(results, results.length, searchTerms, highlightTerms);
},
/**
* search for object names
*/
performObjectSearch: (object, objectTerms) => {
const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const objects = Search._index.objects;
const objNames = Search._index.objnames;
const titles = Search._index.titles;
const results = [];
const objectSearchCallback = (prefix, match) => {
const name = match[4];
const fullname = (prefix ? prefix + "." : "") + name;
const fullnameLower = fullname.toLowerCase();
if (fullnameLower.indexOf(object) < 0) return;
let score = 0;
const parts = fullnameLower.split(".");
// check for different match types: exact matches of full name or
// "last name" (i.e. last dotted part)
if (fullnameLower === object || parts.slice(-1)[0] === object)
score += Scorer.objNameMatch;
else if (parts.slice(-1)[0].indexOf(object) > -1)
score += Scorer.objPartialMatch; // matches in last name
const objName = objNames[match[1]][2];
const title = titles[match[0]];
// If more than one term searched for, we require other words to be
// found in the name/title/description
const otherTerms = new Set(objectTerms);
otherTerms.delete(object);
if (otherTerms.size > 0) {
const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase();
if (
[...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0)
)
return;
}
let anchor = match[3];
if (anchor === "") anchor = fullname;
else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname;
const descr = objName + _(", in ") + title;
// add custom score for some objects according to scorer
if (Scorer.objPrio.hasOwnProperty(match[2]))
score += Scorer.objPrio[match[2]];
else score += Scorer.objPrioDefault;
results.push([
docNames[match[0]],
fullname,
"#" + anchor,
descr,
score,
filenames[match[0]],
SearchResultKind.object,
]);
};
Object.keys(objects).forEach((prefix) =>
objects[prefix].forEach((array) => objectSearchCallback(prefix, array)),
);
return results;
},
/**
* search for full-text terms in the index
*/
performTermsSearch: (searchTerms, excludedTerms) => {
// prepare search
const terms = Search._index.terms;
const titleTerms = Search._index.titleterms;
const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const titles = Search._index.titles;
const scoreMap = new Map();
const fileMap = new Map();
// perform the search on the required terms
searchTerms.forEach((word) => {
const files = [];
// find documents, if any, containing the query word in their text/title term indices
// use Object.hasOwnProperty to avoid mismatching against prototype properties
const arr = [
{
files: terms.hasOwnProperty(word) ? terms[word] : undefined,
score: Scorer.term,
},
{
files: titleTerms.hasOwnProperty(word) ? titleTerms[word] : undefined,
score: Scorer.title,
},
];
// add support for partial matches
if (word.length > 2) {
const escapedWord = _escapeRegExp(word);
if (!terms.hasOwnProperty(word)) {
Object.keys(terms).forEach((term) => {
if (term.match(escapedWord))
arr.push({ files: terms[term], score: Scorer.partialTerm });
});
}
if (!titleTerms.hasOwnProperty(word)) {
Object.keys(titleTerms).forEach((term) => {
if (term.match(escapedWord))
arr.push({ files: titleTerms[term], score: Scorer.partialTitle });
});
}
}
// no match but word was a required one
if (arr.every((record) => record.files === undefined)) return;
// found search word in contents
arr.forEach((record) => {
if (record.files === undefined) return;
let recordFiles = record.files;
if (recordFiles.length === undefined) recordFiles = [recordFiles];
files.push(...recordFiles);
// set score for the word in each file
recordFiles.forEach((file) => {
if (!scoreMap.has(file)) scoreMap.set(file, new Map());
const fileScores = scoreMap.get(file);
fileScores.set(word, record.score);
});
});
// create the mapping
files.forEach((file) => {
if (!fileMap.has(file)) fileMap.set(file, [word]);
else if (fileMap.get(file).indexOf(word) === -1)
fileMap.get(file).push(word);
});
});
// now check if the files don't contain excluded terms
const results = [];
for (const [file, wordList] of fileMap) {
// check if all requirements are matched
// as search terms with length < 3 are discarded
const filteredTermCount = [...searchTerms].filter(
(term) => term.length > 2,
).length;
if (
wordList.length !== searchTerms.size
&& wordList.length !== filteredTermCount
)
continue;
// ensure that none of the excluded terms is in the search result
if (
[...excludedTerms].some(
(term) =>
terms[term] === file
|| titleTerms[term] === file
|| (terms[term] || []).includes(file)
|| (titleTerms[term] || []).includes(file),
)
)
break;
// select one (max) score for the file.
const score = Math.max(...wordList.map((w) => scoreMap.get(file).get(w)));
// add result to the result list
results.push([
docNames[file],
titles[file],
"",
null,
score,
filenames[file],
SearchResultKind.text,
]);
}
return results;
},
/**
* helper function to return a node containing the
* search summary for a given text. keywords is a list
* of stemmed words.
*/
makeSearchSummary: (htmlText, keywords, anchor) => {
const text = Search.htmlToText(htmlText, anchor);
if (text === "") return null;
const textLower = text.toLowerCase();
const actualStartPosition = [...keywords]
.map((k) => textLower.indexOf(k.toLowerCase()))
.filter((i) => i > -1)
.slice(-1)[0];
const startWithContext = Math.max(actualStartPosition - 120, 0);
const top = startWithContext === 0 ? "" : "...";
const tail = startWithContext + 240 < text.length ? "..." : "";
let summary = document.createElement("p");
summary.classList.add("context");
summary.textContent =
top + text.substr(startWithContext, 240).trim() + tail;
return summary;
},
};
_ready(Search.init);
+159
View File
@@ -0,0 +1,159 @@
/* Highlighting utilities for Sphinx HTML documentation. */
"use strict";
const SPHINX_HIGHLIGHT_ENABLED = true;
/**
* highlight a given string on a node by wrapping it in
* span elements with the given class name.
*/
const _highlight = (node, addItems, text, className) => {
if (node.nodeType === Node.TEXT_NODE) {
const val = node.nodeValue;
const parent = node.parentNode;
const pos = val.toLowerCase().indexOf(text);
if (
pos >= 0
&& !parent.classList.contains(className)
&& !parent.classList.contains("nohighlight")
) {
let span;
const closestNode = parent.closest("body, svg, foreignObject");
const isInSVG = closestNode && closestNode.matches("svg");
if (isInSVG) {
span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
} else {
span = document.createElement("span");
span.classList.add(className);
}
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
const rest = document.createTextNode(val.substr(pos + text.length));
parent.insertBefore(span, parent.insertBefore(rest, node.nextSibling));
node.nodeValue = val.substr(0, pos);
/* There may be more occurrences of search term in this node. So call this
* function recursively on the remaining fragment.
*/
_highlight(rest, addItems, text, className);
if (isInSVG) {
const rect = document.createElementNS(
"http://www.w3.org/2000/svg",
"rect",
);
const bbox = parent.getBBox();
rect.x.baseVal.value = bbox.x;
rect.y.baseVal.value = bbox.y;
rect.width.baseVal.value = bbox.width;
rect.height.baseVal.value = bbox.height;
rect.setAttribute("class", className);
addItems.push({ parent: parent, target: rect });
}
}
} else if (node.matches && !node.matches("button, select, textarea")) {
node.childNodes.forEach((el) => _highlight(el, addItems, text, className));
}
};
const _highlightText = (thisNode, text, className) => {
let addItems = [];
_highlight(thisNode, addItems, text, className);
addItems.forEach((obj) =>
obj.parent.insertAdjacentElement("beforebegin", obj.target),
);
};
/**
* Small JavaScript module for the documentation.
*/
const SphinxHighlight = {
/**
* highlight the search words provided in localstorage in the text
*/
highlightSearchWords: () => {
if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight
// get and clear terms from localstorage
const url = new URL(window.location);
const highlight =
localStorage.getItem("sphinx_highlight_terms")
|| url.searchParams.get("highlight")
|| "";
localStorage.removeItem("sphinx_highlight_terms");
// Update history only if '?highlight' is present; otherwise it
// clears text fragments (not set in window.location by the browser)
if (url.searchParams.has("highlight")) {
url.searchParams.delete("highlight");
window.history.replaceState({}, "", url);
}
// get individual terms from highlight string
const terms = highlight
.toLowerCase()
.split(/\s+/)
.filter((x) => x);
if (terms.length === 0) return; // nothing to do
// There should never be more than one element matching "div.body"
const divBody = document.querySelectorAll("div.body");
const body = divBody.length ? divBody[0] : document.querySelector("body");
window.setTimeout(() => {
terms.forEach((term) => _highlightText(body, term, "highlighted"));
}, 10);
const searchBox = document.getElementById("searchbox");
if (searchBox === null) return;
searchBox.appendChild(
document
.createRange()
.createContextualFragment(
'<p class="highlight-link">'
+ '<a href="javascript:SphinxHighlight.hideSearchWords()">'
+ _("Hide Search Matches")
+ "</a></p>",
),
);
},
/**
* helper function to hide the search marks again
*/
hideSearchWords: () => {
document
.querySelectorAll("#searchbox .highlight-link")
.forEach((el) => el.remove());
document
.querySelectorAll("span.highlighted")
.forEach((el) => el.classList.remove("highlighted"));
localStorage.removeItem("sphinx_highlight_terms");
},
initEscapeListener: () => {
// only install a listener if it is really needed
if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return;
document.addEventListener("keydown", (event) => {
// bail for input elements
if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName))
return;
// bail with special keys
if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey)
return;
if (
DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
&& event.key === "Escape"
) {
SphinxHighlight.hideSearchWords();
event.preventDefault();
}
});
},
};
_ready(() => {
/* Do not call highlightSearchWords() when we are on the search page.
* It will highlight words from the *previous* search query.
*/
if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords();
SphinxHighlight.initEscapeListener();
});
Binary file not shown.

After

Width:  |  Height:  |  Size: 513 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 995 KiB

+967
View File
@@ -0,0 +1,967 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta content="tzst CLI API - Command-line interface functions and utilities for tar.zst archive operations" name="description" />
<meta content="tzst CLI API, command line interface, Python CLI, tar.zst commands" name="keywords" />
<meta content="tzst CLI API Reference" name="og:title" />
<meta content="CLI API documentation for tzst - Command-line interface functions and utilities" name="og:description" />
<meta content="tzst CLI API Reference" name="twitter:title" />
<meta content="CLI API documentation for tzst - Command-line interface functions and utilities" name="twitter:description" />
<meta content="website" name="og:type" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="og:image" />
<meta content="https://tzst.xi-xu.me/" name="og:url" />
<meta content="summary_large_image" name="twitter:card" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="twitter:image" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>CLI API &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/api/cli.html" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=3b3401d5"></script>
<script src="../_static/doctools.js?v=fd6eb6e6"></script>
<script src="../_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="../_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="../_static/opensearch.xml"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Exceptions API" href="exceptions.html" />
<link rel="prev" title="Core API" href="core.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "CLI API",
"item": "https://tzst.xi-xu.me/api/cli.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/api/cli.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="../index.html" class="icon icon-home">
tzst
<img src="../_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">API Reference</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="core.html">Core API</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">CLI API</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#overview">Overview</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#core-commands">Core Commands</a></li>
<li class="toctree-l4"><a class="reference internal" href="#key-features">Key Features</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#main-functions">Main Functions</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#main">main</a></li>
<li class="toctree-l4"><a class="reference internal" href="#create-parser">create_parser</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#command-handlers">Command Handlers</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#archive-creation-commands">Archive Creation Commands</a></li>
<li class="toctree-l4"><a class="reference internal" href="#extraction-commands">Extraction Commands</a></li>
<li class="toctree-l4"><a class="reference internal" href="#management-commands">Management Commands</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#utility-functions">Utility Functions</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#print-banner">print_banner</a></li>
<li class="toctree-l4"><a class="reference internal" href="#format-size">format_size</a></li>
<li class="toctree-l4"><a class="reference internal" href="#validate-compression-level">validate_compression_level</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#interactive-features">Interactive Features</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#conflict-resolution-options">Conflict Resolution Options</a></li>
<li class="toctree-l4"><a class="reference internal" href="#security-considerations">Security Considerations</a></li>
<li class="toctree-l4"><a class="reference internal" href="#performance-options">Performance Options</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html">Exceptions API</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#key-features">Key Features</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="index.html">API Reference</a></li>
<li class="breadcrumb-item active">CLI API</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/api/cli.md" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="cli-api">
<h1>CLI API<a class="headerlink" href="#cli-api" title="Link to this heading"></a></h1>
<p>The command-line interface module provides comprehensive functionality for the tzst CLI tool, including argument parsing, command execution, and interactive features.</p>
<p>Command-line interface for tzst.</p>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">cmd_add</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#cmd_add"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Command handler for creating/adding to archives.</p>
<p>Processes the ‘add’, ‘create’, or ‘a’ CLI commands to create new tzst archives
with the specified files and directories. Uses atomic file operations by
default to ensure data integrity.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>args</strong> – Parsed command line arguments containing:
- archive (str): Path to the archive file to create
- files (list[str]): List of files/directories to add
- compression_level (int, optional): Compression level 1-22
- no_atomic (bool, optional): Disable atomic file operations</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code (0 for success, non-zero for failure)</dt><dd><ul class="simple">
<li><p>0: Success</p></li>
<li><p>1: File not found, invalid parameters, or archive operation failed</p></li>
<li><p>130: Operation interrupted by user (Ctrl+C)</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This function uses atomic file operations by default, creating the
archive in a temporary file first, then atomically moving it to the
final location to prevent incomplete archives.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="core.html#tzst.create_archive" title="tzst.create_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">tzst.create_archive()</span></code></a>: The underlying function for archive creation
<code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.add()</span></code>: The core method for adding files to archives</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">cmd_extract_flat</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#cmd_extract_flat"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Command handler for flat extraction without directory structure.</p>
<p>Processes the ‘extract-flat’ or ‘e’ CLI commands to extract files from
tzst archives without preserving directory structure (all files extracted
to a single directory).</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>args</strong> – Parsed command line arguments containing:
- archive (str): Path to the archive file to extract
- output (str, optional): Output directory path
- files (list[str], optional): Specific files to extract
- streaming (bool, optional): Use streaming mode for large archives
- filter (str, optional): Security filter (‘data’, ‘tar’, ‘fully_trusted’)</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code (0 for success, non-zero for failure)</dt><dd><ul class="simple">
<li><p>0: Success</p></li>
<li><p>1: File not found, decompression failed, or archive operation failed</p></li>
<li><p>130: Operation interrupted by user (Ctrl+C)</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Flat extraction may cause filename conflicts if multiple files have
the same name but are in different directories within the archive.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="core.html#tzst.extract_archive" title="tzst.extract_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">tzst.extract_archive()</span></code></a>: The underlying function for extraction
<code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.extract()</span></code>: The core method for extracting from archives
<code class="xref py py-func docutils literal notranslate"><span class="pre">cmd_extract_full()</span></code>: For extraction with directory structure</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">cmd_extract_full</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#cmd_extract_full"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Command handler for extracting archives with full directory structure.</p>
<p>Processes the ‘extract’ or ‘x’ CLI commands to extract files from tzst
archives while preserving the original directory structure.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>args</strong> – Parsed command line arguments containing:
- archive (str): Path to the archive file to extract
- output (str, optional): Output directory path
- files (list[str], optional): Specific files to extract
- streaming (bool, optional): Use streaming mode for large archives
- filter (str, optional): Security filter (‘data’, ‘tar’, ‘fully_trusted’)</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code (0 for success, non-zero for failure)</dt><dd><ul class="simple">
<li><p>0: Success</p></li>
<li><p>1: File not found, decompression failed, or archive operation failed</p></li>
<li><p>130: Operation interrupted by user (Ctrl+C)</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Uses the ‘data’ security filter by default for safe extraction from
untrusted sources. Streaming mode is recommended for archives &gt; 100MB.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="core.html#tzst.extract_archive" title="tzst.extract_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">tzst.extract_archive()</span></code></a>: The underlying function for extraction
<code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.extract()</span></code>: The core method for extracting from archives
<code class="xref py py-func docutils literal notranslate"><span class="pre">cmd_extract_flat()</span></code>: For flat extraction without directory structure</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">cmd_list</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#cmd_list"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Command handler for listing archive contents.</p>
<p>Processes the ‘list’ or ‘l’ CLI commands to display the contents of tzst
archives. Supports both simple and verbose listing modes.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>args</strong> – Parsed command line arguments containing:
- archive (str): Path to the archive file to list
- verbose (bool, optional): Show detailed file information
- streaming (bool, optional): Use streaming mode for large archives</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code (0 for success, non-zero for failure)</dt><dd><ul class="simple">
<li><p>0: Success</p></li>
<li><p>1: File not found, decompression failed, or archive operation failed</p></li>
<li><p>130: Operation interrupted by user (Ctrl+C)</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Verbose mode displays file permissions, sizes, modification times,
and other metadata. Streaming mode is recommended for archives &gt; 100MB.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="core.html#tzst.list_archive" title="tzst.list_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">tzst.list_archive()</span></code></a>: The underlying function for listing contents
<code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.list()</span></code>: The core method for listing archive contents</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">cmd_test</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#cmd_test"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Command handler for testing archive integrity.</p>
<p>Processes the ‘test’ or ‘t’ CLI commands to verify the integrity of tzst
archives by attempting to read all files and checking for corruption.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>args</strong> – Parsed command line arguments containing:
- archive (str): Path to the archive file to test
- streaming (bool, optional): Use streaming mode for large archives</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code (0 for success, non-zero for failure)</dt><dd><ul class="simple">
<li><p>0: Archive passed integrity test</p></li>
<li><p>1: Archive failed integrity test, file not found, or operation failed</p></li>
<li><p>130: Operation interrupted by user (Ctrl+C)</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This command verifies that the archive can be read and all files
can be decompressed without errors. Streaming mode is recommended
for archives &gt; 100MB to reduce memory usage.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="core.html#tzst.test_archive" title="tzst.test_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">tzst.test_archive()</span></code></a>: The underlying function for integrity testing
<code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.test()</span></code>: The core method for testing archive integrity</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">cmd_version</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#cmd_version"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Command handler for version display.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>Exit code (always 0)</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">create_parser</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser" title="(in Python v3.14)"><span class="pre">ArgumentParser</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#create_parser"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Create and configure the command-line argument parser.</p>
<p>Sets up the argparse ArgumentParser with all subcommands and their
respective arguments for the tzst CLI interface. Includes comprehensive
help text and command reference documentation.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>Configured parser ready for argument parsing</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p><a class="reference external" href="https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser" title="(in Python v3.14)">argparse.ArgumentParser</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The parser is configured with RawDescriptionHelpFormatter to preserve
formatting in the epilog help text, and includes detailed command
reference and security notes.</p>
</div>
<dl class="simple">
<dt>Commands Created:</dt><dd><ul class="simple">
<li><p>a, add, create: Archive creation with compression levels</p></li>
<li><p>x, extract: Full extraction with directory structure</p></li>
<li><p>e, extract-flat: Flat extraction without directories</p></li>
<li><p>l, list: Archive content listing</p></li>
<li><p>t, test: Archive integrity testing</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.cli.main" title="tzst.cli.main"><code class="xref py py-func docutils literal notranslate"><span class="pre">main()</span></code></a>: The main entry point that uses this parser</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">format_size</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#format_size"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Format file size in human-readable format.</p>
<p>Converts byte values to human-readable format using standard units
(B, KB, MB, GB, TB, PB) with appropriate decimal places.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>size</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><em>int</em></a>) – Size in bytes to format</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Formatted size string with units (e.g., “1.5 KB”, “2.3 GB”)</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)">str</a></p>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">format_size</span><span class="p">(</span><span class="mi">1024</span><span class="p">)</span>
<span class="go">' 1.0 KB'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">format_size</span><span class="p">(</span><span class="mi">1536</span><span class="p">)</span>
<span class="go">' 1.5 KB'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">format_size</span><span class="p">(</span><span class="mi">2048576</span><span class="p">)</span>
<span class="go">' 2.0 MB'</span>
</pre></div>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">argv</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.14)"><span class="pre">list</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</span></a><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#main"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Main entry point for the tzst command-line interface.</p>
<p>Processes command-line arguments and dispatches to appropriate command
handlers. Displays the version banner and provides error handling for
the overall CLI execution.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>argv</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.14)"><em>list</em></a><em>[</em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><em>str</em></a><em>] </em><em>| </em><em>None</em><em>, </em><em>optional</em>) – Command line arguments to parse.
If None, uses sys.argv. Defaults to None.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code for the program</dt><dd><ul class="simple">
<li><p>0: Success</p></li>
<li><p>1: Invalid compression level, filter, or command error</p></li>
<li><p>2: Argument parsing error (help, unknown options)</p></li>
<li><p>Other codes: Specific to individual command handlers</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This function serves as the console script entry point defined in
pyproject.toml. It displays the version banner before executing
any commands.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.cli.create_parser" title="tzst.cli.create_parser"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_parser()</span></code></a>: Creates the argument parser used by this function</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">print_banner</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#print_banner"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Print the version and copyright banner.</p>
<p>Displays the tzst version number and copyright information to stdout.
Used as a header for CLI operations.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>None</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">validate_compression_level</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#validate_compression_level"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Validate and return compression level.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>value</strong> – String value from command line</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Valid compression level (1-22)</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
<dt class="field-even">Raises<span class="colon">:</span></dt>
<dd class="field-even"><p><a class="reference external" href="https://docs.python.org/3/library/argparse.html#argparse.ArgumentTypeError" title="(in Python v3.14)"><strong>argparse.ArgumentTypeError</strong></a> – If value is not a valid compression level</p>
</dd>
</dl>
</dd></dl>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Link to this heading"></a></h2>
<p>The tzst CLI provides a powerful command-line interface for archive operations with intuitive commands and comprehensive options. The interface is designed for both interactive use and scripting, with robust error handling and user-friendly output.</p>
<section id="core-commands">
<h3>Core Commands<a class="headerlink" href="#core-commands" title="Link to this heading"></a></h3>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Command</p></th>
<th class="head"><p>Aliases</p></th>
<th class="head"><p>Description</p></th>
<th class="head"><p>Streaming Support</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">a</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">add</span></code>, <code class="docutils literal notranslate"><span class="pre">create</span></code></p></td>
<td><p>Create or add to archive</p></td>
<td><p>N/A</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">extract</span></code></p></td>
<td><p>Extract with full paths</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">e</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">extract-flat</span></code></p></td>
<td><p>Extract without directory structure</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">l</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">list</span></code></p></td>
<td><p>List archive contents</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">test</span></code></p></td>
<td><p>Test archive integrity</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
</tbody>
</table>
</section>
<section id="key-features">
<h3>Key Features<a class="headerlink" href="#key-features" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Intuitive Commands</strong>: Simple, memorable command aliases (a, x, e, l, t)</p></li>
<li><p><strong>Streaming Support</strong>: Memory-efficient processing for large archives</p></li>
<li><p><strong>Interactive Conflict Resolution</strong>: User-friendly prompts for handling file conflicts</p></li>
<li><p><strong>Comprehensive Options</strong>: Fine-grained control over compression, extraction, and security</p></li>
<li><p><strong>Cross-Platform</strong>: Consistent behavior across Windows, macOS, and Linux</p></li>
</ul>
</section>
</section>
<section id="main-functions">
<h2>Main Functions<a class="headerlink" href="#main-functions" title="Link to this heading"></a></h2>
<section id="main">
<h3>main<a class="headerlink" href="#main" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.cli.main">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">argv</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.14)"><span class="pre">list</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</span></a><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#main"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.cli.main" title="Link to this definition"></a></dt>
<dd><p>Main entry point for the tzst command-line interface.</p>
<p>Processes command-line arguments and dispatches to appropriate command
handlers. Displays the version banner and provides error handling for
the overall CLI execution.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>argv</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.14)"><em>list</em></a><em>[</em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><em>str</em></a><em>] </em><em>| </em><em>None</em><em>, </em><em>optional</em>) – Command line arguments to parse.
If None, uses sys.argv. Defaults to None.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code for the program</dt><dd><ul class="simple">
<li><p>0: Success</p></li>
<li><p>1: Invalid compression level, filter, or command error</p></li>
<li><p>2: Argument parsing error (help, unknown options)</p></li>
<li><p>Other codes: Specific to individual command handlers</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This function serves as the console script entry point defined in
pyproject.toml. It displays the version banner before executing
any commands.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.cli.create_parser" title="tzst.cli.create_parser"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_parser()</span></code></a>: Creates the argument parser used by this function</p>
</div>
</dd></dl>
<p>The main entry point for the CLI application. Handles argument parsing, command execution, and comprehensive error reporting.</p>
<p><strong>Key Features:</strong></p>
<ul class="simple">
<li><p>Robust argument validation and error handling</p></li>
<li><p>Support for all archive operations</p></li>
<li><p>Consistent exit codes for scripting</p></li>
<li><p>User-friendly error messages</p></li>
</ul>
<p><strong>Exit Codes:</strong></p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">0</span></code>: Success</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">1</span></code>: General error (file not found, archive corruption, etc.)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">2</span></code>: Argument parsing error</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">130</span></code>: Interrupted by user (Ctrl+C)</p></li>
</ul>
</section>
<section id="create-parser">
<h3>create_parser<a class="headerlink" href="#create-parser" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.cli.create_parser">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">create_parser</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser" title="(in Python v3.14)"><span class="pre">ArgumentParser</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#create_parser"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.cli.create_parser" title="Link to this definition"></a></dt>
<dd><p>Create and configure the command-line argument parser.</p>
<p>Sets up the argparse ArgumentParser with all subcommands and their
respective arguments for the tzst CLI interface. Includes comprehensive
help text and command reference documentation.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>Configured parser ready for argument parsing</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p><a class="reference external" href="https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser" title="(in Python v3.14)">argparse.ArgumentParser</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The parser is configured with RawDescriptionHelpFormatter to preserve
formatting in the epilog help text, and includes detailed command
reference and security notes.</p>
</div>
<dl class="simple">
<dt>Commands Created:</dt><dd><ul class="simple">
<li><p>a, add, create: Archive creation with compression levels</p></li>
<li><p>x, extract: Full extraction with directory structure</p></li>
<li><p>e, extract-flat: Flat extraction without directories</p></li>
<li><p>l, list: Archive content listing</p></li>
<li><p>t, test: Archive integrity testing</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.cli.main" title="tzst.cli.main"><code class="xref py py-func docutils literal notranslate"><span class="pre">main()</span></code></a>: The main entry point that uses this parser</p>
</div>
</dd></dl>
<p>Creates and configures the comprehensive argument parser for the CLI interface.</p>
<p><strong>Supported Arguments:</strong></p>
<ul class="simple">
<li><p><strong>Global</strong>: <code class="docutils literal notranslate"><span class="pre">--version</span></code>, <code class="docutils literal notranslate"><span class="pre">--help</span></code></p></li>
<li><p><strong>Archive Creation</strong>: <code class="docutils literal notranslate"><span class="pre">-l/--level</span></code>, <code class="docutils literal notranslate"><span class="pre">--no-atomic</span></code></p></li>
<li><p><strong>Extraction</strong>: <code class="docutils literal notranslate"><span class="pre">-o/--output</span></code>, <code class="docutils literal notranslate"><span class="pre">--streaming</span></code>, <code class="docutils literal notranslate"><span class="pre">--filter</span></code>, <code class="docutils literal notranslate"><span class="pre">--conflict-resolution</span></code></p></li>
<li><p><strong>Listing</strong>: <code class="docutils literal notranslate"><span class="pre">-v/--verbose</span></code>, <code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></li>
<li><p><strong>Testing</strong>: <code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></li>
</ul>
</section>
</section>
<section id="command-handlers">
<h2>Command Handlers<a class="headerlink" href="#command-handlers" title="Link to this heading"></a></h2>
<p>The CLI implements dedicated command handlers for each operation, providing specialized functionality and error handling.</p>
<section id="archive-creation-commands">
<h3>Archive Creation Commands<a class="headerlink" href="#archive-creation-commands" title="Link to this heading"></a></h3>
<section id="cmd-add">
<h4>cmd_add<a class="headerlink" href="#cmd-add" title="Link to this heading"></a></h4>
<p>Creates new archives from files and directories with configurable compression and atomic operations.</p>
<p><strong>Features:</strong></p>
<ul class="simple">
<li><p>Configurable compression levels (1-22)</p></li>
<li><p>Atomic file operations (default) for safe creation</p></li>
<li><p>Recursive directory processing</p></li>
<li><p>Path validation and normalization</p></li>
</ul>
<p><strong>Usage Examples:</strong></p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Basic archive creation</span>
tzst<span class="w"> </span>a<span class="w"> </span>backup.tzst<span class="w"> </span>documents/<span class="w"> </span>photos/
<span class="c1"># High compression with atomic disabled</span>
tzst<span class="w"> </span>a<span class="w"> </span>backup.tzst<span class="w"> </span>files/<span class="w"> </span>-l<span class="w"> </span><span class="m">15</span><span class="w"> </span>--no-atomic
</pre></div>
</div>
</section>
</section>
<section id="extraction-commands">
<h3>Extraction Commands<a class="headerlink" href="#extraction-commands" title="Link to this heading"></a></h3>
<section id="cmd-extract-full">
<h4>cmd_extract_full<a class="headerlink" href="#cmd-extract-full" title="Link to this heading"></a></h4>
<p>Extracts archives preserving complete directory structure with advanced conflict resolution.</p>
<p><strong>Features:</strong></p>
<ul class="simple">
<li><p>Preserves full directory paths</p></li>
<li><p>Multiple conflict resolution strategies</p></li>
<li><p>Security filters for safe extraction</p></li>
<li><p>Selective file extraction</p></li>
<li><p>Streaming mode for large archives</p></li>
</ul>
</section>
<section id="cmd-extract-flat">
<h4>cmd_extract_flat<a class="headerlink" href="#cmd-extract-flat" title="Link to this heading"></a></h4>
<p>Extracts archives flattening all files to a single directory, useful for consolidating files.</p>
<p><strong>Features:</strong></p>
<ul class="simple">
<li><p>Flattens directory structure</p></li>
<li><p>Automatic conflict resolution for filename collisions</p></li>
<li><p>Preserves file content while simplifying structure</p></li>
<li><p>Same security and streaming features as full extraction</p></li>
</ul>
</section>
</section>
<section id="management-commands">
<h3>Management Commands<a class="headerlink" href="#management-commands" title="Link to this heading"></a></h3>
<section id="cmd-list">
<h4>cmd_list<a class="headerlink" href="#cmd-list" title="Link to this heading"></a></h4>
<p>Lists archive contents with optional detailed information and streaming support.</p>
<p><strong>Features:</strong></p>
<ul class="simple">
<li><p>Simple or verbose listing modes</p></li>
<li><p>Human-readable file sizes</p></li>
<li><p>Modification timestamps</p></li>
<li><p>Streaming mode for memory efficiency</p></li>
</ul>
</section>
<section id="cmd-test">
<h4>cmd_test<a class="headerlink" href="#cmd-test" title="Link to this heading"></a></h4>
<p>Tests archive integrity and validity with comprehensive error reporting.</p>
<p><strong>Features:</strong></p>
<ul class="simple">
<li><p>Complete archive validation</p></li>
<li><p>Streaming mode support</p></li>
<li><p>Detailed error reporting</p></li>
<li><p>Exit codes for automated testing</p></li>
</ul>
</section>
<section id="cmd-version">
<h4>cmd_version<a class="headerlink" href="#cmd-version" title="Link to this heading"></a></h4>
<p>Displays version information and system details.</p>
</section>
</section>
</section>
<section id="utility-functions">
<h2>Utility Functions<a class="headerlink" href="#utility-functions" title="Link to this heading"></a></h2>
<section id="print-banner">
<h3>print_banner<a class="headerlink" href="#print-banner" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.cli.print_banner">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">print_banner</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#print_banner"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.cli.print_banner" title="Link to this definition"></a></dt>
<dd><p>Print the version and copyright banner.</p>
<p>Displays the tzst version number and copyright information to stdout.
Used as a header for CLI operations.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>None</p>
</dd>
</dl>
</dd></dl>
<p>Displays the application banner with version and copyright information.</p>
</section>
<section id="format-size">
<h3>format_size<a class="headerlink" href="#format-size" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.cli.format_size">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">format_size</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#format_size"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.cli.format_size" title="Link to this definition"></a></dt>
<dd><p>Format file size in human-readable format.</p>
<p>Converts byte values to human-readable format using standard units
(B, KB, MB, GB, TB, PB) with appropriate decimal places.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>size</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><em>int</em></a>) – Size in bytes to format</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Formatted size string with units (e.g., “1.5 KB”, “2.3 GB”)</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)">str</a></p>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">format_size</span><span class="p">(</span><span class="mi">1024</span><span class="p">)</span>
<span class="go">' 1.0 KB'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">format_size</span><span class="p">(</span><span class="mi">1536</span><span class="p">)</span>
<span class="go">' 1.5 KB'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">format_size</span><span class="p">(</span><span class="mi">2048576</span><span class="p">)</span>
<span class="go">' 2.0 MB'</span>
</pre></div>
</div>
</dd></dl>
<p>Formats file sizes in a human-readable format (bytes, KB, MB, GB).</p>
</section>
<section id="validate-compression-level">
<h3>validate_compression_level<a class="headerlink" href="#validate-compression-level" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.cli.validate_compression_level">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">validate_compression_level</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#validate_compression_level"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.cli.validate_compression_level" title="Link to this definition"></a></dt>
<dd><p>Validate and return compression level.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>value</strong> – String value from command line</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Valid compression level (1-22)</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
<dt class="field-even">Raises<span class="colon">:</span></dt>
<dd class="field-even"><p><a class="reference external" href="https://docs.python.org/3/library/argparse.html#argparse.ArgumentTypeError" title="(in Python v3.14)"><strong>argparse.ArgumentTypeError</strong></a> – If value is not a valid compression level</p>
</dd>
</dl>
</dd></dl>
<p>Validates compression level arguments and converts them to integers.</p>
</section>
</section>
<section id="interactive-features">
<h2>Interactive Features<a class="headerlink" href="#interactive-features" title="Link to this heading"></a></h2>
<p>The CLI includes interactive conflict resolution for file extraction conflicts, allowing users to choose how to handle existing files during extraction operations.</p>
<section id="conflict-resolution-options">
<h3>Conflict Resolution Options<a class="headerlink" href="#conflict-resolution-options" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Replace</strong>: Overwrite the existing file</p></li>
<li><p><strong>Skip</strong>: Keep the existing file, skip extraction</p></li>
<li><p><strong>Replace All</strong>: Apply replace to all subsequent conflicts</p></li>
<li><p><strong>Skip All</strong>: Apply skip to all subsequent conflicts</p></li>
<li><p><strong>Auto-rename All</strong>: Automatically rename conflicting files</p></li>
<li><p><strong>Exit</strong>: Stop extraction process</p></li>
</ul>
</section>
<section id="security-considerations">
<h3>Security Considerations<a class="headerlink" href="#security-considerations" title="Link to this heading"></a></h3>
<p>The CLI implements multiple security filters for safe extraction:</p>
<ul class="simple">
<li><p><strong><code class="docutils literal notranslate"><span class="pre">data</span></code> filter</strong> (default): Safest option, blocks potentially dangerous archive members</p></li>
<li><p><strong><code class="docutils literal notranslate"><span class="pre">tar</span></code> filter</strong>: Preserves more tar features while maintaining basic security</p></li>
<li><p><strong><code class="docutils literal notranslate"><span class="pre">fully_trusted</span></code> filter</strong>: No restrictions, use only with completely trusted archives</p></li>
</ul>
</section>
<section id="performance-options">
<h3>Performance Options<a class="headerlink" href="#performance-options" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Streaming Mode</strong>: Use <code class="docutils literal notranslate"><span class="pre">--streaming</span></code> for memory-efficient processing of large archives (&gt;100MB)</p></li>
<li><p><strong>Compression Levels</strong>: Choose from 1 (fastest) to 22 (maximum compression)</p></li>
<li><p><strong>Atomic Operations</strong>: Default behavior uses temporary files for safe archive creation</p></li>
</ul>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="core.html" class="btn btn-neutral float-left" title="Core API" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="exceptions.html" class="btn btn-neutral float-right" title="Exceptions API" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
+1032
View File
File diff suppressed because it is too large. Load diff
+577
View File
@@ -0,0 +1,577 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta content="Complete reference for tzst exception classes and error handling. Learn about TzstError, TzstArchiveError, and other custom exceptions for robust archive operations." name="description" />
<meta content="tzst exceptions, Python exceptions, error handling, TzstError, TzstArchiveError, archive errors, compression errors" name="keywords" />
<meta content="tzst Exceptions API Reference" name="og:title" />
<meta content="Complete reference for tzst exception classes and error handling. Learn about TzstError, TzstArchiveError, and other custom exceptions for robust archive operations." name="og:description" />
<meta content="website" name="og:type" />
<meta content="tzst Exceptions API Reference" name="twitter:title" />
<meta content="Complete reference for tzst exception classes and error handling. Learn about TzstError, TzstArchiveError, and other custom exceptions for robust archive operations." name="twitter:description" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="og:image" />
<meta content="https://tzst.xi-xu.me/" name="og:url" />
<meta content="summary_large_image" name="twitter:card" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="twitter:image" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Exceptions API &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/api/exceptions.html" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=3b3401d5"></script>
<script src="../_static/doctools.js?v=fd6eb6e6"></script>
<script src="../_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="../_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="../_static/opensearch.xml"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Development Guide" href="../development.html" />
<link rel="prev" title="CLI API" href="cli.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Exceptions API",
"item": "https://tzst.xi-xu.me/api/exceptions.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/api/exceptions.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="../index.html" class="icon icon-home">
tzst
<img src="../_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">API Reference</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="core.html">Core API</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html">CLI API</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Exceptions API</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#overview">Overview</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#exception-hierarchy">Exception Hierarchy</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#exception-classes">Exception Classes</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#base-exception">Base Exception</a></li>
<li class="toctree-l4"><a class="reference internal" href="#archive-operation-exceptions">Archive Operation Exceptions</a></li>
<li class="toctree-l4"><a class="reference internal" href="#compression-exceptions">Compression Exceptions</a></li>
<li class="toctree-l4"><a class="reference internal" href="#decompression-exceptions">Decompression Exceptions</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#error-handling-best-practices">Error Handling Best Practices</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#basic-error-handling">Basic Error Handling</a></li>
<li class="toctree-l4"><a class="reference internal" href="#comprehensive-error-handling">Comprehensive Error Handling</a></li>
<li class="toctree-l4"><a class="reference internal" href="#specific-exception-handling">Specific Exception Handling</a></li>
<li class="toctree-l4"><a class="reference internal" href="#logging-integration">Logging Integration</a></li>
<li class="toctree-l4"><a class="reference internal" href="#error-recovery-patterns">Error Recovery Patterns</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="index.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#key-features">Key Features</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="index.html">API Reference</a></li>
<li class="breadcrumb-item active">Exceptions API</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/api/exceptions.md" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="exceptions-api">
<h1>Exceptions API<a class="headerlink" href="#exceptions-api" title="Link to this heading"></a></h1>
<p>Custom exception classes used by tzst for comprehensive error handling and debugging.</p>
<p>Exception classes for tzst.</p>
<dl class="py exception">
<dt class="sig sig-object py">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.exceptions.</span></span><span class="sig-name descname"><span class="pre">TzstArchiveError</span></span><a class="reference internal" href="../_modules/tzst/exceptions.html#TzstArchiveError"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Bases: <a class="reference internal" href="#tzst.exceptions.TzstError" title="tzst.exceptions.TzstError"><code class="xref py py-class docutils literal notranslate"><span class="pre">TzstError</span></code></a></p>
<p>Exception raised when archive operations fail.</p>
<p>This can occur when:
- Archive file cannot be opened or created
- File permissions prevent archive access
- Archive structure is malformed
- Tar operations fail within the archive
- Atomic file operations fail during creation</p>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.exceptions.</span></span><span class="sig-name descname"><span class="pre">TzstCompressionError</span></span><a class="reference internal" href="../_modules/tzst/exceptions.html#TzstCompressionError"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Bases: <a class="reference internal" href="#tzst.exceptions.TzstError" title="tzst.exceptions.TzstError"><code class="xref py py-class docutils literal notranslate"><span class="pre">TzstError</span></code></a></p>
<p>Exception raised when compression operations fail.</p>
<p>This can occur when:
- Invalid compression level is specified
- Disk space is insufficient during compression
- Input data cannot be compressed due to corruption
- Zstandard compression encounters an internal error</p>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.exceptions.</span></span><span class="sig-name descname"><span class="pre">TzstDecompressionError</span></span><a class="reference internal" href="../_modules/tzst/exceptions.html#TzstDecompressionError"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Bases: <a class="reference internal" href="#tzst.exceptions.TzstError" title="tzst.exceptions.TzstError"><code class="xref py py-class docutils literal notranslate"><span class="pre">TzstError</span></code></a></p>
<p>Exception raised when decompression operations fail.</p>
<p>This can occur when:
- Archive file is corrupted or incomplete
- Archive was not created with zstandard compression
- Decompression buffer overflows or underflows
- Archive format is invalid or unsupported</p>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.exceptions.</span></span><span class="sig-name descname"><span class="pre">TzstError</span></span><a class="reference internal" href="../_modules/tzst/exceptions.html#TzstError"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/exceptions.html#Exception" title="(in Python v3.14)"><code class="xref py py-class docutils literal notranslate"><span class="pre">Exception</span></code></a></p>
<p>Base exception for all tzst operations.</p>
<p>This is the parent class for all tzst-specific exceptions.
Catch this to handle any tzst-related error.</p>
</dd></dl>
<dl class="py exception">
<dt class="sig sig-object py">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.exceptions.</span></span><span class="sig-name descname"><span class="pre">TzstFileNotFoundError</span></span><a class="reference internal" href="../_modules/tzst/exceptions.html#TzstFileNotFoundError"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Bases: <a class="reference internal" href="#tzst.exceptions.TzstError" title="tzst.exceptions.TzstError"><code class="xref py py-class docutils literal notranslate"><span class="pre">TzstError</span></code></a>, <a class="reference external" href="https://docs.python.org/3/library/exceptions.html#FileNotFoundError" title="(in Python v3.14)"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileNotFoundError</span></code></a></p>
<p>Exception raised when a required file is not found.</p>
<p>This can occur when:
- Archive file does not exist for reading operations
- Input files for archiving do not exist
- Output directory cannot be created for extraction
- Temporary files cannot be created during atomic operations</p>
<p>Inherits from both TzstError and FileNotFoundError for compatibility
with standard Python exception handling patterns.</p>
</dd></dl>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Link to this heading"></a></h2>
<p>The tzst library provides a comprehensive hierarchy of exceptions to help identify and handle different types of errors that may occur during archive operations. All exceptions inherit from the base <code class="docutils literal notranslate"><span class="pre">TzstError</span></code> class, making it easy to catch all tzst-related errors with a single exception handler.</p>
<section id="exception-hierarchy">
<h3>Exception Hierarchy<a class="headerlink" href="#exception-hierarchy" title="Link to this heading"></a></h3>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>TzstError (base exception)
├── TzstArchiveError (archive operation failures)
├── TzstCompressionError (compression failures)
└── TzstDecompressionError (decompression failures)
</pre></div>
</div>
</section>
</section>
<section id="exception-classes">
<h2>Exception Classes<a class="headerlink" href="#exception-classes" title="Link to this heading"></a></h2>
<section id="base-exception">
<h3>Base Exception<a class="headerlink" href="#base-exception" title="Link to this heading"></a></h3>
<section id="tzsterror">
<h4>TzstError<a class="headerlink" href="#tzsterror" title="Link to this heading"></a></h4>
<dl class="py exception">
<dt class="sig sig-object py" id="tzst.exceptions.TzstError">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.exceptions.</span></span><span class="sig-name descname"><span class="pre">TzstError</span></span><a class="reference internal" href="../_modules/tzst/exceptions.html#TzstError"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.exceptions.TzstError" title="Link to this definition"></a></dt>
<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/exceptions.html#Exception" title="(in Python v3.14)"><code class="xref py py-class docutils literal notranslate"><span class="pre">Exception</span></code></a></p>
<p>Base exception for all tzst operations.</p>
<p>This is the parent class for all tzst-specific exceptions.
Catch this to handle any tzst-related error.</p>
</dd></dl>
<p>The base exception class for all tzst operations. Catch this exception to handle any tzst-related error in your application.</p>
<p><strong>Usage:</strong></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span><span class="p">,</span> <span class="n">TzstError</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"files/"</span><span class="p">])</span>
<span class="k">except</span> <span class="n">TzstError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"tzst operation failed: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
</pre></div>
</div>
</section>
</section>
<section id="archive-operation-exceptions">
<h3>Archive Operation Exceptions<a class="headerlink" href="#archive-operation-exceptions" title="Link to this heading"></a></h3>
<section id="tzstarchiveerror">
<h4>TzstArchiveError<a class="headerlink" href="#tzstarchiveerror" title="Link to this heading"></a></h4>
<dl class="py exception">
<dt class="sig sig-object py" id="tzst.exceptions.TzstArchiveError">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.exceptions.</span></span><span class="sig-name descname"><span class="pre">TzstArchiveError</span></span><a class="reference internal" href="../_modules/tzst/exceptions.html#TzstArchiveError"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.exceptions.TzstArchiveError" title="Link to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="#tzst.exceptions.TzstError" title="tzst.exceptions.TzstError"><code class="xref py py-class docutils literal notranslate"><span class="pre">TzstError</span></code></a></p>
<p>Exception raised when archive operations fail.</p>
<p>This can occur when:
- Archive file cannot be opened or created
- File permissions prevent archive access
- Archive structure is malformed
- Tar operations fail within the archive
- Atomic file operations fail during creation</p>
</dd></dl>
<p>Raised when archive operations fail, such as:</p>
<ul class="simple">
<li><p>Archive file cannot be opened or created</p></li>
<li><p>File permissions prevent archive access</p></li>
<li><p>Archive structure is malformed</p></li>
<li><p>Tar operations fail within the archive</p></li>
<li><p>Atomic file operations fail during creation</p></li>
</ul>
<p><strong>Common Scenarios:</strong></p>
<ul class="simple">
<li><p>Invalid archive file path</p></li>
<li><p>Insufficient disk space</p></li>
<li><p>File permission errors</p></li>
<li><p>Corrupt archive structure</p></li>
</ul>
</section>
</section>
<section id="compression-exceptions">
<h3>Compression Exceptions<a class="headerlink" href="#compression-exceptions" title="Link to this heading"></a></h3>
<section id="tzstcompressionerror">
<h4>TzstCompressionError<a class="headerlink" href="#tzstcompressionerror" title="Link to this heading"></a></h4>
<dl class="py exception">
<dt class="sig sig-object py" id="tzst.exceptions.TzstCompressionError">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.exceptions.</span></span><span class="sig-name descname"><span class="pre">TzstCompressionError</span></span><a class="reference internal" href="../_modules/tzst/exceptions.html#TzstCompressionError"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.exceptions.TzstCompressionError" title="Link to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="#tzst.exceptions.TzstError" title="tzst.exceptions.TzstError"><code class="xref py py-class docutils literal notranslate"><span class="pre">TzstError</span></code></a></p>
<p>Exception raised when compression operations fail.</p>
<p>This can occur when:
- Invalid compression level is specified
- Disk space is insufficient during compression
- Input data cannot be compressed due to corruption
- Zstandard compression encounters an internal error</p>
</dd></dl>
<p>Raised when compression operations fail, including:</p>
<ul class="simple">
<li><p>Invalid compression level is specified</p></li>
<li><p>Disk space is insufficient during compression</p></li>
<li><p>Input data cannot be compressed due to corruption</p></li>
<li><p>Zstandard compression encounters an internal error</p></li>
</ul>
<p><strong>Common Scenarios:</strong></p>
<ul class="simple">
<li><p>Compression level out of range (1-22)</p></li>
<li><p>Insufficient disk space during compression</p></li>
<li><p>Source file corruption</p></li>
<li><p>Zstandard library errors</p></li>
</ul>
</section>
</section>
<section id="decompression-exceptions">
<h3>Decompression Exceptions<a class="headerlink" href="#decompression-exceptions" title="Link to this heading"></a></h3>
<section id="tzstdecompressionerror">
<h4>TzstDecompressionError<a class="headerlink" href="#tzstdecompressionerror" title="Link to this heading"></a></h4>
<dl class="py exception">
<dt class="sig sig-object py" id="tzst.exceptions.TzstDecompressionError">
<span class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.exceptions.</span></span><span class="sig-name descname"><span class="pre">TzstDecompressionError</span></span><a class="reference internal" href="../_modules/tzst/exceptions.html#TzstDecompressionError"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.exceptions.TzstDecompressionError" title="Link to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="#tzst.exceptions.TzstError" title="tzst.exceptions.TzstError"><code class="xref py py-class docutils literal notranslate"><span class="pre">TzstError</span></code></a></p>
<p>Exception raised when decompression operations fail.</p>
<p>This can occur when:
- Archive file is corrupted or incomplete
- Archive was not created with zstandard compression
- Decompression buffer overflows or underflows
- Archive format is invalid or unsupported</p>
</dd></dl>
<p>Raised when decompression operations fail, such as:</p>
<ul class="simple">
<li><p>Archive file is corrupted or incomplete</p></li>
<li><p>Archive was not created with zstandard compression</p></li>
<li><p>Decompression buffer overflows or underflows</p></li>
<li><p>Archive format is invalid or unsupported</p></li>
</ul>
<p><strong>Common Scenarios:</strong></p>
<ul class="simple">
<li><p>Corrupted or truncated archive files</p></li>
<li><p>Non-zstandard compressed archives</p></li>
<li><p>Invalid tar structure within archive</p></li>
<li><p>Archive format version mismatches</p></li>
</ul>
</section>
</section>
</section>
<section id="error-handling-best-practices">
<h2>Error Handling Best Practices<a class="headerlink" href="#error-handling-best-practices" title="Link to this heading"></a></h2>
<section id="basic-error-handling">
<h3>Basic Error Handling<a class="headerlink" href="#basic-error-handling" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span><span class="p">,</span> <span class="n">TzstArchiveError</span><span class="p">,</span> <span class="n">TzstCompressionError</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"documents/"</span><span class="p">])</span>
<span class="k">except</span> <span class="n">TzstCompressionError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Compression failed: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">except</span> <span class="n">TzstArchiveError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive operation failed: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="comprehensive-error-handling">
<h3>Comprehensive Error Handling<a class="headerlink" href="#comprehensive-error-handling" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">extract_archive</span><span class="p">,</span> <span class="n">TzstError</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="s2">"restore/"</span><span class="p">)</span>
<span class="k">except</span> <span class="n">TzstError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="c1"># Catch any tzst-related error</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Operation failed: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="c1"># Perform cleanup or fallback operations</span>
</pre></div>
</div>
</section>
<section id="specific-exception-handling">
<h3>Specific Exception Handling<a class="headerlink" href="#specific-exception-handling" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">TzstArchive</span><span class="p">,</span> <span class="n">TzstDecompressionError</span><span class="p">,</span> <span class="n">TzstArchiveError</span>
<span class="k">def</span><span class="w"> </span><span class="nf">safe_extract</span><span class="p">(</span><span class="n">archive_path</span><span class="p">,</span> <span class="n">output_dir</span><span class="p">):</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="n">archive_path</span><span class="p">,</span> <span class="s2">"r"</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="c1"># Test integrity first</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">archive</span><span class="o">.</span><span class="n">test</span><span class="p">():</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"Archive integrity check failed"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="c1"># Extract files</span>
<span class="n">archive</span><span class="o">.</span><span class="n">extractall</span><span class="p">(</span><span class="n">output_dir</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">True</span>
<span class="k">except</span> <span class="n">TzstDecompressionError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive is corrupted or invalid: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="k">except</span> <span class="n">TzstArchiveError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive operation failed: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="k">except</span> <span class="ne">FileNotFoundError</span><span class="p">:</span> <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive file not found: </span><span class="si">{</span><span class="n">archive_path</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="k">except</span> <span class="ne">PermissionError</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Permission denied accessing: </span><span class="si">{</span><span class="n">archive_path</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">False</span>
</pre></div>
</div>
</section>
<section id="logging-integration">
<h3>Logging Integration<a class="headerlink" href="#logging-integration" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">logging</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">test_archive</span><span class="p">,</span> <span class="n">TzstDecompressionError</span><span class="p">,</span> <span class="n">TzstError</span>
<span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>
<span class="k">def</span><span class="w"> </span><span class="nf">verify_archive</span><span class="p">(</span><span class="n">archive_path</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""Verify archive integrity with comprehensive logging."""</span>
<span class="k">try</span><span class="p">:</span>
<span class="k">if</span> <span class="n">test_archive</span><span class="p">(</span><span class="n">archive_path</span><span class="p">):</span>
<span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive </span><span class="si">{</span><span class="n">archive_path</span><span class="si">}</span><span class="s2"> is valid"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">True</span>
<span class="k">except</span> <span class="n">TzstDecompressionError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive </span><span class="si">{</span><span class="n">archive_path</span><span class="si">}</span><span class="s2"> is corrupted: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">except</span> <span class="n">TzstError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="sa">f</span><span class="s2">"tzst error for </span><span class="si">{</span><span class="n">archive_path</span><span class="si">}</span><span class="s2">: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Unexpected error testing </span><span class="si">{</span><span class="n">archive_path</span><span class="si">}</span><span class="s2">: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">False</span>
</pre></div>
</div>
</section>
<section id="error-recovery-patterns">
<h3>Error Recovery Patterns<a class="headerlink" href="#error-recovery-patterns" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span><span class="p">,</span> <span class="n">extract_archive</span><span class="p">,</span> <span class="n">TzstError</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">pathlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">Path</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">tempfile</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">shutil</span>
<span class="k">def</span><span class="w"> </span><span class="nf">robust_backup_and_restore</span><span class="p">(</span><span class="n">source_dir</span><span class="p">,</span> <span class="n">backup_path</span><span class="p">,</span> <span class="n">restore_dir</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""Robust backup with error recovery and validation."""</span>
<span class="n">temp_backup</span> <span class="o">=</span> <span class="kc">None</span>
<span class="k">try</span><span class="p">:</span>
<span class="c1"># Create backup with temporary file for atomicity</span>
<span class="k">with</span> <span class="n">tempfile</span><span class="o">.</span><span class="n">NamedTemporaryFile</span><span class="p">(</span><span class="n">suffix</span><span class="o">=</span><span class="s1">'.tzst'</span><span class="p">,</span> <span class="n">delete</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span> <span class="k">as</span> <span class="n">temp_file</span><span class="p">:</span>
<span class="n">temp_backup</span> <span class="o">=</span> <span class="n">Path</span><span class="p">(</span><span class="n">temp_file</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="c1"># Create archive</span>
<span class="n">create_archive</span><span class="p">(</span><span class="n">temp_backup</span><span class="p">,</span> <span class="p">[</span><span class="n">source_dir</span><span class="p">],</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span>
<span class="c1"># Verify archive before moving to final location</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">test_archive</span><span class="p">(</span><span class="n">temp_backup</span><span class="p">):</span>
<span class="k">raise</span> <span class="n">TzstArchiveError</span><span class="p">(</span><span class="s2">"Created archive failed integrity check"</span><span class="p">)</span>
<span class="c1"># Move to final location atomically</span>
<span class="n">shutil</span><span class="o">.</span><span class="n">move</span><span class="p">(</span><span class="n">temp_backup</span><span class="p">,</span> <span class="n">backup_path</span><span class="p">)</span>
<span class="n">temp_backup</span> <span class="o">=</span> <span class="kc">None</span> <span class="c1"># Successfully moved</span>
<span class="c1"># Test restoration</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="n">backup_path</span><span class="p">,</span> <span class="n">restore_dir</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Backup and restore completed successfully"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">True</span>
<span class="k">except</span> <span class="n">TzstError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"tzst operation failed: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="c1"># Cleanup and recovery logic</span>
<span class="k">if</span> <span class="n">restore_dir</span><span class="o">.</span><span class="n">exists</span><span class="p">():</span>
<span class="n">shutil</span><span class="o">.</span><span class="n">rmtree</span><span class="p">(</span><span class="n">restore_dir</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Unexpected error: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="k">finally</span><span class="p">:</span>
<span class="c1"># Cleanup temporary files</span>
<span class="k">if</span> <span class="n">temp_backup</span> <span class="ow">and</span> <span class="n">temp_backup</span><span class="o">.</span><span class="n">exists</span><span class="p">():</span>
<span class="n">temp_backup</span><span class="o">.</span><span class="n">unlink</span><span class="p">()</span>
</pre></div>
</div>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="cli.html" class="btn btn-neutral float-left" title="CLI API" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="../development.html" class="btn btn-neutral float-right" title="Development Guide" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
+397
View File
@@ -0,0 +1,397 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta content="Complete tzst API reference - Core functions, CLI tools, and exception handling for tar.zst archives" name="description" />
<meta content="tzst API, Python API documentation, tar.zst API reference, archive API" name="keywords" />
<meta content="tzst API Reference" name="og:title" />
<meta content="Complete API reference for tzst - Core functions, CLI tools, and exception handling" name="og:description" />
<meta content="tzst API Reference" name="twitter:title" />
<meta content="Complete API reference for tzst - Core functions, CLI tools, and exception handling" name="twitter:description" />
<meta content="website" name="og:type" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="og:image" />
<meta content="https://tzst.xi-xu.me/" name="og:url" />
<meta content="summary_large_image" name="twitter:card" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="twitter:image" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>API Reference &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/api/index.html" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=3b3401d5"></script>
<script src="../_static/doctools.js?v=fd6eb6e6"></script>
<script src="../_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="../_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="../_static/opensearch.xml"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Core API" href="core.html" />
<link rel="prev" title="Examples" href="../examples.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "API Reference",
"item": "https://tzst.xi-xu.me/api/index.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/api/index.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="../index.html" class="icon icon-home">
tzst
<img src="../_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">API Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="core.html">Core API</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html">CLI API</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html">Exceptions API</a></li>
<li class="toctree-l2"><a class="reference internal" href="#overview">Overview</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#main-components">Main Components</a></li>
<li class="toctree-l3"><a class="reference internal" href="#architecture-overview">Architecture Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="#quick-reference">Quick Reference</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#core-classes">Core Classes</a></li>
<li class="toctree-l4"><a class="reference internal" href="#convenience-functions">Convenience Functions</a></li>
<li class="toctree-l4"><a class="reference internal" href="#cli-functions">CLI Functions</a></li>
<li class="toctree-l4"><a class="reference internal" href="#exception-classes">Exception Classes</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#key-features">Key Features</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#security-first">Security First</a></li>
<li class="toctree-l3"><a class="reference internal" href="#high-performance">High Performance</a></li>
<li class="toctree-l3"><a class="reference internal" href="#developer-friendly">Developer Friendly</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cross-platform">Cross-Platform</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">API Reference</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/api/index.md" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="api-reference">
<h1>API Reference<a class="headerlink" href="#api-reference" title="Link to this heading"></a></h1>
<p>This section contains the complete API documentation for tzst, providing detailed information about classes, functions, and exceptions.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="core.html">Core API</a><ul>
<li class="toctree-l2"><a class="reference internal" href="core.html#tzstarchive-class">TzstArchive Class</a></li>
<li class="toctree-l2"><a class="reference internal" href="core.html#convenience-functions">Convenience Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="core.html#enums-and-supporting-classes">Enums and Supporting Classes</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">CLI API</a><ul>
<li class="toctree-l2"><a class="reference internal" href="cli.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#main-functions">Main Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#command-handlers">Command Handlers</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#utility-functions">Utility Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="cli.html#interactive-features">Interactive Features</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="exceptions.html">Exceptions API</a><ul>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#exception-classes">Exception Classes</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#error-handling-best-practices">Error Handling Best Practices</a></li>
</ul>
</li>
</ul>
</div>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Link to this heading"></a></h2>
<p>The tzst library provides both high-level convenience functions and a comprehensive class-based API for working with <code class="docutils literal notranslate"><span class="pre">.tzst</span></code>/<code class="docutils literal notranslate"><span class="pre">.tar.zst</span></code> archives. The library is designed with security, performance, and ease of use in mind.</p>
<section id="main-components">
<h3>Main Components<a class="headerlink" href="#main-components" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong><a class="reference internal" href="core.html"><span class="doc">Core API</span></a></strong>: Core functionality including <code class="docutils literal notranslate"><span class="pre">TzstArchive</span></code> class and convenience functions for archive operations</p></li>
<li><p><strong><a class="reference internal" href="cli.html"><span class="doc">CLI API</span></a></strong>: Command-line interface functions and utilities for batch operations</p></li>
<li><p><strong><a class="reference internal" href="exceptions.html"><span class="doc">Exceptions API</span></a></strong>: Custom exception classes for comprehensive error handling and debugging</p></li>
</ul>
</section>
<section id="architecture-overview">
<h3>Architecture Overview<a class="headerlink" href="#architecture-overview" title="Link to this heading"></a></h3>
<p>The tzst library follows a layered architecture:</p>
<ol class="arabic simple">
<li><p><strong>High-Level API</strong>: Convenience functions for common operations</p></li>
<li><p><strong>Class-Based API</strong>: <code class="docutils literal notranslate"><span class="pre">TzstArchive</span></code> class for advanced control</p></li>
<li><p><strong>CLI Interface</strong>: Command-line tools for interactive and scripted use</p></li>
<li><p><strong>Exception System</strong>: Comprehensive error handling for robust applications</p></li>
</ol>
</section>
<section id="quick-reference">
<h3>Quick Reference<a class="headerlink" href="#quick-reference" title="Link to this heading"></a></h3>
<section id="core-classes">
<h4>Core Classes<a class="headerlink" href="#core-classes" title="Link to this heading"></a></h4>
<table class="autosummary longtable docutils align-default">
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="core.html#tzst.TzstArchive" title="tzst.TzstArchive"><code class="xref py py-obj docutils literal notranslate"><span class="pre">TzstArchive</span></code></a></p></td>
<td><p>A class for handling .tzst/.tar.zst archives.</p></td>
</tr>
</tbody>
</table>
<p>The main class for archive manipulation with context manager support and comprehensive functionality.</p>
</section>
<section id="convenience-functions">
<h4>Convenience Functions<a class="headerlink" href="#convenience-functions" title="Link to this heading"></a></h4>
<table class="autosummary longtable docutils align-default">
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="core.html#tzst.create_archive" title="tzst.create_archive"><code class="xref py py-obj docutils literal notranslate"><span class="pre">create_archive</span></code></a></p></td>
<td><p>Create a new .tzst archive with atomic file operations.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="core.html#tzst.extract_archive" title="tzst.extract_archive"><code class="xref py py-obj docutils literal notranslate"><span class="pre">extract_archive</span></code></a></p></td>
<td><p>Extract files from a .tzst archive.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="core.html#tzst.list_archive" title="tzst.list_archive"><code class="xref py py-obj docutils literal notranslate"><span class="pre">list_archive</span></code></a></p></td>
<td><p>List contents of a .tzst archive.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="core.html#tzst.test_archive" title="tzst.test_archive"><code class="xref py py-obj docutils literal notranslate"><span class="pre">test_archive</span></code></a></p></td>
<td><p>Test the integrity of a .tzst archive.</p></td>
</tr>
</tbody>
</table>
<p>High-level functions that provide simple interfaces for common archive operations.</p>
</section>
<section id="cli-functions">
<h4>CLI Functions<a class="headerlink" href="#cli-functions" title="Link to this heading"></a></h4>
<table class="autosummary longtable docutils align-default">
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="cli.html#tzst.cli.main" title="tzst.cli.main"><code class="xref py py-obj docutils literal notranslate"><span class="pre">main</span></code></a></p></td>
<td><p>Main entry point for the tzst command-line interface.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="cli.html#tzst.cli.create_parser" title="tzst.cli.create_parser"><code class="xref py py-obj docutils literal notranslate"><span class="pre">create_parser</span></code></a></p></td>
<td><p>Create and configure the command-line argument parser.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="cli.html#tzst.cli.print_banner" title="tzst.cli.print_banner"><code class="xref py py-obj docutils literal notranslate"><span class="pre">print_banner</span></code></a></p></td>
<td><p>Print the version and copyright banner.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="cli.html#tzst.cli.format_size" title="tzst.cli.format_size"><code class="xref py py-obj docutils literal notranslate"><span class="pre">format_size</span></code></a></p></td>
<td><p>Format file size in human-readable format.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="cli.html#tzst.cli.validate_compression_level" title="tzst.cli.validate_compression_level"><code class="xref py py-obj docutils literal notranslate"><span class="pre">validate_compression_level</span></code></a></p></td>
<td><p>Validate and return compression level.</p></td>
</tr>
</tbody>
</table>
<p>Command-line interface utilities for interactive and batch operations.</p>
</section>
<section id="exception-classes">
<h4>Exception Classes<a class="headerlink" href="#exception-classes" title="Link to this heading"></a></h4>
<table class="autosummary longtable docutils align-default">
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="exceptions.html#tzst.exceptions.TzstError" title="tzst.exceptions.TzstError"><code class="xref py py-obj docutils literal notranslate"><span class="pre">TzstError</span></code></a></p></td>
<td><p>Base exception for all tzst operations.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="exceptions.html#tzst.exceptions.TzstArchiveError" title="tzst.exceptions.TzstArchiveError"><code class="xref py py-obj docutils literal notranslate"><span class="pre">TzstArchiveError</span></code></a></p></td>
<td><p>Exception raised when archive operations fail.</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="exceptions.html#tzst.exceptions.TzstCompressionError" title="tzst.exceptions.TzstCompressionError"><code class="xref py py-obj docutils literal notranslate"><span class="pre">TzstCompressionError</span></code></a></p></td>
<td><p>Exception raised when compression operations fail.</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="exceptions.html#tzst.exceptions.TzstDecompressionError" title="tzst.exceptions.TzstDecompressionError"><code class="xref py py-obj docutils literal notranslate"><span class="pre">TzstDecompressionError</span></code></a></p></td>
<td><p>Exception raised when decompression operations fail.</p></td>
</tr>
</tbody>
</table>
<p>Exception hierarchy for comprehensive error handling and debugging support.</p>
</section>
</section>
</section>
<section id="key-features">
<h2>Key Features<a class="headerlink" href="#key-features" title="Link to this heading"></a></h2>
<section id="security-first">
<h3>Security First<a class="headerlink" href="#security-first" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Built-in path traversal protection</p></li>
<li><p>Multiple security filter options</p></li>
<li><p>Safe extraction by default</p></li>
</ul>
</section>
<section id="high-performance">
<h3>High Performance<a class="headerlink" href="#high-performance" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Zstandard compression with configurable levels</p></li>
<li><p>Streaming support for large archives</p></li>
<li><p>Memory-efficient operations</p></li>
</ul>
</section>
<section id="developer-friendly">
<h3>Developer Friendly<a class="headerlink" href="#developer-friendly" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Clean, Pythonic API</p></li>
<li><p>Comprehensive error handling</p></li>
<li><p>Context manager support</p></li>
<li><p>Extensive documentation and examples</p></li>
</ul>
</section>
<section id="cross-platform">
<h3>Cross-Platform<a class="headerlink" href="#cross-platform" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Works on Windows, macOS, and Linux</p></li>
<li><p>Consistent behavior across platforms</p></li>
<li><p>Native performance optimizations</p></li>
</ul>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="../examples.html" class="btn btn-neutral float-left" title="Examples" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="core.html" class="btn btn-neutral float-right" title="Core API" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
+659
View File
@@ -0,0 +1,659 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta content="Complete development guide for tzst - Setup, testing, contribution guidelines, and best practices" name="description" />
<meta content="tzst development, Python development, contributing to tzst, testing guide, documentation" name="keywords" />
<meta content="tzst Development Guide" name="og:title" />
<meta content="Complete development guide for tzst - Setup, testing, contribution guidelines, and best practices" name="og:description" />
<meta content="tzst Development Guide" name="twitter:title" />
<meta content="Complete development guide for tzst - Setup, testing, contribution guidelines, and best practices" name="twitter:description" />
<meta content="website" name="og:type" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="og:image" />
<meta content="https://tzst.xi-xu.me/development.html" name="og:url" />
<meta content="summary_large_image" name="twitter:card" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="twitter:image" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Development Guide &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/development.html" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=3b3401d5"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="_static/opensearch.xml"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="prev" title="Exceptions API" href="api/exceptions.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Development Guide",
"item": "https://tzst.xi-xu.me/development.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "Development Guide",
"description": "",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"publisher": {
"@type": "Person",
"name": "Xi Xu"
},
"datePublished": "2025-01-01",
"dateModified": "2025-01-12",
"url": "https://tzst.xi-xu.me/development.html",
"inLanguage": "en-US",
"about": {
"@type": "SoftwareApplication",
"name": "tzst"
}
}
</script>
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/development.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="index.html" class="icon icon-home">
tzst
<img src="_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API Reference</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Development Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#setting-up-development-environment">Setting up Development Environment</a></li>
<li class="toctree-l2"><a class="reference internal" href="#running-tests">Running Tests</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#basic-test-commands">Basic Test Commands</a></li>
<li class="toctree-l3"><a class="reference internal" href="#test-structure">Test Structure</a></li>
<li class="toctree-l3"><a class="reference internal" href="#writing-tests">Writing Tests</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#code-quality">Code Quality</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#running-code-style-tools">Running Code Style Tools</a></li>
<li class="toctree-l3"><a class="reference internal" href="#configuration">Configuration</a></li>
<li class="toctree-l3"><a class="reference internal" href="#code-style-guidelines">Code Style Guidelines</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#documentation">Documentation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#building-documentation">Building Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="#documentation-structure">Documentation Structure</a></li>
<li class="toctree-l3"><a class="reference internal" href="#writing-documentation">Writing Documentation</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#project-structure">Project Structure</a></li>
<li class="toctree-l2"><a class="reference internal" href="#contributing-workflow">Contributing Workflow</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#making-changes">1. Making Changes</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#types-of-contributions">Types of Contributions</a></li>
<li class="toctree-l4"><a class="reference internal" href="#branch-naming">Branch Naming</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#commit-messages">2. Commit Messages</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pull-request-process">3. Pull Request Process</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pull-request-guidelines">4. Pull Request Guidelines</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#development-tips">Development Tips</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#performance-considerations">Performance Considerations</a></li>
<li class="toctree-l3"><a class="reference internal" href="#security-considerations">Security Considerations</a></li>
<li class="toctree-l3"><a class="reference internal" href="#compatibility">Compatibility</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#release-process">Release Process</a></li>
<li class="toctree-l2"><a class="reference internal" href="#getting-help">Getting Help</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#resources">Resources</a></li>
<li class="toctree-l3"><a class="reference internal" href="#reporting-issues">Reporting Issues</a></li>
<li class="toctree-l3"><a class="reference internal" href="#suggesting-features">Suggesting Features</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#code-of-conduct">Code of Conduct</a></li>
<li class="toctree-l2"><a class="reference internal" href="#recognition">Recognition</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Development Guide</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/development.md" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="development-guide">
<h1>Development Guide<a class="headerlink" href="#development-guide" title="Link to this heading"></a></h1>
<p>This guide provides comprehensive information for developers contributing to or working with the tzst library.</p>
<section id="setting-up-development-environment">
<h2>Setting up Development Environment<a class="headerlink" href="#setting-up-development-environment" title="Link to this heading"></a></h2>
<p>This project uses modern Python packaging standards:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/xixu-me/tzst.git
<span class="nb">cd</span><span class="w"> </span>tzst
pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>.<span class="o">[</span>dev<span class="o">]</span>
</pre></div>
</div>
<p>The development installation includes all necessary tools:</p>
<ul class="simple">
<li><p><strong>pytest</strong> - Testing framework</p></li>
<li><p><strong>ruff</strong> - Linting and formatting</p></li>
<li><p><strong>coverage</strong> - Code coverage analysis</p></li>
<li><p><strong>sphinx</strong> - Documentation generation</p></li>
</ul>
</section>
<section id="running-tests">
<h2>Running Tests<a class="headerlink" href="#running-tests" title="Link to this heading"></a></h2>
<section id="basic-test-commands">
<h3>Basic Test Commands<a class="headerlink" href="#basic-test-commands" title="Link to this heading"></a></h3>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Run all tests</span>
python<span class="w"> </span>-m<span class="w"> </span>pytest
<span class="c1"># Run tests with coverage</span>
pytest<span class="w"> </span>--cov<span class="o">=</span>tzst<span class="w"> </span>--cov-report<span class="o">=</span>html
<span class="c1"># Or use the simpler command (coverage settings are in pyproject.toml)</span>
pytest
<span class="c1"># Run with verbose output</span>
python<span class="w"> </span>-m<span class="w"> </span>pytest<span class="w"> </span>-v
<span class="c1"># Run specific test file</span>
python<span class="w"> </span>-m<span class="w"> </span>pytest<span class="w"> </span>tests/test_core.py
<span class="c1"># Run integration tests only</span>
python<span class="w"> </span>-m<span class="w"> </span>pytest<span class="w"> </span>-m<span class="w"> </span>integration
</pre></div>
</div>
</section>
<section id="test-structure">
<h3>Test Structure<a class="headerlink" href="#test-structure" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Unit tests</strong>: Test individual functions and methods</p></li>
<li><p><strong>Integration tests</strong>: Test component interactions</p></li>
<li><p><strong>CLI tests</strong>: Test command-line interface</p></li>
<li><p><strong>Platform-specific tests</strong>: Test OS-specific functionality</p></li>
</ul>
</section>
<section id="writing-tests">
<h3>Writing Tests<a class="headerlink" href="#writing-tests" title="Link to this heading"></a></h3>
<ol class="arabic">
<li><p><strong>Use descriptive test names:</strong></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">test_create_archive_with_compression_level_9</span><span class="p">():</span>
</pre></div>
</div>
</li>
<li><p><strong>Use fixtures for common test data:</strong></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">test_extract_archive</span><span class="p">(</span><span class="n">sample_archive_path</span><span class="p">,</span> <span class="n">temp_dir</span><span class="p">):</span>
</pre></div>
</div>
</li>
<li><p><strong>Test edge cases:</strong></p>
<ul class="simple">
<li><p>Empty files</p></li>
<li><p>Large files</p></li>
<li><p>Invalid inputs</p></li>
<li><p>Corrupted archives</p></li>
</ul>
</li>
<li><p><strong>Add markers for test categorization:</strong></p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">integration</span>
<span class="k">def</span><span class="w"> </span><span class="nf">test_full_archive_workflow</span><span class="p">():</span>
</pre></div>
</div>
</li>
</ol>
</section>
</section>
<section id="code-quality">
<h2>Code Quality<a class="headerlink" href="#code-quality" title="Link to this heading"></a></h2>
<section id="running-code-style-tools">
<h3>Running Code Style Tools<a class="headerlink" href="#running-code-style-tools" title="Link to this heading"></a></h3>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Check code quality</span>
ruff<span class="w"> </span>check<span class="w"> </span>src<span class="w"> </span>tests
<span class="c1"># Fix auto-fixable issues</span>
ruff<span class="w"> </span>check<span class="w"> </span>--fix<span class="w"> </span>src<span class="w"> </span>tests
<span class="c1"># Format code</span>
ruff<span class="w"> </span>format<span class="w"> </span>src<span class="w"> </span>tests
<span class="c1"># Check formatting without making changes</span>
ruff<span class="w"> </span>format<span class="w"> </span>--check<span class="w"> </span>src<span class="w"> </span>tests
</pre></div>
</div>
</section>
<section id="configuration">
<h3>Configuration<a class="headerlink" href="#configuration" title="Link to this heading"></a></h3>
<p>Settings are defined in <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code>:</p>
<ul class="simple">
<li><p>Line length: 88 characters</p></li>
<li><p>Target Python version: 3.12+ (tested on 3.12-3.14)</p></li>
<li><p>Import sorting with isort</p></li>
<li><p>Quote style: double quotes</p></li>
</ul>
</section>
<section id="code-style-guidelines">
<h3>Code Style Guidelines<a class="headerlink" href="#code-style-guidelines" title="Link to this heading"></a></h3>
<ol class="arabic simple">
<li><p><strong>Follow PEP 8</strong> with project-specific modifications</p></li>
<li><p><strong>Use type hints</strong> for all public APIs</p></li>
<li><p><strong>Write docstrings</strong> for classes and public methods</p></li>
<li><p><strong>Keep functions focused</strong> and reasonably sized</p></li>
<li><p><strong>Use meaningful variable names</strong></p></li>
<li><p><strong>Add comments</strong> for complex logic</p></li>
</ol>
</section>
</section>
<section id="documentation">
<h2>Documentation<a class="headerlink" href="#documentation" title="Link to this heading"></a></h2>
<section id="building-documentation">
<h3>Building Documentation<a class="headerlink" href="#building-documentation" title="Link to this heading"></a></h3>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Navigate to docs directory</span>
<span class="nb">cd</span><span class="w"> </span>docs
<span class="c1"># Install documentation dependencies</span>
pip<span class="w"> </span>install<span class="w"> </span>-r<span class="w"> </span>requirements.txt
<span class="c1"># Build HTML documentation</span>
make<span class="w"> </span>html
<span class="c1"># On Windows, use:</span>
make.bat<span class="w"> </span>html
<span class="c1"># View built documentation</span>
<span class="c1"># Open docs/_build/html/index.html in your browser</span>
</pre></div>
</div>
</section>
<section id="documentation-structure">
<h3>Documentation Structure<a class="headerlink" href="#documentation-structure" title="Link to this heading"></a></h3>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>docs/
├── index.md # Main documentation landing page
├── quickstart.md # Getting started guide
├── performance.md # Performance guide and comparisons
├── examples.md # Usage examples
├── development.md # This development guide
├── api/ # API reference documentation
│ ├── index.md
│ ├── core.md
│ ├── cli.md
│ └── exceptions.md
├── conf.py # Sphinx configuration
└── requirements.txt # Documentation dependencies
</pre></div>
</div>
</section>
<section id="writing-documentation">
<h3>Writing Documentation<a class="headerlink" href="#writing-documentation" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Use <strong>MyST Markdown</strong> format</p></li>
<li><p>Include <strong>code examples</strong> for new features</p></li>
<li><p>Add <strong>cross-references</strong> using proper syntax</p></li>
<li><p>Test all <strong>code snippets</strong> to ensure they work</p></li>
</ul>
</section>
</section>
<section id="project-structure">
<h2>Project Structure<a class="headerlink" href="#project-structure" title="Link to this heading"></a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>tzst/
├── src/tzst/ # Main package source code
│ ├── __init__.py # Package initialization and exports
│ ├── __main__.py # CLI entry point
│ ├── cli.py # Command-line interface
│ ├── core.py # Core archive functionality
│ └── exceptions.py # Custom exceptions
├── tests/ # Test suite
│ ├── conftest.py # Pytest configuration and fixtures
│ ├── test_core.py # Core functionality tests
│ ├── test_cli.py # CLI tests
│ └── test_*.py # Additional test modules
├── docs/ # Documentation source
├── .github/ # GitHub workflows and templates
├── pyproject.toml # Project configuration
├── README.md # Project Readme
├── LICENSE # BSD 3-Clause License
└── CONTRIBUTING.md # Contribution guidelines
</pre></div>
</div>
</section>
<section id="contributing-workflow">
<h2>Contributing Workflow<a class="headerlink" href="#contributing-workflow" title="Link to this heading"></a></h2>
<section id="making-changes">
<h3>1. Making Changes<a class="headerlink" href="#making-changes" title="Link to this heading"></a></h3>
<section id="types-of-contributions">
<h4>Types of Contributions<a class="headerlink" href="#types-of-contributions" title="Link to this heading"></a></h4>
<ul class="simple">
<li><p><strong>Bug fixes</strong>: Fix issues in existing functionality</p></li>
<li><p><strong>Features</strong>: Add new capabilities to the library</p></li>
<li><p><strong>Documentation</strong>: Improve or add documentation</p></li>
<li><p><strong>Tests</strong>: Add or improve test coverage</p></li>
<li><p><strong>Performance</strong>: Optimize existing code</p></li>
<li><p><strong>Security</strong>: Address security vulnerabilities</p></li>
</ul>
</section>
<section id="branch-naming">
<h4>Branch Naming<a class="headerlink" href="#branch-naming" title="Link to this heading"></a></h4>
<p>Use descriptive branch names:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">feature/add-streaming-mode</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fix/handle-corrupted-archives</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">docs/improve-api-documentation</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">test/add-compression-tests</span></code></p></li>
</ul>
</section>
</section>
<section id="commit-messages">
<h3>2. Commit Messages<a class="headerlink" href="#commit-messages" title="Link to this heading"></a></h3>
<p>Follow conventional commit format:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">type</span><span class="p">(</span><span class="n">scope</span><span class="p">):</span> <span class="n">description</span>
<span class="p">[</span><span class="n">optional</span> <span class="n">body</span><span class="p">]</span>
<span class="p">[</span><span class="n">optional</span> <span class="n">footer</span><span class="p">]</span>
</pre></div>
</div>
<p><strong>Types:</strong></p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">feat</span></code>: New feature</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fix</span></code>: Bug fix</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">docs</span></code>: Documentation changes</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">test</span></code>: Adding or modifying tests</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">refactor</span></code>: Code refactoring</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">perf</span></code>: Performance improvements</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">chore</span></code>: Build process or auxiliary tool changes</p></li>
</ul>
<p><strong>Examples:</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">feat</span><span class="p">(</span><span class="n">core</span><span class="p">):</span> <span class="n">add</span> <span class="n">streaming</span> <span class="n">compression</span> <span class="n">support</span>
<span class="n">fix</span><span class="p">(</span><span class="n">cli</span><span class="p">):</span> <span class="n">handle</span> <span class="n">invalid</span> <span class="n">archive</span> <span class="n">paths</span> <span class="n">gracefully</span>
<span class="n">docs</span><span class="p">(</span><span class="n">readme</span><span class="p">):</span> <span class="n">update</span> <span class="n">installation</span> <span class="n">instructions</span>
</pre></div>
</div>
</section>
<section id="pull-request-process">
<h3>3. Pull Request Process<a class="headerlink" href="#pull-request-process" title="Link to this heading"></a></h3>
<ol class="arabic">
<li><p><strong>Create a feature branch:</strong></p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>checkout<span class="w"> </span>-b<span class="w"> </span>feature/your-feature-name
</pre></div>
</div>
</li>
<li><p><strong>Make your changes</strong> following the guidelines above</p></li>
<li><p><strong>Add tests</strong> for new functionality</p></li>
<li><p><strong>Update documentation</strong> if needed</p></li>
<li><p><strong>Run the test suite:</strong></p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python<span class="w"> </span>-m<span class="w"> </span>pytest
ruff<span class="w"> </span>check<span class="w"> </span>.
ruff<span class="w"> </span>format<span class="w"> </span>--check<span class="w"> </span>.
</pre></div>
</div>
</li>
<li><p><strong>Commit your changes:</strong></p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>add<span class="w"> </span>.
git<span class="w"> </span>commit<span class="w"> </span>-m<span class="w"> </span><span class="s2">"feat: add your feature description"</span>
</pre></div>
</div>
</li>
<li><p><strong>Push to your fork:</strong></p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>push<span class="w"> </span>origin<span class="w"> </span>feature/your-feature-name
</pre></div>
</div>
</li>
<li><p><strong>Create a pull request</strong> using the provided template</p></li>
</ol>
</section>
<section id="pull-request-guidelines">
<h3>4. Pull Request Guidelines<a class="headerlink" href="#pull-request-guidelines" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Fill out the PR template</strong> completely</p></li>
<li><p><strong>Link related issues</strong> using keywords (fixes #123)</p></li>
<li><p><strong>Keep PRs focused</strong> - one feature/fix per PR</p></li>
<li><p><strong>Ensure all CI checks pass</strong></p></li>
<li><p><strong>Respond to review feedback</strong> promptly</p></li>
</ul>
</section>
</section>
<section id="development-tips">
<h2>Development Tips<a class="headerlink" href="#development-tips" title="Link to this heading"></a></h2>
<section id="performance-considerations">
<h3>Performance Considerations<a class="headerlink" href="#performance-considerations" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Use streaming for large files</p></li>
<li><p>Consider memory usage patterns</p></li>
<li><p>Profile code for bottlenecks</p></li>
<li><p>Test with various file sizes</p></li>
</ul>
</section>
<section id="security-considerations">
<h3>Security Considerations<a class="headerlink" href="#security-considerations" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Validate all user inputs</p></li>
<li><p>Use secure defaults (e.g., ‘data’ filter)</p></li>
<li><p>Handle malicious archives safely</p></li>
<li><p>Be cautious with file paths</p></li>
</ul>
</section>
<section id="compatibility">
<h3>Compatibility<a class="headerlink" href="#compatibility" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Support Python 3.12+ with CI coverage for 3.12-3.14</p></li>
<li><p>Test on multiple platforms (Windows, macOS, Linux)</p></li>
<li><p>Consider different filesystem behaviors</p></li>
<li><p>Maintain backwards compatibility when possible</p></li>
</ul>
</section>
</section>
<section id="release-process">
<h2>Release Process<a class="headerlink" href="#release-process" title="Link to this heading"></a></h2>
<p>Releases are handled by maintainers:</p>
<ol class="arabic simple">
<li><p>Update version in <code class="docutils literal notranslate"><span class="pre">src/tzst/__init__.py</span></code></p></li>
<li><p>Create a release tag</p></li>
<li><p>Automated CI/CD publishes to PyPI</p></li>
</ol>
</section>
<section id="getting-help">
<h2>Getting Help<a class="headerlink" href="#getting-help" title="Link to this heading"></a></h2>
<section id="resources">
<h3>Resources<a class="headerlink" href="#resources" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Issues</strong>: <a class="reference external" href="https://github.com/xixu-me/tzst/issues">GitHub Issues</a></p></li>
<li><p><strong>Discussions</strong>: Use GitHub Discussions for questions</p></li>
<li><p><strong>Documentation</strong>: Check the README and code comments</p></li>
</ul>
</section>
<section id="reporting-issues">
<h3>Reporting Issues<a class="headerlink" href="#reporting-issues" title="Link to this heading"></a></h3>
<p>When reporting bugs:</p>
<ol class="arabic simple">
<li><p><strong>Use the bug report template</strong></p></li>
<li><p><strong>Provide a minimal reproduction case</strong></p></li>
<li><p><strong>Include system information</strong> (OS, Python version)</p></li>
<li><p><strong>Attach relevant files</strong> if possible (archives, logs)</p></li>
</ol>
</section>
<section id="suggesting-features">
<h3>Suggesting Features<a class="headerlink" href="#suggesting-features" title="Link to this heading"></a></h3>
<p>When suggesting features:</p>
<ol class="arabic simple">
<li><p><strong>Use the feature request template</strong></p></li>
<li><p><strong>Explain the use case</strong> and motivation</p></li>
<li><p><strong>Consider backwards compatibility</strong></p></li>
<li><p><strong>Provide implementation ideas</strong> if you have them</p></li>
</ol>
</section>
</section>
<section id="code-of-conduct">
<h2>Code of Conduct<a class="headerlink" href="#code-of-conduct" title="Link to this heading"></a></h2>
<p>This project follows the principles of respectful collaboration. Please be kind, constructive, and professional in all interactions.</p>
</section>
<section id="recognition">
<h2>Recognition<a class="headerlink" href="#recognition" title="Link to this heading"></a></h2>
<p>Contributors are recognized in several ways:</p>
<ul class="simple">
<li><p>Listed in release notes for significant contributions</p></li>
<li><p>Mentioned in README acknowledgments</p></li>
<li><p>GitHub contributor statistics</p></li>
</ul>
<p>Thank you for contributing to tzst! Your efforts help make this library better for everyone.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="api/exceptions.html" class="btn btn-neutral float-left" title="Exceptions API" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
+1473
View File
File diff suppressed because it is too large. Load diff
+349
View File
@@ -0,0 +1,349 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Index &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/genindex.html" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=3b3401d5"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="_static/opensearch.xml"/>
<link rel="index" title="Index" href="#" />
<link rel="search" title="Search" href="search.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Index",
"item": "https://tzst.xi-xu.me/genindex.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/genindex.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="index.html" class="icon icon-home">
tzst
<img src="_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="development.html">Development Guide</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Index</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/genindex" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<h1 id="index">Index</h1>
<div class="genindex-jumpbox">
<a href="#_"><strong>_</strong></a>
| <a href="#A"><strong>A</strong></a>
| <a href="#C"><strong>C</strong></a>
| <a href="#E"><strong>E</strong></a>
| <a href="#F"><strong>F</strong></a>
| <a href="#G"><strong>G</strong></a>
| <a href="#L"><strong>L</strong></a>
| <a href="#M"><strong>M</strong></a>
| <a href="#O"><strong>O</strong></a>
| <a href="#P"><strong>P</strong></a>
| <a href="#T"><strong>T</strong></a>
| <a href="#V"><strong>V</strong></a>
</div>
<h2 id="_">_</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.TzstArchive.__enter__">__enter__() (tzst.TzstArchive method)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.TzstArchive.__exit__">__exit__() (tzst.TzstArchive method)</a>
</li>
<li><a href="api/core.html#tzst.TzstArchive.__init__">__init__() (tzst.TzstArchive method)</a>
</li>
</ul></td>
</tr></table>
<h2 id="A">A</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.TzstArchive.add">add() (tzst.TzstArchive method)</a>
</li>
</ul></td>
</tr></table>
<h2 id="C">C</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.TzstArchive.close">close() (tzst.TzstArchive method)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.create_archive">create_archive() (in module tzst)</a>
</li>
<li><a href="api/cli.html#tzst.cli.create_parser">create_parser() (in module tzst.cli)</a>
</li>
</ul></td>
</tr></table>
<h2 id="E">E</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.TzstArchive.extract">extract() (tzst.TzstArchive method)</a>
</li>
<li><a href="api/core.html#tzst.extract_archive">extract_archive() (in module tzst)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.TzstArchive.extractall">extractall() (tzst.TzstArchive method)</a>
</li>
<li><a href="api/core.html#tzst.TzstArchive.extractfile">extractfile() (tzst.TzstArchive method)</a>
</li>
</ul></td>
</tr></table>
<h2 id="F">F</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/cli.html#tzst.cli.format_size">format_size() (in module tzst.cli)</a>
</li>
</ul></td>
</tr></table>
<h2 id="G">G</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.TzstArchive.getmembers">getmembers() (tzst.TzstArchive method)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.TzstArchive.getnames">getnames() (tzst.TzstArchive method)</a>
</li>
</ul></td>
</tr></table>
<h2 id="L">L</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.TzstArchive.list">list() (tzst.TzstArchive method)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.list_archive">list_archive() (in module tzst)</a>
</li>
</ul></td>
</tr></table>
<h2 id="M">M</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/cli.html#tzst.cli.main">main() (in module tzst.cli)</a>
</li>
</ul></td>
</tr></table>
<h2 id="O">O</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.TzstArchive.open">open() (tzst.TzstArchive method)</a>
</li>
</ul></td>
</tr></table>
<h2 id="P">P</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/cli.html#tzst.cli.print_banner">print_banner() (in module tzst.cli)</a>
</li>
</ul></td>
</tr></table>
<h2 id="T">T</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/core.html#tzst.TzstArchive.test">test() (tzst.TzstArchive method)</a>
</li>
<li><a href="api/core.html#tzst.test_archive">test_archive() (in module tzst)</a>
</li>
<li><a href="api/core.html#tzst.TzstArchive">TzstArchive (class in tzst)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/exceptions.html#tzst.exceptions.TzstArchiveError">TzstArchiveError</a>
</li>
<li><a href="api/exceptions.html#tzst.exceptions.TzstCompressionError">TzstCompressionError</a>
</li>
<li><a href="api/exceptions.html#tzst.exceptions.TzstDecompressionError">TzstDecompressionError</a>
</li>
<li><a href="api/exceptions.html#tzst.exceptions.TzstError">TzstError</a>
</li>
</ul></td>
</tr></table>
<h2 id="V">V</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="api/cli.html#tzst.cli.validate_compression_level">validate_compression_level() (in module tzst.cli)</a>
</li>
</ul></td>
</tr></table>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
+421
View File
@@ -0,0 +1,421 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta content="tzst - Next-generation Python library for tar.zst archives with Zstandard compression. Fast, secure, and reliable archive management." name="description" />
<meta content="tzst, Python, tar.zst, Zstandard, compression, archive, backup, file management" name="keywords" />
<meta content="tzst - Next-Generation Archive Management" name="og:title" />
<meta content="Fast, secure, and reliable Python library for tar.zst archives with Zstandard compression" name="og:description" />
<meta content="tzst - Next-Generation Archive Management" name="twitter:title" />
<meta content="Fast, secure, and reliable Python library for tar.zst archives with Zstandard compression" name="twitter:description" />
<meta content="website" name="og:type" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="og:image" />
<meta content="https://tzst.xi-xu.me/" name="og:url" />
<meta content="summary_large_image" name="twitter:card" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="twitter:image" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>tzst Documentation &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/index.html" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=3b3401d5"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="_static/opensearch.xml"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Quick Start Guide" href="quickstart.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<!-- Article/TechArticle Schema for documentation pages -->
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="#" class="icon icon-home">
tzst
<img src="_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="#">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="#" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">tzst Documentation</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/index.md" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="tzst-documentation">
<h1>tzst Documentation<a class="headerlink" href="#tzst-documentation" title="Link to this heading"></a></h1>
<p><a class="reference external" href="https://codecov.io/gh/xixu-me/tzst"><img alt="codecov" src="https://codecov.io/gh/xixu-me/tzst/graph/badge.svg?token=2AIN1559WU" /></a>
<a class="reference external" href="https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql"><img alt="CodeQL" src="https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql/badge.svg" /></a>
<a class="reference external" href="https://github.com/xixu-me/tzst/actions/workflows/ci.yml"><img alt="CI/CD" src="https://github.com/xixu-me/tzst/actions/workflows/ci.yml/badge.svg" /></a>
<a class="reference external" href="https://pypi.org/project/tzst/"><img alt="PyPI - Version" src="https://img.shields.io/pypi/v/tzst" /></a>
<a class="reference external" href="https://pypistats.org/packages/tzst"><img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/tzst" /></a>
<a class="reference external" href="https://github.com/xixu-me/tzst/blob/main/LICENSE"><img alt="GitHub License" src="https://img.shields.io/github/license/xixu-me/tzst" /></a>
<a class="reference external" href="https://xi-xu.me/#sponsorships"><img alt="Sponsor" src="https://img.shields.io/badge/Sponsor-violet" /></a></p>
<p>Welcome to <strong>tzst</strong>, the next-generation Python library engineered for modern archive management, leveraging cutting-edge Zstandard compression to deliver superior performance, security, and reliability.</p>
<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick Start Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#installation">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#basic-usage">Basic Usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#advanced-features">Advanced Features</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#error-handling">Error Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#next-steps">Next Steps</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#read-an-existing-archive">Read an Existing Archive</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#common-patterns">Common Patterns</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html#further-learning">Further Learning</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="performance.html">Performance Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="performance.html#performance-tips">Performance Tips</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance.html#comparison-with-other-tools">Comparison with Other Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance.html#benchmarking-examples">Benchmarking Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance.html#best-practices">Best Practices</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance.html#hardware-considerations">Hardware Considerations</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance.html#integration-with-build-systems">Integration with Build Systems</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a><ul>
<li class="toctree-l2"><a class="reference internal" href="examples.html#table-of-contents">Table of Contents</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#basic-operations">Basic Operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#command-line-usage">Command Line Usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#advanced-archive-creation">Advanced Archive Creation</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#flexible-extraction">Flexible Extraction</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#security-and-filtering">Security and Filtering</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#performance-optimization">Performance Optimization</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#error-handling">Error Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#real-world-scenarios">Real-World Scenarios</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#integration-examples">Integration Examples</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="api/core.html">Core API</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/cli.html">CLI API</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/exceptions.html">Exceptions API</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/index.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="api/index.html#key-features">Key Features</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="development.html">Development Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="development.html#setting-up-development-environment">Setting up Development Environment</a></li>
<li class="toctree-l2"><a class="reference internal" href="development.html#running-tests">Running Tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="development.html#code-quality">Code Quality</a></li>
<li class="toctree-l2"><a class="reference internal" href="development.html#documentation">Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="development.html#project-structure">Project Structure</a></li>
<li class="toctree-l2"><a class="reference internal" href="development.html#contributing-workflow">Contributing Workflow</a></li>
<li class="toctree-l2"><a class="reference internal" href="development.html#development-tips">Development Tips</a></li>
<li class="toctree-l2"><a class="reference internal" href="development.html#release-process">Release Process</a></li>
<li class="toctree-l2"><a class="reference internal" href="development.html#getting-help">Getting Help</a></li>
<li class="toctree-l2"><a class="reference internal" href="development.html#code-of-conduct">Code of Conduct</a></li>
<li class="toctree-l2"><a class="reference internal" href="development.html#recognition">Recognition</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="genindex.html">Index</a></li>
</ul>
</div>
<div class="toctree-wrapper compound">
</div>
<section id="what-is-tzst">
<h2>What is tzst?<a class="headerlink" href="#what-is-tzst" title="Link to this heading"></a></h2>
<p><strong>tzst</strong> is a modern Python library built exclusively for Python 3.12+ that provides comprehensive support for creating, extracting, and managing <code class="docutils literal notranslate"><span class="pre">.tzst</span></code> and <code class="docutils literal notranslate"><span class="pre">.tar.zst</span></code> archives. It combines the proven reliability of the tar format with the superior compression efficiency of Zstandard (zstd) to deliver:</p>
<ul class="simple">
<li><p><strong>Superior Performance</strong>: Fast compression and decompression with excellent compression ratios</p></li>
<li><p><strong>Enterprise-Grade Security</strong>: Safe extraction with built-in protections against path traversal attacks</p></li>
<li><p><strong>Memory Efficiency</strong>: Streaming mode for handling large archives with minimal memory usage</p></li>
<li><p><strong>Cross-Platform Compatibility</strong>: Works seamlessly on Windows, macOS, and Linux</p></li>
<li><p><strong>Developer-Friendly</strong>: Clean, Pythonic API with comprehensive error handling</p></li>
</ul>
</section>
<section id="key-features">
<h2>Key Features<a class="headerlink" href="#key-features" title="Link to this heading"></a></h2>
<section id="advanced-compression">
<h3>Advanced Compression<a class="headerlink" href="#advanced-compression" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Zstandard Compression</strong>: Best-in-class compression algorithm with configurable levels (1-22)</p></li>
<li><p><strong>Multiple Extensions</strong>: Support for both <code class="docutils literal notranslate"><span class="pre">.tzst</span></code> and <code class="docutils literal notranslate"><span class="pre">.tar.zst</span></code> file extensions</p></li>
<li><p><strong>Streaming Support</strong>: Memory-efficient processing for large archives</p></li>
</ul>
</section>
<section id="security-first">
<h3>Security First<a class="headerlink" href="#security-first" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Safe by Default</strong>: Uses ‘data’ filter for secure extraction without dangerous path traversal</p></li>
<li><p><strong>Multiple Filter Options</strong>: Choose from ‘data’, ‘tar’, or ‘fully_trusted’ filters based on your security needs</p></li>
<li><p><strong>Atomic Operations</strong>: All file operations use temporary files with atomic moves to prevent corruption</p></li>
</ul>
</section>
<section id="dual-interfaces">
<h3>Dual Interfaces<a class="headerlink" href="#dual-interfaces" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Command Line</strong>: Intuitive CLI with comprehensive options for batch operations</p></li>
<li><p><strong>Python API</strong>: Clean, object-oriented interface for programmatic use</p></li>
<li><p><strong>Convenience Functions</strong>: High-level functions for common operations</p></li>
</ul>
</section>
<section id="high-performance">
<h3>High Performance<a class="headerlink" href="#high-performance" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Optimized I/O</strong>: Efficient buffering and streaming for large files</p></li>
<li><p><strong>Conflict Resolution</strong>: Intelligent handling of file conflicts during extraction</p></li>
<li><p><strong>Cross-Platform</strong>: Native performance on all major operating systems</p></li>
</ul>
</section>
</section>
<section id="quick-example">
<h2>Quick Example<a class="headerlink" href="#quick-example" title="Link to this heading"></a></h2>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">TzstArchive</span><span class="p">,</span> <span class="n">create_archive</span><span class="p">,</span> <span class="n">extract_archive</span>
<span class="c1"># Create an archive</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"documents/"</span><span class="p">,</span> <span class="s2">"photos/"</span><span class="p">],</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
<span class="c1"># Extract an archive</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="s2">"restore/"</span><span class="p">)</span>
<span class="c1"># Work with archives programmatically</span>
<span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"data.tzst"</span><span class="p">,</span> <span class="s2">"r"</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">list</span><span class="p">(</span><span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">archive</span><span class="o">.</span><span class="n">extract</span><span class="p">(</span><span class="s2">"important.txt"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">)</span>
<span class="n">is_valid</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">test</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h2>
<p>For detailed installation instructions, including standalone binaries and source installation, please refer to the <a class="reference internal" href="quickstart.html"><span class="doc">Quick Start Guide</span></a> guide.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install from PyPI</span>
pip<span class="w"> </span>install<span class="w"> </span>tzst
<span class="c1"># Or using uv (recommended)</span>
uv<span class="w"> </span>tool<span class="w"> </span>install<span class="w"> </span>tzst
</pre></div>
</div>
</section>
<section id="getting-started">
<h2>Getting Started<a class="headerlink" href="#getting-started" title="Link to this heading"></a></h2>
<p>For a quick introduction, see the <a class="reference internal" href="quickstart.html"><span class="doc">Quick Start Guide</span></a> guide. For comprehensive usage examples, explore the <a class="reference internal" href="examples.html"><span class="doc">Examples</span></a> section.</p>
<section id="api-documentation">
<h3>API Documentation<a class="headerlink" href="#api-documentation" title="Link to this heading"></a></h3>
<p>Complete API documentation is available in the <a class="reference internal" href="api/index.html"><span class="doc">API Reference</span></a> section, covering:</p>
<ul class="simple">
<li><p><a class="reference internal" href="api/core.html"><span class="doc">Core API</span></a>: Main classes and functions</p></li>
<li><p><a class="reference internal" href="api/cli.html"><span class="doc">CLI API</span></a>: Command-line interface</p></li>
<li><p><a class="reference internal" href="api/exceptions.html"><span class="doc">Exceptions API</span></a>: Error handling</p></li>
</ul>
</section>
</section>
<section id="development">
<h2>Development<a class="headerlink" href="#development" title="Link to this heading"></a></h2>
<p>For comprehensive development information, see the <a class="reference internal" href="development.html"><span class="doc">Development Guide</span></a> guide, which covers:</p>
<ul class="simple">
<li><p>Setting up development environment</p></li>
<li><p>Running tests and code quality checks</p></li>
<li><p>Documentation building</p></li>
<li><p>Contributing workflow and guidelines</p></li>
<li><p>Project structure and best practices</p></li>
</ul>
<section id="quick-start">
<h3>Quick Start<a class="headerlink" href="#quick-start" title="Link to this heading"></a></h3>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/xixu-me/tzst.git
<span class="nb">cd</span><span class="w"> </span>tzst
pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>.<span class="o">[</span>dev<span class="o">]</span>
pytest
</pre></div>
</div>
</section>
</section>
<section id="contributing">
<h2>Contributing<a class="headerlink" href="#contributing" title="Link to this heading"></a></h2>
<p>We welcome contributions! Please read our <a class="reference external" href="https://github.com/xixu-me/tzst/blob/main/CONTRIBUTING.md">Contributing Guide</a> for:</p>
<ul class="simple">
<li><p>Development setup and project structure</p></li>
<li><p>Code style guidelines and best practices</p></li>
<li><p>Testing requirements and writing tests</p></li>
<li><p>Pull request process and review workflow</p></li>
</ul>
<section id="types-of-contributions-welcome">
<h3>Types of Contributions Welcome<a class="headerlink" href="#types-of-contributions-welcome" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Bug fixes</strong> - Fix issues in existing functionality</p></li>
<li><p><strong>Features</strong> - Add new capabilities to the library</p></li>
<li><p><strong>Documentation</strong> - Improve or add documentation</p></li>
<li><p><strong>Tests</strong> - Add or improve test coverage</p></li>
<li><p><strong>Performance</strong> - Optimize existing code</p></li>
<li><p><strong>Security</strong> - Address security vulnerabilities</p></li>
</ul>
</section>
</section>
<section id="acknowledgments">
<h2>Acknowledgments<a class="headerlink" href="#acknowledgments" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/facebook/zstd">Meta Zstandard</a> for the excellent compression algorithm</p></li>
<li><p><a class="reference external" href="https://github.com/indygreg/python-zstandard">python-zstandard</a> for Python bindings</p></li>
<li><p>The Python community for inspiration and feedback</p></li>
</ul>
</section>
<section id="license">
<h2>License<a class="headerlink" href="#license" title="Link to this heading"></a></h2>
<p>Copyright © <a class="reference external" href="https://xi-xu.me">Xi Xu</a>. All rights reserved.</p>
<p>Licensed under the <a class="reference external" href="https://github.com/xixu-me/tzst/blob/main/LICENSE">BSD 3-Clause</a> license.</p>
</section>
<section id="documentation-guide">
<h2>Documentation Guide<a class="headerlink" href="#documentation-guide" title="Link to this heading"></a></h2>
<ol class="arabic simple">
<li><p><strong><a class="reference internal" href="quickstart.html"><span class="doc">Quick Start Guide</span></a></strong> - Get up and running quickly with basic examples</p></li>
<li><p><strong><a class="reference internal" href="performance.html"><span class="doc">Performance Guide</span></a></strong> - Performance optimization guide and comparisons</p></li>
<li><p><strong><a class="reference internal" href="examples.html"><span class="doc">Examples</span></a></strong> - Comprehensive usage examples and patterns</p></li>
<li><p><strong><a class="reference internal" href="api/index.html"><span class="doc">API Reference</span></a></strong> - Complete API reference documentation</p></li>
<li><p><strong><a class="reference internal" href="development.html"><span class="doc">Development Guide</span></a></strong> - Development and contribution guidelines</p></li>
<li><p><strong><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></strong> - Index of all documented items</p></li>
</ol>
</section>
<section id="requirements">
<h2>Requirements<a class="headerlink" href="#requirements" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p>Python 3.12 or higher (tested on 3.12-3.14)</p></li>
<li><p>zstandard &gt;= 0.19.0</p></li>
</ul>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="quickstart.html" class="btn btn-neutral float-right" title="Quick Start Guide" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
BIN
View File
Binary file not shown.
+556
View File
@@ -0,0 +1,556 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta content="tzst Performance Guide - Compression level optimization, performance tips, and comparison with other archive tools" name="description" />
<meta content="tzst performance, compression benchmarks, tar gzip comparison, archive performance optimization" name="keywords" />
<meta content="tzst Performance Guide" name="og:title" />
<meta content="Performance optimization tips and comparison with other archive tools for tzst" name="og:description" />
<meta content="tzst Performance Guide" name="twitter:title" />
<meta content="Performance optimization tips and comparison with other archive tools for tzst" name="twitter:description" />
<meta content="website" name="og:type" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="og:image" />
<meta content="https://tzst.xi-xu.me/" name="og:url" />
<meta content="summary_large_image" name="twitter:card" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="twitter:image" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Performance Guide &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/performance.html" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=3b3401d5"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="_static/opensearch.xml"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Examples" href="examples.html" />
<link rel="prev" title="Quick Start Guide" href="quickstart.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Performance Guide",
"item": "https://tzst.xi-xu.me/performance.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "Performance Guide",
"description": "",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"publisher": {
"@type": "Person",
"name": "Xi Xu"
},
"datePublished": "2025-01-01",
"dateModified": "2025-01-12",
"url": "https://tzst.xi-xu.me/performance.html",
"inLanguage": "en-US",
"about": {
"@type": "SoftwareApplication",
"name": "tzst"
}
}
</script>
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/performance.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="index.html" class="icon icon-home">
tzst
<img src="_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Performance Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#performance-tips">Performance Tips</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#compression-levels">1. Compression Levels</a></li>
<li class="toctree-l3"><a class="reference internal" href="#streaming">2. Streaming</a></li>
<li class="toctree-l3"><a class="reference internal" href="#batch-operations">3. Batch Operations</a></li>
<li class="toctree-l3"><a class="reference internal" href="#file-type-considerations">4. File Type Considerations</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#comparison-with-other-tools">Comparison with Other Tools</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#vs-tar-gzip">vs tar + gzip</a></li>
<li class="toctree-l3"><a class="reference internal" href="#vs-tar-xz">vs tar + xz</a></li>
<li class="toctree-l3"><a class="reference internal" href="#vs-zip">vs zip</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#benchmarking-examples">Benchmarking Examples</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#compression-level-benchmark">Compression Level Benchmark</a></li>
<li class="toctree-l3"><a class="reference internal" href="#memory-usage-comparison">Memory Usage Comparison</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#best-practices">Best Practices</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#for-development">For Development</a></li>
<li class="toctree-l3"><a class="reference internal" href="#for-backups">For Backups</a></li>
<li class="toctree-l3"><a class="reference internal" href="#for-distribution">For Distribution</a></li>
<li class="toctree-l3"><a class="reference internal" href="#for-archival-storage">For Archival Storage</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#hardware-considerations">Hardware Considerations</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#cpu-usage">CPU Usage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#memory-usage">Memory Usage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#storage">Storage</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#integration-with-build-systems">Integration with Build Systems</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#makefile-example">Makefile Example</a></li>
<li class="toctree-l3"><a class="reference internal" href="#github-actions-example">GitHub Actions Example</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Performance Guide</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/performance.md" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="performance-guide">
<h1>Performance Guide<a class="headerlink" href="#performance-guide" title="Link to this heading"></a></h1>
<p>This guide covers performance optimization techniques and provides detailed comparisons with other archive tools.</p>
<section id="performance-tips">
<h2>Performance Tips<a class="headerlink" href="#performance-tips" title="Link to this heading"></a></h2>
<section id="compression-levels">
<h3>1. Compression Levels<a class="headerlink" href="#compression-levels" title="Link to this heading"></a></h3>
<p>Choose the right compression level for your use case:</p>
<ul class="simple">
<li><p><strong>Level 1-3</strong>: Fast compression, larger files (good for temporary archives or real-time processing)</p></li>
<li><p><strong>Level 3</strong> (default): Optimal balance for most use cases</p></li>
<li><p><strong>Level 6-9</strong>: Higher compression, moderate speed (good for regular backups)</p></li>
<li><p><strong>Level 15-22</strong>: Maximum compression, slower (for long-term storage or bandwidth-limited scenarios)</p></li>
</ul>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span>
<span class="c1"># For temporary files or frequent operations</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"temp.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="c1"># Balanced default (recommended)</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="c1"># Long-term storage</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"archive.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">9</span><span class="p">)</span>
<span class="c1"># Maximum compression for critical space savings</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"minimal.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">22</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="streaming">
<h3>2. Streaming<a class="headerlink" href="#streaming" title="Link to this heading"></a></h3>
<p>Use streaming mode for archives larger than 100MB:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">extract_archive</span><span class="p">,</span> <span class="n">list_archive</span><span class="p">,</span> <span class="n">test_archive</span>
<span class="c1"># Memory-efficient operations for large archives</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"large-backup.tzst"</span><span class="p">,</span> <span class="s2">"restore/"</span><span class="p">,</span> <span class="n">streaming</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">list_archive</span><span class="p">(</span><span class="s2">"large-backup.tzst"</span><span class="p">,</span> <span class="n">streaming</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">is_valid</span> <span class="o">=</span> <span class="n">test_archive</span><span class="p">(</span><span class="s2">"large-backup.tzst"</span><span class="p">,</span> <span class="n">streaming</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p><strong>Streaming Benefits:</strong></p>
<ul class="simple">
<li><p>Significantly reduced memory usage</p></li>
<li><p>Better performance for large archives</p></li>
<li><p>Handles archives that don’t fit in memory</p></li>
</ul>
</section>
<section id="batch-operations">
<h3>3. Batch Operations<a class="headerlink" href="#batch-operations" title="Link to this heading"></a></h3>
<p>Add multiple files in a single session when possible:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">TzstArchive</span>
<span class="c1"># Efficient: Single archive session</span>
<span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="n">archive</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"file1.txt"</span><span class="p">)</span>
<span class="n">archive</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"file2.txt"</span><span class="p">)</span>
<span class="n">archive</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"directory/"</span><span class="p">,</span> <span class="n">recursive</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="c1"># Less efficient: Multiple separate operations</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup1.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"file1.txt"</span><span class="p">])</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup2.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"file2.txt"</span><span class="p">])</span>
</pre></div>
</div>
</section>
<section id="file-type-considerations">
<h3>4. File Type Considerations<a class="headerlink" href="#file-type-considerations" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Already compressed files (<code class="docutils literal notranslate"><span class="pre">.jpg</span></code>, <code class="docutils literal notranslate"><span class="pre">.png</span></code>, <code class="docutils literal notranslate"><span class="pre">.mp4</span></code>, <code class="docutils literal notranslate"><span class="pre">.pdf</span></code>) won’t compress much further</p></li>
<li><p>Text files, source code, and logs compress very well</p></li>
<li><p>Consider compression level based on your data types</p></li>
</ul>
</section>
</section>
<section id="comparison-with-other-tools">
<h2>Comparison with Other Tools<a class="headerlink" href="#comparison-with-other-tools" title="Link to this heading"></a></h2>
<section id="vs-tar-gzip">
<h3>vs tar + gzip<a class="headerlink" href="#vs-tar-gzip" title="Link to this heading"></a></h3>
<p><strong>tzst Advantages:</strong></p>
<ul class="simple">
<li><p><strong>Better compression ratios</strong>: 10-40% smaller archives</p></li>
<li><p><strong>Faster decompression</strong>: 2-3x faster extraction</p></li>
<li><p><strong>Modern algorithm</strong>: Better handling of various file types</p></li>
<li><p><strong>Streaming support</strong>: Better memory efficiency</p></li>
</ul>
<p><strong>When to use tar + gzip:</strong></p>
<ul class="simple">
<li><p>Legacy system compatibility requirements</p></li>
<li><p>Very old systems without zstd support</p></li>
</ul>
</section>
<section id="vs-tar-xz">
<h3>vs tar + xz<a class="headerlink" href="#vs-tar-xz" title="Link to this heading"></a></h3>
<p><strong>tzst Advantages:</strong></p>
<ul class="simple">
<li><p><strong>Significantly faster compression</strong>: 3-10x faster creation</p></li>
<li><p><strong>Faster decompression</strong>: 2-4x faster extraction</p></li>
<li><p><strong>Better speed/compression trade-off</strong>: Similar compression with much better speed</p></li>
<li><p><strong>More compression levels</strong>: Fine-grained control (22 levels vs 9)</p></li>
</ul>
<p><strong>When to use tar + xz:</strong></p>
<ul class="simple">
<li><p>Maximum compression is critical and time is not a factor</p></li>
<li><p>Systems that don’t support zstd</p></li>
</ul>
</section>
<section id="vs-zip">
<h3>vs zip<a class="headerlink" href="#vs-zip" title="Link to this heading"></a></h3>
<p><strong>tzst Advantages:</strong></p>
<ul class="simple">
<li><p><strong>Better compression</strong>: 15-30% smaller archives</p></li>
<li><p><strong>Preserves Unix permissions and metadata</strong>: Full POSIX compatibility</p></li>
<li><p><strong>Better streaming support</strong>: Memory-efficient for large archives</p></li>
<li><p><strong>Better directory handling</strong>: Preserves directory structure and timestamps</p></li>
</ul>
<p><strong>When to use zip:</strong></p>
<ul class="simple">
<li><p>Cross-platform compatibility with very old systems</p></li>
<li><p>Individual file access without full extraction is required</p></li>
<li><p>Windows-centric environments with no command-line tools</p></li>
</ul>
</section>
</section>
<section id="benchmarking-examples">
<h2>Benchmarking Examples<a class="headerlink" href="#benchmarking-examples" title="Link to this heading"></a></h2>
<section id="compression-level-benchmark">
<h3>Compression Level Benchmark<a class="headerlink" href="#compression-level-benchmark" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">time</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">pathlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">Path</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span>
<span class="k">def</span><span class="w"> </span><span class="nf">benchmark_compression_levels</span><span class="p">(</span><span class="n">files</span><span class="p">,</span> <span class="n">output_prefix</span><span class="o">=</span><span class="s2">"benchmark"</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""Compare different compression levels."""</span>
<span class="n">levels_to_test</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">22</span><span class="p">]</span>
<span class="n">results</span> <span class="o">=</span> <span class="p">[]</span>
<span class="k">for</span> <span class="n">level</span> <span class="ow">in</span> <span class="n">levels_to_test</span><span class="p">:</span>
<span class="n">output_file</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">output_prefix</span><span class="si">}</span><span class="s2">_level_</span><span class="si">{</span><span class="n">level</span><span class="si">}</span><span class="s2">.tzst"</span>
<span class="c1"># Measure compression time</span>
<span class="n">start_time</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span>
<span class="n">create_archive</span><span class="p">(</span><span class="n">output_file</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="n">level</span><span class="p">)</span>
<span class="n">compress_time</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span> <span class="o">-</span> <span class="n">start_time</span>
<span class="c1"># Get file size</span>
<span class="n">file_size</span> <span class="o">=</span> <span class="n">Path</span><span class="p">(</span><span class="n">output_file</span><span class="p">)</span><span class="o">.</span><span class="n">stat</span><span class="p">()</span><span class="o">.</span><span class="n">st_size</span>
<span class="n">results</span><span class="o">.</span><span class="n">append</span><span class="p">({</span>
<span class="s1">'level'</span><span class="p">:</span> <span class="n">level</span><span class="p">,</span>
<span class="s1">'time'</span><span class="p">:</span> <span class="n">compress_time</span><span class="p">,</span>
<span class="s1">'size'</span><span class="p">:</span> <span class="n">file_size</span><span class="p">,</span>
<span class="s1">'size_mb'</span><span class="p">:</span> <span class="n">file_size</span> <span class="o">/</span> <span class="p">(</span><span class="mi">1024</span> <span class="o">*</span> <span class="mi">1024</span><span class="p">)</span>
<span class="p">})</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Level </span><span class="si">{</span><span class="n">level</span><span class="si">}</span><span class="s2">: </span><span class="si">{</span><span class="n">compress_time</span><span class="si">:</span><span class="s2">.2f</span><span class="si">}</span><span class="s2">s, </span><span class="si">{</span><span class="n">file_size</span><span class="o">/</span><span class="mi">1024</span><span class="o">/</span><span class="mi">1024</span><span class="si">:</span><span class="s2">.1f</span><span class="si">}</span><span class="s2"> MB"</span><span class="p">)</span>
<span class="k">return</span> <span class="n">results</span>
<span class="c1"># Example usage</span>
<span class="n">files</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"documents/"</span><span class="p">,</span> <span class="s2">"projects/"</span><span class="p">]</span>
<span class="n">results</span> <span class="o">=</span> <span class="n">benchmark_compression_levels</span><span class="p">(</span><span class="n">files</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="memory-usage-comparison">
<h3>Memory Usage Comparison<a class="headerlink" href="#memory-usage-comparison" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">psutil</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">os</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">extract_archive</span>
<span class="k">def</span><span class="w"> </span><span class="nf">monitor_memory_usage</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""Monitor memory usage during function execution."""</span>
<span class="n">process</span> <span class="o">=</span> <span class="n">psutil</span><span class="o">.</span><span class="n">Process</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">getpid</span><span class="p">())</span>
<span class="n">initial_memory</span> <span class="o">=</span> <span class="n">process</span><span class="o">.</span><span class="n">memory_info</span><span class="p">()</span><span class="o">.</span><span class="n">rss</span> <span class="o">/</span> <span class="mi">1024</span> <span class="o">/</span> <span class="mi">1024</span> <span class="c1"># MB</span>
<span class="n">func</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<span class="n">peak_memory</span> <span class="o">=</span> <span class="n">process</span><span class="o">.</span><span class="n">memory_info</span><span class="p">()</span><span class="o">.</span><span class="n">rss</span> <span class="o">/</span> <span class="mi">1024</span> <span class="o">/</span> <span class="mi">1024</span> <span class="c1"># MB</span>
<span class="k">return</span> <span class="n">peak_memory</span> <span class="o">-</span> <span class="n">initial_memory</span>
<span class="c1"># Compare streaming vs non-streaming extraction</span>
<span class="n">large_archive</span> <span class="o">=</span> <span class="s2">"large-dataset.tzst"</span>
<span class="n">memory_normal</span> <span class="o">=</span> <span class="n">monitor_memory_usage</span><span class="p">(</span><span class="n">extract_archive</span><span class="p">,</span> <span class="n">large_archive</span><span class="p">,</span> <span class="s2">"output1/"</span><span class="p">)</span>
<span class="n">memory_streaming</span> <span class="o">=</span> <span class="n">monitor_memory_usage</span><span class="p">(</span><span class="n">extract_archive</span><span class="p">,</span> <span class="n">large_archive</span><span class="p">,</span> <span class="s2">"output2/"</span><span class="p">,</span> <span class="n">streaming</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Normal extraction: </span><span class="si">{</span><span class="n">memory_normal</span><span class="si">:</span><span class="s2">.1f</span><span class="si">}</span><span class="s2"> MB"</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Streaming extraction: </span><span class="si">{</span><span class="n">memory_streaming</span><span class="si">:</span><span class="s2">.1f</span><span class="si">}</span><span class="s2"> MB"</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Memory savings: </span><span class="si">{</span><span class="n">memory_normal</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">memory_streaming</span><span class="si">:</span><span class="s2">.1f</span><span class="si">}</span><span class="s2"> MB"</span><span class="p">)</span>
</pre></div>
</div>
</section>
</section>
<section id="best-practices">
<h2>Best Practices<a class="headerlink" href="#best-practices" title="Link to this heading"></a></h2>
<section id="for-development">
<h3>For Development<a class="headerlink" href="#for-development" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Fast compression for frequent builds</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"build-artifacts.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"build/"</span><span class="p">],</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="for-backups">
<h3>For Backups<a class="headerlink" href="#for-backups" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Balanced compression for regular backups</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"daily-backup.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"data/"</span><span class="p">],</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="for-distribution">
<h3>For Distribution<a class="headerlink" href="#for-distribution" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Higher compression for software distribution</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"software-package.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"app/"</span><span class="p">],</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">9</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="for-archival-storage">
<h3>For Archival Storage<a class="headerlink" href="#for-archival-storage" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Maximum compression for long-term storage</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"archive-2024.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"historical-data/"</span><span class="p">],</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">22</span><span class="p">)</span>
</pre></div>
</div>
</section>
</section>
<section id="hardware-considerations">
<h2>Hardware Considerations<a class="headerlink" href="#hardware-considerations" title="Link to this heading"></a></h2>
<section id="cpu-usage">
<h3>CPU Usage<a class="headerlink" href="#cpu-usage" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Higher compression levels use more CPU but for shorter time periods</p></li>
<li><p>Modern multi-core systems handle zstd compression very efficiently</p></li>
<li><p>Consider system load when choosing compression levels</p></li>
</ul>
</section>
<section id="memory-usage">
<h3>Memory Usage<a class="headerlink" href="#memory-usage" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>Streaming mode: ~16-32 MB memory usage regardless of archive size</p></li>
<li><p>Normal mode: Memory usage proportional to archive size</p></li>
<li><p>Use streaming for archives &gt;100 MB or on memory-constrained systems</p></li>
</ul>
</section>
<section id="storage">
<h3>Storage<a class="headerlink" href="#storage" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p>SSDs benefit from higher compression (less I/O)</p></li>
<li><p>HDDs may prefer lower compression levels (CPU vs I/O trade-off)</p></li>
<li><p>Network storage benefits from higher compression (bandwidth savings)</p></li>
</ul>
</section>
</section>
<section id="integration-with-build-systems">
<h2>Integration with Build Systems<a class="headerlink" href="#integration-with-build-systems" title="Link to this heading"></a></h2>
<section id="makefile-example">
<h3>Makefile Example<a class="headerlink" href="#makefile-example" title="Link to this heading"></a></h3>
<div class="highlight-makefile notranslate"><div class="highlight"><pre><span></span><span class="c"># Fast compression for development</span>
<span class="nf">build-dev</span><span class="o">:</span><span class="w"> </span>
<span class="w"> </span>tzst<span class="w"> </span>a<span class="w"> </span>build-dev.tzst<span class="w"> </span>build/<span class="w"> </span>-l<span class="w"> </span><span class="m">1</span>
<span class="c"># Production compression</span>
<span class="nf">build-prod</span><span class="o">:</span>
<span class="w"> </span>tzst<span class="w"> </span>a<span class="w"> </span>build-prod.tzst<span class="w"> </span>build/<span class="w"> </span>-l<span class="w"> </span><span class="m">9</span>
<span class="c"># CI/CD artifacts</span>
<span class="nf">artifacts</span><span class="o">:</span>
<span class="w"> </span>tzst<span class="w"> </span>a<span class="w"> </span>artifacts.tzst<span class="w"> </span>dist/<span class="w"> </span>logs/<span class="w"> </span>-l<span class="w"> </span><span class="m">6</span>
</pre></div>
</div>
</section>
<section id="github-actions-example">
<h3>GitHub Actions Example<a class="headerlink" href="#github-actions-example" title="Link to this heading"></a></h3>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Create release archive</span>
<span class="w"> </span><span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">|</span>
<span class="w"> </span><span class="no">tzst a release-${{ github.ref_name }}.tzst \</span>
<span class="w"> </span><span class="no">build/ docs/ \</span>
<span class="w"> </span><span class="no">--compression-level 9</span>
</pre></div>
</div>
<p>This performance guide helps you choose the right settings for your specific use case and understand how tzst compares to alternative archive tools.</p>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="quickstart.html" class="btn btn-neutral float-left" title="Quick Start Guide" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="examples.html" class="btn btn-neutral float-right" title="Examples" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
+819
View File
@@ -0,0 +1,819 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta content="Quick start guide for tzst - Learn how to install and use the Python tar.zst archive library in minutes" name="description" />
<meta content="tzst tutorial, Python archive tutorial, tar.zst guide, Zstandard compression guide" name="keywords" />
<meta content="tzst Quick Start Guide" name="og:title" />
<meta content="Learn how to install and use tzst for Python tar.zst archive management in minutes" name="og:description" />
<meta content="tzst Quick Start Guide" name="twitter:title" />
<meta content="Learn how to install and use tzst for Python tar.zst archive management in minutes" name="twitter:description" />
<meta content="website" name="og:type" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="og:image" />
<meta content="https://tzst.xi-xu.me/" name="og:url" />
<meta content="summary_large_image" name="twitter:card" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="twitter:image" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Quick Start Guide &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/quickstart.html" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=3b3401d5"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="_static/opensearch.xml"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Performance Guide" href="performance.html" />
<link rel="prev" title="tzst Documentation" href="index.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Quick Start Guide",
"item": "https://tzst.xi-xu.me/quickstart.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "Quick Start Guide",
"description": "",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"publisher": {
"@type": "Person",
"name": "Xi Xu"
},
"datePublished": "2025-01-01",
"dateModified": "2025-01-12",
"url": "https://tzst.xi-xu.me/quickstart.html",
"inLanguage": "en-US",
"about": {
"@type": "SoftwareApplication",
"name": "tzst"
}
}
</script>
<!-- FAQ Schema for pages with common questions -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "How do I install tzst?",
"acceptedAnswer": {
"@type": "Answer",
"text": "You can install tzst using pip (pip install tzst), download standalone binaries from GitHub Releases, use uvx for no-installation usage (uvx tzst), or install from source."
}
},
{
"@type": "Question",
"name": "What compression levels does tzst support?",
"acceptedAnswer": {
"@type": "Answer",
"text": "tzst supports compression levels from 1 to 22. Level 1 is fastest with lower compression, level 3 is the default balance, and level 22 provides maximum compression but is slower."
}
},
{
"@type": "Question",
"name": "Is tzst secure for extracting untrusted archives?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes, tzst uses the 'data' security filter by default, which protects against path traversal attacks and blocks dangerous files. This makes it safe for extracting untrusted archives."
}
},
{
"@type": "Question",
"name": "When should I use streaming mode?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Use streaming mode for archives larger than 100MB to reduce memory usage. Streaming mode is memory-efficient but has limitations such as no random access or specific file extraction."
}
},
{
"@type": "Question",
"name": "What file extensions does tzst support?",
"acceptedAnswer": {
"@type": "Answer",
"text": "tzst supports both .tzst and .tar.zst file extensions. The library automatically handles extension detection and normalization when creating or opening archives."
}
}
]
}
</script>
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/quickstart.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="index.html" class="icon icon-home">
tzst
<img src="_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Quick Start Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#from-github-releases">From GitHub Releases</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#supported-platforms">Supported Platforms</a></li>
<li class="toctree-l4"><a class="reference internal" href="#installation-steps">🛠️ Installation Steps</a></li>
<li class="toctree-l4"><a class="reference internal" href="#benefits-of-binary-installation">🎯 Benefits of Binary Installation</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#from-pypi">From PyPI</a></li>
<li class="toctree-l3"><a class="reference internal" href="#from-source">From Source</a></li>
<li class="toctree-l3"><a class="reference internal" href="#development-installation">Development Installation</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#basic-usage">Basic Usage</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#command-line-interface">Command Line Interface</a></li>
<li class="toctree-l3"><a class="reference internal" href="#command-reference">Command Reference</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cli-options">CLI Options</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#create-archives">Create Archives</a></li>
<li class="toctree-l4"><a class="reference internal" href="#extract-archives">Extract Archives</a></li>
<li class="toctree-l4"><a class="reference internal" href="#list-contents">List Contents</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#python-api">Python API</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#quick-start">Quick Start</a></li>
<li class="toctree-l4"><a class="reference internal" href="#using-the-tzstarchive-class">Using the TzstArchive Class</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#advanced-features">Advanced Features</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#security-and-filtering">Security and Filtering</a></li>
<li class="toctree-l3"><a class="reference internal" href="#security-filters">Security Filters</a></li>
<li class="toctree-l3"><a class="reference internal" href="#conflict-resolution">Conflict Resolution</a></li>
<li class="toctree-l3"><a class="reference internal" href="#performance-optimization">Performance Optimization</a></li>
<li class="toctree-l3"><a class="reference internal" href="#streaming-mode">Streaming Mode</a></li>
<li class="toctree-l3"><a class="reference internal" href="#file-extensions">File Extensions</a></li>
<li class="toctree-l3"><a class="reference internal" href="#atomic-operations">Atomic Operations</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#error-handling">Error Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="#next-steps">Next Steps</a></li>
<li class="toctree-l2"><a class="reference internal" href="#read-an-existing-archive">Read an Existing Archive</a></li>
<li class="toctree-l2"><a class="reference internal" href="#common-patterns">Common Patterns</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#backup-script">Backup Script</a></li>
<li class="toctree-l3"><a class="reference internal" href="#archive-verification">Archive Verification</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#further-learning">Further Learning</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Quick Start Guide</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/quickstart.md" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="quick-start-guide">
<h1>Quick Start Guide<a class="headerlink" href="#quick-start-guide" title="Link to this heading"></a></h1>
<p>This guide will get you up and running with tzst in just a few minutes.</p>
<section id="installation">
<span id="id1"></span><h2>Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h2>
<p>Choose your preferred installation method:</p>
<section id="from-github-releases">
<h3>From GitHub Releases<a class="headerlink" href="#from-github-releases" title="Link to this heading"></a></h3>
<p>Download standalone executables that don’t require Python installation:</p>
<section id="supported-platforms">
<h4>Supported Platforms<a class="headerlink" href="#supported-platforms" title="Link to this heading"></a></h4>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Platform</p></th>
<th class="head"><p>Architecture</p></th>
<th class="head"><p>File</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><strong>🐧 Linux</strong></p></td>
<td><p>x86_64</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tzst-{version}-linux-amd64.zip</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><strong>🐧 Linux</strong></p></td>
<td><p>ARM64</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tzst-{version}-linux-arm64.zip</span></code></p></td>
</tr>
<tr class="row-even"><td><p><strong>🪟 Windows</strong></p></td>
<td><p>x64</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tzst-{version}-windows-amd64.zip</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><strong>🪟 Windows</strong></p></td>
<td><p>ARM64</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tzst-{version}-windows-arm64.zip</span></code></p></td>
</tr>
<tr class="row-even"><td><p><strong>🍎 macOS</strong></p></td>
<td><p>Intel</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tzst-{version}-darwin-amd64.zip</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><strong>🍎 macOS</strong></p></td>
<td><p>Apple Silicon</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tzst-{version}-darwin-arm64.zip</span></code></p></td>
</tr>
</tbody>
</table>
</section>
<section id="installation-steps">
<h4>🛠️ Installation Steps<a class="headerlink" href="#installation-steps" title="Link to this heading"></a></h4>
<ol class="arabic simple">
<li><p><strong>📥 Download</strong> the appropriate archive for your platform from the <a class="reference external" href="https://github.com/xixu-me/tzst/releases/latest">latest releases page</a></p></li>
<li><p><strong>📦 Extract</strong> the archive to get the <code class="docutils literal notranslate"><span class="pre">tzst</span></code> executable (or <code class="docutils literal notranslate"><span class="pre">tzst.exe</span></code> on Windows)</p></li>
<li><p><strong>📂 Move</strong> the executable to a directory in your PATH:</p>
<ul class="simple">
<li><p><strong>🐧 Linux/macOS</strong>: <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">mv</span> <span class="pre">tzst</span> <span class="pre">/usr/local/bin/</span></code></p></li>
<li><p><strong>🪟 Windows</strong>: Add the directory containing <code class="docutils literal notranslate"><span class="pre">tzst.exe</span></code> to your PATH environment variable</p></li>
</ul>
</li>
<li><p><strong>✅ Verify</strong> installation: <code class="docutils literal notranslate"><span class="pre">tzst</span> <span class="pre">--help</span></code></p></li>
</ol>
</section>
<section id="benefits-of-binary-installation">
<h4>🎯 Benefits of Binary Installation<a class="headerlink" href="#benefits-of-binary-installation" title="Link to this heading"></a></h4>
<ul class="simple">
<li><p>✅ <strong>No Python required</strong> - Standalone executable</p></li>
<li><p>✅ <strong>Faster startup</strong> - No Python interpreter overhead</p></li>
<li><p>✅ <strong>Easy deployment</strong> - Single file distribution</p></li>
<li><p>✅ <strong>Consistent behavior</strong> - Bundled dependencies</p></li>
</ul>
</section>
</section>
<section id="from-pypi">
<h3>From PyPI<a class="headerlink" href="#from-pypi" title="Link to this heading"></a></h3>
<p>Using pip:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>tzst
</pre></div>
</div>
<p>Or using uv (recommended):</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>uv<span class="w"> </span>tool<span class="w"> </span>install<span class="w"> </span>tzst
</pre></div>
</div>
</section>
<section id="from-source">
<h3>From Source<a class="headerlink" href="#from-source" title="Link to this heading"></a></h3>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/xixu-me/tzst.git
<span class="nb">cd</span><span class="w"> </span>tzst
pip<span class="w"> </span>install<span class="w"> </span>.
</pre></div>
</div>
</section>
<section id="development-installation">
<h3>Development Installation<a class="headerlink" href="#development-installation" title="Link to this heading"></a></h3>
<p>This project uses modern Python packaging standards:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/xixu-me/tzst.git
<span class="nb">cd</span><span class="w"> </span>tzst
pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>.<span class="o">[</span>dev<span class="o">]</span>
</pre></div>
</div>
</section>
</section>
<section id="basic-usage">
<span id="id2"></span><h2>Basic Usage<a class="headerlink" href="#basic-usage" title="Link to this heading"></a></h2>
<section id="command-line-interface">
<h3>Command Line Interface<a class="headerlink" href="#command-line-interface" title="Link to this heading"></a></h3>
<blockquote>
<div><p><strong>Note</strong>: Download the <a class="reference internal" href="#installation"><span class="std std-ref">standalone binary</span></a> for the best performance and no Python dependency. Alternatively, use <code class="docutils literal notranslate"><span class="pre">uvx</span> <span class="pre">tzst</span></code> for running without installation. See <a class="reference external" href="https://docs.astral.sh/uv/">uv documentation</a> for details.</p>
</div></blockquote>
<p>The CLI provides four main operations:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create an archive</span>
tzst<span class="w"> </span>a<span class="w"> </span>archive.tzst<span class="w"> </span>file1.txt<span class="w"> </span>file2.txt<span class="w"> </span>directory/
<span class="c1"># Extract an archive </span>
tzst<span class="w"> </span>x<span class="w"> </span>archive.tzst
<span class="c1"># List archive contents</span>
tzst<span class="w"> </span>l<span class="w"> </span>archive.tzst
<span class="c1"># Test archive integrity</span>
tzst<span class="w"> </span>t<span class="w"> </span>archive.tzst
</pre></div>
</div>
</section>
<section id="command-reference">
<h3>Command Reference<a class="headerlink" href="#command-reference" title="Link to this heading"></a></h3>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Command</p></th>
<th class="head"><p>Aliases</p></th>
<th class="head"><p>Description</p></th>
<th class="head"><p>Streaming Support</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">a</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">add</span></code>, <code class="docutils literal notranslate"><span class="pre">create</span></code></p></td>
<td><p>Create or add to archive</p></td>
<td><p>N/A</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">extract</span></code></p></td>
<td><p>Extract with full paths</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">e</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">extract-flat</span></code></p></td>
<td><p>Extract without directory structure</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">l</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">list</span></code></p></td>
<td><p>List archive contents</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">test</span></code></p></td>
<td><p>Test archive integrity</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
</tbody>
</table>
</section>
<section id="cli-options">
<h3>CLI Options<a class="headerlink" href="#cli-options" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">-v,</span> <span class="pre">--verbose</span></code>: Enable verbose output</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-o,</span> <span class="pre">--output</span> <span class="pre">DIR</span></code>: Specify output directory (extract commands)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-l,</span> <span class="pre">--level</span> <span class="pre">LEVEL</span></code>: Set compression level 1-22 (create command)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code>: Enable streaming mode for memory-efficient processing</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--filter</span> <span class="pre">FILTER</span></code>: Security filter for extraction (data/tar/fully_trusted)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--no-atomic</span></code>: Disable atomic file operations (not recommended)</p></li>
</ul>
<section id="create-archives">
<h4>Create Archives<a class="headerlink" href="#create-archives" title="Link to this heading"></a></h4>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create archive with default compression (level 3)</span>
tzst<span class="w"> </span>a<span class="w"> </span>backup.tzst<span class="w"> </span>documents/<span class="w"> </span>photos/
<span class="c1"># Create with high compression</span>
tzst<span class="w"> </span>a<span class="w"> </span>backup.tzst<span class="w"> </span>documents/<span class="w"> </span>photos/<span class="w"> </span>--compression-level<span class="w"> </span><span class="m">9</span>
<span class="c1"># Create from current directory</span>
tzst<span class="w"> </span>a<span class="w"> </span>project.tzst<span class="w"> </span>.
<span class="c1"># Specify different output location</span>
tzst<span class="w"> </span>a<span class="w"> </span>/backups/data.tzst<span class="w"> </span>/home/user/important/
</pre></div>
</div>
</section>
<section id="extract-archives">
<h4>Extract Archives<a class="headerlink" href="#extract-archives" title="Link to this heading"></a></h4>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Extract to current directory</span>
tzst<span class="w"> </span>x<span class="w"> </span>backup.tzst
<span class="c1"># Extract to specific directory</span>
tzst<span class="w"> </span>x<span class="w"> </span>backup.tzst<span class="w"> </span>--output<span class="w"> </span>/restore/
<span class="c1"># Extract specific files only</span>
tzst<span class="w"> </span>x<span class="w"> </span>backup.tzst<span class="w"> </span>documents/report.pdf<span class="w"> </span>photos/vacation.jpg
<span class="c1"># Extract with conflict resolution</span>
tzst<span class="w"> </span>x<span class="w"> </span>backup.tzst<span class="w"> </span>--conflict-resolution<span class="w"> </span>skip
</pre></div>
</div>
</section>
<section id="list-contents">
<h4>List Contents<a class="headerlink" href="#list-contents" title="Link to this heading"></a></h4>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Simple listing</span>
tzst<span class="w"> </span>l<span class="w"> </span>backup.tzst
<span class="c1"># Detailed listing with file info</span>
tzst<span class="w"> </span>l<span class="w"> </span>backup.tzst<span class="w"> </span>--verbose
<span class="c1"># Stream large archives efficiently</span>
tzst<span class="w"> </span>l<span class="w"> </span>huge-archive.tzst<span class="w"> </span>--streaming
</pre></div>
</div>
</section>
</section>
<section id="python-api">
<h3>Python API<a class="headerlink" href="#python-api" title="Link to this heading"></a></h3>
<section id="quick-start">
<h4>Quick Start<a class="headerlink" href="#quick-start" title="Link to this heading"></a></h4>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span><span class="p">,</span> <span class="n">extract_archive</span><span class="p">,</span> <span class="n">list_archive</span><span class="p">,</span> <span class="n">test_archive</span>
<span class="c1"># Create an archive</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"documents/"</span><span class="p">,</span> <span class="s2">"photos/"</span><span class="p">],</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
<span class="c1"># Extract an archive</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="s2">"restore/"</span><span class="p">)</span>
<span class="c1"># List contents</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">list_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">contents</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">item</span><span class="p">[</span><span class="s1">'name'</span><span class="p">]</span><span class="si">}</span><span class="s2"> - </span><span class="si">{</span><span class="n">item</span><span class="p">[</span><span class="s1">'size'</span><span class="p">]</span><span class="si">}</span><span class="s2"> bytes"</span><span class="p">)</span>
<span class="c1"># Test integrity</span>
<span class="n">is_valid</span> <span class="o">=</span> <span class="n">test_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive is </span><span class="si">{</span><span class="s1">'valid'</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="n">is_valid</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="s1">'corrupted'</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="using-the-tzstarchive-class">
<h4>Using the TzstArchive Class<a class="headerlink" href="#using-the-tzstarchive-class" title="Link to this heading"></a></h4>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">TzstArchive</span>
<span class="c1"># Create a new archive</span>
<span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"data.tzst"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="n">archive</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"file.txt"</span><span class="p">)</span>
<span class="n">archive</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"directory/"</span><span class="p">,</span> <span class="n">recursive</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="c1"># Add with custom archive name</span>
<span class="n">archive</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"config/prod.yaml"</span><span class="p">,</span> <span class="n">arcname</span><span class="o">=</span><span class="s2">"config.yaml"</span><span class="p">)</span>
<span class="c1"># Read an existing archive</span>
<span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"data.tzst"</span><span class="p">,</span> <span class="s2">"r"</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="c1"># List contents</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">list</span><span class="p">(</span><span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">contents</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">item</span><span class="p">[</span><span class="s1">'name'</span><span class="p">]</span><span class="si">}</span><span class="s2"> - </span><span class="si">{</span><span class="n">item</span><span class="p">[</span><span class="s1">'size'</span><span class="p">]</span><span class="si">}</span><span class="s2"> bytes"</span><span class="p">)</span>
<span class="c1"># Test integrity</span>
<span class="n">is_valid</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">test</span><span class="p">()</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive is </span><span class="si">{</span><span class="s1">'valid'</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="n">is_valid</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="s1">'corrupted'</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="c1"># Extract specific files</span>
<span class="n">archive</span><span class="o">.</span><span class="n">extract</span><span class="p">(</span><span class="s2">"file.txt"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">)</span>
<span class="c1"># Extract all files</span>
<span class="n">archive</span><span class="o">.</span><span class="n">extractall</span><span class="p">(</span><span class="s2">"restore/"</span><span class="p">)</span>
</pre></div>
</div>
</section>
</section>
</section>
<section id="advanced-features">
<h2>Advanced Features<a class="headerlink" href="#advanced-features" title="Link to this heading"></a></h2>
<section id="security-and-filtering">
<h3>Security and Filtering<a class="headerlink" href="#security-and-filtering" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">extract_archive</span>
<span class="c1"># Safe extraction with built-in security (default)</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"untrusted.tzst"</span><span class="p">,</span> <span class="s2">"safe-output/"</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="s2">"data"</span><span class="p">)</span>
<span class="c1"># For trusted archives with special features</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"trusted.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="s2">"tar"</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="security-filters">
<h3>Security Filters<a class="headerlink" href="#security-filters" title="Link to this heading"></a></h3>
<p>tzst provides three security filter options for extraction:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">extract_archive</span>
<span class="c1"># Extract with maximum security (default)</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"archive.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="s2">"data"</span><span class="p">)</span>
<span class="c1"># Extract with standard tar compatibility</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"archive.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="s2">"tar"</span><span class="p">)</span>
<span class="c1"># Extract with full trust (dangerous - only for trusted archives)</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"archive.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="s2">"fully_trusted"</span><span class="p">)</span>
</pre></div>
</div>
<p><strong>Security Filter Options:</strong></p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">data</span></code> (default): Most secure. Blocks dangerous files, absolute paths, and paths outside extraction directory</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">tar</span></code>: Standard tar compatibility. Blocks absolute paths and directory traversal</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fully_trusted</span></code>: No security restrictions. Only use with completely trusted archives</p></li>
</ul>
</section>
<section id="conflict-resolution">
<h3>Conflict Resolution<a class="headerlink" href="#conflict-resolution" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">extract_archive</span><span class="p">,</span> <span class="n">ConflictResolution</span>
<span class="c1"># Skip existing files</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"archive.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span>
<span class="n">conflict_resolution</span><span class="o">=</span><span class="n">ConflictResolution</span><span class="o">.</span><span class="n">SKIP_ALL</span><span class="p">)</span>
<span class="c1"># Auto-rename conflicting files</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"archive.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span>
<span class="n">conflict_resolution</span><span class="o">=</span><span class="n">ConflictResolution</span><span class="o">.</span><span class="n">AUTO_RENAME_ALL</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="performance-optimization">
<h3>Performance Optimization<a class="headerlink" href="#performance-optimization" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span><span class="p">,</span> <span class="n">extract_archive</span>
<span class="c1"># Create with different compression levels</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"fast.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span> <span class="c1"># Fastest</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"balanced.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span> <span class="c1"># Balanced</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"best.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">22</span><span class="p">)</span> <span class="c1"># Best compression</span>
<span class="c1"># Memory-efficient operations for large archives</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"huge-archive.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span> <span class="n">streaming</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="streaming-mode">
<h3>Streaming Mode<a class="headerlink" href="#streaming-mode" title="Link to this heading"></a></h3>
<p>For large archives (&gt;100MB), use streaming mode to reduce memory usage:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Memory-efficient operations</span>
<span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"large-archive.tzst"</span><span class="p">,</span> <span class="s2">"r"</span><span class="p">,</span> <span class="n">streaming</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">list</span><span class="p">()</span>
<span class="n">archive</span><span class="o">.</span><span class="n">extractall</span><span class="p">(</span><span class="s2">"output/"</span><span class="p">)</span>
<span class="n">is_valid</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">test</span><span class="p">()</span>
</pre></div>
</div>
<p><strong>Note</strong>: Streaming mode has limitations - you cannot extract specific files or use random access operations.</p>
</section>
<section id="file-extensions">
<h3>File Extensions<a class="headerlink" href="#file-extensions" title="Link to this heading"></a></h3>
<p>The library automatically handles file extensions with intelligent normalization:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">.tzst</span></code> - Primary extension for tar+zstandard archives</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">.tar.zst</span></code> - Alternative standard extension</p></li>
<li><p>Auto-detection when opening existing archives</p></li>
<li><p>Automatic extension addition when creating archives</p></li>
</ul>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span>
<span class="c1"># These all create valid archives</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">)</span> <span class="c1"># Creates backup.tzst</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.tar.zst"</span><span class="p">,</span> <span class="n">files</span><span class="p">)</span> <span class="c1"># Creates backup.tar.zst </span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup"</span><span class="p">,</span> <span class="n">files</span><span class="p">)</span> <span class="c1"># Creates backup.tzst</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.txt"</span><span class="p">,</span> <span class="n">files</span><span class="p">)</span> <span class="c1"># Creates backup.tzst (normalized)</span>
</pre></div>
</div>
</section>
<section id="atomic-operations">
<h3>Atomic Operations<a class="headerlink" href="#atomic-operations" title="Link to this heading"></a></h3>
<p>All file creation operations use atomic file operations by default:</p>
<ul class="simple">
<li><p>Archives created in temporary files first, then atomically moved</p></li>
<li><p>Automatic cleanup if process is interrupted</p></li>
<li><p>No risk of corrupted or incomplete archives</p></li>
<li><p>Cross-platform compatibility</p></li>
</ul>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Atomic operations enabled by default</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"important.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">)</span> <span class="c1"># Safe from interruption</span>
<span class="c1"># Can be disabled if needed (not recommended)</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"test.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">use_temp_file</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</pre></div>
</div>
</section>
</section>
<section id="error-handling">
<h2>Error Handling<a class="headerlink" href="#error-handling" title="Link to this heading"></a></h2>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span><span class="p">,</span> <span class="n">TzstArchiveError</span><span class="p">,</span> <span class="n">TzstCompressionError</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"documents/"</span><span class="p">])</span>
<span class="k">except</span> <span class="n">TzstCompressionError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Compression failed: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">except</span> <span class="n">TzstArchiveError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive operation failed: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Unexpected error: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="next-steps">
<h2>Next Steps<a class="headerlink" href="#next-steps" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p>Explore comprehensive <a class="reference internal" href="examples.html"><span class="doc">Examples</span></a> for real-world scenarios</p></li>
<li><p>Check the <a class="reference internal" href="api/index.html"><span class="doc">API Reference</span></a> for detailed API documentation</p></li>
<li><p>See advanced features like atomic operations and custom filters</p></li>
<li><p>Learn about integration with web frameworks and automation tools</p></li>
</ul>
</section>
<section id="read-an-existing-archive">
<h2>Read an Existing Archive<a class="headerlink" href="#read-an-existing-archive" title="Link to this heading"></a></h2>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"data.tzst"</span><span class="p">,</span> <span class="s2">"r"</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="c1"># List contents</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">list</span><span class="p">(</span><span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="c1"># Extract specific file</span>
<span class="n">archive</span><span class="o">.</span><span class="n">extract</span><span class="p">(</span><span class="s2">"file.txt"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">)</span>
<span class="c1"># Test integrity</span>
<span class="n">is_valid</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">test</span><span class="p">()</span>
<span class="c1"># Get raw member information</span>
<span class="n">members</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">getmembers</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="common-patterns">
<h2>Common Patterns<a class="headerlink" href="#common-patterns" title="Link to this heading"></a></h2>
<section id="backup-script">
<h3>Backup Script<a class="headerlink" href="#backup-script" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python3</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">pathlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">Path</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span>
<span class="k">def</span><span class="w"> </span><span class="nf">create_backup</span><span class="p">():</span>
<span class="n">timestamp</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s2">"%Y%m</span><span class="si">%d</span><span class="s2">_%H%M%S"</span><span class="p">)</span>
<span class="n">backup_name</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">"backup_</span><span class="si">{</span><span class="n">timestamp</span><span class="si">}</span><span class="s2">.tzst"</span>
<span class="c1"># Backup important directories</span>
<span class="n">directories</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"documents/"</span><span class="p">,</span> <span class="s2">"projects/"</span><span class="p">,</span> <span class="s2">"config/"</span><span class="p">]</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Creating backup: </span><span class="si">{</span><span class="n">backup_name</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="n">create_archive</span><span class="p">(</span><span class="n">backup_name</span><span class="p">,</span> <span class="n">directories</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Backup created: </span><span class="si">{</span><span class="n">Path</span><span class="p">(</span><span class="n">backup_name</span><span class="p">)</span><span class="o">.</span><span class="n">stat</span><span class="p">()</span><span class="o">.</span><span class="n">st_size</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="mi">1024</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="mi">1024</span><span class="si">:</span><span class="s2">.1f</span><span class="si">}</span><span class="s2"> MB"</span><span class="p">)</span>
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>
<span class="n">create_backup</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="archive-verification">
<h3>Archive Verification<a class="headerlink" href="#archive-verification" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">test_archive</span><span class="p">,</span> <span class="n">list_archive</span>
<span class="k">def</span><span class="w"> </span><span class="nf">verify_archive</span><span class="p">(</span><span class="n">archive_path</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Verifying </span><span class="si">{</span><span class="n">archive_path</span><span class="si">}</span><span class="s2">..."</span><span class="p">)</span>
<span class="c1"># Test integrity</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">test_archive</span><span class="p">(</span><span class="n">archive_path</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"Archive is corrupted!"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="c1"># List contents</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">list_archive</span><span class="p">(</span><span class="n">archive_path</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">total_size</span> <span class="o">=</span> <span class="nb">sum</span><span class="p">(</span><span class="n">item</span><span class="p">[</span><span class="s1">'size'</span><span class="p">]</span> <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">contents</span> <span class="k">if</span> <span class="n">item</span><span class="p">[</span><span class="s1">'is_file'</span><span class="p">])</span>
<span class="n">file_count</span> <span class="o">=</span> <span class="nb">sum</span><span class="p">(</span><span class="mi">1</span> <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">contents</span> <span class="k">if</span> <span class="n">item</span><span class="p">[</span><span class="s1">'is_file'</span><span class="p">])</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive is valid"</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Files: </span><span class="si">{</span><span class="n">file_count</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Total size: </span><span class="si">{</span><span class="n">total_size</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="mi">1024</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="mi">1024</span><span class="si">:</span><span class="s2">.1f</span><span class="si">}</span><span class="s2"> MB"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">True</span>
</pre></div>
</div>
</section>
</section>
<section id="further-learning">
<h2>Further Learning<a class="headerlink" href="#further-learning" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p>Explore <a class="reference internal" href="examples.html"><span class="doc">Examples</span></a> for more advanced usage patterns</p></li>
<li><p>Check <a class="reference internal" href="performance.html"><span class="doc">Performance Guide</span></a> for detailed performance guidance</p></li>
<li><p>Refer to the <a class="reference internal" href="api/index.html"><span class="doc">API Reference</span></a> for complete API documentation</p></li>
</ul>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="index.html" class="btn btn-neutral float-left" title="tzst Documentation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="performance.html" class="btn btn-neutral float-right" title="Performance Guide" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
+213
View File
@@ -0,0 +1,213 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Search &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/search.html" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=3b3401d5"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="_static/opensearch.xml"/>
<script src="_static/searchtools.js"></script>
<script src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="#" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Search",
"item": "https://tzst.xi-xu.me/search.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/search.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="index.html" class="icon icon-home">
tzst
<img src="_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="#" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Search</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<noscript>
<div id="fallback" class="admonition warning">
<p class="last">
Please activate JavaScript to enable the search functionality.
</p>
</div>
</noscript>
<div id="search-results">
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
<script>
jQuery(function() { Search.loadIndex("searchindex.js"); });
</script>
<script id="searchindexloader"></script>
</body>
</html>
Loaded 100 of 102 files, more files were not shown because too many files have changed in this diff. Show more