Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
tarfile.html1963 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="tarfile — Read and write tar archive files" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/tarfile.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/tarfile.py The tarfile module makes it possible to read and write tar archives, including those using gzip, bz2 and lzma compression. Use the zipfile module to read or write.zip fi..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_tarfile_00581196.png" />15<meta property="og:image:alt" content="Source code: Lib/tarfile.py The tarfile module makes it possible to read and write tar archives, including those using gzip, bz2 and lzma compression. Use the zipfile module to read or write.zip fi..." />16<meta name="description" content="Source code: Lib/tarfile.py The tarfile module makes it possible to read and write tar archives, including those using gzip, bz2 and lzma compression. Use the zipfile module to read or write.zip fi..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>tarfile — Read and write tar archive files &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="File Formats" href="fileformats.html" />43    <link rel="prev" title="zipfile — Work with ZIP archives" href="zipfile.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/tarfile.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h3><a href="../contents.html">Table of Contents</a></h3>106    <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code> — Read and write tar archive files</a><ul>108<li><a class="reference internal" href="#tarfile-objects">TarFile Objects</a></li>109<li><a class="reference internal" href="#tarinfo-objects">TarInfo Objects</a></li>110<li><a class="reference internal" href="#extraction-filters">Extraction filters</a><ul>111<li><a class="reference internal" href="#default-named-filters">Default named filters</a></li>112<li><a class="reference internal" href="#filter-errors">Filter errors</a></li>113<li><a class="reference internal" href="#hints-for-further-verification">Hints for further verification</a></li>114<li><a class="reference internal" href="#supporting-older-python-versions">Supporting older Python versions</a></li>115<li><a class="reference internal" href="#stateful-extraction-filter-example">Stateful extraction filter example</a></li>116</ul>117</li>118<li><a class="reference internal" href="#command-line-interface">Command-Line Interface</a><ul>119<li><a class="reference internal" href="#command-line-options">Command-line options</a></li>120</ul>121</li>122<li><a class="reference internal" href="#examples">Examples</a><ul>123<li><a class="reference internal" href="#reading-examples">Reading examples</a></li>124<li><a class="reference internal" href="#writing-examples">Writing examples</a></li>125</ul>126</li>127<li><a class="reference internal" href="#supported-tar-formats">Supported tar formats</a></li>128<li><a class="reference internal" href="#unicode-issues">Unicode issues</a></li>129</ul>130</li>131</ul>132 133  </div>134  <div>135    <h4>Previous topic</h4>136    <p class="topless"><a href="zipfile.html"137                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code> — Work with ZIP archives</a></p>138  </div>139  <div>140    <h4>Next topic</h4>141    <p class="topless"><a href="fileformats.html"142                          title="next chapter">File Formats</a></p>143  </div>144  <script>145    document.addEventListener('DOMContentLoaded', () => {146        const title = document.querySelector('meta[property="og:title"]').content;147        const elements = document.querySelectorAll('.improvepage');148        const pageurl = window.location.href.split('?')[0];149        elements.forEach(element => {150            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));151            url.searchParams.set('pagetitle', title);152            url.searchParams.set('pageurl', pageurl);153            url.searchParams.set('pagesource', "library/tarfile.rst");154            element.href = url.toString();155        });156    });157  </script>158  <div role="note" aria-label="source link">159    <h3>This page</h3>160    <ul class="this-page-menu">161      <li><a href="../bugs.html">Report a bug</a></li>162      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>163      <li>164        <a href="https://github.com/python/cpython/blob/main/Doc/library/tarfile.rst?plain=1"165            rel="nofollow">Show source166        </a>167      </li>168      169    </ul>170  </div>171        </nav>172    </div>173</div>174 175  176    <div class="related" role="navigation" aria-label="Related">177      <h3>Navigation</h3>178      <ul>179        <li class="right" style="margin-right: 10px">180          <a href="../genindex.html" title="General Index"181             accesskey="I">index</a></li>182        <li class="right" >183          <a href="../py-modindex.html" title="Python Module Index"184             >modules</a> |</li>185        <li class="right" >186          <a href="fileformats.html" title="File Formats"187             accesskey="N">next</a> |</li>188        <li class="right" >189          <a href="zipfile.html" title="zipfile — Work with ZIP archives"190             accesskey="P">previous</a> |</li>191 192          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>193          <li><a href="https://www.python.org/">Python</a> &#187;</li>194          <li class="switchers">195            <div class="language_switcher_placeholder"></div>196            <div class="version_switcher_placeholder"></div>197          </li>198          <li>199              200          </li>201    <li id="cpython-language-and-version">202      <a href="../index.html">3.15.0a6 Documentation</a> &#187;203    </li>204 205          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>206          <li class="nav-item nav-item-2"><a href="archiving.html" accesskey="U">Data Compression and Archiving</a> &#187;</li>207        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code> — Read and write tar archive files</a></li>208                <li class="right">209                    210 211    <div class="inline-search" role="search">212        <form class="inline-search" action="../search.html" method="get">213          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">214          <input type="submit" value="Go">215        </form>216    </div>217                     |218                </li>219            <li class="right">220<label class="theme-selector-label">221    Theme222    <select class="theme-selector" oninput="activateTheme(this.value)">223        <option value="auto" selected>Auto</option>224        <option value="light">Light</option>225        <option value="dark">Dark</option>226    </select>227</label> |</li>228            229      </ul>230    </div>    231 232    <div class="document">233      <div class="documentwrapper">234        <div class="bodywrapper">235          <div class="body" role="main">236            237  <section id="module-tarfile">238<span id="tarfile-read-and-write-tar-archive-files"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code> — Read and write tar archive files<a class="headerlink" href="#module-tarfile" title="Link to this heading">¶</a></h1>239<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/tarfile.py">Lib/tarfile.py</a></p>240<hr class="docutils" />241<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code> module makes it possible to read and write tar242archives, including those using gzip, bz2 and lzma compression.243Use the <a class="reference internal" href="zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code></a> module to read or write <code class="file docutils literal notranslate"><span class="pre">.zip</span></code> files, or the244higher-level functions in <a class="reference internal" href="shutil.html#archiving-operations"><span class="std std-ref">shutil</span></a>.</p>245<p>Some facts and figures:</p>246<ul>247<li><p>reads and writes <a class="reference internal" href="gzip.html#module-gzip" title="gzip: Interfaces for gzip compression and decompression using file objects."><code class="xref py py-mod docutils literal notranslate"><span class="pre">gzip</span></code></a>, <a class="reference internal" href="bz2.html#module-bz2" title="bz2: Interfaces for bzip2 compression and decompression."><code class="xref py py-mod docutils literal notranslate"><span class="pre">bz2</span></code></a>, <a class="reference internal" href="compression.zstd.html#module-compression.zstd" title="compression.zstd: Low-level interface to compression and decompression routines in the zstd library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">compression.zstd</span></code></a>, and248<a class="reference internal" href="lzma.html#module-lzma" title="lzma: A Python wrapper for the liblzma compression library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">lzma</span></code></a> compressed archives if the respective modules are available.</p>249<p>If any of these <a class="reference internal" href="../glossary.html#term-optional-module"><span class="xref std std-term">optional modules</span></a> are missing from250your copy of CPython, look for documentation from your distributor (that is,251whoever provided Python to you).252If you are the distributor, see <a class="reference internal" href="../using/configure.html#optional-module-requirements"><span class="std std-ref">Requirements for optional modules</span></a>.</p>253</li>254<li><p>read/write support for the POSIX.1-1988 (ustar) format.</p></li>255<li><p>read/write support for the GNU tar format including <em>longname</em> and <em>longlink</em>256extensions, read-only support for all variants of the <em>sparse</em> extension257including restoration of sparse files.</p></li>258<li><p>read/write support for the POSIX.1-2001 (pax) format.</p></li>259<li><p>handles directories, regular files, hardlinks, symbolic links, fifos,260character devices and block devices and is able to acquire and restore file261information like timestamp, access permissions and owner.</p></li>262</ul>263<div class="versionchanged">264<p><span class="versionmodified changed">Changed in version 3.3: </span>Added support for <a class="reference internal" href="lzma.html#module-lzma" title="lzma: A Python wrapper for the liblzma compression library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">lzma</span></code></a> compression.</p>265</div>266<div class="versionchanged">267<p><span class="versionmodified changed">Changed in version 3.12: </span>Archives are extracted using a <a class="reference internal" href="#tarfile-extraction-filter"><span class="std std-ref">filter</span></a>,268which makes it possible to either limit surprising/dangerous features,269or to acknowledge that they are expected and the archive is fully trusted.</p>270</div>271<div class="versionchanged">272<p><span class="versionmodified changed">Changed in version 3.14: </span>Set the default extraction filter to <a class="reference internal" href="#tarfile.data_filter" title="tarfile.data_filter"><code class="xref py py-func docutils literal notranslate"><span class="pre">data</span></code></a>,273which disallows some dangerous features such as links to absolute paths274or paths outside of the destination. Previously, the filter strategy275was equivalent to <a class="reference internal" href="#tarfile.fully_trusted_filter" title="tarfile.fully_trusted_filter"><code class="xref py py-func docutils literal notranslate"><span class="pre">fully_trusted</span></code></a>.</p>276</div>277<div class="versionchanged">278<p><span class="versionmodified changed">Changed in version 3.14: </span>Added support for Zstandard compression using <a class="reference internal" href="compression.zstd.html#module-compression.zstd" title="compression.zstd: Low-level interface to compression and decompression routines in the zstd library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">compression.zstd</span></code></a>.</p>279</div>280<dl class="py function">281<dt class="sig sig-object py" id="tarfile.open">282<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">open</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fileobj</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">bufsize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">10240</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.open" title="Link to this definition">¶</a></dt>283<dd><p>Return a <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> object for the pathname <em>name</em>. For detailed284information on <code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code> objects and the keyword arguments that are285allowed, see <a class="reference internal" href="#tarfile-objects"><span class="std std-ref">TarFile Objects</span></a>.</p>286<p><em>mode</em> has to be a string of the form <code class="docutils literal notranslate"><span class="pre">'filemode[:compression]'</span></code>, it defaults287to <code class="docutils literal notranslate"><span class="pre">'r'</span></code>. Here is a full list of mode combinations:</p>288<table class="docutils align-default">289<thead>290<tr class="row-odd"><th class="head"><p>mode</p></th>291<th class="head"><p>action</p></th>292</tr>293</thead>294<tbody>295<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r'</span></code> or296<code class="docutils literal notranslate"><span class="pre">'r:*'</span></code></p></td>297<td><p>Open for reading with transparent298compression (recommended).</p></td>299</tr>300<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'r:'</span></code></p></td>301<td><p>Open for reading exclusively without302compression.</p></td>303</tr>304<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r:gz'</span></code></p></td>305<td><p>Open for reading with gzip compression.</p></td>306</tr>307<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'r:bz2'</span></code></p></td>308<td><p>Open for reading with bzip2 compression.</p></td>309</tr>310<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r:xz'</span></code></p></td>311<td><p>Open for reading with lzma compression.</p></td>312</tr>313<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'r:zst'</span></code></p></td>314<td><p>Open for reading with Zstandard compression.</p></td>315</tr>316<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'x'</span></code> or317<code class="docutils literal notranslate"><span class="pre">'x:'</span></code></p></td>318<td><p>Create a tarfile exclusively without319compression.320Raise a <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> exception321if it already exists.</p></td>322</tr>323<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'x:gz'</span></code></p></td>324<td><p>Create a tarfile with gzip compression.325Raise a <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> exception326if it already exists.</p></td>327</tr>328<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'x:bz2'</span></code></p></td>329<td><p>Create a tarfile with bzip2 compression.330Raise a <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> exception331if it already exists.</p></td>332</tr>333<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'x:xz'</span></code></p></td>334<td><p>Create a tarfile with lzma compression.335Raise a <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> exception336if it already exists.</p></td>337</tr>338<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'x:zst'</span></code></p></td>339<td><p>Create a tarfile with Zstandard compression.340Raise a <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> exception341if it already exists.</p></td>342</tr>343<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'a'</span></code> or344<code class="docutils literal notranslate"><span class="pre">'a:'</span></code></p></td>345<td><p>Open for appending with no compression. The346file is created if it does not exist.</p></td>347</tr>348<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'w'</span></code> or349<code class="docutils literal notranslate"><span class="pre">'w:'</span></code></p></td>350<td><p>Open for uncompressed writing.</p></td>351</tr>352<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'w:gz'</span></code></p></td>353<td><p>Open for gzip compressed writing.</p></td>354</tr>355<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'w:bz2'</span></code></p></td>356<td><p>Open for bzip2 compressed writing.</p></td>357</tr>358<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'w:xz'</span></code></p></td>359<td><p>Open for lzma compressed writing.</p></td>360</tr>361<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'w:zst'</span></code></p></td>362<td><p>Open for Zstandard compressed writing.</p></td>363</tr>364</tbody>365</table>366<p>Note that <code class="docutils literal notranslate"><span class="pre">'a:gz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'a:bz2'</span></code> or <code class="docutils literal notranslate"><span class="pre">'a:xz'</span></code> is not possible. If <em>mode</em>367is not suitable to open a certain (compressed) file for reading,368<a class="reference internal" href="#tarfile.ReadError" title="tarfile.ReadError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ReadError</span></code></a> is raised. Use <em>mode</em> <code class="docutils literal notranslate"><span class="pre">'r'</span></code> to avoid this.  If a369compression method is not supported, <a class="reference internal" href="#tarfile.CompressionError" title="tarfile.CompressionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">CompressionError</span></code></a> is raised.</p>370<p>If <em>fileobj</em> is specified, it is used as an alternative to a <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>371opened in binary mode for <em>name</em>. It is supposed to be at position 0.</p>372<p>For modes <code class="docutils literal notranslate"><span class="pre">'w:gz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'x:gz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'w|gz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'w:bz2'</span></code>, <code class="docutils literal notranslate"><span class="pre">'x:bz2'</span></code>,373<code class="docutils literal notranslate"><span class="pre">'w|bz2'</span></code>, <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a> accepts the keyword argument374<em>compresslevel</em> (default <code class="docutils literal notranslate"><span class="pre">6</span></code>) to specify the compression level of the file.</p>375<p>For modes <code class="docutils literal notranslate"><span class="pre">'w:xz'</span></code>, <code class="docutils literal notranslate"><span class="pre">'x:xz'</span></code> and <code class="docutils literal notranslate"><span class="pre">'w|xz'</span></code>, <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a> accepts the376keyword argument <em>preset</em> to specify the compression level of the file.</p>377<p>For modes <code class="docutils literal notranslate"><span class="pre">'w:zst'</span></code>, <code class="docutils literal notranslate"><span class="pre">'x:zst'</span></code> and <code class="docutils literal notranslate"><span class="pre">'w|zst'</span></code>, <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a>378accepts the keyword argument <em>level</em> to specify the compression level of379the file. The keyword argument <em>options</em> may also be passed, providing380advanced Zstandard compression parameters described by381<a class="reference internal" href="compression.zstd.html#compression.zstd.CompressionParameter" title="compression.zstd.CompressionParameter"><code class="xref py py-class docutils literal notranslate"><span class="pre">CompressionParameter</span></code></a>. The keyword argument382<em>zstd_dict</em> can be passed to provide a <a class="reference internal" href="compression.zstd.html#compression.zstd.ZstdDict" title="compression.zstd.ZstdDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZstdDict</span></code></a>,383a Zstandard dictionary used to improve compression of smaller amounts of384data.</p>385<p>For special purposes, there is a second format for <em>mode</em>:386<code class="docutils literal notranslate"><span class="pre">'filemode|[compression]'</span></code>.  <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a> will return a <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a>387object that processes its data as a stream of blocks.  No random seeking will388be done on the file. If given, <em>fileobj</em> may be any object that has a389<a class="reference internal" href="io.html#io.RawIOBase.read" title="io.RawIOBase.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> or <a class="reference internal" href="io.html#io.RawIOBase.write" title="io.RawIOBase.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code></a> method390(depending on the <em>mode</em>) that works with bytes.391<em>bufsize</em> specifies the blocksize and defaults to <code class="docutils literal notranslate"><span class="pre">20</span> <span class="pre">*</span> <span class="pre">512</span></code> bytes.392Use this variant in combination with e.g. <code class="docutils literal notranslate"><span class="pre">sys.stdin.buffer</span></code>, a socket393<a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> or a tape device.394However, such a <code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code> object is limited in that it does395not allow random access, see <a class="reference internal" href="#tar-examples"><span class="std std-ref">Examples</span></a>.  The currently396possible modes:</p>397<table class="docutils align-default">398<thead>399<tr class="row-odd"><th class="head"><p>Mode</p></th>400<th class="head"><p>Action</p></th>401</tr>402</thead>403<tbody>404<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r|*'</span></code></p></td>405<td><p>Open a <em>stream</em> of tar blocks for reading406with transparent compression.</p></td>407</tr>408<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'r|'</span></code></p></td>409<td><p>Open a <em>stream</em> of uncompressed tar blocks410for reading.</p></td>411</tr>412<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r|gz'</span></code></p></td>413<td><p>Open a gzip compressed <em>stream</em> for414reading.</p></td>415</tr>416<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'r|bz2'</span></code></p></td>417<td><p>Open a bzip2 compressed <em>stream</em> for418reading.</p></td>419</tr>420<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'r|xz'</span></code></p></td>421<td><p>Open an lzma compressed <em>stream</em> for422reading.</p></td>423</tr>424<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'r|zst'</span></code></p></td>425<td><p>Open a Zstandard compressed <em>stream</em> for426reading.</p></td>427</tr>428<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'w|'</span></code></p></td>429<td><p>Open an uncompressed <em>stream</em> for writing.</p></td>430</tr>431<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'w|gz'</span></code></p></td>432<td><p>Open a gzip compressed <em>stream</em> for433writing.</p></td>434</tr>435<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'w|bz2'</span></code></p></td>436<td><p>Open a bzip2 compressed <em>stream</em> for437writing.</p></td>438</tr>439<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">'w|xz'</span></code></p></td>440<td><p>Open an lzma compressed <em>stream</em> for441writing.</p></td>442</tr>443<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">'w|zst'</span></code></p></td>444<td><p>Open a Zstandard compressed <em>stream</em> for445writing.</p></td>446</tr>447</tbody>448</table>449<div class="versionchanged">450<p><span class="versionmodified changed">Changed in version 3.5: </span>The <code class="docutils literal notranslate"><span class="pre">'x'</span></code> (exclusive creation) mode was added.</p>451</div>452<div class="versionchanged">453<p><span class="versionmodified changed">Changed in version 3.6: </span>The <em>name</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>454</div>455<div class="versionchanged">456<p><span class="versionmodified changed">Changed in version 3.12: </span>The <em>compresslevel</em> keyword argument also works for streams.</p>457</div>458<div class="versionchanged">459<p><span class="versionmodified changed">Changed in version 3.14: </span>The <em>preset</em> keyword argument also works for streams.</p>460</div>461<div class="versionchanged">462<p><span class="versionmodified changed">Changed in version 3.15: </span>The default compression level was reduced to 6 (down from 9).463It is the default level used by most compression tools and a better464tradeoff between speed and performance.</p>465</div>466</dd></dl>467 468<dl class="py class">469<dt class="sig sig-object py">470<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">TarFile</span></span></dt>471<dd><p>Class for reading and writing tar archives. Do not use this class directly:472use <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a> instead. See <a class="reference internal" href="#tarfile-objects"><span class="std std-ref">TarFile Objects</span></a>.</p>473</dd></dl>474 475<dl class="py function">476<dt class="sig sig-object py" id="tarfile.is_tarfile">477<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">is_tarfile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.is_tarfile" title="Link to this definition">¶</a></dt>478<dd><p>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if <em>name</em> is a tar archive file, that the <code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code>479module can read. <em>name</em> may be a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>, file, or file-like object.</p>480<div class="versionchanged">481<p><span class="versionmodified changed">Changed in version 3.9: </span>Support for file and file-like objects.</p>482</div>483</dd></dl>484 485<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code> module defines the following exceptions:</p>486<dl class="py exception">487<dt class="sig sig-object py" id="tarfile.TarError">488<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">TarError</span></span><a class="headerlink" href="#tarfile.TarError" title="Link to this definition">¶</a></dt>489<dd><p>Base class for all <code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code> exceptions.</p>490</dd></dl>491 492<dl class="py exception">493<dt class="sig sig-object py" id="tarfile.ReadError">494<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">ReadError</span></span><a class="headerlink" href="#tarfile.ReadError" title="Link to this definition">¶</a></dt>495<dd><p>Is raised when a tar archive is opened, that either cannot be handled by the496<code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code> module or is somehow invalid.</p>497</dd></dl>498 499<dl class="py exception">500<dt class="sig sig-object py" id="tarfile.CompressionError">501<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">CompressionError</span></span><a class="headerlink" href="#tarfile.CompressionError" title="Link to this definition">¶</a></dt>502<dd><p>Is raised when a compression method is not supported or when the data cannot be503decoded properly.</p>504</dd></dl>505 506<dl class="py exception">507<dt class="sig sig-object py" id="tarfile.StreamError">508<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">StreamError</span></span><a class="headerlink" href="#tarfile.StreamError" title="Link to this definition">¶</a></dt>509<dd><p>Is raised for the limitations that are typical for stream-like <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a>510objects.</p>511</dd></dl>512 513<dl class="py exception">514<dt class="sig sig-object py" id="tarfile.ExtractError">515<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">ExtractError</span></span><a class="headerlink" href="#tarfile.ExtractError" title="Link to this definition">¶</a></dt>516<dd><p>Is raised for <em>non-fatal</em> errors when using <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.extract()</span></code></a>, but only if517<a class="reference internal" href="#tarfile.TarFile.errorlevel" title="tarfile.TarFile.errorlevel"><code class="xref py py-attr docutils literal notranslate"><span class="pre">TarFile.errorlevel</span></code></a><code class="docutils literal notranslate"><span class="pre">==</span> <span class="pre">2</span></code>.</p>518</dd></dl>519 520<dl class="py exception">521<dt class="sig sig-object py" id="tarfile.HeaderError">522<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">HeaderError</span></span><a class="headerlink" href="#tarfile.HeaderError" title="Link to this definition">¶</a></dt>523<dd><p>Is raised by <a class="reference internal" href="#tarfile.TarInfo.frombuf" title="tarfile.TarInfo.frombuf"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarInfo.frombuf()</span></code></a> if the buffer it gets is invalid.</p>524</dd></dl>525 526<dl class="py exception">527<dt class="sig sig-object py" id="tarfile.FilterError">528<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">FilterError</span></span><a class="headerlink" href="#tarfile.FilterError" title="Link to this definition">¶</a></dt>529<dd><p>Base class for members <a class="reference internal" href="#tarfile-extraction-refuse"><span class="std std-ref">refused</span></a> by530filters.</p>531<dl class="py attribute">532<dt class="sig sig-object py" id="tarfile.FilterError.tarinfo">533<span class="sig-name descname"><span class="pre">tarinfo</span></span><a class="headerlink" href="#tarfile.FilterError.tarinfo" title="Link to this definition">¶</a></dt>534<dd><p>Information about the member that the filter refused to extract,535as <a class="reference internal" href="#tarinfo-objects"><span class="std std-ref">TarInfo</span></a>.</p>536</dd></dl>537 538</dd></dl>539 540<dl class="py exception">541<dt class="sig sig-object py" id="tarfile.AbsolutePathError">542<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">AbsolutePathError</span></span><a class="headerlink" href="#tarfile.AbsolutePathError" title="Link to this definition">¶</a></dt>543<dd><p>Raised to refuse extracting a member with an absolute path.</p>544</dd></dl>545 546<dl class="py exception">547<dt class="sig sig-object py" id="tarfile.OutsideDestinationError">548<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">OutsideDestinationError</span></span><a class="headerlink" href="#tarfile.OutsideDestinationError" title="Link to this definition">¶</a></dt>549<dd><p>Raised to refuse extracting a member outside the destination directory.</p>550</dd></dl>551 552<dl class="py exception">553<dt class="sig sig-object py" id="tarfile.SpecialFileError">554<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">SpecialFileError</span></span><a class="headerlink" href="#tarfile.SpecialFileError" title="Link to this definition">¶</a></dt>555<dd><p>Raised to refuse extracting a special file (e.g. a device or pipe).</p>556</dd></dl>557 558<dl class="py exception">559<dt class="sig sig-object py" id="tarfile.AbsoluteLinkError">560<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">AbsoluteLinkError</span></span><a class="headerlink" href="#tarfile.AbsoluteLinkError" title="Link to this definition">¶</a></dt>561<dd><p>Raised to refuse extracting a symbolic link with an absolute path.</p>562</dd></dl>563 564<dl class="py exception">565<dt class="sig sig-object py" id="tarfile.LinkOutsideDestinationError">566<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">LinkOutsideDestinationError</span></span><a class="headerlink" href="#tarfile.LinkOutsideDestinationError" title="Link to this definition">¶</a></dt>567<dd><p>Raised to refuse extracting a symbolic link pointing outside the destination568directory.</p>569</dd></dl>570 571<dl class="py exception">572<dt class="sig sig-object py" id="tarfile.LinkFallbackError">573<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">LinkFallbackError</span></span><a class="headerlink" href="#tarfile.LinkFallbackError" title="Link to this definition">¶</a></dt>574<dd><p>Raised to refuse emulating a link (hard or symbolic) by extracting another575archive member, when that member would be rejected by the filter location.576The exception that was raised to reject the replacement member is available577as <code class="xref py py-attr docutils literal notranslate"><span class="pre">BaseException.__context__</span></code>.</p>578<div class="versionadded">579<p><span class="versionmodified added">Added in version 3.15.</span></p>580</div>581</dd></dl>582 583<p>The following constants are available at the module level:</p>584<dl class="py data">585<dt class="sig sig-object py" id="tarfile.ENCODING">586<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">ENCODING</span></span><a class="headerlink" href="#tarfile.ENCODING" title="Link to this definition">¶</a></dt>587<dd><p>The default character encoding: <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code> on Windows, the value returned by588<a class="reference internal" href="sys.html#sys.getfilesystemencoding" title="sys.getfilesystemencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getfilesystemencoding()</span></code></a> otherwise.</p>589</dd></dl>590 591<dl class="py data">592<dt class="sig sig-object py" id="tarfile.REGTYPE">593<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">REGTYPE</span></span><a class="headerlink" href="#tarfile.REGTYPE" title="Link to this definition">¶</a></dt>594<dt class="sig sig-object py" id="tarfile.AREGTYPE">595<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">AREGTYPE</span></span><a class="headerlink" href="#tarfile.AREGTYPE" title="Link to this definition">¶</a></dt>596<dd><p>A regular file <a class="reference internal" href="#tarfile.TarInfo.type" title="tarfile.TarInfo.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>.</p>597</dd></dl>598 599<dl class="py data">600<dt class="sig sig-object py" id="tarfile.LNKTYPE">601<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">LNKTYPE</span></span><a class="headerlink" href="#tarfile.LNKTYPE" title="Link to this definition">¶</a></dt>602<dd><p>A link (inside tarfile) <a class="reference internal" href="#tarfile.TarInfo.type" title="tarfile.TarInfo.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>.</p>603</dd></dl>604 605<dl class="py data">606<dt class="sig sig-object py" id="tarfile.SYMTYPE">607<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">SYMTYPE</span></span><a class="headerlink" href="#tarfile.SYMTYPE" title="Link to this definition">¶</a></dt>608<dd><p>A symbolic link <a class="reference internal" href="#tarfile.TarInfo.type" title="tarfile.TarInfo.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>.</p>609</dd></dl>610 611<dl class="py data">612<dt class="sig sig-object py" id="tarfile.CHRTYPE">613<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">CHRTYPE</span></span><a class="headerlink" href="#tarfile.CHRTYPE" title="Link to this definition">¶</a></dt>614<dd><p>A character special device <a class="reference internal" href="#tarfile.TarInfo.type" title="tarfile.TarInfo.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>.</p>615</dd></dl>616 617<dl class="py data">618<dt class="sig sig-object py" id="tarfile.BLKTYPE">619<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">BLKTYPE</span></span><a class="headerlink" href="#tarfile.BLKTYPE" title="Link to this definition">¶</a></dt>620<dd><p>A block special device <a class="reference internal" href="#tarfile.TarInfo.type" title="tarfile.TarInfo.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>.</p>621</dd></dl>622 623<dl class="py data">624<dt class="sig sig-object py" id="tarfile.DIRTYPE">625<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">DIRTYPE</span></span><a class="headerlink" href="#tarfile.DIRTYPE" title="Link to this definition">¶</a></dt>626<dd><p>A directory <a class="reference internal" href="#tarfile.TarInfo.type" title="tarfile.TarInfo.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>.</p>627</dd></dl>628 629<dl class="py data">630<dt class="sig sig-object py" id="tarfile.FIFOTYPE">631<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">FIFOTYPE</span></span><a class="headerlink" href="#tarfile.FIFOTYPE" title="Link to this definition">¶</a></dt>632<dd><p>A FIFO special device <a class="reference internal" href="#tarfile.TarInfo.type" title="tarfile.TarInfo.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>.</p>633</dd></dl>634 635<dl class="py data">636<dt class="sig sig-object py" id="tarfile.CONTTYPE">637<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">CONTTYPE</span></span><a class="headerlink" href="#tarfile.CONTTYPE" title="Link to this definition">¶</a></dt>638<dd><p>A contiguous file <a class="reference internal" href="#tarfile.TarInfo.type" title="tarfile.TarInfo.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>.</p>639</dd></dl>640 641<dl class="py data">642<dt class="sig sig-object py" id="tarfile.GNUTYPE_LONGNAME">643<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">GNUTYPE_LONGNAME</span></span><a class="headerlink" href="#tarfile.GNUTYPE_LONGNAME" title="Link to this definition">¶</a></dt>644<dd><p>A GNU tar longname <a class="reference internal" href="#tarfile.TarInfo.type" title="tarfile.TarInfo.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>.</p>645</dd></dl>646 647<dl class="py data">648<dt class="sig sig-object py" id="tarfile.GNUTYPE_LONGLINK">649<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">GNUTYPE_LONGLINK</span></span><a class="headerlink" href="#tarfile.GNUTYPE_LONGLINK" title="Link to this definition">¶</a></dt>650<dd><p>A GNU tar longlink <a class="reference internal" href="#tarfile.TarInfo.type" title="tarfile.TarInfo.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>.</p>651</dd></dl>652 653<dl class="py data">654<dt class="sig sig-object py" id="tarfile.GNUTYPE_SPARSE">655<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">GNUTYPE_SPARSE</span></span><a class="headerlink" href="#tarfile.GNUTYPE_SPARSE" title="Link to this definition">¶</a></dt>656<dd><p>A GNU tar sparse file <a class="reference internal" href="#tarfile.TarInfo.type" title="tarfile.TarInfo.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>.</p>657</dd></dl>658 659<p>Each of the following constants defines a tar archive format that the660<code class="xref py py-mod docutils literal notranslate"><span class="pre">tarfile</span></code> module is able to create. See section <a class="reference internal" href="#tar-formats"><span class="std std-ref">Supported tar formats</span></a> for661details.</p>662<dl class="py data">663<dt class="sig sig-object py" id="tarfile.USTAR_FORMAT">664<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">USTAR_FORMAT</span></span><a class="headerlink" href="#tarfile.USTAR_FORMAT" title="Link to this definition">¶</a></dt>665<dd><p>POSIX.1-1988 (ustar) format.</p>666</dd></dl>667 668<dl class="py data">669<dt class="sig sig-object py" id="tarfile.GNU_FORMAT">670<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">GNU_FORMAT</span></span><a class="headerlink" href="#tarfile.GNU_FORMAT" title="Link to this definition">¶</a></dt>671<dd><p>GNU tar format.</p>672</dd></dl>673 674<dl class="py data">675<dt class="sig sig-object py" id="tarfile.PAX_FORMAT">676<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">PAX_FORMAT</span></span><a class="headerlink" href="#tarfile.PAX_FORMAT" title="Link to this definition">¶</a></dt>677<dd><p>POSIX.1-2001 (pax) format.</p>678</dd></dl>679 680<dl class="py data">681<dt class="sig sig-object py" id="tarfile.DEFAULT_FORMAT">682<span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">DEFAULT_FORMAT</span></span><a class="headerlink" href="#tarfile.DEFAULT_FORMAT" title="Link to this definition">¶</a></dt>683<dd><p>The default format for creating archives. This is currently <a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a>.</p>684<div class="versionchanged">685<p><span class="versionmodified changed">Changed in version 3.8: </span>The default format for new archives was changed to686<a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a> from <a class="reference internal" href="#tarfile.GNU_FORMAT" title="tarfile.GNU_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">GNU_FORMAT</span></code></a>.</p>687</div>688</dd></dl>689 690<div class="admonition seealso">691<p class="admonition-title">See also</p>692<dl class="simple">693<dt>Module <a class="reference internal" href="zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code></a></dt><dd><p>Documentation of the <a class="reference internal" href="zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code></a> standard module.</p>694</dd>695<dt><a class="reference internal" href="shutil.html#archiving-operations"><span class="std std-ref">Archiving operations</span></a></dt><dd><p>Documentation of the higher-level archiving facilities provided by the696standard <a class="reference internal" href="shutil.html#module-shutil" title="shutil: High-level file operations, including copying."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shutil</span></code></a> module.</p>697</dd>698<dt><a class="reference external" href="https://www.gnu.org/software/tar/manual/html_node/Standard.html">GNU tar manual, Basic Tar Format</a></dt><dd><p>Documentation for tar archive files, including GNU tar extensions.</p>699</dd>700</dl>701</div>702<section id="tarfile-objects">703<span id="id1"></span><h2>TarFile Objects<a class="headerlink" href="#tarfile-objects" title="Link to this heading">¶</a></h2>704<p>The <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> object provides an interface to a tar archive. A tar705archive is a sequence of blocks. An archive member (a stored file) is made up of706a header block followed by data blocks. It is possible to store a file in a tar707archive several times. Each archive member is represented by a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a>708object, see <a class="reference internal" href="#tarinfo-objects"><span class="std std-ref">TarInfo Objects</span></a> for details.</p>709<p>A <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> object can be used as a context manager in a <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a>710statement. It will automatically be closed when the block is completed. Please711note that in the event of an exception an archive opened for writing will not712be finalized; only the internally used file object will be closed. See the713<a class="reference internal" href="#tar-examples"><span class="std std-ref">Examples</span></a> section for a use case.</p>714<div class="versionadded">715<p><span class="versionmodified added">Added in version 3.2: </span>Added support for the context management protocol.</p>716</div>717<dl class="py class">718<dt class="sig sig-object py" id="tarfile.TarFile">719<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">TarFile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fileobj</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DEFAULT_FORMAT</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tarinfo</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">TarInfo</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dereference</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ignore_zeros</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">ENCODING</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'surrogateescape'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pax_headers</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">debug</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errorlevel</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stream</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile" title="Link to this definition">¶</a></dt>720<dd><p>All following arguments are optional and can be accessed as instance attributes721as well.</p>722<p><em>name</em> is the pathname of the archive. <em>name</em> may be a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.723It can be omitted if <em>fileobj</em> is given.724In this case, the file object’s <code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code> attribute is used if it exists.</p>725<p><em>mode</em> is either <code class="docutils literal notranslate"><span class="pre">'r'</span></code> to read from an existing archive, <code class="docutils literal notranslate"><span class="pre">'a'</span></code> to append726data to an existing file, <code class="docutils literal notranslate"><span class="pre">'w'</span></code> to create a new file overwriting an existing727one, or <code class="docutils literal notranslate"><span class="pre">'x'</span></code> to create a new file only if it does not already exist.</p>728<p>If <em>fileobj</em> is given, it is used for reading or writing data. If it can be729determined, <em>mode</em> is overridden by <em>fileobj</em>’s mode. <em>fileobj</em> will be used730from position 0.</p>731<div class="admonition note">732<p class="admonition-title">Note</p>733<p><em>fileobj</em> is not closed, when <code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code> is closed.</p>734</div>735<p><em>format</em> controls the archive format for writing. It must be one of the constants736<a class="reference internal" href="#tarfile.USTAR_FORMAT" title="tarfile.USTAR_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">USTAR_FORMAT</span></code></a>, <a class="reference internal" href="#tarfile.GNU_FORMAT" title="tarfile.GNU_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">GNU_FORMAT</span></code></a> or <a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a> that are737defined at module level. When reading, format will be automatically detected, even738if different formats are present in a single archive.</p>739<p>The <em>tarinfo</em> argument can be used to replace the default <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> class740with a different one.</p>741<p>If <em>dereference</em> is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>, add symbolic and hard links to the archive. If it742is <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, add the content of the target files to the archive. This has no743effect on systems that do not support symbolic links.</p>744<p>If <em>ignore_zeros</em> is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>, treat an empty block as the end of the archive.745If it is <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, skip empty (and invalid) blocks and try to get as many members746as possible. This is only useful for reading concatenated or damaged archives.</p>747<p><em>debug</em> can be set from <code class="docutils literal notranslate"><span class="pre">0</span></code> (no debug messages) up to <code class="docutils literal notranslate"><span class="pre">3</span></code> (all debug748messages). The messages are written to <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code>.</p>749<p><em>errorlevel</em> controls how extraction errors are handled,750see <a class="reference internal" href="#tarfile.TarFile.errorlevel" title="tarfile.TarFile.errorlevel"><code class="xref py py-attr docutils literal notranslate"><span class="pre">the</span> <span class="pre">corresponding</span> <span class="pre">attribute</span></code></a>.</p>751<p>The <em>encoding</em> and <em>errors</em> arguments define the character encoding to be752used for reading or writing the archive and how conversion errors are going753to be handled. The default settings will work for most users.754See section <a class="reference internal" href="#tar-unicode"><span class="std std-ref">Unicode issues</span></a> for in-depth information.</p>755<p>The <em>pax_headers</em> argument is an optional dictionary of strings which756will be added as a pax global header if <em>format</em> is <a class="reference internal" href="#tarfile.PAX_FORMAT" title="tarfile.PAX_FORMAT"><code class="xref py py-const docutils literal notranslate"><span class="pre">PAX_FORMAT</span></code></a>.</p>757<p>If <em>stream</em> is set to <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> then while reading the archive info about files758in the archive are not cached, saving memory.</p>759<div class="versionchanged">760<p><span class="versionmodified changed">Changed in version 3.2: </span>Use <code class="docutils literal notranslate"><span class="pre">'surrogateescape'</span></code> as the default for the <em>errors</em> argument.</p>761</div>762<div class="versionchanged">763<p><span class="versionmodified changed">Changed in version 3.5: </span>The <code class="docutils literal notranslate"><span class="pre">'x'</span></code> (exclusive creation) mode was added.</p>764</div>765<div class="versionchanged">766<p><span class="versionmodified changed">Changed in version 3.6: </span>The <em>name</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>767</div>768<div class="versionchanged">769<p><span class="versionmodified changed">Changed in version 3.13: </span>Add the <em>stream</em> parameter.</p>770</div>771</dd></dl>772 773<dl class="py method">774<dt class="sig sig-object py" id="tarfile.TarFile.open">775<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><span class="sig-name descname"><span class="pre">open</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">...</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.open" title="Link to this definition">¶</a></dt>776<dd><p>Alternative constructor. The <a class="reference internal" href="#tarfile.open" title="tarfile.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">tarfile.open()</span></code></a> function is actually a777shortcut to this classmethod.</p>778</dd></dl>779 780<dl class="py method">781<dt class="sig sig-object py" id="tarfile.TarFile.getmember">782<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><span class="sig-name descname"><span class="pre">getmember</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.getmember" title="Link to this definition">¶</a></dt>783<dd><p>Return a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object for member <em>name</em>. If <em>name</em> can not be found784in the archive, <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> is raised.</p>785<div class="admonition note">786<p class="admonition-title">Note</p>787<p>If a member occurs more than once in the archive, its last occurrence is assumed788to be the most up-to-date version.</p>789</div>790</dd></dl>791 792<dl class="py method">793<dt class="sig sig-object py" id="tarfile.TarFile.getmembers">794<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><span class="sig-name descname"><span class="pre">getmembers</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.getmembers" title="Link to this definition">¶</a></dt>795<dd><p>Return the members of the archive as a list of <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> objects. The796list has the same order as the members in the archive.</p>797</dd></dl>798 799<dl class="py method">800<dt class="sig sig-object py" id="tarfile.TarFile.getnames">801<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><span class="sig-name descname"><span class="pre">getnames</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.getnames" title="Link to this definition">¶</a></dt>802<dd><p>Return the members as a list of their names. It has the same order as the list803returned by <a class="reference internal" href="#tarfile.TarFile.getmembers" title="tarfile.TarFile.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a>.</p>804</dd></dl>805 806<dl class="py method">807<dt class="sig sig-object py" id="tarfile.TarFile.list">808<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><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="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</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">members</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.list" title="Link to this definition">¶</a></dt>809<dd><p>Print a table of contents to <code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code>. If <em>verbose</em> is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>,810only the names of the members are printed. If it is <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, output811similar to that of <strong class="program">ls -l</strong> is produced. If optional <em>members</em> is812given, it must be a subset of the list returned by <a class="reference internal" href="#tarfile.TarFile.getmembers" title="tarfile.TarFile.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a>.</p>813<div class="versionchanged">814<p><span class="versionmodified changed">Changed in version 3.5: </span>Added the <em>members</em> parameter.</p>815</div>816</dd></dl>817 818<dl class="py method">819<dt class="sig sig-object py" id="tarfile.TarFile.next">820<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><span class="sig-name descname"><span class="pre">next</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.next" title="Link to this definition">¶</a></dt>821<dd><p>Return the next member of the archive as a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object, when822<a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> is opened for reading. Return <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> if there is no more823available.</p>824</dd></dl>825 826<dl class="py method">827<dt class="sig sig-object py" id="tarfile.TarFile.extractall">828<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><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="o"><span class="pre">=</span></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="o"><span class="pre">=</span></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="o"><span class="pre">=</span></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="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.extractall" title="Link to this definition">¶</a></dt>829<dd><p>Extract all members from the archive to the current working directory or830directory <em>path</em>. If optional <em>members</em> is given, it must be a subset of the831list returned by <a class="reference internal" href="#tarfile.TarFile.getmembers" title="tarfile.TarFile.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a>. Directory information like owner,832modification time and permissions are set after all members have been extracted.833This is done to work around two problems: A directory’s modification time is834reset each time a file is created in it. And, if a directory’s permissions do835not allow writing, extracting files to it will fail.</p>836<p>If <em>numeric_owner</em> is <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, the uid and gid numbers from the tarfile837are used to set the owner/group for the extracted files. Otherwise, the named838values from the tarfile are used.</p>839<p>The <em>filter</em> argument specifies how <code class="docutils literal notranslate"><span class="pre">members</span></code> are modified or rejected840before extraction.841See <a class="reference internal" href="#tarfile-extraction-filter"><span class="std std-ref">Extraction filters</span></a> for details.842It is recommended to set this explicitly only if specific <em>tar</em> features843are required, or as <code class="docutils literal notranslate"><span class="pre">filter='data'</span></code> to support Python versions with a less844secure default (3.13 and lower).</p>845<div class="admonition warning">846<p class="admonition-title">Warning</p>847<p>Never extract archives from untrusted sources without prior inspection.</p>848<p>Since Python 3.14, the default (<a class="reference internal" href="#tarfile.data_filter" title="tarfile.data_filter"><code class="xref py py-func docutils literal notranslate"><span class="pre">data</span></code></a>) will prevent849the most dangerous security issues.850However, it will not prevent <em>all</em> unintended or insecure behavior.851Read the <a class="reference internal" href="#tarfile-extraction-filter"><span class="std std-ref">Extraction filters</span></a> section for details.</p>852</div>853<div class="versionchanged">854<p><span class="versionmodified changed">Changed in version 3.5: </span>Added the <em>numeric_owner</em> parameter.</p>855</div>856<div class="versionchanged">857<p><span class="versionmodified changed">Changed in version 3.6: </span>The <em>path</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>858</div>859<div class="versionchanged">860<p><span class="versionmodified changed">Changed in version 3.12: </span>Added the <em>filter</em> parameter.</p>861</div>862<div class="versionchanged">863<p><span class="versionmodified changed">Changed in version 3.14: </span>The <em>filter</em> parameter now defaults to <code class="docutils literal notranslate"><span class="pre">'data'</span></code>.</p>864</div>865</dd></dl>866 867<dl class="py method">868<dt class="sig sig-object py" id="tarfile.TarFile.extract">869<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><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></em>, <em class="sig-param"><span class="n"><span class="pre">path</span></span><span class="o"><span class="pre">=</span></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="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</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="o"><span class="pre">=</span></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="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.extract" title="Link to this definition">¶</a></dt>870<dd><p>Extract a member from the archive to the current working directory, using its871full name. Its file information is extracted as accurately as possible. <em>member</em>872may be a filename or a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object. You can specify a different873directory using <em>path</em>. <em>path</em> may be a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.874File attributes (owner, mtime, mode) are set unless <em>set_attrs</em> is false.</p>875<p>The <em>numeric_owner</em> and <em>filter</em> arguments are the same as876for <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a>.</p>877<div class="admonition note">878<p class="admonition-title">Note</p>879<p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code> method does not take care of several extraction issues.880In most cases you should consider using the <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> method.</p>881</div>882<div class="admonition warning">883<p class="admonition-title">Warning</p>884<p>Never extract archives from untrusted sources without prior inspection.885See the warning for <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> for details.</p>886</div>887<div class="versionchanged">888<p><span class="versionmodified changed">Changed in version 3.2: </span>Added the <em>set_attrs</em> parameter.</p>889</div>890<div class="versionchanged">891<p><span class="versionmodified changed">Changed in version 3.5: </span>Added the <em>numeric_owner</em> parameter.</p>892</div>893<div class="versionchanged">894<p><span class="versionmodified changed">Changed in version 3.6: </span>The <em>path</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>895</div>896<div class="versionchanged">897<p><span class="versionmodified changed">Changed in version 3.12: </span>Added the <em>filter</em> parameter.</p>898</div>899</dd></dl>900 901<dl class="py method">902<dt class="sig sig-object py" id="tarfile.TarFile.extractfile">903<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><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></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.extractfile" title="Link to this definition">¶</a></dt>904<dd><p>Extract a member from the archive as a file object. <em>member</em> may be905a filename or a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object. If <em>member</em> is a regular file or906a link, an <a class="reference internal" href="io.html#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.BufferedReader</span></code></a> object is returned. For all other907existing members, <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> is returned. If <em>member</em> does not appear908in the archive, <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> is raised.</p>909<div class="versionchanged">910<p><span class="versionmodified changed">Changed in version 3.3: </span>Return an <a class="reference internal" href="io.html#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.BufferedReader</span></code></a> object.</p>911</div>912<div class="versionchanged">913<p><span class="versionmodified changed">Changed in version 3.13: </span>The returned <a class="reference internal" href="io.html#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.BufferedReader</span></code></a> object has the <code class="xref py py-attr docutils literal notranslate"><span class="pre">mode</span></code>914attribute which is always equal to <code class="docutils literal notranslate"><span class="pre">'rb'</span></code>.</p>915</div>916</dd></dl>917 918<dl class="py attribute">919<dt class="sig sig-object py" id="tarfile.TarFile.errorlevel">920<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><span class="sig-name descname"><span class="pre">errorlevel</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></em><a class="headerlink" href="#tarfile.TarFile.errorlevel" title="Link to this definition">¶</a></dt>921<dd><p>If <em>errorlevel</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code>, errors are ignored when using <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.extract()</span></code></a>922and <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TarFile.extractall()</span></code></a>.923Nevertheless, they appear as error messages in the debug output when924<em>debug</em> is greater than 0.925If <code class="docutils literal notranslate"><span class="pre">1</span></code> (the default), all <em>fatal</em> errors are raised as <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> or926<a class="reference internal" href="#tarfile.FilterError" title="tarfile.FilterError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FilterError</span></code></a> exceptions. If <code class="docutils literal notranslate"><span class="pre">2</span></code>, all <em>non-fatal</em> errors are raised927as <a class="reference internal" href="#tarfile.TarError" title="tarfile.TarError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TarError</span></code></a> exceptions as well.</p>928<p>Some exceptions, e.g. ones caused by wrong argument types or data929corruption, are always raised.</p>930<p>Custom <a class="reference internal" href="#tarfile-extraction-filter"><span class="std std-ref">extraction filters</span></a>931should raise <a class="reference internal" href="#tarfile.FilterError" title="tarfile.FilterError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FilterError</span></code></a> for <em>fatal</em> errors932and <a class="reference internal" href="#tarfile.ExtractError" title="tarfile.ExtractError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ExtractError</span></code></a> for <em>non-fatal</em> ones.</p>933<p>Note that when an exception is raised, the archive may be partially934extracted. It is the user’s responsibility to clean up.</p>935</dd></dl>936 937<dl class="py attribute">938<dt class="sig sig-object py" id="tarfile.TarFile.extraction_filter">939<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><span class="sig-name descname"><span class="pre">extraction_filter</span></span><a class="headerlink" href="#tarfile.TarFile.extraction_filter" title="Link to this definition">¶</a></dt>940<dd><div class="versionadded">941<p><span class="versionmodified added">Added in version 3.12.</span></p>942</div>943<p>The <a class="reference internal" href="#tarfile-extraction-filter"><span class="std std-ref">extraction filter</span></a> used944as a default for the <em>filter</em> argument of <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a>945and <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a>.</p>946<p>The attribute may be <code class="docutils literal notranslate"><span class="pre">None</span></code> or a callable.947String names are not allowed for this attribute, unlike the <em>filter</em>948argument to <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a>.</p>949<p>If <code class="docutils literal notranslate"><span class="pre">extraction_filter</span></code> is <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default), extraction methods950will use the <a class="reference internal" href="#tarfile.data_filter" title="tarfile.data_filter"><code class="xref py py-func docutils literal notranslate"><span class="pre">data</span></code></a> filter by default.</p>951<p>The attribute may be set on instances or overridden in subclasses.952It also is possible to set it on the <code class="docutils literal notranslate"><span class="pre">TarFile</span></code> class itself to set a953global default, although, since it affects all uses of <em>tarfile</em>,954it is best practice to only do so in top-level applications or955<a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span> <span class="pre">configuration</span></code></a>.956To set a global default this way, a filter function needs to be wrapped in957<a class="reference internal" href="functions.html#staticmethod" title="staticmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">staticmethod()</span></code></a> to prevent injection of a <code class="docutils literal notranslate"><span class="pre">self</span></code> argument.</p>958<div class="versionchanged">959<p><span class="versionmodified changed">Changed in version 3.14: </span>The default filter is set to <a class="reference internal" href="#tarfile.data_filter" title="tarfile.data_filter"><code class="xref py py-func docutils literal notranslate"><span class="pre">data</span></code></a>,960which disallows some dangerous features such as links to absolute paths961or paths outside of the destination.962Previously, the default was equivalent to963<a class="reference internal" href="#tarfile.fully_trusted_filter" title="tarfile.fully_trusted_filter"><code class="xref py py-func docutils literal notranslate"><span class="pre">fully_trusted</span></code></a>.</p>964</div>965</dd></dl>966 967<dl class="py method">968<dt class="sig sig-object py" id="tarfile.TarFile.add">969<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><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></em>, <em class="sig-param"><span class="n"><span class="pre">arcname</span></span><span class="o"><span class="pre">=</span></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="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</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">filter</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.add" title="Link to this definition">¶</a></dt>970<dd><p>Add the file <em>name</em> to the archive. <em>name</em> may be any type of file971(directory, fifo, symbolic link, etc.). If given, <em>arcname</em> specifies an972alternative name for the file in the archive. Directories are added973recursively by default. This can be avoided by setting <em>recursive</em> to974<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>. Recursion adds entries in sorted order.975If <em>filter</em> is given, it976should be a function that takes a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object argument and977returns the changed <code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code> object. If it instead returns978<a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> the <code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code> object will be excluded from the979archive. See <a class="reference internal" href="#tar-examples"><span class="std std-ref">Examples</span></a> for an example.</p>980<div class="versionchanged">981<p><span class="versionmodified changed">Changed in version 3.2: </span>Added the <em>filter</em> parameter.</p>982</div>983<div class="versionchanged">984<p><span class="versionmodified changed">Changed in version 3.7: </span>Recursion adds entries in sorted order.</p>985</div>986</dd></dl>987 988<dl class="py method">989<dt class="sig sig-object py" id="tarfile.TarFile.addfile">990<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><span class="sig-name descname"><span class="pre">addfile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tarinfo</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fileobj</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.addfile" title="Link to this definition">¶</a></dt>991<dd><p>Add the <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object <em>tarinfo</em> to the archive. If <em>tarinfo</em> represents992a non zero-size regular file, the <em>fileobj</em> argument should be a <a class="reference internal" href="../glossary.html#term-binary-file"><span class="xref std std-term">binary file</span></a>,993and <code class="docutils literal notranslate"><span class="pre">tarinfo.size</span></code> bytes are read from it and added to the archive.  You can994create <code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code> objects directly, or by using <a class="reference internal" href="#tarfile.TarFile.gettarinfo" title="tarfile.TarFile.gettarinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">gettarinfo()</span></code></a>.</p>995<div class="versionchanged">996<p><span class="versionmodified changed">Changed in version 3.13: </span><em>fileobj</em> must be given for non-zero-sized regular files.</p>997</div>998</dd></dl>999 1000<dl class="py method">1001<dt class="sig sig-object py" id="tarfile.TarFile.gettarinfo">1002<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><span class="sig-name descname"><span class="pre">gettarinfo</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">arcname</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fileobj</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.gettarinfo" title="Link to this definition">¶</a></dt>1003<dd><p>Create a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object from the result of <a class="reference internal" href="os.html#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a> or1004equivalent on an existing file.  The file is either named by <em>name</em>, or1005specified as a <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> <em>fileobj</em> with a file descriptor.1006<em>name</em> may be a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.  If1007given, <em>arcname</em> specifies an alternative name for the file in the1008archive, otherwise, the name is taken from <em>fileobj</em>’s1009<a class="reference internal" href="io.html#io.FileIO.name" title="io.FileIO.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a> attribute, or the <em>name</em> argument.  The name1010should be a text string.</p>1011<p>You can modify1012some of the <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a>’s attributes before you add it using <a class="reference internal" href="#tarfile.TarFile.addfile" title="tarfile.TarFile.addfile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">addfile()</span></code></a>.1013If the file object is not an ordinary file object positioned at the1014beginning of the file, attributes such as <a class="reference internal" href="#tarfile.TarInfo.size" title="tarfile.TarInfo.size"><code class="xref py py-attr docutils literal notranslate"><span class="pre">size</span></code></a> may need1015modifying.  This is the case for objects such as <a class="reference internal" href="gzip.html#gzip.GzipFile" title="gzip.GzipFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">GzipFile</span></code></a>.1016The <a class="reference internal" href="#tarfile.TarInfo.name" title="tarfile.TarInfo.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a> may also be modified, in which case <em>arcname</em>1017could be a dummy string.</p>1018<div class="versionchanged">1019<p><span class="versionmodified changed">Changed in version 3.6: </span>The <em>name</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>1020</div>1021</dd></dl>1022 1023<dl class="py method">1024<dt class="sig sig-object py" id="tarfile.TarFile.close">1025<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarFile.close" title="Link to this definition">¶</a></dt>1026<dd><p>Close the <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a>. In write mode, two finishing zero blocks are1027appended to the archive.</p>1028</dd></dl>1029 1030<dl class="py attribute">1031<dt class="sig sig-object py" id="tarfile.TarFile.pax_headers">1032<span class="sig-prename descclassname"><span class="pre">TarFile.</span></span><span class="sig-name descname"><span class="pre">pax_headers</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="stdtypes.html#dict" title="dict"><span class="pre">dict</span></a></em><a class="headerlink" href="#tarfile.TarFile.pax_headers" title="Link to this definition">¶</a></dt>1033<dd><p>A dictionary containing key-value pairs of pax global headers.</p>1034</dd></dl>1035 1036</section>1037<section id="tarinfo-objects">1038<span id="id2"></span><h2>TarInfo Objects<a class="headerlink" href="#tarinfo-objects" title="Link to this heading">¶</a></h2>1039<p>A <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object represents one member in a <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a>. Aside1040from storing all required attributes of a file (like file type, size, time,1041permissions, owner etc.), it provides some useful methods to determine its type.1042It does <em>not</em> contain the file’s data itself.</p>1043<p><a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> objects are returned by <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a>’s methods1044<a class="reference internal" href="#tarfile.TarFile.getmember" title="tarfile.TarFile.getmember"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmember()</span></code></a>, <a class="reference internal" href="#tarfile.TarFile.getmembers" title="tarfile.TarFile.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a> and1045<a class="reference internal" href="#tarfile.TarFile.gettarinfo" title="tarfile.TarFile.gettarinfo"><code class="xref py py-meth docutils literal notranslate"><span class="pre">gettarinfo()</span></code></a>.</p>1046<p>Modifying the objects returned by <a class="reference internal" href="#tarfile.TarFile.getmember" title="tarfile.TarFile.getmember"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmember()</span></code></a> or1047<a class="reference internal" href="#tarfile.TarFile.getmembers" title="tarfile.TarFile.getmembers"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getmembers()</span></code></a> will affect all subsequent1048operations on the archive.1049For cases where this is unwanted, you can use <a class="reference internal" href="copy.html#module-copy" title="copy: Shallow and deep copy operations."><code class="xref py py-mod docutils literal notranslate"><span class="pre">copy.copy()</span></code></a> or1050call the <a class="reference internal" href="#tarfile.TarInfo.replace" title="tarfile.TarInfo.replace"><code class="xref py py-meth docutils literal notranslate"><span class="pre">replace()</span></code></a> method to create a modified copy in one step.</p>1051<p>Several attributes can be set to <code class="docutils literal notranslate"><span class="pre">None</span></code> to indicate that a piece of metadata1052is unused or unknown.1053Different <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> methods handle <code class="docutils literal notranslate"><span class="pre">None</span></code> differently:</p>1054<ul class="simple">1055<li><p>The <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> or <a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a> methods will1056ignore the corresponding metadata, leaving it set to a default.</p></li>1057<li><p><a class="reference internal" href="#tarfile.TarFile.addfile" title="tarfile.TarFile.addfile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">addfile()</span></code></a> will fail.</p></li>1058<li><p><a class="reference internal" href="#tarfile.TarFile.list" title="tarfile.TarFile.list"><code class="xref py py-meth docutils literal notranslate"><span class="pre">list()</span></code></a> will print a placeholder string.</p></li>1059</ul>1060<dl class="py class">1061<dt class="sig sig-object py" id="tarfile.TarInfo">1062<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">tarfile.</span></span><span class="sig-name descname"><span class="pre">TarInfo</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo" title="Link to this definition">¶</a></dt>1063<dd><p>Create a <code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code> object.</p>1064</dd></dl>1065 1066<dl class="py method">1067<dt class="sig sig-object py" id="tarfile.TarInfo.frombuf">1068<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">frombuf</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">buf</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.frombuf" title="Link to this definition">¶</a></dt>1069<dd><p>Create and return a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object from string buffer <em>buf</em>.</p>1070<p>Raises <a class="reference internal" href="#tarfile.HeaderError" title="tarfile.HeaderError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">HeaderError</span></code></a> if the buffer is invalid.</p>1071</dd></dl>1072 1073<dl class="py method">1074<dt class="sig sig-object py" id="tarfile.TarInfo.fromtarfile">1075<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">fromtarfile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tarfile</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.fromtarfile" title="Link to this definition">¶</a></dt>1076<dd><p>Read the next member from the <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> object <em>tarfile</em> and return it as1077a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object.</p>1078</dd></dl>1079 1080<dl class="py method">1081<dt class="sig sig-object py" id="tarfile.TarInfo.tobuf">1082<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">tobuf</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DEFAULT_FORMAT</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">ENCODING</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'surrogateescape'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#tarfile.TarInfo.tobuf" title="Link to this definition">¶</a></dt>1083<dd><p>Create a string buffer from a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object. For information on the1084arguments see the constructor of the <a class="reference internal" href="#tarfile.TarFile" title="tarfile.TarFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarFile</span></code></a> class.</p>1085<div class="versionchanged">1086<p><span class="versionmodified changed">Changed in version 3.2: </span>Use <code class="docutils literal notranslate"><span class="pre">'surrogateescape'</span></code> as the default for the <em>errors</em> argument.</p>1087</div>1088</dd></dl>1089 1090<p>A <code class="docutils literal notranslate"><span class="pre">TarInfo</span></code> object has the following public data attributes:</p>1091<dl class="py attribute">1092<dt class="sig sig-object py" id="tarfile.TarInfo.name">1093<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">name</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="stdtypes.html#str" title="str"><span class="pre">str</span></a></em><a class="headerlink" href="#tarfile.TarInfo.name" title="Link to this definition">¶</a></dt>1094<dd><p>Name of the archive member.</p>1095</dd></dl>1096 1097<dl class="py attribute">1098<dt class="sig sig-object py" id="tarfile.TarInfo.size">1099<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">size</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></em><a class="headerlink" href="#tarfile.TarInfo.size" title="Link to this definition">¶</a></dt>1100<dd><p>Size in bytes.</p>1101</dd></dl>1102 1103<dl class="py attribute">1104<dt class="sig sig-object py" id="tarfile.TarInfo.mtime">1105<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">mtime</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="functions.html#float" title="float"><span class="pre">float</span></a></em><a class="headerlink" href="#tarfile.TarInfo.mtime" title="Link to this definition">¶</a></dt>1106<dd><p>Time of last modification in seconds since the <a class="reference internal" href="time.html#epoch"><span class="std std-ref">epoch</span></a>,1107as in <a class="reference internal" href="os.html#os.stat_result.st_mtime" title="os.stat_result.st_mtime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">os.stat_result.st_mtime</span></code></a>.</p>1108<div class="versionchanged">1109<p><span class="versionmodified changed">Changed in version 3.12: </span>Can be set to <code class="docutils literal notranslate"><span class="pre">None</span></code> for <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> and1110<a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a>, causing extraction to skip applying this1111attribute.</p>1112</div>1113</dd></dl>1114 1115<dl class="py attribute">1116<dt class="sig sig-object py" id="tarfile.TarInfo.mode">1117<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">mode</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></em><a class="headerlink" href="#tarfile.TarInfo.mode" title="Link to this definition">¶</a></dt>1118<dd><p>Permission bits, as for <a class="reference internal" href="os.html#os.chmod" title="os.chmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.chmod()</span></code></a>.</p>1119<div class="versionchanged">1120<p><span class="versionmodified changed">Changed in version 3.12: </span>Can be set to <code class="docutils literal notranslate"><span class="pre">None</span></code> for <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> and1121<a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a>, causing extraction to skip applying this1122attribute.</p>1123</div>1124</dd></dl>1125 1126<dl class="py attribute">1127<dt class="sig sig-object py" id="tarfile.TarInfo.type">1128<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">type</span></span><a class="headerlink" href="#tarfile.TarInfo.type" title="Link to this definition">¶</a></dt>1129<dd><p>File type.  <em>type</em> is usually one of these constants: <a class="reference internal" href="#tarfile.REGTYPE" title="tarfile.REGTYPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">REGTYPE</span></code></a>,1130<a class="reference internal" href="#tarfile.AREGTYPE" title="tarfile.AREGTYPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">AREGTYPE</span></code></a>, <a class="reference internal" href="#tarfile.LNKTYPE" title="tarfile.LNKTYPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">LNKTYPE</span></code></a>, <a class="reference internal" href="#tarfile.SYMTYPE" title="tarfile.SYMTYPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">SYMTYPE</span></code></a>, <a class="reference internal" href="#tarfile.DIRTYPE" title="tarfile.DIRTYPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">DIRTYPE</span></code></a>,1131<a class="reference internal" href="#tarfile.FIFOTYPE" title="tarfile.FIFOTYPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">FIFOTYPE</span></code></a>, <a class="reference internal" href="#tarfile.CONTTYPE" title="tarfile.CONTTYPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">CONTTYPE</span></code></a>, <a class="reference internal" href="#tarfile.CHRTYPE" title="tarfile.CHRTYPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">CHRTYPE</span></code></a>, <a class="reference internal" href="#tarfile.BLKTYPE" title="tarfile.BLKTYPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">BLKTYPE</span></code></a>,1132<a class="reference internal" href="#tarfile.GNUTYPE_SPARSE" title="tarfile.GNUTYPE_SPARSE"><code class="xref py py-const docutils literal notranslate"><span class="pre">GNUTYPE_SPARSE</span></code></a>.  To determine the type of a <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> object1133more conveniently, use the <code class="docutils literal notranslate"><span class="pre">is*()</span></code> methods below.</p>1134</dd></dl>1135 1136<dl class="py attribute">1137<dt class="sig sig-object py" id="tarfile.TarInfo.linkname">1138<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">linkname</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="stdtypes.html#str" title="str"><span class="pre">str</span></a></em><a class="headerlink" href="#tarfile.TarInfo.linkname" title="Link to this definition">¶</a></dt>1139<dd><p>Name of the target file name, which is only present in <a class="reference internal" href="#tarfile.TarInfo" title="tarfile.TarInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">TarInfo</span></code></a> objects1140of type <a class="reference internal" href="#tarfile.LNKTYPE" title="tarfile.LNKTYPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">LNKTYPE</span></code></a> and <a class="reference internal" href="#tarfile.SYMTYPE" title="tarfile.SYMTYPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">SYMTYPE</span></code></a>.</p>1141<p>For symbolic links (<code class="docutils literal notranslate"><span class="pre">SYMTYPE</span></code>), the <em>linkname</em> is relative to the directory1142that contains the link.1143For hard links (<code class="docutils literal notranslate"><span class="pre">LNKTYPE</span></code>), the <em>linkname</em> is relative to the root of1144the archive.</p>1145</dd></dl>1146 1147<dl class="py attribute">1148<dt class="sig sig-object py" id="tarfile.TarInfo.uid">1149<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">uid</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></em><a class="headerlink" href="#tarfile.TarInfo.uid" title="Link to this definition">¶</a></dt>1150<dd><p>User ID of the user who originally stored this member.</p>1151<div class="versionchanged">1152<p><span class="versionmodified changed">Changed in version 3.12: </span>Can be set to <code class="docutils literal notranslate"><span class="pre">None</span></code> for <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> and1153<a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a>, causing extraction to skip applying this1154attribute.</p>1155</div>1156</dd></dl>1157 1158<dl class="py attribute">1159<dt class="sig sig-object py" id="tarfile.TarInfo.gid">1160<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">gid</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></em><a class="headerlink" href="#tarfile.TarInfo.gid" title="Link to this definition">¶</a></dt>1161<dd><p>Group ID of the user who originally stored this member.</p>1162<div class="versionchanged">1163<p><span class="versionmodified changed">Changed in version 3.12: </span>Can be set to <code class="docutils literal notranslate"><span class="pre">None</span></code> for <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> and1164<a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a>, causing extraction to skip applying this1165attribute.</p>1166</div>1167</dd></dl>1168 1169<dl class="py attribute">1170<dt class="sig sig-object py" id="tarfile.TarInfo.uname">1171<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">uname</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="stdtypes.html#str" title="str"><span class="pre">str</span></a></em><a class="headerlink" href="#tarfile.TarInfo.uname" title="Link to this definition">¶</a></dt>1172<dd><p>User name.</p>1173<div class="versionchanged">1174<p><span class="versionmodified changed">Changed in version 3.12: </span>Can be set to <code class="docutils literal notranslate"><span class="pre">None</span></code> for <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> and1175<a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a>, causing extraction to skip applying this1176attribute.</p>1177</div>1178</dd></dl>1179 1180<dl class="py attribute">1181<dt class="sig sig-object py" id="tarfile.TarInfo.gname">1182<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">gname</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="stdtypes.html#str" title="str"><span class="pre">str</span></a></em><a class="headerlink" href="#tarfile.TarInfo.gname" title="Link to this definition">¶</a></dt>1183<dd><p>Group name.</p>1184<div class="versionchanged">1185<p><span class="versionmodified changed">Changed in version 3.12: </span>Can be set to <code class="docutils literal notranslate"><span class="pre">None</span></code> for <a class="reference internal" href="#tarfile.TarFile.extract" title="tarfile.TarFile.extract"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extract()</span></code></a> and1186<a class="reference internal" href="#tarfile.TarFile.extractall" title="tarfile.TarFile.extractall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">extractall()</span></code></a>, causing extraction to skip applying this1187attribute.</p>1188</div>1189</dd></dl>1190 1191<dl class="py attribute">1192<dt class="sig sig-object py" id="tarfile.TarInfo.chksum">1193<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">chksum</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></em><a class="headerlink" href="#tarfile.TarInfo.chksum" title="Link to this definition">¶</a></dt>1194<dd><p>Header checksum.</p>1195</dd></dl>1196 1197<dl class="py attribute">1198<dt class="sig sig-object py" id="tarfile.TarInfo.devmajor">1199<span class="sig-prename descclassname"><span class="pre">TarInfo.</span></span><span class="sig-name descname"><span class="pre">devmajor</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="functions.html#int" title="int"><span class="pre">int</span></a></em><a class="headerlink" href="#tarfile.TarInfo.devmajor" title="Link to this definition">¶</a></dt>1200<dd><p>Device major number.</p>

Showing the first 1,200 of 1963 lines. Download the file for the rest.