Files
tzst/quickstart.html
T

819 lines
57 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta content="Quick start guide for tzst - Learn how to install and use the Python tar.zst archive library in minutes" name="description" />
<meta content="tzst tutorial, Python archive tutorial, tar.zst guide, Zstandard compression guide" name="keywords" />
<meta content="tzst Quick Start Guide" name="og:title" />
<meta content="Learn how to install and use tzst for Python tar.zst archive management in minutes" name="og:description" />
<meta content="tzst Quick Start Guide" name="twitter:title" />
<meta content="Learn how to install and use tzst for Python tar.zst archive management in minutes" name="twitter:description" />
<meta content="website" name="og:type" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="og:image" />
<meta content="https://tzst.xi-xu.me/" name="og:url" />
<meta content="summary_large_image" name="twitter:card" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="twitter:image" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Quick Start Guide &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/quickstart.html" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=3b3401d5"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="_static/opensearch.xml"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Performance Guide" href="performance.html" />
<link rel="prev" title="tzst Documentation" href="index.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Quick Start Guide",
"item": "https://tzst.xi-xu.me/quickstart.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "Quick Start Guide",
"description": "",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"publisher": {
"@type": "Person",
"name": "Xi Xu"
},
"datePublished": "2025-01-01",
"dateModified": "2025-01-12",
"url": "https://tzst.xi-xu.me/quickstart.html",
"inLanguage": "en-US",
"about": {
"@type": "SoftwareApplication",
"name": "tzst"
}
}
</script>
<!-- FAQ Schema for pages with common questions -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "How do I install tzst?",
"acceptedAnswer": {
"@type": "Answer",
"text": "You can install tzst using pip (pip install tzst), download standalone binaries from GitHub Releases, use uvx for no-installation usage (uvx tzst), or install from source."
}
},
{
"@type": "Question",
"name": "What compression levels does tzst support?",
"acceptedAnswer": {
"@type": "Answer",
"text": "tzst supports compression levels from 1 to 22. Level 1 is fastest with lower compression, level 3 is the default balance, and level 22 provides maximum compression but is slower."
}
},
{
"@type": "Question",
"name": "Is tzst secure for extracting untrusted archives?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes, tzst uses the 'data' security filter by default, which protects against path traversal attacks and blocks dangerous files. This makes it safe for extracting untrusted archives."
}
},
{
"@type": "Question",
"name": "When should I use streaming mode?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Use streaming mode for archives larger than 100MB to reduce memory usage. Streaming mode is memory-efficient but has limitations such as no random access or specific file extraction."
}
},
{
"@type": "Question",
"name": "What file extensions does tzst support?",
"acceptedAnswer": {
"@type": "Answer",
"text": "tzst supports both .tzst and .tar.zst file extensions. The library automatically handles extension detection and normalization when creating or opening archives."
}
}
]
}
</script>
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/quickstart.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="index.html" class="icon icon-home">
tzst
<img src="_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Quick Start Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#from-github-releases">From GitHub Releases</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#supported-platforms">Supported Platforms</a></li>
<li class="toctree-l4"><a class="reference internal" href="#installation-steps">🛠️ Installation Steps</a></li>
<li class="toctree-l4"><a class="reference internal" href="#benefits-of-binary-installation">🎯 Benefits of Binary Installation</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#from-pypi">From PyPI</a></li>
<li class="toctree-l3"><a class="reference internal" href="#from-source">From Source</a></li>
<li class="toctree-l3"><a class="reference internal" href="#development-installation">Development Installation</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#basic-usage">Basic Usage</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#command-line-interface">Command Line Interface</a></li>
<li class="toctree-l3"><a class="reference internal" href="#command-reference">Command Reference</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cli-options">CLI Options</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#create-archives">Create Archives</a></li>
<li class="toctree-l4"><a class="reference internal" href="#extract-archives">Extract Archives</a></li>
<li class="toctree-l4"><a class="reference internal" href="#list-contents">List Contents</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#python-api">Python API</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#quick-start">Quick Start</a></li>
<li class="toctree-l4"><a class="reference internal" href="#using-the-tzstarchive-class">Using the TzstArchive Class</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#advanced-features">Advanced Features</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#security-and-filtering">Security and Filtering</a></li>
<li class="toctree-l3"><a class="reference internal" href="#security-filters">Security Filters</a></li>
<li class="toctree-l3"><a class="reference internal" href="#conflict-resolution">Conflict Resolution</a></li>
<li class="toctree-l3"><a class="reference internal" href="#performance-optimization">Performance Optimization</a></li>
<li class="toctree-l3"><a class="reference internal" href="#streaming-mode">Streaming Mode</a></li>
<li class="toctree-l3"><a class="reference internal" href="#file-extensions">File Extensions</a></li>
<li class="toctree-l3"><a class="reference internal" href="#atomic-operations">Atomic Operations</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#error-handling">Error Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="#next-steps">Next Steps</a></li>
<li class="toctree-l2"><a class="reference internal" href="#read-an-existing-archive">Read an Existing Archive</a></li>
<li class="toctree-l2"><a class="reference internal" href="#common-patterns">Common Patterns</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#backup-script">Backup Script</a></li>
<li class="toctree-l3"><a class="reference internal" href="#archive-verification">Archive Verification</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#further-learning">Further Learning</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Quick Start Guide</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/quickstart.md" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="quick-start-guide">
<h1>Quick Start Guide<a class="headerlink" href="#quick-start-guide" title="Link to this heading"></a></h1>
<p>This guide will get you up and running with tzst in just a few minutes.</p>
<section id="installation">
<span id="id1"></span><h2>Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h2>
<p>Choose your preferred installation method:</p>
<section id="from-github-releases">
<h3>From GitHub Releases<a class="headerlink" href="#from-github-releases" title="Link to this heading"></a></h3>
<p>Download standalone executables that don’t require Python installation:</p>
<section id="supported-platforms">
<h4>Supported Platforms<a class="headerlink" href="#supported-platforms" title="Link to this heading"></a></h4>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Platform</p></th>
<th class="head"><p>Architecture</p></th>
<th class="head"><p>File</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><strong>🐧 Linux</strong></p></td>
<td><p>x86_64</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tzst-{version}-linux-amd64.zip</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><strong>🐧 Linux</strong></p></td>
<td><p>ARM64</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tzst-{version}-linux-arm64.zip</span></code></p></td>
</tr>
<tr class="row-even"><td><p><strong>🪟 Windows</strong></p></td>
<td><p>x64</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tzst-{version}-windows-amd64.zip</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><strong>🪟 Windows</strong></p></td>
<td><p>ARM64</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tzst-{version}-windows-arm64.zip</span></code></p></td>
</tr>
<tr class="row-even"><td><p><strong>🍎 macOS</strong></p></td>
<td><p>Intel</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tzst-{version}-darwin-amd64.zip</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><strong>🍎 macOS</strong></p></td>
<td><p>Apple Silicon</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">tzst-{version}-darwin-arm64.zip</span></code></p></td>
</tr>
</tbody>
</table>
</section>
<section id="installation-steps">
<h4>🛠️ Installation Steps<a class="headerlink" href="#installation-steps" title="Link to this heading"></a></h4>
<ol class="arabic simple">
<li><p><strong>📥 Download</strong> the appropriate archive for your platform from the <a class="reference external" href="https://github.com/xixu-me/tzst/releases/latest">latest releases page</a></p></li>
<li><p><strong>📦 Extract</strong> the archive to get the <code class="docutils literal notranslate"><span class="pre">tzst</span></code> executable (or <code class="docutils literal notranslate"><span class="pre">tzst.exe</span></code> on Windows)</p></li>
<li><p><strong>📂 Move</strong> the executable to a directory in your PATH:</p>
<ul class="simple">
<li><p><strong>🐧 Linux/macOS</strong>: <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">mv</span> <span class="pre">tzst</span> <span class="pre">/usr/local/bin/</span></code></p></li>
<li><p><strong>🪟 Windows</strong>: Add the directory containing <code class="docutils literal notranslate"><span class="pre">tzst.exe</span></code> to your PATH environment variable</p></li>
</ul>
</li>
<li><p><strong>✅ Verify</strong> installation: <code class="docutils literal notranslate"><span class="pre">tzst</span> <span class="pre">--help</span></code></p></li>
</ol>
</section>
<section id="benefits-of-binary-installation">
<h4>🎯 Benefits of Binary Installation<a class="headerlink" href="#benefits-of-binary-installation" title="Link to this heading"></a></h4>
<ul class="simple">
<li><p>✅ <strong>No Python required</strong> - Standalone executable</p></li>
<li><p>✅ <strong>Faster startup</strong> - No Python interpreter overhead</p></li>
<li><p>✅ <strong>Easy deployment</strong> - Single file distribution</p></li>
<li><p>✅ <strong>Consistent behavior</strong> - Bundled dependencies</p></li>
</ul>
</section>
</section>
<section id="from-pypi">
<h3>From PyPI<a class="headerlink" href="#from-pypi" title="Link to this heading"></a></h3>
<p>Using pip:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>tzst
</pre></div>
</div>
<p>Or using uv (recommended):</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>uv<span class="w"> </span>tool<span class="w"> </span>install<span class="w"> </span>tzst
</pre></div>
</div>
</section>
<section id="from-source">
<h3>From Source<a class="headerlink" href="#from-source" title="Link to this heading"></a></h3>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/xixu-me/tzst.git
<span class="nb">cd</span><span class="w"> </span>tzst
pip<span class="w"> </span>install<span class="w"> </span>.
</pre></div>
</div>
</section>
<section id="development-installation">
<h3>Development Installation<a class="headerlink" href="#development-installation" title="Link to this heading"></a></h3>
<p>This project uses modern Python packaging standards:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/xixu-me/tzst.git
<span class="nb">cd</span><span class="w"> </span>tzst
pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>.<span class="o">[</span>dev<span class="o">]</span>
</pre></div>
</div>
</section>
</section>
<section id="basic-usage">
<span id="id2"></span><h2>Basic Usage<a class="headerlink" href="#basic-usage" title="Link to this heading"></a></h2>
<section id="command-line-interface">
<h3>Command Line Interface<a class="headerlink" href="#command-line-interface" title="Link to this heading"></a></h3>
<blockquote>
<div><p><strong>Note</strong>: Download the <a class="reference internal" href="#installation"><span class="std std-ref">standalone binary</span></a> for the best performance and no Python dependency. Alternatively, use <code class="docutils literal notranslate"><span class="pre">uvx</span> <span class="pre">tzst</span></code> for running without installation. See <a class="reference external" href="https://docs.astral.sh/uv/">uv documentation</a> for details.</p>
</div></blockquote>
<p>The CLI provides four main operations:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create an archive</span>
tzst<span class="w"> </span>a<span class="w"> </span>archive.tzst<span class="w"> </span>file1.txt<span class="w"> </span>file2.txt<span class="w"> </span>directory/
<span class="c1"># Extract an archive </span>
tzst<span class="w"> </span>x<span class="w"> </span>archive.tzst
<span class="c1"># List archive contents</span>
tzst<span class="w"> </span>l<span class="w"> </span>archive.tzst
<span class="c1"># Test archive integrity</span>
tzst<span class="w"> </span>t<span class="w"> </span>archive.tzst
</pre></div>
</div>
</section>
<section id="command-reference">
<h3>Command Reference<a class="headerlink" href="#command-reference" title="Link to this heading"></a></h3>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Command</p></th>
<th class="head"><p>Aliases</p></th>
<th class="head"><p>Description</p></th>
<th class="head"><p>Streaming Support</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">a</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">add</span></code>, <code class="docutils literal notranslate"><span class="pre">create</span></code></p></td>
<td><p>Create or add to archive</p></td>
<td><p>N/A</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">extract</span></code></p></td>
<td><p>Extract with full paths</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">e</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">extract-flat</span></code></p></td>
<td><p>Extract without directory structure</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">l</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">list</span></code></p></td>
<td><p>List archive contents</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">test</span></code></p></td>
<td><p>Test archive integrity</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
</tbody>
</table>
</section>
<section id="cli-options">
<h3>CLI Options<a class="headerlink" href="#cli-options" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">-v,</span> <span class="pre">--verbose</span></code>: Enable verbose output</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-o,</span> <span class="pre">--output</span> <span class="pre">DIR</span></code>: Specify output directory (extract commands)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-l,</span> <span class="pre">--level</span> <span class="pre">LEVEL</span></code>: Set compression level 1-22 (create command)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code>: Enable streaming mode for memory-efficient processing</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--filter</span> <span class="pre">FILTER</span></code>: Security filter for extraction (data/tar/fully_trusted)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">--no-atomic</span></code>: Disable atomic file operations (not recommended)</p></li>
</ul>
<section id="create-archives">
<h4>Create Archives<a class="headerlink" href="#create-archives" title="Link to this heading"></a></h4>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create archive with default compression (level 3)</span>
tzst<span class="w"> </span>a<span class="w"> </span>backup.tzst<span class="w"> </span>documents/<span class="w"> </span>photos/
<span class="c1"># Create with high compression</span>
tzst<span class="w"> </span>a<span class="w"> </span>backup.tzst<span class="w"> </span>documents/<span class="w"> </span>photos/<span class="w"> </span>--compression-level<span class="w"> </span><span class="m">9</span>
<span class="c1"># Create from current directory</span>
tzst<span class="w"> </span>a<span class="w"> </span>project.tzst<span class="w"> </span>.
<span class="c1"># Specify different output location</span>
tzst<span class="w"> </span>a<span class="w"> </span>/backups/data.tzst<span class="w"> </span>/home/user/important/
</pre></div>
</div>
</section>
<section id="extract-archives">
<h4>Extract Archives<a class="headerlink" href="#extract-archives" title="Link to this heading"></a></h4>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Extract to current directory</span>
tzst<span class="w"> </span>x<span class="w"> </span>backup.tzst
<span class="c1"># Extract to specific directory</span>
tzst<span class="w"> </span>x<span class="w"> </span>backup.tzst<span class="w"> </span>--output<span class="w"> </span>/restore/
<span class="c1"># Extract specific files only</span>
tzst<span class="w"> </span>x<span class="w"> </span>backup.tzst<span class="w"> </span>documents/report.pdf<span class="w"> </span>photos/vacation.jpg
<span class="c1"># Extract with conflict resolution</span>
tzst<span class="w"> </span>x<span class="w"> </span>backup.tzst<span class="w"> </span>--conflict-resolution<span class="w"> </span>skip
</pre></div>
</div>
</section>
<section id="list-contents">
<h4>List Contents<a class="headerlink" href="#list-contents" title="Link to this heading"></a></h4>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Simple listing</span>
tzst<span class="w"> </span>l<span class="w"> </span>backup.tzst
<span class="c1"># Detailed listing with file info</span>
tzst<span class="w"> </span>l<span class="w"> </span>backup.tzst<span class="w"> </span>--verbose
<span class="c1"># Stream large archives efficiently</span>
tzst<span class="w"> </span>l<span class="w"> </span>huge-archive.tzst<span class="w"> </span>--streaming
</pre></div>
</div>
</section>
</section>
<section id="python-api">
<h3>Python API<a class="headerlink" href="#python-api" title="Link to this heading"></a></h3>
<section id="quick-start">
<h4>Quick Start<a class="headerlink" href="#quick-start" title="Link to this heading"></a></h4>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span><span class="p">,</span> <span class="n">extract_archive</span><span class="p">,</span> <span class="n">list_archive</span><span class="p">,</span> <span class="n">test_archive</span>
<span class="c1"># Create an archive</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"documents/"</span><span class="p">,</span> <span class="s2">"photos/"</span><span class="p">],</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
<span class="c1"># Extract an archive</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="s2">"restore/"</span><span class="p">)</span>
<span class="c1"># List contents</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">list_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">contents</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">item</span><span class="p">[</span><span class="s1">'name'</span><span class="p">]</span><span class="si">}</span><span class="s2"> - </span><span class="si">{</span><span class="n">item</span><span class="p">[</span><span class="s1">'size'</span><span class="p">]</span><span class="si">}</span><span class="s2"> bytes"</span><span class="p">)</span>
<span class="c1"># Test integrity</span>
<span class="n">is_valid</span> <span class="o">=</span> <span class="n">test_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive is </span><span class="si">{</span><span class="s1">'valid'</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="n">is_valid</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="s1">'corrupted'</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="using-the-tzstarchive-class">
<h4>Using the TzstArchive Class<a class="headerlink" href="#using-the-tzstarchive-class" title="Link to this heading"></a></h4>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">TzstArchive</span>
<span class="c1"># Create a new archive</span>
<span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"data.tzst"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="n">archive</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"file.txt"</span><span class="p">)</span>
<span class="n">archive</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"directory/"</span><span class="p">,</span> <span class="n">recursive</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="c1"># Add with custom archive name</span>
<span class="n">archive</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"config/prod.yaml"</span><span class="p">,</span> <span class="n">arcname</span><span class="o">=</span><span class="s2">"config.yaml"</span><span class="p">)</span>
<span class="c1"># Read an existing archive</span>
<span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"data.tzst"</span><span class="p">,</span> <span class="s2">"r"</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="c1"># List contents</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">list</span><span class="p">(</span><span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">contents</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">item</span><span class="p">[</span><span class="s1">'name'</span><span class="p">]</span><span class="si">}</span><span class="s2"> - </span><span class="si">{</span><span class="n">item</span><span class="p">[</span><span class="s1">'size'</span><span class="p">]</span><span class="si">}</span><span class="s2"> bytes"</span><span class="p">)</span>
<span class="c1"># Test integrity</span>
<span class="n">is_valid</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">test</span><span class="p">()</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive is </span><span class="si">{</span><span class="s1">'valid'</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="n">is_valid</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="s1">'corrupted'</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="c1"># Extract specific files</span>
<span class="n">archive</span><span class="o">.</span><span class="n">extract</span><span class="p">(</span><span class="s2">"file.txt"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">)</span>
<span class="c1"># Extract all files</span>
<span class="n">archive</span><span class="o">.</span><span class="n">extractall</span><span class="p">(</span><span class="s2">"restore/"</span><span class="p">)</span>
</pre></div>
</div>
</section>
</section>
</section>
<section id="advanced-features">
<h2>Advanced Features<a class="headerlink" href="#advanced-features" title="Link to this heading"></a></h2>
<section id="security-and-filtering">
<h3>Security and Filtering<a class="headerlink" href="#security-and-filtering" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">extract_archive</span>
<span class="c1"># Safe extraction with built-in security (default)</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"untrusted.tzst"</span><span class="p">,</span> <span class="s2">"safe-output/"</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="s2">"data"</span><span class="p">)</span>
<span class="c1"># For trusted archives with special features</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"trusted.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="s2">"tar"</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="security-filters">
<h3>Security Filters<a class="headerlink" href="#security-filters" title="Link to this heading"></a></h3>
<p>tzst provides three security filter options for extraction:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">extract_archive</span>
<span class="c1"># Extract with maximum security (default)</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"archive.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="s2">"data"</span><span class="p">)</span>
<span class="c1"># Extract with standard tar compatibility</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"archive.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="s2">"tar"</span><span class="p">)</span>
<span class="c1"># Extract with full trust (dangerous - only for trusted archives)</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"archive.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span> <span class="nb">filter</span><span class="o">=</span><span class="s2">"fully_trusted"</span><span class="p">)</span>
</pre></div>
</div>
<p><strong>Security Filter Options:</strong></p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">data</span></code> (default): Most secure. Blocks dangerous files, absolute paths, and paths outside extraction directory</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">tar</span></code>: Standard tar compatibility. Blocks absolute paths and directory traversal</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fully_trusted</span></code>: No security restrictions. Only use with completely trusted archives</p></li>
</ul>
</section>
<section id="conflict-resolution">
<h3>Conflict Resolution<a class="headerlink" href="#conflict-resolution" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">extract_archive</span><span class="p">,</span> <span class="n">ConflictResolution</span>
<span class="c1"># Skip existing files</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"archive.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span>
<span class="n">conflict_resolution</span><span class="o">=</span><span class="n">ConflictResolution</span><span class="o">.</span><span class="n">SKIP_ALL</span><span class="p">)</span>
<span class="c1"># Auto-rename conflicting files</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"archive.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span>
<span class="n">conflict_resolution</span><span class="o">=</span><span class="n">ConflictResolution</span><span class="o">.</span><span class="n">AUTO_RENAME_ALL</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="performance-optimization">
<h3>Performance Optimization<a class="headerlink" href="#performance-optimization" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span><span class="p">,</span> <span class="n">extract_archive</span>
<span class="c1"># Create with different compression levels</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"fast.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span> <span class="c1"># Fastest</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"balanced.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span> <span class="c1"># Balanced</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"best.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">22</span><span class="p">)</span> <span class="c1"># Best compression</span>
<span class="c1"># Memory-efficient operations for large archives</span>
<span class="n">extract_archive</span><span class="p">(</span><span class="s2">"huge-archive.tzst"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">,</span> <span class="n">streaming</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="streaming-mode">
<h3>Streaming Mode<a class="headerlink" href="#streaming-mode" title="Link to this heading"></a></h3>
<p>For large archives (&gt;100MB), use streaming mode to reduce memory usage:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Memory-efficient operations</span>
<span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"large-archive.tzst"</span><span class="p">,</span> <span class="s2">"r"</span><span class="p">,</span> <span class="n">streaming</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">list</span><span class="p">()</span>
<span class="n">archive</span><span class="o">.</span><span class="n">extractall</span><span class="p">(</span><span class="s2">"output/"</span><span class="p">)</span>
<span class="n">is_valid</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">test</span><span class="p">()</span>
</pre></div>
</div>
<p><strong>Note</strong>: Streaming mode has limitations - you cannot extract specific files or use random access operations.</p>
</section>
<section id="file-extensions">
<h3>File Extensions<a class="headerlink" href="#file-extensions" title="Link to this heading"></a></h3>
<p>The library automatically handles file extensions with intelligent normalization:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">.tzst</span></code> - Primary extension for tar+zstandard archives</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">.tar.zst</span></code> - Alternative standard extension</p></li>
<li><p>Auto-detection when opening existing archives</p></li>
<li><p>Automatic extension addition when creating archives</p></li>
</ul>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span>
<span class="c1"># These all create valid archives</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">)</span> <span class="c1"># Creates backup.tzst</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.tar.zst"</span><span class="p">,</span> <span class="n">files</span><span class="p">)</span> <span class="c1"># Creates backup.tar.zst </span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup"</span><span class="p">,</span> <span class="n">files</span><span class="p">)</span> <span class="c1"># Creates backup.tzst</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.txt"</span><span class="p">,</span> <span class="n">files</span><span class="p">)</span> <span class="c1"># Creates backup.tzst (normalized)</span>
</pre></div>
</div>
</section>
<section id="atomic-operations">
<h3>Atomic Operations<a class="headerlink" href="#atomic-operations" title="Link to this heading"></a></h3>
<p>All file creation operations use atomic file operations by default:</p>
<ul class="simple">
<li><p>Archives created in temporary files first, then atomically moved</p></li>
<li><p>Automatic cleanup if process is interrupted</p></li>
<li><p>No risk of corrupted or incomplete archives</p></li>
<li><p>Cross-platform compatibility</p></li>
</ul>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Atomic operations enabled by default</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"important.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">)</span> <span class="c1"># Safe from interruption</span>
<span class="c1"># Can be disabled if needed (not recommended)</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"test.tzst"</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">use_temp_file</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</pre></div>
</div>
</section>
</section>
<section id="error-handling">
<h2>Error Handling<a class="headerlink" href="#error-handling" title="Link to this heading"></a></h2>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span><span class="p">,</span> <span class="n">TzstArchiveError</span><span class="p">,</span> <span class="n">TzstCompressionError</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">create_archive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"documents/"</span><span class="p">])</span>
<span class="k">except</span> <span class="n">TzstCompressionError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Compression failed: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">except</span> <span class="n">TzstArchiveError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive operation failed: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Unexpected error: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="next-steps">
<h2>Next Steps<a class="headerlink" href="#next-steps" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p>Explore comprehensive <a class="reference internal" href="examples.html"><span class="doc">Examples</span></a> for real-world scenarios</p></li>
<li><p>Check the <a class="reference internal" href="api/index.html"><span class="doc">API Reference</span></a> for detailed API documentation</p></li>
<li><p>See advanced features like atomic operations and custom filters</p></li>
<li><p>Learn about integration with web frameworks and automation tools</p></li>
</ul>
</section>
<section id="read-an-existing-archive">
<h2>Read an Existing Archive<a class="headerlink" href="#read-an-existing-archive" title="Link to this heading"></a></h2>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"data.tzst"</span><span class="p">,</span> <span class="s2">"r"</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="c1"># List contents</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">list</span><span class="p">(</span><span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="c1"># Extract specific file</span>
<span class="n">archive</span><span class="o">.</span><span class="n">extract</span><span class="p">(</span><span class="s2">"file.txt"</span><span class="p">,</span> <span class="s2">"output/"</span><span class="p">)</span>
<span class="c1"># Test integrity</span>
<span class="n">is_valid</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">test</span><span class="p">()</span>
<span class="c1"># Get raw member information</span>
<span class="n">members</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">getmembers</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="common-patterns">
<h2>Common Patterns<a class="headerlink" href="#common-patterns" title="Link to this heading"></a></h2>
<section id="backup-script">
<h3>Backup Script<a class="headerlink" href="#backup-script" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python3</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">pathlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">Path</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">create_archive</span>
<span class="k">def</span><span class="w"> </span><span class="nf">create_backup</span><span class="p">():</span>
<span class="n">timestamp</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s2">"%Y%m</span><span class="si">%d</span><span class="s2">_%H%M%S"</span><span class="p">)</span>
<span class="n">backup_name</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">"backup_</span><span class="si">{</span><span class="n">timestamp</span><span class="si">}</span><span class="s2">.tzst"</span>
<span class="c1"># Backup important directories</span>
<span class="n">directories</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"documents/"</span><span class="p">,</span> <span class="s2">"projects/"</span><span class="p">,</span> <span class="s2">"config/"</span><span class="p">]</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Creating backup: </span><span class="si">{</span><span class="n">backup_name</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="n">create_archive</span><span class="p">(</span><span class="n">backup_name</span><span class="p">,</span> <span class="n">directories</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Backup created: </span><span class="si">{</span><span class="n">Path</span><span class="p">(</span><span class="n">backup_name</span><span class="p">)</span><span class="o">.</span><span class="n">stat</span><span class="p">()</span><span class="o">.</span><span class="n">st_size</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="mi">1024</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="mi">1024</span><span class="si">:</span><span class="s2">.1f</span><span class="si">}</span><span class="s2"> MB"</span><span class="p">)</span>
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>
<span class="n">create_backup</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="archive-verification">
<h3>Archive Verification<a class="headerlink" href="#archive-verification" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">tzst</span><span class="w"> </span><span class="kn">import</span> <span class="n">test_archive</span><span class="p">,</span> <span class="n">list_archive</span>
<span class="k">def</span><span class="w"> </span><span class="nf">verify_archive</span><span class="p">(</span><span class="n">archive_path</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Verifying </span><span class="si">{</span><span class="n">archive_path</span><span class="si">}</span><span class="s2">..."</span><span class="p">)</span>
<span class="c1"># Test integrity</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">test_archive</span><span class="p">(</span><span class="n">archive_path</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"Archive is corrupted!"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">False</span>
<span class="c1"># List contents</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">list_archive</span><span class="p">(</span><span class="n">archive_path</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">total_size</span> <span class="o">=</span> <span class="nb">sum</span><span class="p">(</span><span class="n">item</span><span class="p">[</span><span class="s1">'size'</span><span class="p">]</span> <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">contents</span> <span class="k">if</span> <span class="n">item</span><span class="p">[</span><span class="s1">'is_file'</span><span class="p">])</span>
<span class="n">file_count</span> <span class="o">=</span> <span class="nb">sum</span><span class="p">(</span><span class="mi">1</span> <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">contents</span> <span class="k">if</span> <span class="n">item</span><span class="p">[</span><span class="s1">'is_file'</span><span class="p">])</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Archive is valid"</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Files: </span><span class="si">{</span><span class="n">file_count</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Total size: </span><span class="si">{</span><span class="n">total_size</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="mi">1024</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="mi">1024</span><span class="si">:</span><span class="s2">.1f</span><span class="si">}</span><span class="s2"> MB"</span><span class="p">)</span>
<span class="k">return</span> <span class="kc">True</span>
</pre></div>
</div>
</section>
</section>
<section id="further-learning">
<h2>Further Learning<a class="headerlink" href="#further-learning" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p>Explore <a class="reference internal" href="examples.html"><span class="doc">Examples</span></a> for more advanced usage patterns</p></li>
<li><p>Check <a class="reference internal" href="performance.html"><span class="doc">Performance Guide</span></a> for detailed performance guidance</p></li>
<li><p>Refer to the <a class="reference internal" href="api/index.html"><span class="doc">API Reference</span></a> for complete API documentation</p></li>
</ul>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="index.html" class="btn btn-neutral float-left" title="tzst Documentation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="performance.html" class="btn btn-neutral float-right" title="Performance Guide" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>