Files
tzst/api/core.html
T

1032 lines
122 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta content="tzst Core API - TzstArchive class and convenience functions for tar.zst archive operations" name="description" />
<meta content="tzst core API, TzstArchive, Python archive class, tar.zst functions" name="keywords" />
<meta content="tzst Core API Reference" name="og:title" />
<meta content="Core API documentation for tzst - TzstArchive class and convenience functions" name="og:description" />
<meta content="tzst Core API Reference" name="twitter:title" />
<meta content="Core API documentation for tzst - TzstArchive class and convenience functions" 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>Core 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/core.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="CLI API" href="cli.html" />
<link rel="prev" title="API Reference" href="index.html" />
<!-- Additional SEO and social meta tags -->
<meta name="application-name" content="tzst" />
<meta name="generator" content="Sphinx 9.1.0" />
<meta name="rating" content="General" />
<meta name="revisit-after" content="7 days" />
<!-- Schema.org markup for search engines -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "tzst",
"description": "A Python library for creating and extracting tar.zst archives with high performance and comprehensive features",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Cross-platform",
"programmingLanguage": "Python",
"license": "https://opensource.org/licenses/BSD-3-Clause",
"url": "https://tzst.xi-xu.me/",
"downloadUrl": "https://pypi.org/project/tzst/",
"codeRepository": "https://github.com/xixu-me/tzst",
"softwareVersion": "1.3.3",
"author": {
"@type": "Person",
"name": "Xi Xu",
"url": "https://xi-xu.me"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5",
"reviewCount": "1"
},
"keywords": "tzst, tar, zstandard, compression, archive, python, extraction, backup"
}
</script>
<!-- Breadcrumb Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://tzst.xi-xu.me/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Core API",
"item": "https://tzst.xi-xu.me/api/core.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/core.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 current"><a class="current reference internal" href="#">Core API</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#tzstarchive-class">TzstArchive Class</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#tzst.TzstArchive"><code class="docutils literal notranslate"><span class="pre">TzstArchive</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#key-features">Key Features</a></li>
<li class="toctree-l4"><a class="reference internal" href="#usage-examples">Usage Examples</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#convenience-functions">Convenience Functions</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#create-archive">create_archive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#extract-archive">extract_archive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#list-archive">list_archive</a></li>
<li class="toctree-l4"><a class="reference internal" href="#test-archive">test_archive</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#enums-and-supporting-classes">Enums and Supporting Classes</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#conflictresolution">ConflictResolution</a></li>
<li class="toctree-l4"><a class="reference internal" href="#conflictresolutionstate">ConflictResolutionState</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="cli.html">CLI API</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html">Exceptions API</a></li>
<li class="toctree-l2"><a class="reference internal" href="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">Core API</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/xixu-me/tzst/blob/main/docs/api/core.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="core-api">
<h1>Core API<a class="headerlink" href="#core-api" title="Link to this heading"></a></h1>
<p>The core module provides the main functionality for working with tzst archives, including the primary <code class="docutils literal notranslate"><span class="pre">TzstArchive</span></code> class and high-level convenience functions.</p>
<p>Core functionality for tzst archives.</p>
<dl class="py class">
<dt class="sig sig-object py">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.core.</span></span><span class="sig-name descname"><span class="pre">ConflictResolution</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">values</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#ConflictResolution"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/enum.html#enum.Enum" title="(in Python v3.14)"><code class="xref py py-class docutils literal notranslate"><span class="pre">Enum</span></code></a></p>
<p>Enum for conflict resolution strategies.</p>
<dl class="py attribute">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">ASK</span></span><span class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'ask'</span></span></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">AUTO_RENAME</span></span><span class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'auto_rename'</span></span></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">AUTO_RENAME_ALL</span></span><span class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'auto_rename_all'</span></span></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">EXIT</span></span><span class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'exit'</span></span></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">REPLACE</span></span><span class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'replace'</span></span></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">REPLACE_ALL</span></span><span class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'replace_all'</span></span></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">SKIP</span></span><span class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'skip'</span></span></dt>
<dd></dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">SKIP_ALL</span></span><span class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'skip_all'</span></span></dt>
<dd></dd></dl>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.core.</span></span><span class="sig-name descname"><span class="pre">ConflictResolutionState</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">initial_resolution</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ConflictResolution</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><a class="reference internal" href="../_modules/tzst/core.html#ConflictResolutionState"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.14)"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a></p>
<p>State management for conflict resolution during extraction.</p>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">initial_resolution</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ConflictResolution</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><a class="reference internal" href="../_modules/tzst/core.html#ConflictResolutionState.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd></dd></dl>
<dl class="py property">
<dt class="sig sig-object py">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">apply_to_all</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.14)"><span class="pre">bool</span></a></span></dt>
<dd><p>Check if the current resolution applies to all future conflicts.</p>
</dd></dl>
<dl class="py property">
<dt class="sig sig-object py">
<span class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></span><span class="sig-name descname"><span class="pre">current_resolution</span></span><span class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">ConflictResolution</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></dt>
<dd><p>Get the current resolution state.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">should_continue</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/functions.html#bool" title="(in Python v3.14)"><span class="pre">bool</span></a></span></span><a class="reference internal" href="../_modules/tzst/core.html#ConflictResolutionState.should_continue"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Check if extraction should continue.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">update_resolution</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">resolution</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ConflictResolution</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/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span></span><a class="reference internal" href="../_modules/tzst/core.html#ConflictResolutionState.update_resolution"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Update the global resolution state.</p>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt class="sig sig-object py">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.core.</span></span><span class="sig-name descname"><span class="pre">TzstArchive</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</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><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">compression_level</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><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">3</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">streaming</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.14)"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a></p>
<p>A class for handling .tzst/.tar.zst archives.</p>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">__enter__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.__enter__"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Enter context manager.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">__exit__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">exc_type</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_val</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_tb</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.__exit__"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Exit context manager.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</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><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">compression_level</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><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">3</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">streaming</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Initialize a TzstArchive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>filename</strong> – Path to the archive file</p></li>
<li><p><strong>mode</strong> – Open mode (‘r’, ‘w’, ‘a’)</p></li>
<li><p><strong>compression_level</strong> – Zstandard compression level (1-22)</p></li>
<li><p><strong>streaming</strong> – If True, use streaming mode for reading (reduces memory usage
for very large archives but may limit some tarfile operations
that require seeking. Recommended for archives &gt; 100MB)</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">add</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">arcname</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 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>, <em class="sig-param"><span class="n"><span class="pre">recursive</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">True</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.add"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Add a file or directory to the archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>name</strong> – Path to file or directory to add</p></li>
<li><p><strong>arcname</strong> – Alternative name for the file in the archive</p></li>
<li><p><strong>recursive</strong> – If True, add directories recursively</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><code class="xref py py-func docutils literal notranslate"><span class="pre">create_archive()</span></code>: Convenience function for creating archives</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.close"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Close the archive.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">extract</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">member</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 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>, <em class="sig-param"><span class="n"><span class="pre">path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</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">'.'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">set_attrs</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">numeric_owner</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">filter</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 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/collections.abc.html#collections.abc.Callable" title="(in Python v3.14)"><span class="pre">Callable</span></a><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">'data'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.extract"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Extract files from the archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>member</strong> – Specific member to extract (None for all)</p></li>
<li><p><strong>path</strong> – Destination directory</p></li>
<li><p><strong>set_attrs</strong> – Whether to set file attributes</p></li>
<li><p><strong>numeric_owner</strong> – Whether to use numeric owner</p></li>
<li><p><strong>filter</strong> – Extraction filter for security. Can be:
- ‘data’: Safe filter for cross-platform data archives (default, recommended)
- ‘tar’: Honor most tar features but block dangerous ones
- ‘fully_trusted’: Honor all metadata (use only for trusted archives)
- None: Use default behavior (may show deprecation warning in Python 3.12+)
- callable: Custom filter function</p></li>
</ul>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Never extract archives from untrusted sources without proper filtering.
The ‘data’ filter is recommended for most use cases as it prevents
dangerous security issues like path traversal attacks.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>In streaming mode, extracting specific members is not supported.
Some extraction operations may be limited due to the sequential
nature of streaming mode.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><code class="xref py py-func docutils literal notranslate"><span class="pre">extract_archive()</span></code>: Convenience function for extracting archives</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">extractall</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</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">'.'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">members</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/tarfile.html#tarfile.TarInfo" title="(in Python v3.14)"><span class="pre">TarInfo</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>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">numeric_owner</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">filter</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 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/collections.abc.html#collections.abc.Callable" title="(in Python v3.14)"><span class="pre">Callable</span></a><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">'data'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.extractall"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Extract all members from the archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>path</strong> – Destination directory (default: current directory)</p></li>
<li><p><strong>members</strong> – Specific members to extract (None for all)</p></li>
<li><p><strong>numeric_owner</strong> – Whether to use numeric owner IDs</p></li>
<li><p><strong>filter</strong> – Extraction filter for security. Can be:
- ‘data’: Safe filter for cross-platform data archives
- ‘tar’: Honor most tar features but block dangerous ones
- ‘fully_trusted’: Honor all metadata (trusted archives only)
- None: Use default behavior (may show deprecation warning)
- callable: Custom filter function</p></li>
</ul>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Never extract archives from untrusted sources without proper filtering.
The ‘data’ filter is recommended for most use cases as it prevents
dangerous security issues like path traversal attacks.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>In streaming mode, extracting specific members is not supported.
Some extraction operations may be limited due to the sequential
nature of streaming mode.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code>: Extract a single member from the archive
<code class="xref py py-func docutils literal notranslate"><span class="pre">extract_archive()</span></code>: Convenience function for extracting archives</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">extractfile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">member</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 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/tarfile.html#tarfile.TarInfo" title="(in Python v3.14)"><span class="pre">TarInfo</span></a></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.extractfile"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Extract a file-like object from the archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>member</strong> – Member name or TarInfo object</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>File-like object or None if member is not a file</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">getmembers</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/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/tarfile.html#tarfile.TarInfo" title="(in Python v3.14)"><span class="pre">TarInfo</span></a><span class="p"><span class="pre">]</span></span></span></span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.getmembers"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Get list of all members in the archive.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">getnames</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/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></span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.getnames"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Get list of all member names in the archive.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">list</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">verbose</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</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/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#dict" title="(in Python v3.14)"><span class="pre">dict</span></a><span class="p"><span class="pre">]</span></span></span></span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.list"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>List contents of the archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>verbose</strong> – Include detailed information</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>List of file information dictionaries</p>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code>: Get TarInfo objects for all archive members
<code class="xref py py-meth docutils literal notranslate"><span class="pre">getnames()</span></code>: Get names of all archive members
<code class="xref py py-func docutils literal notranslate"><span class="pre">list_archive()</span></code>: Convenience function for listing archives</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">open</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.open"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Open the archive.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code>: Method to close the archive</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py">
<span class="sig-name descname"><span class="pre">test</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/functions.html#bool" title="(in Python v3.14)"><span class="pre">bool</span></a></span></span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.test"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Test the integrity of the archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>True if archive is valid, False otherwise</p>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><code class="xref py py-func docutils literal notranslate"><span class="pre">test_archive()</span></code>: Convenience function for testing archive integrity</p>
</div>
</dd></dl>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.core.</span></span><span class="sig-name descname"><span class="pre">create_archive</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">archive_path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">files</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/collections.abc.html#collections.abc.Sequence" title="(in Python v3.14)"><span class="pre">Sequence</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="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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">compression_level</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><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">3</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">use_temp_file</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">True</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/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span></span><a class="reference internal" href="../_modules/tzst/core.html#create_archive"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Create a new .tzst archive with atomic file operations.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>archive_path</strong> – Path for the new archive</p></li>
<li><p><strong>files</strong> – List of files/directories to add</p></li>
<li><p><strong>compression_level</strong> – Zstandard compression level (1-22)</p></li>
<li><p><strong>use_temp_file</strong> – If True, create archive in temporary file first, then move
to final location for atomic operation</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.add()</span></code>: Method for adding files to an open archive</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.core.</span></span><span class="sig-name descname"><span class="pre">extract_archive</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">archive_path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">extract_path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</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">'.'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">members</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>, <em class="sig-param"><span class="n"><span class="pre">flatten</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">streaming</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">filter</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 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/collections.abc.html#collections.abc.Callable" title="(in Python v3.14)"><span class="pre">Callable</span></a><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">'data'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">conflict_resolution</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ConflictResolution</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/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</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">ConflictResolution.REPLACE</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">interactive_callback</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/collections.abc.html#collections.abc.Callable" title="(in Python v3.14)"><span class="pre">Callable</span></a><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">ConflictResolution</span><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/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span></span><a class="reference internal" href="../_modules/tzst/core.html#extract_archive"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Extract files from a .tzst archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>archive_path</strong> – Path to the archive</p></li>
<li><p><strong>extract_path</strong> – Destination directory</p></li>
<li><p><strong>members</strong> – Specific members to extract (None for all)</p></li>
<li><p><strong>flatten</strong> – If True, extract without directory structure</p></li>
<li><p><strong>streaming</strong> – If True, use streaming mode (memory efficient for large archives)</p></li>
<li><p><strong>filter</strong> – Extraction filter for security. Can be:
- ‘data’: Safe filter for cross-platform data archives (default)
- ‘tar’: Honor most tar features but block dangerous ones
- ‘fully_trusted’: Honor all metadata (use only for trusted archives)
- None: Use default behavior (may show deprecation warning)
- callable: Custom filter function</p></li>
<li><p><strong>conflict_resolution</strong> – How to handle file conflicts during extraction</p></li>
<li><p><strong>interactive_callback</strong> – Function to call for interactive conflict resolution</p></li>
</ul>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Never extract archives from untrusted sources without proper filtering. The ‘data’ filter is recommended for most use cases as it prevents
dangerous security issues like path traversal attacks.</p>
<p>See Also:
<code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.extract()</span></code>: Method for extracting from an open archive</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.core.</span></span><span class="sig-name descname"><span class="pre">list_archive</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">archive_path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbose</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">streaming</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</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/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#dict" title="(in Python v3.14)"><span class="pre">dict</span></a><span class="p"><span class="pre">]</span></span></span></span><a class="reference internal" href="../_modules/tzst/core.html#list_archive"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>List contents of a .tzst archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>archive_path</strong> – Path to the archive</p></li>
<li><p><strong>verbose</strong> – Include detailed information</p></li>
<li><p><strong>streaming</strong> – If True, use streaming mode (memory efficient for large archives)</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>List of file information dictionaries</p>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.list()</span></code>: Method for listing an open archive</p>
</div>
</dd></dl>
<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">tzst.core.</span></span><span class="sig-name descname"><span class="pre">test_archive</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">archive_path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">streaming</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</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#bool" title="(in Python v3.14)"><span class="pre">bool</span></a></span></span><a class="reference internal" href="../_modules/tzst/core.html#test_archive"><span class="viewcode-link"><span class="pre">[source]</span></span></a></dt>
<dd><p>Test the integrity of a .tzst archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>archive_path</strong> – Path to the archive</p></li>
<li><p><strong>streaming</strong> – If True, use streaming mode (memory efficient for large archives)</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>True if archive is valid, False otherwise</p>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.test()</span></code>: Method for testing an open archive</p>
</div>
</dd></dl>
<section id="tzstarchive-class">
<h2>TzstArchive Class<a class="headerlink" href="#tzstarchive-class" title="Link to this heading"></a></h2>
<p>The main class for handling <code class="docutils literal notranslate"><span class="pre">.tzst</span></code>/<code class="docutils literal notranslate"><span class="pre">.tar.zst</span></code> archives with comprehensive functionality for creation, extraction, and manipulation.</p>
<dl class="py class">
<dt class="sig sig-object py" id="tzst.TzstArchive">
<span class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></span><span class="sig-prename descclassname"><span class="pre">tzst.</span></span><span class="sig-name descname"><span class="pre">TzstArchive</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</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><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">compression_level</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><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">3</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">streaming</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive" title="Link to this definition"></a></dt>
<dd><p>Bases: <a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.14)"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a></p>
<p>A class for handling .tzst/.tar.zst archives.</p>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.__enter__">
<span class="sig-name descname"><span class="pre">__enter__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.__enter__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.__enter__" title="Link to this definition"></a></dt>
<dd><p>Enter context manager.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.__exit__">
<span class="sig-name descname"><span class="pre">__exit__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">exc_type</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_val</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_tb</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.__exit__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.__exit__" title="Link to this definition"></a></dt>
<dd><p>Exit context manager.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.__init__">
<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</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><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">compression_level</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><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">3</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">streaming</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.__init__" title="Link to this definition"></a></dt>
<dd><p>Initialize a TzstArchive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>filename</strong> – Path to the archive file</p></li>
<li><p><strong>mode</strong> – Open mode (‘r’, ‘w’, ‘a’)</p></li>
<li><p><strong>compression_level</strong> – Zstandard compression level (1-22)</p></li>
<li><p><strong>streaming</strong> – If True, use streaming mode for reading (reduces memory usage
for very large archives but may limit some tarfile operations
that require seeking. Recommended for archives &gt; 100MB)</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.add">
<span class="sig-name descname"><span class="pre">add</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">arcname</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 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>, <em class="sig-param"><span class="n"><span class="pre">recursive</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">True</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.add"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.add" title="Link to this definition"></a></dt>
<dd><p>Add a file or directory to the archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>name</strong> – Path to file or directory to add</p></li>
<li><p><strong>arcname</strong> – Alternative name for the file in the archive</p></li>
<li><p><strong>recursive</strong> – If True, add directories recursively</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.create_archive" title="tzst.create_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">create_archive()</span></code></a>: Convenience function for creating archives</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.close">
<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.close"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.close" title="Link to this definition"></a></dt>
<dd><p>Close the archive.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.extract">
<span class="sig-name descname"><span class="pre">extract</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">member</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 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>, <em class="sig-param"><span class="n"><span class="pre">path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</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">'.'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">set_attrs</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">numeric_owner</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">filter</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 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/collections.abc.html#collections.abc.Callable" title="(in Python v3.14)"><span class="pre">Callable</span></a><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">'data'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.extract"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.extract" title="Link to this definition"></a></dt>
<dd><p>Extract files from the archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>member</strong> – Specific member to extract (None for all)</p></li>
<li><p><strong>path</strong> – Destination directory</p></li>
<li><p><strong>set_attrs</strong> – Whether to set file attributes</p></li>
<li><p><strong>numeric_owner</strong> – Whether to use numeric owner</p></li>
<li><p><strong>filter</strong> – Extraction filter for security. Can be:
- ‘data’: Safe filter for cross-platform data archives (default, recommended)
- ‘tar’: Honor most tar features but block dangerous ones
- ‘fully_trusted’: Honor all metadata (use only for trusted archives)
- None: Use default behavior (may show deprecation warning in Python 3.12+)
- callable: Custom filter function</p></li>
</ul>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Never extract archives from untrusted sources without proper filtering.
The ‘data’ filter is recommended for most use cases as it prevents
dangerous security issues like path traversal attacks.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>In streaming mode, extracting specific members is not supported.
Some extraction operations may be limited due to the sequential
nature of streaming mode.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.extract_archive" title="tzst.extract_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">extract_archive()</span></code></a>: Convenience function for extracting archives</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.extractall">
<span class="sig-name descname"><span class="pre">extractall</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</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">'.'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">members</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/tarfile.html#tarfile.TarInfo" title="(in Python v3.14)"><span class="pre">TarInfo</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>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">numeric_owner</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">filter</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 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/collections.abc.html#collections.abc.Callable" title="(in Python v3.14)"><span class="pre">Callable</span></a><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">'data'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.extractall"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.extractall" title="Link to this definition"></a></dt>
<dd><p>Extract all members from the archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>path</strong> – Destination directory (default: current directory)</p></li>
<li><p><strong>members</strong> – Specific members to extract (None for all)</p></li>
<li><p><strong>numeric_owner</strong> – Whether to use numeric owner IDs</p></li>
<li><p><strong>filter</strong> – Extraction filter for security. Can be:
- ‘data’: Safe filter for cross-platform data archives
- ‘tar’: Honor most tar features but block dangerous ones
- ‘fully_trusted’: Honor all metadata (trusted archives only)
- None: Use default behavior (may show deprecation warning)
- callable: Custom filter function</p></li>
</ul>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Never extract archives from untrusted sources without proper filtering.
The ‘data’ filter is recommended for most use cases as it prevents
dangerous security issues like path traversal attacks.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>In streaming mode, extracting specific members is not supported.
Some extraction operations may be limited due to the sequential
nature of streaming mode.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.TzstArchive.extract" title="tzst.TzstArchive.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a>: Extract a single member from the archive
<a class="reference internal" href="#tzst.extract_archive" title="tzst.extract_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">extract_archive()</span></code></a>: Convenience function for extracting archives</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.extractfile">
<span class="sig-name descname"><span class="pre">extractfile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">member</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 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/tarfile.html#tarfile.TarInfo" title="(in Python v3.14)"><span class="pre">TarInfo</span></a></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.extractfile"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.extractfile" title="Link to this definition"></a></dt>
<dd><p>Extract a file-like object from the archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>member</strong> – Member name or TarInfo object</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>File-like object or None if member is not a file</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.getmembers">
<span class="sig-name descname"><span class="pre">getmembers</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/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/tarfile.html#tarfile.TarInfo" title="(in Python v3.14)"><span class="pre">TarInfo</span></a><span class="p"><span class="pre">]</span></span></span></span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.getmembers"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.getmembers" title="Link to this definition"></a></dt>
<dd><p>Get list of all members in the archive.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.getnames">
<span class="sig-name descname"><span class="pre">getnames</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/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></span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.getnames"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.getnames" title="Link to this definition"></a></dt>
<dd><p>Get list of all member names in the archive.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.list">
<span class="sig-name descname"><span class="pre">list</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">verbose</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</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/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#dict" title="(in Python v3.14)"><span class="pre">dict</span></a><span class="p"><span class="pre">]</span></span></span></span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.list"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.list" title="Link to this definition"></a></dt>
<dd><p>List contents of the archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>verbose</strong> – Include detailed information</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>List of file information dictionaries</p>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.TzstArchive.getmembers" title="tzst.TzstArchive.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a>: Get TarInfo objects for all archive members
<a class="reference internal" href="#tzst.TzstArchive.getnames" title="tzst.TzstArchive.getnames"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getnames()</span></code></a>: Get names of all archive members
<a class="reference internal" href="#tzst.list_archive" title="tzst.list_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">list_archive()</span></code></a>: Convenience function for listing archives</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.open">
<span class="sig-name descname"><span class="pre">open</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.open"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.open" title="Link to this definition"></a></dt>
<dd><p>Open the archive.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.TzstArchive.close" title="tzst.TzstArchive.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a>: Method to close the archive</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="tzst.TzstArchive.test">
<span class="sig-name descname"><span class="pre">test</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/functions.html#bool" title="(in Python v3.14)"><span class="pre">bool</span></a></span></span><a class="reference internal" href="../_modules/tzst/core.html#TzstArchive.test"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.TzstArchive.test" title="Link to this definition"></a></dt>
<dd><p>Test the integrity of the archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>True if archive is valid, False otherwise</p>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.test_archive" title="tzst.test_archive"><code class="xref py py-func docutils literal notranslate"><span class="pre">test_archive()</span></code></a>: Convenience function for testing archive integrity</p>
</div>
</dd></dl>
</dd></dl>
<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>Context Manager Support</strong>: Use with <code class="docutils literal notranslate"><span class="pre">with</span></code> statements for automatic resource management</p></li>
<li><p><strong>Multiple Access Modes</strong>: Read (‘r’), write (‘w’), and append (‘a’) modes</p></li>
<li><p><strong>Streaming Support</strong>: Memory-efficient processing for large archives</p></li>
<li><p><strong>Security Features</strong>: Built-in protection against path traversal attacks</p></li>
<li><p><strong>Flexible Extraction</strong>: Support for selective extraction and conflict resolution</p></li>
</ul>
</section>
<section id="usage-examples">
<h3>Usage Examples<a class="headerlink" href="#usage-examples" title="Link to this heading"></a></h3>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Create a new archive</span>
<span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">,</span> <span class="n">compression_level</span><span class="o">=</span><span class="mi">6</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="n">archive</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"important_file.txt"</span><span class="p">)</span>
<span class="n">archive</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"documents/"</span><span class="p">,</span> <span class="n">recursive</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="c1"># Read an existing archive</span>
<span class="k">with</span> <span class="n">TzstArchive</span><span class="p">(</span><span class="s2">"backup.tzst"</span><span class="p">,</span> <span class="s2">"r"</span><span class="p">)</span> <span class="k">as</span> <span class="n">archive</span><span class="p">:</span>
<span class="n">contents</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">list</span><span class="p">(</span><span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">is_valid</span> <span class="o">=</span> <span class="n">archive</span><span class="o">.</span><span class="n">test</span><span class="p">()</span>
<span class="n">archive</span><span class="o">.</span><span class="n">extractall</span><span class="p">(</span><span class="s2">"restore/"</span><span class="p">)</span>
</pre></div>
</div>
</section>
</section>
<section id="convenience-functions">
<h2>Convenience Functions<a class="headerlink" href="#convenience-functions" title="Link to this heading"></a></h2>
<p>High-level functions for common archive operations without needing to instantiate the <code class="docutils literal notranslate"><span class="pre">TzstArchive</span></code> class directly.</p>
<section id="create-archive">
<h3>create_archive<a class="headerlink" href="#create-archive" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.create_archive">
<span class="sig-prename descclassname"><span class="pre">tzst.</span></span><span class="sig-name descname"><span class="pre">create_archive</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">archive_path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">files</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/collections.abc.html#collections.abc.Sequence" title="(in Python v3.14)"><span class="pre">Sequence</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="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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">compression_level</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><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">3</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">use_temp_file</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">True</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/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span></span><a class="reference internal" href="../_modules/tzst/core.html#create_archive"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.create_archive" title="Link to this definition"></a></dt>
<dd><p>Create a new .tzst archive with atomic file operations.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>archive_path</strong> – Path for the new archive</p></li>
<li><p><strong>files</strong> – List of files/directories to add</p></li>
<li><p><strong>compression_level</strong> – Zstandard compression level (1-22)</p></li>
<li><p><strong>use_temp_file</strong> – If True, create archive in temporary file first, then move
to final location for atomic operation</p></li>
</ul>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.TzstArchive.add" title="tzst.TzstArchive.add"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.add()</span></code></a>: Method for adding files to an open archive</p>
</div>
</dd></dl>
<p>Creates a new tzst archive from the specified files and directories.</p>
<p><strong>Key Features:</strong></p>
<ul class="simple">
<li><p>Configurable compression levels (1-22)</p></li>
<li><p>Atomic creation using temporary files</p></li>
<li><p>Automatic path validation and normalization</p></li>
<li><p>Support for both files and directories</p></li>
</ul>
</section>
<section id="extract-archive">
<h3>extract_archive<a class="headerlink" href="#extract-archive" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.extract_archive">
<span class="sig-prename descclassname"><span class="pre">tzst.</span></span><span class="sig-name descname"><span class="pre">extract_archive</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">archive_path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">extract_path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</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">'.'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">members</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>, <em class="sig-param"><span class="n"><span class="pre">flatten</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">streaming</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">filter</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 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/collections.abc.html#collections.abc.Callable" title="(in Python v3.14)"><span class="pre">Callable</span></a><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">'data'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">conflict_resolution</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ConflictResolution</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/stdtypes.html#str" title="(in Python v3.14)"><span class="pre">str</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">ConflictResolution.REPLACE</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">interactive_callback</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/collections.abc.html#collections.abc.Callable" title="(in Python v3.14)"><span class="pre">Callable</span></a><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">ConflictResolution</span><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/constants.html#None" title="(in Python v3.14)"><span class="pre">None</span></a></span></span><a class="reference internal" href="../_modules/tzst/core.html#extract_archive"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.extract_archive" title="Link to this definition"></a></dt>
<dd><p>Extract files from a .tzst archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>archive_path</strong> – Path to the archive</p></li>
<li><p><strong>extract_path</strong> – Destination directory</p></li>
<li><p><strong>members</strong> – Specific members to extract (None for all)</p></li>
<li><p><strong>flatten</strong> – If True, extract without directory structure</p></li>
<li><p><strong>streaming</strong> – If True, use streaming mode (memory efficient for large archives)</p></li>
<li><p><strong>filter</strong> – Extraction filter for security. Can be:
- ‘data’: Safe filter for cross-platform data archives (default)
- ‘tar’: Honor most tar features but block dangerous ones
- ‘fully_trusted’: Honor all metadata (use only for trusted archives)
- None: Use default behavior (may show deprecation warning)
- callable: Custom filter function</p></li>
<li><p><strong>conflict_resolution</strong> – How to handle file conflicts during extraction</p></li>
<li><p><strong>interactive_callback</strong> – Function to call for interactive conflict resolution</p></li>
</ul>
</dd>
</dl>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Never extract archives from untrusted sources without proper filtering. The ‘data’ filter is recommended for most use cases as it prevents
dangerous security issues like path traversal attacks.</p>
<p>See Also:
<a class="reference internal" href="#tzst.TzstArchive.extract" title="tzst.TzstArchive.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.extract()</span></code></a>: Method for extracting from an open archive</p>
</div>
</dd></dl>
<p>Extracts files from a tzst archive with advanced options for handling conflicts and filtering.</p>
<p><strong>Key Features:</strong></p>
<ul class="simple">
<li><p>Selective extraction with member filtering</p></li>
<li><p>Multiple conflict resolution strategies</p></li>
<li><p>Flatten option to extract all files to a single directory</p></li>
<li><p>Streaming mode for memory efficiency</p></li>
<li><p>Security filters to prevent path traversal attacks</p></li>
</ul>
</section>
<section id="list-archive">
<h3>list_archive<a class="headerlink" href="#list-archive" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.list_archive">
<span class="sig-prename descclassname"><span class="pre">tzst.</span></span><span class="sig-name descname"><span class="pre">list_archive</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">archive_path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbose</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">streaming</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</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/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#dict" title="(in Python v3.14)"><span class="pre">dict</span></a><span class="p"><span class="pre">]</span></span></span></span><a class="reference internal" href="../_modules/tzst/core.html#list_archive"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.list_archive" title="Link to this definition"></a></dt>
<dd><p>List contents of a .tzst archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>archive_path</strong> – Path to the archive</p></li>
<li><p><strong>verbose</strong> – Include detailed information</p></li>
<li><p><strong>streaming</strong> – If True, use streaming mode (memory efficient for large archives)</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>List of file information dictionaries</p>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.TzstArchive.list" title="tzst.TzstArchive.list"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.list()</span></code></a>: Method for listing an open archive</p>
</div>
</dd></dl>
<p>Lists the contents of a tzst archive with optional detailed information.</p>
<p><strong>Returns:</strong></p>
<ul class="simple">
<li><p>List of dictionaries containing file information</p></li>
<li><p>Each entry includes name, size, modification time, and type</p></li>
<li><p>Verbose mode provides additional metadata</p></li>
</ul>
</section>
<section id="test-archive">
<h3>test_archive<a class="headerlink" href="#test-archive" title="Link to this heading"></a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="tzst.test_archive">
<span class="sig-prename descclassname"><span class="pre">tzst.</span></span><span class="sig-name descname"><span class="pre">test_archive</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">archive_path</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 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/pathlib.html#pathlib.Path" title="(in Python v3.14)"><span class="pre">Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">streaming</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#bool" title="(in Python v3.14)"><span class="pre">bool</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">False</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#bool" title="(in Python v3.14)"><span class="pre">bool</span></a></span></span><a class="reference internal" href="../_modules/tzst/core.html#test_archive"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#tzst.test_archive" title="Link to this definition"></a></dt>
<dd><p>Test the integrity of a .tzst archive.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>archive_path</strong> – Path to the archive</p></li>
<li><p><strong>streaming</strong> – If True, use streaming mode (memory efficient for large archives)</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>True if archive is valid, False otherwise</p>
</dd>
</dl>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="#tzst.TzstArchive.test" title="tzst.TzstArchive.test"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TzstArchive.test()</span></code></a>: Method for testing an open archive</p>
</div>
</dd></dl>
<p>Tests the integrity of a tzst archive to verify it can be successfully decompressed.</p>
<p><strong>Returns:</strong></p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the archive is valid and can be extracted</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">False</span></code> if the archive is corrupted or cannot be processed</p></li>
</ul>
</section>
</section>
<section id="enums-and-supporting-classes">
<h2>Enums and Supporting Classes<a class="headerlink" href="#enums-and-supporting-classes" title="Link to this heading"></a></h2>
<section id="conflictresolution">
<h3>ConflictResolution<a class="headerlink" href="#conflictresolution" title="Link to this heading"></a></h3>
<p>Enumeration for handling file conflicts during extraction:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">REPLACE</span></code>: Overwrite existing files</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">SKIP</span></code>: Skip existing files</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">REPLACE_ALL</span></code>: Overwrite all existing files without prompting</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">SKIP_ALL</span></code>: Skip all existing files without prompting</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">AUTO_RENAME</span></code>: Automatically rename conflicting files</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">AUTO_RENAME_ALL</span></code>: Automatically rename all conflicting files</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ASK</span></code>: Prompt user for each conflict (interactive mode)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">EXIT</span></code>: Stop extraction on first conflict</p></li>
</ul>
</section>
<section id="conflictresolutionstate">
<h3>ConflictResolutionState<a class="headerlink" href="#conflictresolutionstate" title="Link to this heading"></a></h3>
<p>State management class for tracking conflict resolution decisions during batch operations.</p>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="index.html" class="btn btn-neutral float-left" title="API Reference" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="cli.html" class="btn btn-neutral float-right" title="CLI 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>