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