Deploy documentation from 1efdd4c091 1efdd4c091
No files matched your search
@@ -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
|
||||
@@ -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 — 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 & 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>© Copyright 2026, Xi Xu.</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -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 — 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>© Copyright 2026, Xi Xu.</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -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 — 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>© Copyright 2026, Xi Xu.</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -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 — 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>© 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;
|
||||
}
|
||||
@@ -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);
|
||||
};
|
||||
};
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
@@ -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}
|
||||
|
After Width: | Height: | Size: 434 KiB |
@@ -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
|
||||
@@ -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);
|
||||
@@ -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,
|
||||
};
|
||||
|
After Width: | Height: | Size: 48 KiB |
|
After Width: | Height: | Size: 286 B |
@@ -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
|
||||
@@ -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){}});
|
||||
@@ -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
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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;
|
||||
|
After Width: | Height: | Size: 90 B |
@@ -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>
|
||||
|
After Width: | Height: | Size: 90 B |
@@ -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 */
|
||||
@@ -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
|
||||
@@ -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("&", "&")
|
||||
.replaceAll("<", "<")
|
||||
.replaceAll(">", ">")
|
||||
.replaceAll('"', """)
|
||||
.replaceAll("'", "'");
|
||||
};
|
||||
|
||||
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);
|
||||
@@ -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();
|
||||
});
|
||||
|
After Width: | Height: | Size: 513 KiB |
|
After Width: | Height: | Size: 995 KiB |
@@ -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 — 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">→</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">→</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">→</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 > 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">→</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 > 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">→</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 > 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">→</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">→</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">→</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">>>> </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">>>> </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">>>> </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">→</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">→</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">→</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">→</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">→</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">→</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">→</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">>>> </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">>>> </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">>>> </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">→</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 (>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>© Copyright 2026, Xi Xu.</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -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 — 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>© Copyright 2026, Xi Xu.</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -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 — 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>© Copyright 2026, Xi Xu.</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -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 — 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>© Copyright 2026, Xi Xu.</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -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 — 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>© Copyright 2026, Xi Xu.</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -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 — 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 >= 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>© Copyright 2026, Xi Xu.</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -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 — 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 >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>© Copyright 2026, Xi Xu.</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -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 — 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 (>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>© Copyright 2026, Xi Xu.</p>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -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 — 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>© 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>
|
||||