Files
tzst/api/cli.html

967 lines
63 KiB
HTML
Raw Permalink 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="tzst CLI API - Command-line interface functions and utilities for tar.zst archive operations" name="description" />
<meta content="tzst CLI API, command line interface, Python CLI, tar.zst commands" name="keywords" />
<meta content="tzst CLI API Reference" name="og:title" />
<meta content="CLI API documentation for tzst - Command-line interface functions and utilities" name="og:description" />
<meta content="tzst CLI API Reference" name="twitter:title" />
<meta content="CLI API documentation for tzst - Command-line interface functions and utilities" name="twitter:description" />
<meta content="website" name="og:type" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="og:image" />
<meta content="https://tzst.xi-xu.me/" name="og:url" />
<meta content="summary_large_image" name="twitter:card" />
<meta content="https://tzst.xi-xu.me/_static/tzst-square-logo.png" name="twitter:image" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>CLI API &mdash; tzst 1.3.3 Documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=9edc463e" />
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="canonical" href="https://tzst.xi-xu.me/api/cli.html" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=3b3401d5"></script>
<script src="../_static/doctools.js?v=fd6eb6e6"></script>
<script src="../_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="../_static/js/theme.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within tzst 1.3.3 Documentation"
href="../_static/opensearch.xml"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Exceptions API" href="exceptions.html" />
<link rel="prev" title="Core API" href="core.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "CLI API",
"item": "https://tzst.xi-xu.me/api/cli.html"
}
]
}
</script>
<!-- Article/TechArticle Schema for documentation pages -->
<!-- FAQ Schema for pages with common questions -->
<!-- HowTo Schema for examples page -->
<!-- Canonical URL for better SEO -->
<link rel="canonical" href="https://tzst.xi-xu.me/api/cli.html" />
<!-- Preconnect to external domains for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://cdnjs.cloudflare.com" />
<link rel="dns-prefetch" href="https://pypi.org" />
<link rel="dns-prefetch" href="https://github.com" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #2980B9" >
<a href="../index.html" class="icon icon-home">
tzst
<img src="../_static/tzst-logo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../performance.html">Performance Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">API Reference</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="core.html">Core API</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">CLI API</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#overview">Overview</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#core-commands">Core Commands</a></li>
<li class="toctree-l4"><a class="reference internal" href="#key-features">Key Features</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#main-functions">Main Functions</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#main">main</a></li>
<li class="toctree-l4"><a class="reference internal" href="#create-parser">create_parser</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#command-handlers">Command Handlers</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#archive-creation-commands">Archive Creation Commands</a></li>
<li class="toctree-l4"><a class="reference internal" href="#extraction-commands">Extraction Commands</a></li>
<li class="toctree-l4"><a class="reference internal" href="#management-commands">Management Commands</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#utility-functions">Utility Functions</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#print-banner">print_banner</a></li>
<li class="toctree-l4"><a class="reference internal" href="#format-size">format_size</a></li>
<li class="toctree-l4"><a class="reference internal" href="#validate-compression-level">validate_compression_level</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#interactive-features">Interactive Features</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#conflict-resolution-options">Conflict Resolution Options</a></li>
<li class="toctree-l4"><a class="reference internal" href="#security-considerations">Security Considerations</a></li>
<li class="toctree-l4"><a class="reference internal" href="#performance-options">Performance Options</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html">Exceptions API</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#key-features">Key Features</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../development.html">Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #2980B9" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">tzst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="index.html">API Reference</a></li>
<li class="breadcrumb-item active">CLI API</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/api/cli.md" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="cli-api">
<h1>CLI API<a class="headerlink" href="#cli-api" title="Link to this heading"></a></h1>
<p>The command-line interface module provides comprehensive functionality for the tzst CLI tool, including argument parsing, command execution, and interactive features.</p>
<p>Command-line interface for tzst.</p>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">cmd_add</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#cmd_add"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Command handler for creating/adding to archives.</p>
<p>Processes the ‘add’, ‘create’, or ‘a’ CLI commands to create new tzst archives
with the specified files and directories. Uses atomic file operations by
default to ensure data integrity.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>args</strong> – Parsed command line arguments containing:
- archive (str): Path to the archive file to create
- files (list[str]): List of files/directories to add
- compression_level (int, optional): Compression level 1-22
- no_atomic (bool, optional): Disable atomic file operations</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code (0 for success, non-zero for failure)</dt><dd><ul class="simple">
<li><p>0: Success</p></li>
<li><p>1: File not found, invalid parameters, or archive operation failed</p></li>
<li><p>130: Operation interrupted by user (Ctrl+C)</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This function uses atomic file operations by default, creating the
archive in a temporary file first, then atomically moving it to the
final location to prevent incomplete archives.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="core.html#tzst.create_archive" title="tzst.create_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">tzst.create_archive()</span></code></a>: The underlying function for archive creation
<code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.add()</span></code>: The core method for adding files to archives</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">cmd_extract_flat</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#cmd_extract_flat"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Command handler for flat extraction without directory structure.</p>
<p>Processes the ‘extract-flat’ or ‘e’ CLI commands to extract files from
tzst archives without preserving directory structure (all files extracted
to a single directory).</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>args</strong> – Parsed command line arguments containing:
- archive (str): Path to the archive file to extract
- output (str, optional): Output directory path
- files (list[str], optional): Specific files to extract
- streaming (bool, optional): Use streaming mode for large archives
- filter (str, optional): Security filter (‘data’, ‘tar’, ‘fully_trusted’)</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code (0 for success, non-zero for failure)</dt><dd><ul class="simple">
<li><p>0: Success</p></li>
<li><p>1: File not found, decompression failed, or archive operation failed</p></li>
<li><p>130: Operation interrupted by user (Ctrl+C)</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Flat extraction may cause filename conflicts if multiple files have
the same name but are in different directories within the archive.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="core.html#tzst.extract_archive" title="tzst.extract_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">tzst.extract_archive()</span></code></a>: The underlying function for extraction
<code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.extract()</span></code>: The core method for extracting from archives
<code class="xref py py-func docutils literal notranslate"><span class="pre">cmd_extract_full()</span></code>: For extraction with directory structure</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">cmd_extract_full</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#cmd_extract_full"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Command handler for extracting archives with full directory structure.</p>
<p>Processes the ‘extract’ or ‘x’ CLI commands to extract files from tzst
archives while preserving the original directory structure.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>args</strong> – Parsed command line arguments containing:
- archive (str): Path to the archive file to extract
- output (str, optional): Output directory path
- files (list[str], optional): Specific files to extract
- streaming (bool, optional): Use streaming mode for large archives
- filter (str, optional): Security filter (‘data’, ‘tar’, ‘fully_trusted’)</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code (0 for success, non-zero for failure)</dt><dd><ul class="simple">
<li><p>0: Success</p></li>
<li><p>1: File not found, decompression failed, or archive operation failed</p></li>
<li><p>130: Operation interrupted by user (Ctrl+C)</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Uses the ‘data’ security filter by default for safe extraction from
untrusted sources. Streaming mode is recommended for archives &gt; 100MB.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="core.html#tzst.extract_archive" title="tzst.extract_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">tzst.extract_archive()</span></code></a>: The underlying function for extraction
<code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.extract()</span></code>: The core method for extracting from archives
<code class="xref py py-func docutils literal notranslate"><span class="pre">cmd_extract_flat()</span></code>: For flat extraction without directory structure</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">cmd_list</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#cmd_list"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Command handler for listing archive contents.</p>
<p>Processes the ‘list’ or ‘l’ CLI commands to display the contents of tzst
archives. Supports both simple and verbose listing modes.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>args</strong> – Parsed command line arguments containing:
- archive (str): Path to the archive file to list
- verbose (bool, optional): Show detailed file information
- streaming (bool, optional): Use streaming mode for large archives</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code (0 for success, non-zero for failure)</dt><dd><ul class="simple">
<li><p>0: Success</p></li>
<li><p>1: File not found, decompression failed, or archive operation failed</p></li>
<li><p>130: Operation interrupted by user (Ctrl+C)</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Verbose mode displays file permissions, sizes, modification times,
and other metadata. Streaming mode is recommended for archives &gt; 100MB.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="core.html#tzst.list_archive" title="tzst.list_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">tzst.list_archive()</span></code></a>: The underlying function for listing contents
<code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.list()</span></code>: The core method for listing archive contents</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">cmd_test</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#cmd_test"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Command handler for testing archive integrity.</p>
<p>Processes the ‘test’ or ‘t’ CLI commands to verify the integrity of tzst
archives by attempting to read all files and checking for corruption.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>args</strong> – Parsed command line arguments containing:
- archive (str): Path to the archive file to test
- streaming (bool, optional): Use streaming mode for large archives</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code (0 for success, non-zero for failure)</dt><dd><ul class="simple">
<li><p>0: Archive passed integrity test</p></li>
<li><p>1: Archive failed integrity test, file not found, or operation failed</p></li>
<li><p>130: Operation interrupted by user (Ctrl+C)</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This command verifies that the archive can be read and all files
can be decompressed without errors. Streaming mode is recommended
for archives &gt; 100MB to reduce memory usage.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="core.html#tzst.test_archive" title="tzst.test_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">tzst.test_archive()</span></code></a>: The underlying function for integrity testing
<code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.test()</span></code>: The core method for testing archive integrity</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">cmd_version</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#cmd_version"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Command handler for version display.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>Exit code (always 0)</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">create_parser</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser" title="(in Python v3.14)"><span class="pre">ArgumentParser</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#create_parser"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Create and configure the command-line argument parser.</p>
<p>Sets up the argparse ArgumentParser with all subcommands and their
respective arguments for the tzst CLI interface. Includes comprehensive
help text and command reference documentation.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>Configured parser ready for argument parsing</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p><a class="reference external" href="https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser" title="(in Python v3.14)">argparse.ArgumentParser</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The parser is configured with RawDescriptionHelpFormatter to preserve
formatting in the epilog help text, and includes detailed command
reference and security notes.</p>
</div>
<dl class="simple">
<dt>Commands Created:</dt><dd><ul class="simple">
<li><p>a, add, create: Archive creation with compression levels</p></li>
<li><p>x, extract: Full extraction with directory structure</p></li>
<li><p>e, extract-flat: Flat extraction without directories</p></li>
<li><p>l, list: Archive content listing</p></li>
<li><p>t, test: Archive integrity testing</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.cli.main" title="tzst.cli.main"><code class="xref py py-func docutils literal notranslate"><span class="pre">main()</span></code></a>: The main entry point that uses this parser</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">format_size</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#format_size"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Format file size in human-readable format.</p>
<p>Converts byte values to human-readable format using standard units
(B, KB, MB, GB, TB, PB) with appropriate decimal places.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>size</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><em>int</em></a>) – Size in bytes to format</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Formatted size string with units (e.g., “1.5 KB”, “2.3 GB”)</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)">str</a></p>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">format_size</span><span class="p">(</span><span class="mi">1024</span><span class="p">)</span>
<span class="go">' 1.0 KB'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">format_size</span><span class="p">(</span><span class="mi">1536</span><span class="p">)</span>
<span class="go">' 1.5 KB'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">format_size</span><span class="p">(</span><span class="mi">2048576</span><span class="p">)</span>
<span class="go">' 2.0 MB'</span>
</pre></div>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">argv</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.14)"><span class="pre">list</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</span></a><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#main"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Main entry point for the tzst command-line interface.</p>
<p>Processes command-line arguments and dispatches to appropriate command
handlers. Displays the version banner and provides error handling for
the overall CLI execution.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>argv</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.14)"><em>list</em></a><em>[</em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><em>str</em></a><em>] </em><em>| </em><em>None</em><em>, </em><em>optional</em>) – Command line arguments to parse.
If None, uses sys.argv. Defaults to None.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code for the program</dt><dd><ul class="simple">
<li><p>0: Success</p></li>
<li><p>1: Invalid compression level, filter, or command error</p></li>
<li><p>2: Argument parsing error (help, unknown options)</p></li>
<li><p>Other codes: Specific to individual command handlers</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This function serves as the console script entry point defined in
pyproject.toml. It displays the version banner before executing
any commands.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.cli.create_parser" title="tzst.cli.create_parser"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_parser()</span></code></a>: Creates the argument parser used by this function</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">print_banner</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#print_banner"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Print the version and copyright banner.</p>
<p>Displays the tzst version number and copyright information to stdout.
Used as a header for CLI operations.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>None</p>
</dd>
</dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">validate_compression_level</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#validate_compression_level"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Validate and return compression level.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>value</strong> – String value from command line</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Valid compression level (1-22)</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
<dt class="field-even">Raises<span class="colon">:</span></dt>
<dd class="field-even"><p><a class="reference external" href="https://docs.python.org/3/library/argparse.html#argparse.ArgumentTypeError" title="(in Python v3.14)"><strong>argparse.ArgumentTypeError</strong></a> – If value is not a valid compression level</p>
</dd>
</dl>
</dd></dl>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Link to this heading"></a></h2>
<p>The tzst CLI provides a powerful command-line interface for archive operations with intuitive commands and comprehensive options. The interface is designed for both interactive use and scripting, with robust error handling and user-friendly output.</p>
<section id="core-commands">
<h3>Core Commands<a class="headerlink" href="#core-commands" title="Link to this heading"></a></h3>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Command</p></th>
<th class="head"><p>Aliases</p></th>
<th class="head"><p>Description</p></th>
<th class="head"><p>Streaming Support</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">a</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">add</span></code>, <code class="docutils literal notranslate"><span class="pre">create</span></code></p></td>
<td><p>Create or add to archive</p></td>
<td><p>N/A</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">x</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">extract</span></code></p></td>
<td><p>Extract with full paths</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">e</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">extract-flat</span></code></p></td>
<td><p>Extract without directory structure</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">l</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">list</span></code></p></td>
<td><p>List archive contents</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">t</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">test</span></code></p></td>
<td><p>Test archive integrity</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></td>
</tr>
</tbody>
</table>
</section>
<section id="key-features">
<h3>Key Features<a class="headerlink" href="#key-features" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Intuitive Commands</strong>: Simple, memorable command aliases (a, x, e, l, t)</p></li>
<li><p><strong>Streaming Support</strong>: Memory-efficient processing for large archives</p></li>
<li><p><strong>Interactive Conflict Resolution</strong>: User-friendly prompts for handling file conflicts</p></li>
<li><p><strong>Comprehensive Options</strong>: Fine-grained control over compression, extraction, and security</p></li>
<li><p><strong>Cross-Platform</strong>: Consistent behavior across Windows, macOS, and Linux</p></li>
</ul>
</section>
</section>
<section id="main-functions">
<h2>Main Functions<a class="headerlink" href="#main-functions" title="Link to this heading"></a></h2>
<section id="main">
<h3>main<a class="headerlink" href="#main" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.cli.main">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">argv</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.14)"><span class="pre">list</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</span></a><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#main"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.cli.main" title="Link to this definition"></a></dt>
<dd><p>Main entry point for the tzst command-line interface.</p>
<p>Processes command-line arguments and dispatches to appropriate command
handlers. Displays the version banner and provides error handling for
the overall CLI execution.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>argv</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.14)"><em>list</em></a><em>[</em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><em>str</em></a><em>] </em><em>| </em><em>None</em><em>, </em><em>optional</em>) – Command line arguments to parse.
If None, uses sys.argv. Defaults to None.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>Exit code for the program</dt><dd><ul class="simple">
<li><p>0: Success</p></li>
<li><p>1: Invalid compression level, filter, or command error</p></li>
<li><p>2: Argument parsing error (help, unknown options)</p></li>
<li><p>Other codes: Specific to individual command handlers</p></li>
</ul>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This function serves as the console script entry point defined in
pyproject.toml. It displays the version banner before executing
any commands.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.cli.create_parser" title="tzst.cli.create_parser"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_parser()</span></code></a>: Creates the argument parser used by this function</p>
</div>
</dd></dl>
<p>The main entry point for the CLI application. Handles argument parsing, command execution, and comprehensive error reporting.</p>
<p><strong>Key Features:</strong></p>
<ul class="simple">
<li><p>Robust argument validation and error handling</p></li>
<li><p>Support for all archive operations</p></li>
<li><p>Consistent exit codes for scripting</p></li>
<li><p>User-friendly error messages</p></li>
</ul>
<p><strong>Exit Codes:</strong></p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">0</span></code>: Success</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">1</span></code>: General error (file not found, archive corruption, etc.)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">2</span></code>: Argument parsing error</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">130</span></code>: Interrupted by user (Ctrl+C)</p></li>
</ul>
</section>
<section id="create-parser">
<h3>create_parser<a class="headerlink" href="#create-parser" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.cli.create_parser">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">create_parser</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser" title="(in Python v3.14)"><span class="pre">ArgumentParser</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#create_parser"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.cli.create_parser" title="Link to this definition"></a></dt>
<dd><p>Create and configure the command-line argument parser.</p>
<p>Sets up the argparse ArgumentParser with all subcommands and their
respective arguments for the tzst CLI interface. Includes comprehensive
help text and command reference documentation.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>Configured parser ready for argument parsing</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p><a class="reference external" href="https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser" title="(in Python v3.14)">argparse.ArgumentParser</a></p>
</dd>
</dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The parser is configured with RawDescriptionHelpFormatter to preserve
formatting in the epilog help text, and includes detailed command
reference and security notes.</p>
</div>
<dl class="simple">
<dt>Commands Created:</dt><dd><ul class="simple">
<li><p>a, add, create: Archive creation with compression levels</p></li>
<li><p>x, extract: Full extraction with directory structure</p></li>
<li><p>e, extract-flat: Flat extraction without directories</p></li>
<li><p>l, list: Archive content listing</p></li>
<li><p>t, test: Archive integrity testing</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.cli.main" title="tzst.cli.main"><code class="xref py py-func docutils literal notranslate"><span class="pre">main()</span></code></a>: The main entry point that uses this parser</p>
</div>
</dd></dl>
<p>Creates and configures the comprehensive argument parser for the CLI interface.</p>
<p><strong>Supported Arguments:</strong></p>
<ul class="simple">
<li><p><strong>Global</strong>: <code class="docutils literal notranslate"><span class="pre">--version</span></code>, <code class="docutils literal notranslate"><span class="pre">--help</span></code></p></li>
<li><p><strong>Archive Creation</strong>: <code class="docutils literal notranslate"><span class="pre">-l/--level</span></code>, <code class="docutils literal notranslate"><span class="pre">--no-atomic</span></code></p></li>
<li><p><strong>Extraction</strong>: <code class="docutils literal notranslate"><span class="pre">-o/--output</span></code>, <code class="docutils literal notranslate"><span class="pre">--streaming</span></code>, <code class="docutils literal notranslate"><span class="pre">--filter</span></code>, <code class="docutils literal notranslate"><span class="pre">--conflict-resolution</span></code></p></li>
<li><p><strong>Listing</strong>: <code class="docutils literal notranslate"><span class="pre">-v/--verbose</span></code>, <code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></li>
<li><p><strong>Testing</strong>: <code class="docutils literal notranslate"><span class="pre">--streaming</span></code></p></li>
</ul>
</section>
</section>
<section id="command-handlers">
<h2>Command Handlers<a class="headerlink" href="#command-handlers" title="Link to this heading"></a></h2>
<p>The CLI implements dedicated command handlers for each operation, providing specialized functionality and error handling.</p>
<section id="archive-creation-commands">
<h3>Archive Creation Commands<a class="headerlink" href="#archive-creation-commands" title="Link to this heading"></a></h3>
<section id="cmd-add">
<h4>cmd_add<a class="headerlink" href="#cmd-add" title="Link to this heading"></a></h4>
<p>Creates new archives from files and directories with configurable compression and atomic operations.</p>
<p><strong>Features:</strong></p>
<ul class="simple">
<li><p>Configurable compression levels (1-22)</p></li>
<li><p>Atomic file operations (default) for safe creation</p></li>
<li><p>Recursive directory processing</p></li>
<li><p>Path validation and normalization</p></li>
</ul>
<p><strong>Usage Examples:</strong></p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Basic archive creation</span>
tzst<span class="w"> </span>a<span class="w"> </span>backup.tzst<span class="w"> </span>documents/<span class="w"> </span>photos/
<span class="c1"># High compression with atomic disabled</span>
tzst<span class="w"> </span>a<span class="w"> </span>backup.tzst<span class="w"> </span>files/<span class="w"> </span>-l<span class="w"> </span><span class="m">15</span><span class="w"> </span>--no-atomic
</pre></div>
</div>
</section>
</section>
<section id="extraction-commands">
<h3>Extraction Commands<a class="headerlink" href="#extraction-commands" title="Link to this heading"></a></h3>
<section id="cmd-extract-full">
<h4>cmd_extract_full<a class="headerlink" href="#cmd-extract-full" title="Link to this heading"></a></h4>
<p>Extracts archives preserving complete directory structure with advanced conflict resolution.</p>
<p><strong>Features:</strong></p>
<ul class="simple">
<li><p>Preserves full directory paths</p></li>
<li><p>Multiple conflict resolution strategies</p></li>
<li><p>Security filters for safe extraction</p></li>
<li><p>Selective file extraction</p></li>
<li><p>Streaming mode for large archives</p></li>
</ul>
</section>
<section id="cmd-extract-flat">
<h4>cmd_extract_flat<a class="headerlink" href="#cmd-extract-flat" title="Link to this heading"></a></h4>
<p>Extracts archives flattening all files to a single directory, useful for consolidating files.</p>
<p><strong>Features:</strong></p>
<ul class="simple">
<li><p>Flattens directory structure</p></li>
<li><p>Automatic conflict resolution for filename collisions</p></li>
<li><p>Preserves file content while simplifying structure</p></li>
<li><p>Same security and streaming features as full extraction</p></li>
</ul>
</section>
</section>
<section id="management-commands">
<h3>Management Commands<a class="headerlink" href="#management-commands" title="Link to this heading"></a></h3>
<section id="cmd-list">
<h4>cmd_list<a class="headerlink" href="#cmd-list" title="Link to this heading"></a></h4>
<p>Lists archive contents with optional detailed information and streaming support.</p>
<p><strong>Features:</strong></p>
<ul class="simple">
<li><p>Simple or verbose listing modes</p></li>
<li><p>Human-readable file sizes</p></li>
<li><p>Modification timestamps</p></li>
<li><p>Streaming mode for memory efficiency</p></li>
</ul>
</section>
<section id="cmd-test">
<h4>cmd_test<a class="headerlink" href="#cmd-test" title="Link to this heading"></a></h4>
<p>Tests archive integrity and validity with comprehensive error reporting.</p>
<p><strong>Features:</strong></p>
<ul class="simple">
<li><p>Complete archive validation</p></li>
<li><p>Streaming mode support</p></li>
<li><p>Detailed error reporting</p></li>
<li><p>Exit codes for automated testing</p></li>
</ul>
</section>
<section id="cmd-version">
<h4>cmd_version<a class="headerlink" href="#cmd-version" title="Link to this heading"></a></h4>
<p>Displays version information and system details.</p>
</section>
</section>
</section>
<section id="utility-functions">
<h2>Utility Functions<a class="headerlink" href="#utility-functions" title="Link to this heading"></a></h2>
<section id="print-banner">
<h3>print_banner<a class="headerlink" href="#print-banner" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.cli.print_banner">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">print_banner</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#print_banner"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.cli.print_banner" title="Link to this definition"></a></dt>
<dd><p>Print the version and copyright banner.</p>
<p>Displays the tzst version number and copyright information to stdout.
Used as a header for CLI operations.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>None</p>
</dd>
</dl>
</dd></dl>
<p>Displays the application banner with version and copyright information.</p>
</section>
<section id="format-size">
<h3>format_size<a class="headerlink" href="#format-size" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.cli.format_size">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">format_size</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#format_size"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.cli.format_size" title="Link to this definition"></a></dt>
<dd><p>Format file size in human-readable format.</p>
<p>Converts byte values to human-readable format using standard units
(B, KB, MB, GB, TB, PB) with appropriate decimal places.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>size</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><em>int</em></a>) – Size in bytes to format</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Formatted size string with units (e.g., “1.5 KB”, “2.3 GB”)</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)">str</a></p>
</dd>
</dl>
<p class="rubric">Examples</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">format_size</span><span class="p">(</span><span class="mi">1024</span><span class="p">)</span>
<span class="go">' 1.0 KB'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">format_size</span><span class="p">(</span><span class="mi">1536</span><span class="p">)</span>
<span class="go">' 1.5 KB'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">format_size</span><span class="p">(</span><span class="mi">2048576</span><span class="p">)</span>
<span class="go">' 2.0 MB'</span>
</pre></div>
</div>
</dd></dl>
<p>Formats file sizes in a human-readable format (bytes, KB, MB, GB).</p>
</section>
<section id="validate-compression-level">
<h3>validate_compression_level<a class="headerlink" href="#validate-compression-level" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.cli.validate_compression_level">
<span class="sig-prename descclassname"><span class="pre">tzst.cli.</span></span><span class="sig-name descname"><span class="pre">validate_compression_level</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">value</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)"><span class="pre">int</span></a></span></span><a class="reference internal" href="../_modules/tzst/cli.html#validate_compression_level"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.cli.validate_compression_level" title="Link to this definition"></a></dt>
<dd><p>Validate and return compression level.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>value</strong> – String value from command line</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Valid compression level (1-22)</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.14)">int</a></p>
</dd>
<dt class="field-even">Raises<span class="colon">:</span></dt>
<dd class="field-even"><p><a class="reference external" href="https://docs.python.org/3/library/argparse.html#argparse.ArgumentTypeError" title="(in Python v3.14)"><strong>argparse.ArgumentTypeError</strong></a> – If value is not a valid compression level</p>
</dd>
</dl>
</dd></dl>
<p>Validates compression level arguments and converts them to integers.</p>
</section>
</section>
<section id="interactive-features">
<h2>Interactive Features<a class="headerlink" href="#interactive-features" title="Link to this heading"></a></h2>
<p>The CLI includes interactive conflict resolution for file extraction conflicts, allowing users to choose how to handle existing files during extraction operations.</p>
<section id="conflict-resolution-options">
<h3>Conflict Resolution Options<a class="headerlink" href="#conflict-resolution-options" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Replace</strong>: Overwrite the existing file</p></li>
<li><p><strong>Skip</strong>: Keep the existing file, skip extraction</p></li>
<li><p><strong>Replace All</strong>: Apply replace to all subsequent conflicts</p></li>
<li><p><strong>Skip All</strong>: Apply skip to all subsequent conflicts</p></li>
<li><p><strong>Auto-rename All</strong>: Automatically rename conflicting files</p></li>
<li><p><strong>Exit</strong>: Stop extraction process</p></li>
</ul>
</section>
<section id="security-considerations">
<h3>Security Considerations<a class="headerlink" href="#security-considerations" title="Link to this heading"></a></h3>
<p>The CLI implements multiple security filters for safe extraction:</p>
<ul class="simple">
<li><p><strong><code class="docutils literal notranslate"><span class="pre">data</span></code> filter</strong> (default): Safest option, blocks potentially dangerous archive members</p></li>
<li><p><strong><code class="docutils literal notranslate"><span class="pre">tar</span></code> filter</strong>: Preserves more tar features while maintaining basic security</p></li>
<li><p><strong><code class="docutils literal notranslate"><span class="pre">fully_trusted</span></code> filter</strong>: No restrictions, use only with completely trusted archives</p></li>
</ul>
</section>
<section id="performance-options">
<h3>Performance Options<a class="headerlink" href="#performance-options" title="Link to this heading"></a></h3>
<ul class="simple">
<li><p><strong>Streaming Mode</strong>: Use <code class="docutils literal notranslate"><span class="pre">--streaming</span></code> for memory-efficient processing of large archives (&gt;100MB)</p></li>
<li><p><strong>Compression Levels</strong>: Choose from 1 (fastest) to 22 (maximum compression)</p></li>
<li><p><strong>Atomic Operations</strong>: Default behavior uses temporary files for safe archive creation</p></li>
</ul>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="core.html" class="btn btn-neutral float-left" title="Core API" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="exceptions.html" class="btn btn-neutral float-right" title="Exceptions API" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2026, Xi Xu.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>