Deploy documentation from 1efdd4c091 1efdd4c091
This commit is contained in:
commit
89feb571a2
102 files changed
+18140
No files matched your search
+819
@@ -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>
|
||||
Reference in new issue
Block a user