# `tarfile` --- tar アーカイブファイルの読み書き

ソースコード: Lib/tarfile.py

`tarfile` モジュールは、gzip、bz2、および lzma 圧縮されたものを含む、tar アーカイブを読み書きできます。`.zip` ファイルの読み書きには `zipfile` モジュールか、あるいは shutil の高水準関数を使用してください。

いくつかの事実と形態:

- モジュールが利用可能な場合、`gzip`、`bz2` ならびに `lzma` で圧縮されたアーカイブを読み書きします。

- POSIX.1-1988 (ustar) フォーマットの読み書きをサポートしています。

- longname および longlink 拡張を含む GNU tar フォーマットの読み書きをサポートしています。スパースファイルの復元を含む sparse 拡張は読み込みのみサポートしています。

- POSIX.1-2001 (pax) フォーマットの読み書きをサポートしています。

- ディレクトリ、一般ファイル、ハードリンク、シンボリックリンク、fifo、キャラクターデバイスおよびブロックデバイスを処理します。また、タイムスタンプ、アクセス許可や所有者のようなファイル情報の取得および保存が可能です。

バージョン 3.3 で変更: `lzma` 圧縮をサポートしました。

`tarfile.``open`(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

  パス名 name の `TarFile` オブジェクトを返します。`TarFile` オブジェクトと、利用できるキーワード引数に関する詳細な情報については、TarFile オブジェクト 節を参照してください。

  mode は `'filemode[:compression]'` の形式をとる文字列でなければなりません。デフォルトの値は `'r'` です。以下に mode のとりうる組み合わせすべてを示します:

  mode | action
  --- | ---
  `'r' または 'r:*'` | 圧縮方法に関して透過的に、読み込み用にオープンします (推奨)。
  `'r:'` | 非圧縮で読み込み用に排他的にオープンします。
  `'r:gz'` | gzip 圧縮で読み込み用にオープンします。
  `'r:bz2'` | bzip2 圧縮で読み込み用にオープンします。
  `'r:xz'` | lzma 圧縮で読み込み用にオープンします。
  `'x'` or `'x:'` | 圧縮せずに tarfile を排他的に作成します。tarfile が既存の場合 `FileExistsError` 例外を送出します。
  `'x:gz'` | gzip 圧縮で tarfile を作成します。tarfile が既存の場合 `FileExistsError` 例外を送出します。
  `'x:bz2'` | bzip2 圧縮で tarfile を作成します。tarfile が既存の場合 `FileExistsError` 例外を送出します。
  `'x:xz'` | lzma 圧縮で tarfile を作成します。tarfile が既存の場合 `FileExistsError` 例外を送出します。
  `'a' または 'a:'` | 非圧縮で追記用にオープンします。ファイルが存在しない場合は新たに作成されます。
  `'w' または 'w:'` | 非圧縮で書き込み用にオープンします。
  `'w:gz'` | gzip 圧縮で書き込み用にオープンします。
  `'w:bz2'` | bzip2 圧縮で書き込み用にオープンします。
  `'w:xz'` | lzma 圧縮で書き込み用にオープンします。

  `'a:gz'`、`'a:bz2'`、`'a:xz'` は利用できないことに注意して下さい。もし mode が、ある (圧縮した) ファイルを読み込み用にオープンするのに適していないなら、`ReadError` が送出されます。これを防ぐには mode `'r'` を使って下さい。もし圧縮方式がサポートされていなければ、`CompressionError` が送出されます。

  もし fileobj が指定されていれば、それは name でバイナリモードでオープンされた ファイルオブジェクト の代替として使うことができます。そのファイルオブジェクトの位置が 0 であることを前提に動作します。

  `'w:gz'`、`'r:gz'`、`'w:bz2'`、`'r:bz2'`, `'x:gz'`, `'x:bz2'` モードの場合、`tarfile.open()` はファイルの圧縮レベルを指定するキーワード引数 compresslevel (デフォルトは `9`) を受け付けます。

  特別な目的のために、mode には 2 番目の形式: `'ファイルモード|[圧縮]'` があります。この形式を使うと、`tarfile.open()` が返すのは、データをブロックからなるストリームとして扱う `TarFile` オブジェクトになります。この場合、ファイルに対してランダムなシークが行えなくなります。fileobj を指定する場合、 `read()` および `write()` メソッドを持つ (mode に依存した) 任意のオブジェクトにできます。bufsize にはブロックサイズを指定します。デフォルトは `20 * 512` バイトです。`sys.stdin`、ソケット file object、あるいはテープデバイスと組み合わせる場合にはこの形式を使ってください。ただし、このような `TarFile` オブジェクトにはランダムアクセスを行えないという制限があります。使用例 節を参照してください。現在可能なモードは以下のとおりです。

  モード | 動作
  --- | ---
  `'r|*'` | tar ブロックの stream を圧縮方法に関して透過的に読み込み用にオープンします。
  `'r|'` | 非圧縮 tar ブロックの stream を読み込み用にオープンします。
  `'r|gz'` | gzip 圧縮の stream を読み込み用にオープンします。
  `'r|bz2'` | bzip2 圧縮の stream を読み込み用にオープンします。
  `'r|xz'` | lzma 圧縮の stream を読み込み用にオープンします。
  `'w|'` | 非圧縮の stream を書き込み用にオープンします。
  `'w|gz'` | gzip 圧縮の stream を書き込み用にオープンします。
  `'w|bz2'` | bzip2 圧縮の stream を書き込み用にオープンします。
  `'w|xz'` | lzma 圧縮の stream を書き込み用にオープンします。

  バージョン 3.5 で変更: `'x'` (排他的作成) モードが追加されました。

  バージョン 3.6 で変更: name パラメタが path-like object を受け付けるようになりました。

class `tarfile.``TarFile`

  tar アーカイブを読み書きするためのクラスです。このクラスを直接使わないこと: 代わりに `tarfile.open()` を使ってください。TarFile オブジェクト を参照してください。

`tarfile.``is_tarfile`(name)

  もし name が tar アーカイブファイルであり、`tarfile` モジュールで読み込める場合に `True` を返します。

`tarfile` モジュールは以下の例外を定義しています:

exception `tarfile.``TarError`

  すべての `tarfile` 例外のための基本クラスです。

exception `tarfile.``ReadError`

  tar アーカイブがオープンされた時、`tarfile` モジュールで操作できないか、あるいは何か無効であるとき送出されます。

exception `tarfile.``CompressionError`

  圧縮方法がサポートされていないか、あるいはデータを正しくデコードできない時に送出されます。

exception `tarfile.``StreamError`

  ストリームのような `TarFile` オブジェクトで典型的な制限のために送出されます。

exception `tarfile.``ExtractError`

  `TarFile.extract()` を使った時に 致命的でない エラーに対して送出されます。ただし `TarFile.errorlevel``== 2` の場合に限ります。

exception `tarfile.``HeaderError`

  `TarInfo.frombuf()` メソッドが取得したバッファーが不正だったときに送出されます。

exception `tarfile.``FilterError`

  Base class for members refused by filters.

  `tarinfo`

    Information about the member that the filter refused to extract, as TarInfo.

exception `tarfile.``AbsolutePathError`

  Raised to refuse extracting a member with an absolute path.

exception `tarfile.``OutsideDestinationError`

  Raised to refuse extracting a member outside the destination directory.

exception `tarfile.``SpecialFileError`

  Raised to refuse extracting a special file (e.g. a device or pipe).

exception `tarfile.``AbsoluteLinkError`

  Raised to refuse extracting a symbolic link with an absolute path.

exception `tarfile.``LinkOutsideDestinationError`

  Raised to refuse extracting a symbolic link pointing outside the destination directory.

モジュールレベルで以下の定数が利用できます。

`tarfile.``ENCODING`

  既定の文字エンコーディング。Windows では `'utf-8'` 、それ以外では `sys.getfilesystemencoding()` の返り値です。

以下の各定数は、`tarfile` モジュールが作成できる tar アーカイブフォーマットを定義しています。詳細は、サポートしている tar フォーマット を参照してください。

`tarfile.``USTAR_FORMAT`

  POSIX.1-1988 (ustar) フォーマット。

`tarfile.``GNU_FORMAT`

  GNU tar フォーマット。

`tarfile.``PAX_FORMAT`

  POSIX.1-2001 (pax) フォーマット。

`tarfile.``DEFAULT_FORMAT`

  アーカイブを作成する際のデフォルトのフォーマット。現在は `PAX_FORMAT` です。

  バージョン 3.8 で変更: 新しいアーカイブのデフォルトフォーマットが `GNU_FORMAT` から `PAX_FORMAT` に変更されました。

参考

`zipfile` モジュール

  `zipfile` 標準モジュールのドキュメント。

アーカイブ化操作

  `shutil` が提供するより高水準のアーカイブ機能についてのドキュメント。

GNU tar manual, Basic Tar Format

  GNU tar 拡張機能を含む、tar アーカイブファイルのためのドキュメント。

## TarFile オブジェクト

`TarFile` オブジェクトは、tar アーカイブへのインターフェースを提供します。tar アーカイブは一連のブロックです。アーカイブメンバー (保存されたファイル) は、ヘッダーブロックとそれに続くデータブロックで構成されています。一つの tar アーカイブにファイルを何回も保存することができます。各アーカイブメンバーは、`TarInfo` オブジェクトで確認できます。詳細については TarInfo オブジェクト を参照してください。

`TarFile` オブジェクトは `with` 文のコンテキストマネージャーとして利用できます。with ブロックが終了したときにオブジェクトはクローズされます。例外が発生した時、内部で利用されているファイルオブジェクトのみがクローズされ、書き込み用にオープンされたアーカイブのファイナライズは行われないことに注意してください。使用例 節のユースケースを参照してください。

バージョン 3.2 で追加: コンテキスト管理のプロトコルがサポートされました。

class `tarfile.``TarFile`(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors='surrogateescape', pax_headers=None, debug=0, errorlevel=1)

  以下のすべての引数はオプションで、インスタンス属性としてもアクセスできます。

  name はアーカイブのパス名です。name は path-like object でも構いません。fileobj が渡された場合は省略可能です。その場合、ファイルオブジェクトに `name` 属性があれば、それを利用します。

  mode は、既存のアーカイブから読み込むための `'r'`、既存のアーカイブに追記するための `'a'`、既存のファイルがあれば上書きして新しいファイルを作成する `'w'` 、あるいは存在しない場合にのみ新しいファイルを作成する `'x'` のいずれかです。

  fileobj が与えられていれば、それを使ってデータを読み書きします。もしそれが決定できれば、mode は fileobj のモードで上書きされます。fileobj は位置 0 から利用されます。

  注釈

  `TarFile` をクローズした時、fileobj はクローズされません。

  format はアーカイブの書き込みフォーマットを制御します。モジュールレベルで定義されている、`USTAR_FORMAT`、`GNU_FORMAT`、あるいは `PAX_FORMAT` のいずれかである必要があります。 読み出しのときは、1 つのアーカイブに異なるフォーマットが混在していたとしても、フォーマットは自動的に検知されます。

  tarinfo 引数を利用して、デフォルトの `TarInfo` クラスを別のクラスで置き換えることができます。

  dereference が `False` だった場合、シンボリックリンクやハードリンクがアーカイブに追加されます。`True` だった場合、リンクのターゲットとなるファイルの内容がアーカイブに追加されます。シンボリックリンクをサポートしていないシステムでは効果がありません。

  ignore_zeros が `False` だった場合、空ブロックをアーカイブの終端として扱います。`True` だった場合、空の (無効な) ブロックをスキップして、可能な限り多くのメンバーを取得しようとします。このオプションは、連結されたり、壊れたアーカイブファイルを扱うときにのみ、意味があります。

  debug は `0` (デバッグメッセージ無し) から `3` (全デバッグメッセージ) まで設定できます。このメッセージは `sys.stderr` に書き込まれます。

  errorlevel controls how extraction errors are handled, see `the corresponding attribute`.

  引数 encoding および errors にはアーカイブの読み書きやエラー文字列の変換に使用する文字エンコーディングを指定します。ほとんどのユーザーはデフォルト設定のままで動作します。詳細に関しては Unicode に関する問題 節を参照してください。

  引数 pax_headers は、オプションの文字列辞書で、format が `PAX_FORMAT` だった場合に pax グローバルヘッダーに追加されます。

  バージョン 3.2 で変更: 引数 errors のデフォルトが `'surrogateescape'` になりました。

  バージョン 3.5 で変更: `'x'` (排他的作成) モードが追加されました。

  バージョン 3.6 で変更: name パラメタが path-like object を受け付けるようになりました。

classmethod `TarFile.``open`(...)

  代替コンストラクターです。モジュールレベルでの `tarfile.open()` 関数は、実際はこのクラスメソッドへのショートカットです。

`TarFile.``getmember`(name)

  メンバー name に対する `TarInfo` オブジェクトを返します。name がアーカイブに見つからなければ、`KeyError` が送出されます。

  注釈

  アーカイブ内にメンバーが複数ある場合は、最後に出現するものが最新のバージョンとみなされます。

`TarFile.``getmembers`()

  `TarInfo` アーカイブのメンバーをオブジェクトのリストとして返します。このリストはアーカイブ内のメンバーと同じ順番です。

`TarFile.``getnames`()

  メンバーをその名前のリストを返します。これは `getmembers()` で返されるリストと同じ順番です。

`TarFile.``list`(verbose=True, *, members=None)

  内容の一覧を `sys.stdout` に出力します。verbose が `False` の場合、メンバー名のみ表示します。`True` の場合、 ls -l に似た出力を生成します。オプションの members を与える場合、 `getmembers()` が返すリストのサブセットである必要があります。

  バージョン 3.5 で変更: members 引数が追加されました。.

`TarFile.``next`()

  `TarFile` が読み込み用にオープンされている時、アーカイブの次のメンバーを `TarInfo` オブジェクトとして返します。もしそれ以上利用可能なものがなければ、`None` を返します。

`TarFile.``extractall`(path=".", members=None, *, numeric_owner=False, filter=None)

  すべてのメンバーをアーカイブから現在の作業ディレクトリまたは path に抽出します。オプションの members が与えられるときには、`getmembers()` で返されるリストの一部でなければなりません。所有者、変更時刻、アクセス権限のようなディレクトリ情報はすべてのメンバーが抽出された後にセットされます。これは二つの問題を回避するためです。一つはディレクトリの変更時刻はその中にファイルが作成されるたびにリセットされるということ、もう一つはディレクトリに書き込み許可がなければその中のファイル抽出は失敗してしまうということです。

  numeric_owner が `True` の場合、tarfile の uid と gid 数値が抽出されたファイルのオーナー/グループを設定するために使用されます。False の場合、tarfile の名前付きの値が使用されます。

  The filter argument, which was added in Python 3.8.17, specifies how `members` are modified or rejected before extraction. See Extraction filters for details. It is recommended to set this explicitly depending on which tar features you need to support.

  警告

  内容を信頼できない tar アーカイブを、事前の内部チェック前に展開してはいけません。ファイルが path の外側に作られる可能性があります。例えば、`"/"` で始まる絶対パスのファイル名や、2 重ドット `".."` で始まるパスのファイル名です。

  Set `filter='data'` to prevent the most dangerous security issues, and read the Extraction filters section for details.

  バージョン 3.5 で変更: numeric_owner 引数が追加されました。

  バージョン 3.6 で変更: path パラメタが path-like object を受け付けるようになりました。

  バージョン 3.8.17 で変更: filter パラメータが追加されました。

`TarFile.``extract`(member, path="", set_attrs=True, *, numeric_owner=False, filter=None)

  アーカイブからメンバーの完全な名前を使って、現在のディレクトリに展開します。ファイル情報はできる限り正確に展開されます。 member はファイル名もしくは `TarInfo` オブジェクトです。 path を使って別のディレクトリを指定することもできます。 path はpath-like object でも構いません。set_attrs が false でない限り、ファイルの属性 (所有者、最終更新時刻、モード) は設定されます。

  The numeric_owner and filter arguments are the same as for `extractall()`.

  注釈

  `extract()` メソッドはいくつかの展開に関する問題を扱いません。ほとんどの場合、`extractall()` メソッドの利用を考慮するべきです。

  警告

  `extractall()` の警告を参してください。

  Set `filter='data'` to prevent the most dangerous security issues, and read the Extraction filters section for details.

  バージョン 3.2 で変更: パラメーターに set_attrs を追加しました。

  バージョン 3.5 で変更: numeric_owner 引数が追加されました。

  バージョン 3.6 で変更: path パラメタが path-like object を受け付けるようになりました。

  バージョン 3.8.17 で変更: filter パラメータが追加されました。

`TarFile.``extractfile`(member)

  アーカイブからメンバーをファイルオブジェクトとして抽出します。member はファイル名でも `TarInfo` オブジェクトでも構いません。member が一般ファイルまたはリンクの場合、`io.BufferedReader` オブジェクトが返されます。それ以外の場合、`None` が返されます。

  バージョン 3.3 で変更: 戻り値が `io.BufferedReader` オブジェクトになりました。

`TarFile.``errorlevel`: int

  If errorlevel is `0`, errors are ignored when using `TarFile.extract()` and `TarFile.extractall()`. Nevertheless, they appear as error messages in the debug output when debug is greater than 0. If `1` (the default), all fatal errors are raised as `OSError` or `FilterError` exceptions. If `2`, all non-fatal errors are raised as `TarError` exceptions as well.

  Some exceptions, e.g. ones caused by wrong argument types or data corruption, are always raised.

  Custom extraction filters should raise `FilterError` for fatal errors and `ExtractError` for non-fatal ones.

  Note that when an exception is raised, the archive may be partially extracted. It is the user’s responsibility to clean up.

`TarFile.``extraction_filter`

  バージョン 3.8.17 で追加.

  The extraction filter used as a default for the filter argument of `extract()` and `extractall()`.

  The attribute may be `None` or a callable. String names are not allowed for this attribute, unlike the filter argument to `extract()`.

  If `extraction_filter` is `None` (the default), calling an extraction method without a filter argument will use the `fully_trusted` filter for compatibility with previous Python versions.

  In Python 3.12+, leaving `extraction_filter=None` will emit a `DeprecationWarning`.

  In Python 3.14+, leaving `extraction_filter=None` will cause extraction methods to use the `data` filter by default.

  The attribute may be set on instances or overridden in subclasses. It also is possible to set it on the `TarFile` class itself to set a global default, although, since it affects all uses of tarfile, it is best practice to only do so in top-level applications or `site configuration`. To set a global default this way, a filter function needs to be wrapped in `staticmethod()` to prevent injection of a `self` argument.

`TarFile.``add`(name, arcname=None, recursive=True, *, filter=None)

  ファイル name をアーカイブに追加します。 name は、任意のファイルタイプ (ディレクトリ、fifo、シンボリックリンク等)です。 arcname が与えられている場合は、それはアーカイブ内のファイルの代替名を指定します。 デフォルトではディレクトリは再帰的に追加されます。 これは、 recursive を `False` に設定すると避けられます。 再帰処理はソートされた順序でエントリーを追加します。 filter が与えられた場合、それは `TarInfo` オブジェクトを引数として受け取り、操作した `TarInfo` オブジェクトを返す関数でなければなりません。 代わりに `None` を返した場合、 `TarInfo` オブジェクトはアーカイブから除外されます。 使用例 にある例を参照してください。

  バージョン 3.2 で変更: filter パラメータが追加されました。

  バージョン 3.7 で変更: 再帰処理はソートされた順序でエントリーを追加するようになりました。

`TarFile.``addfile`(tarinfo, fileobj=None)

  `TarInfo` オブジェクト tarinfo をアーカイブに追加します。fileobj を与える場合、binary file にしなければならず、 `tarinfo.size` バイトがそれから読まれ、アーカイブに追加されます。`TarInfo` オブジェクトを直接作成するか、`gettarinfo()` を使って作成することができます。

`TarFile.``gettarinfo`(name=None, arcname=None, fileobj=None)

  `os.stat()` の結果か、既存のファイルに相当するものから、`TarInfo` オブジェクトを作成します。このファイルは、name で名付けられるか、ファイル記述子を持つ file object fileobj として指定されます。name は:term:path-like object でも構いません。 arcname が与えられた場合、アーカイブ内のファイルに対して代替名を指定します。与えられない場合、名前は fileobj の `name` 属性 name 属性から取られます。名前はテキスト文字列にしてください。

  `TarInfo` の属性の一部は、`addfile()` を使用して追加する前に修正できます。ファイルオブジェクトが、ファイルの先頭にある通常のファイルオブジェクトでない場合、 `size` などの属性は修正が必要かもしれません。これは、 `GzipFile` などの属性に当てはまります。`name` も修正できるかもしれず、この場合、arcname はダミーの文字列にすることができます。

  バージョン 3.6 で変更: name パラメタが path-like object を受け付けるようになりました。

`TarFile.``close`()

  `TarFile` をクローズします。書き込みモードでは、完了ゼロブロックが 2 個アーカイブに追加されます。

`TarFile.``pax_headers`

  pax グローバルヘッダーに含まれる key-value ペアの辞書です。

## TarInfo オブジェクト

`TarInfo` オブジェクトは `TarFile` の一つのメンバーを表します。ファイルに必要なすべての属性 (ファイルタイプ、ファイルサイズ、時刻、アクセス権限、所有者等のような) を保存する他に、そのタイプを決定するのに役に立ついくつかのメソッドを提供します。これにはファイルのデータそのものは 含まれません 。

`TarInfo` objects are returned by `TarFile`'s methods `getmember()`, `getmembers()` and `gettarinfo()`.

Modifying the objects returned by `getmember()` or `getmembers()` will affect all subsequent operations on the archive. For cases where this is unwanted, you can use `copy.copy()` or call the `replace()` method to create a modified copy in one step.

Several attributes can be set to `None` to indicate that a piece of metadata is unused or unknown. Different `TarInfo` methods handle `None` differently:

- The `extract()` or `extractall()` methods will ignore the corresponding metadata, leaving it set to a default.

- `addfile()` will fail.

- `list()` will print a placeholder string.

バージョン 3.8.17 で変更: Added `replace()` and handling of `None`.

class `tarfile.``TarInfo`(name="")

  `TarInfo` オブジェクトを作成します。

classmethod `TarInfo.``frombuf`(buf, encoding, errors)

  `TarInfo` オブジェクトを文字列バッファー buf から作成して返します。

  バッファーが不正な場合 `HeaderError` を送出します。

classmethod `TarInfo.``fromtarfile`(tarfile)

  `TarFile` オブジェクトの tarfile から、次のメンバーを読み込んで、それを `TarInfo` オブジェクトとして返します。

`TarInfo.``tobuf`(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')

  `TarInfo` オブジェクトから文字列バッファーを作成します。引数についての情報は、`TarFile` クラスのコンストラクターを参照してください。

  バージョン 3.2 で変更: 引数 errors のデフォルトが `'surrogateescape'` になりました。

`TarInfo` オブジェクトには以下のデータ属性があります:

`TarInfo.``name`: str

  アーカイブメンバーの名前。

`TarInfo.``size`: int

  バイト単位でのサイズ。

`TarInfo.``mtime`: int | float

  Time of last modification in seconds since the epoch, as in `os.stat_result.st_mtime`.

  バージョン 3.8.17 で変更: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

`TarInfo.``mode`: int

  Permission bits, as for `os.chmod()`.

  バージョン 3.8.17 で変更: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

`TarInfo.``type`

  ファイルタイプ。type は通常、定数 `REGTYPE`、`AREGTYPE`、`LNKTYPE`、`SYMTYPE`、`DIRTYPE`、`FIFOTYPE`、`CONTTYPE`、`CHRTYPE`、`BLKTYPE`、あるいは `GNUTYPE_SPARSE` のいずれかです。`TarInfo` オブジェクトのタイプをもっと簡単に解決するには、下記の `is*()` メソッドを使って下さい。

`TarInfo.``linkname`: str

  リンク先ファイルの名前。これはタイプ `LNKTYPE` と `SYMTYPE` の `TarInfo` オブジェクトにだけ存在します。

  For symbolic links (`SYMTYPE`), the linkname is relative to the directory that contains the link. For hard links (`LNKTYPE`), the linkname is relative to the root of the archive.

`TarInfo.``uid`: int

  ファイルメンバーを保存した元のユーザーのユーザー ID。

  バージョン 3.8.17 で変更: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

`TarInfo.``gid`: int

  ファイルメンバーを保存した元のユーザーのグループ ID。

  バージョン 3.8.17 で変更: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

`TarInfo.``uname`: str

  ファイルメンバーを保存した元のユーザーのユーザー名。

  バージョン 3.8.17 で変更: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

`TarInfo.``gname`: str

  ファイルメンバーを保存した元のユーザーのグループ名。

  バージョン 3.8.17 で変更: Can be set to `None` for `extract()` and `extractall()`, causing extraction to skip applying this attribute.

`TarInfo.``pax_headers`: dict

  pax 拡張ヘッダーに関連付けられた、key-value ペアの辞書。

`TarInfo.replace(name=..., mtime=..., mode=..., linkname=...,`
`uid=..., gid=..., uname=..., gname=...,`
`deep=True)`

  バージョン 3.8.17 で追加.

  Return a new copy of the `TarInfo` object with the given attributes changed. For example, to return a `TarInfo` with the group name set to `'staff'`, use:

      new_tarinfo = old_tarinfo.replace(gname='staff')

  By default, a deep copy is made. If deep is false, the copy is shallow, i.e. `pax_headers` and any custom attributes are shared with the original `TarInfo` object.

`TarInfo` オブジェクトは便利な照会用のメソッドもいくつか提供しています:

`TarInfo.``isfile`()

  `Tarinfo` オブジェクトが一般ファイルの場合に、`True` を返します。

`TarInfo.``isreg`()

  `isfile()` と同じです。

`TarInfo.``isdir`()

  ディレクトリの場合に `True` を返します。

`TarInfo.``issym`()

  シンボリックリンクの場合に `True` を返します。

`TarInfo.``islnk`()

  ハードリンクの場合に `True` を返します。

`TarInfo.``ischr`()

  キャラクターデバイスの場合に `True` を返します。

`TarInfo.``isblk`()

  ブロックデバイスの場合に `True` を返します。

`TarInfo.``isfifo`()

  FIFO の場合に `True` を返します。

`TarInfo.``isdev`()

  キャラクターデバイス、ブロックデバイスあるいは FIFO のいずれかの場合に `True` を返します。

## Extraction filters

バージョン 3.8.17 で追加.

The tar format is designed to capture all details of a UNIX-like filesystem, which makes it very powerful. Unfortunately, the features make it easy to create tar files that have unintended -- and possibly malicious -- effects when extracted. For example, extracting a tar file can overwrite arbitrary files in various ways (e.g. by using absolute paths, `..` path components, or symlinks that affect later members).

In most cases, the full functionality is not needed. Therefore, tarfile supports extraction filters: a mechanism to limit functionality, and thus mitigate some of the security issues.

参考

PEP 706

  Contains further motivation and rationale behind the design.

The filter argument to `TarFile.extract()` or `extractall()` can be:

- the string `'fully_trusted'`: Honor all metadata as specified in the archive. Should be used if the user trusts the archive completely, or implements their own complex verification.

- the string `'tar'`: Honor most tar-specific features (i.e. features of UNIX-like filesystems), but block features that are very likely to be surprising or malicious. See `tar_filter()` for details.

- the string `'data'`: Ignore or block most features specific to UNIX-like filesystems. Intended for extracting cross-platform data archives. See `data_filter()` for details.

- `None` (default): Use `TarFile.extraction_filter`.

  If that is also `None` (the default), the `'fully_trusted'` filter will be used (for compatibility with earlier versions of Python).

  In Python 3.12, the default will emit a `DeprecationWarning`.

  In Python 3.14, the `'data'` filter will become the default instead. It's possible to switch earlier; see `TarFile.extraction_filter`.

- A callable which will be called for each extracted member with a TarInfo describing the member and the destination path to where the archive is extracted (i.e. the same path is used for all members):

      filter(/, member: TarInfo, path: str) -> TarInfo | None

  The callable is called just before each member is extracted, so it can take the current state of the disk into account. It can:

  - return a `TarInfo` object which will be used instead of the metadata in the archive, or

  - return `None`, in which case the member will be skipped, or

  - raise an exception to abort the operation or skip the member, depending on `errorlevel`. Note that when extraction is aborted, `extractall()` may leave the archive partially extracted. It does not attempt to clean up.

### Default named filters

The pre-defined, named filters are available as functions, so they can be reused in custom filters:

`tarfile.``fully_trusted_filter`(/, member, path)

  Return member unchanged.

  This implements the `'fully_trusted'` filter.

`tarfile.``tar_filter`(/, member, path)

  Implements the `'tar'` filter.

  - Strip leading slashes (`/` and `os.sep`) from filenames.

  - Refuse to extract files with absolute paths (in case the name is absolute even after stripping slashes, e.g. `C:/foo` on Windows). This raises `AbsolutePathError`.

  - Refuse to extract files whose absolute path (after following symlinks) would end up outside the destination. This raises `OutsideDestinationError`.

  - Clear high mode bits (setuid, setgid, sticky) and group/other write bits (`S_IWOTH`).

  Return the modified `TarInfo` member.

`tarfile.``data_filter`(/, member, path)

  Implements the `'data'` filter. In addition to what `tar_filter` does:

  - Refuse to extract links (hard or soft) that link to absolute paths, or ones that link outside the destination.

    This raises `AbsoluteLinkError` or `LinkOutsideDestinationError`.

    Note that such files are refused even on platforms that do not support symbolic links.

  - Refuse to extract device files (including pipes). This raises `SpecialFileError`.

  - For regular files, including hard links:

    - Set the owner read and write permissions (`S_IWUSR`).

    - Remove the group & other executable permission (`S_IXOTH`) if the owner doesn’t have it (`S_IXUSR`).

  - For other files (directories), set `mode` to `None`, so that extraction methods skip applying permission bits.

  - Set user and group info (`uid`, `gid`, `uname`, `gname`) to `None`, so that extraction methods skip setting it.

  Return the modified `TarInfo` member.

### Filter errors

When a filter refuses to extract a file, it will raise an appropriate exception, a subclass of `FilterError`. This will abort the extraction if `TarFile.errorlevel` is 1 or more. With `errorlevel=0` the error will be logged and the member will be skipped, but extraction will continue.

### Hints for further verification

Even with `filter='data'`, tarfile is not suited for extracting untrusted files without prior inspection. Among other issues, the pre-defined filters do not prevent denial-of-service attacks. Users should do additional checks.

Here is an incomplete list of things to consider:

- Extract to a `new temporary directory` to prevent e.g. exploiting pre-existing links, and to make it easier to clean up after a failed extraction.

- When working with untrusted data, use external (e.g. OS-level) limits on disk, memory and CPU usage.

- Check filenames against an allow-list of characters (to filter out control characters, confusables, foreign path separators, etc.).

- Check that filenames have expected extensions (discouraging files that execute when you “click on them”, or extension-less files like Windows special device names).

- Limit the number of extracted files, total size of extracted data, filename length (including symlink length), and size of individual files.

- Check for files that would be shadowed on case-insensitive filesystems.

Also note that:

- Tar files may contain multiple versions of the same file. Later ones are expected to overwrite any earlier ones. This feature is crucial to allow updating tape archives, but can be abused maliciously.

- tarfile does not protect against issues with “live” data, e.g. an attacker tinkering with the destination (or source) directory while extraction (or archiving) is in progress.

### Supporting older Python versions

Extraction filters were added to Python 3.12, and are backported to older versions as security updates. To check whether the feature is available, use e.g. `hasattr(tarfile, 'data_filter')` rather than checking the Python version.

The following examples show how to support Python versions with and without the feature. Note that setting `extraction_filter` will affect any subsequent operations.

- Fully trusted archive:

      my_tarfile.extraction_filter = (lambda member, path: member)
      my_tarfile.extractall()

- Use the `'data'` filter if available, but revert to Python 3.11 behavior (`'fully_trusted'`) if this feature is not available:

      my_tarfile.extraction_filter = getattr(tarfile, 'data_filter',
                                             (lambda member, path: member))
      my_tarfile.extractall()

- Use the `'data'` filter; fail if it is not available:

      my_tarfile.extractall(filter=tarfile.data_filter)

  or:

      my_tarfile.extraction_filter = tarfile.data_filter
      my_tarfile.extractall()

- Use the `'data'` filter; warn if it is not available:

      if hasattr(tarfile, 'data_filter'):
          my_tarfile.extractall(filter='data')
      else:
          # remove this when no longer needed
          warn_the_user('Extracting may be unsafe; consider updating Python')
          my_tarfile.extractall()

### Stateful extraction filter example

While tarfile's extraction methods take a simple filter callable, custom filters may be more complex objects with an internal state. It may be useful to write these as context managers, to be used like this:

    with StatefulFilter() as filter_func:
        tar.extractall(path, filter=filter_func)

Such a filter can be written as, for example:

    class StatefulFilter:
        def __init__(self):
            self.file_count = 0

        def __enter__(self):
            return self

        def __call__(self, member, path):
            self.file_count += 1
            return member

        def __exit__(self, *exc_info):
            print(f'{self.file_count} files extracted')

## コマンドラインインターフェイス

バージョン 3.4 で追加.

`tarfile` モジュールは、 tar アーカイブを操作するための簡単なコマンドラインインターフェースを提供しています。

tar アーカイブを新規に作成したい場合、`-c` オプションの後にまとめたいファイル名のリストを指定してください:

    $ python -m tarfile -c monty.tar  spam.txt eggs.txt

ディレクトリを渡すこともできます:

    $ python -m tarfile -c monty.tar life-of-brian_1979/

tar アーカイブをカレントディレクトリに展開したい場合、`-e` オプションを使用してください:

    $ python -m tarfile -e monty.tar

ディレクトリ名を渡すことで tar アーカイブを別のディレクトリに取り出すこともできます:

    $ python -m tarfile -e monty.tar  other-dir/

tar アーカイブ内のファイル一覧を表示するには `-l` を使用してください:

    $ python -m tarfile -l monty.tar

### コマンドラインオプション

`-l``<tarfile>`
`--list``<tarfile>`

  tarfile 内のファイル一覧を表示します。

`-c``<tarfile> <source1> ... <sourceN>`
`--create``<tarfile> <source1> ... <sourceN>`

  ソースファイルから tarfile を作成します。

`-e``<tarfile> [<output_dir>]`
`--extract``<tarfile> [<output_dir>]`

  output_dir が指定されていない場合、カレントディレクトリに tarfile を展開します。

`-t``<tarfile>`
`--test``<tarfile>`

  tarfile が有効かどうか調べます。

`-v````,` `--verbose```

  詳細も出力します。

`--filter``<filtername>`

  Specifies the filter for `--extract`. See Extraction filters for details. Only string names are accepted (that is, `fully_trusted`, `tar`, and `data`).

  バージョン 3.8.17 で追加.

## 使用例

tar アーカイブから現在のディレクトリにすべて抽出する方法:

    import tarfile
    tar = tarfile.open("sample.tar.gz")
    tar.extractall()
    tar.close()

tar アーカイブの一部を、リストの代わりにジェネレーター関数を利用して `TarFile.extractall()` で展開する方法:

    import os
    import tarfile

    def py_files(members):
        for tarinfo in members:
            if os.path.splitext(tarinfo.name)[1] == ".py":
                yield tarinfo

    tar = tarfile.open("sample.tar.gz")
    tar.extractall(members=py_files(tar))
    tar.close()

非圧縮 tar アーカイブをファイル名のリストから作成する方法:

    import tarfile
    tar = tarfile.open("sample.tar", "w")
    for name in ["foo", "bar", "quux"]:
        tar.add(name)
    tar.close()

`with` 文を利用した同じ例:

    import tarfile
    with tarfile.open("sample.tar", "w") as tar:
        for name in ["foo", "bar", "quux"]:
            tar.add(name)

gzip 圧縮 tar アーカイブを作成してメンバー情報のいくつかを表示する方法:

    import tarfile
    tar = tarfile.open("sample.tar.gz", "r:gz")
    for tarinfo in tar:
        print(tarinfo.name, "is", tarinfo.size, "bytes in size and is ", end="")
        if tarinfo.isreg():
            print("a regular file.")
        elif tarinfo.isdir():
            print("a directory.")
        else:
            print("something else.")
    tar.close()

`TarFile.add()` 関数の filter 引数を利用してユーザー情報をリセットしながらアーカイブを作成する方法:

    import tarfile
    def reset(tarinfo):
        tarinfo.uid = tarinfo.gid = 0
        tarinfo.uname = tarinfo.gname = "root"
        return tarinfo
    tar = tarfile.open("sample.tar.gz", "w:gz")
    tar.add("foo", filter=reset)
    tar.close()

## サポートしている tar フォーマット

`tarfile` モジュールは 3 種類の tar フォーマットを作成することができます:

- POSIX.1-1988 ustar format (`USTAR_FORMAT`). ファイル名の長さは256文字までで、リンク名の長さは100文字までです。最大のファイルサイズは8GiBです。このフォーマットは古くて制限が多いですが、広くサポートされています。

- GNU tar format (`GNU_FORMAT`). 長いファイル名とリンク名、8GiBを超えるファイルやスパース(sparse)ファイルをサポートしています。これは GNU/Linux システムにおいてデファクト・スタンダードになっています。 `tarfile` モジュールは長いファイル名を完全にサポートしています。 スパースファイルは読み込みのみサポートしています。

- The POSIX.1-2001 pax format (`PAX_FORMAT`). It is the most flexible format with virtually no limits. It supports long filenames and linknames, large files and stores pathnames in a portable way. Modern tar implementations, including GNU tar, bsdtar/libarchive and star, fully support extended pax features; some old or unmaintained libraries may not, but should treat pax archives as if they were in the universally-supported ustar format. It is the current default format for new archives.

  It extends the existing ustar format with extra headers for information that cannot be stored otherwise. There are two flavours of pax headers: Extended headers only affect the subsequent file header, global headers are valid for the complete archive and affect all following files. All the data in a pax header is encoded in UTF-8 for portability reasons.

他にも、読み込みのみサポートしている tar フォーマットがいくつかあります:

- ancient V7 フォーマット。これは Unix 7th Edition から存在する、最初の tar フォーマットです。通常のファイルとディレクトリのみ保存します。名前は 100 文字を超えてはならず、ユーザー/グループ名に関する情報は保存されません。いくつかのアーカイブは、フィールドが ASCII でない文字を含む場合に、ヘッダーのチェックサムの計算を誤ります。

- SunOS tar 拡張フォーマット。POSIX.1-2001 pax フォーマットの亜流ですが、互換性がありません。

## Unicode に関する問題

tar フォーマットは、もともとテープドライブにファイルシステムのバックアップをとる目的で設計されました。現在、tarアーカイブはファイルを配布する際に一般的に用いられ、ネットワーク上で交換されています。オリジナルフォーマットが抱える一つの問題は (他の多くのフォーマットでも同じですが)、様々な文字エンコーディングのサポートについて考慮していないことです。例えば、UTF-8 システム上で作成された通常の tar アーカイブは、非 ASCII 文字を含んでいた場合、Latin-1 システムでは正しく読み取ることができません。テキストのメタデータ (ファイル名、リンク名、ユーザー/グループ名など) は破壊されます。残念なことに、アーカイブのエンコーディングを自動検出する方法はありません。pax フォーマットはこの問題を解決するために設計されました。これは非 ASCII メタデータをユニバーサル文字エンコーディング UTF-8 を使用して格納します。

`tarfile` における文字変換処理の詳細は `TarFile` クラスのキーワード引数 encoding および errors によって制御されます。

encoding はアーカイブのメタデータに使用する文字エンコーディングを指定します。デフォルト値は `sys.getfilesystemencoding()` で、フォールバックとして `'ascii'` が使用されます。アーカイブの読み書き時に、メタデータはそれぞれデコードまたはエンコードしなければなりません。encoding に適切な値が設定されていない場合、その変換は失敗することがあります。

引数 errors は文字を変換できない時の扱いを指定します。指定できる値は エラーハンドラ 節を参照してください。デフォルトのスキームは `'surrogateescape'` で、Python はそのファイルシステムの呼び出しも使用します。ファイル名、コマンドライン引数、および環境変数 を参照してください。

デフォルトの `PAX_FORMAT` アーカイブでは、メタデータはすべて UTF-8 で格納されるため、encoding は通常指定する必要はありません。encoding は、まれにある、バイナリの pax ヘッダーがデコードされた場合、あるいはサロゲート文字を含む文字列が格納されていた場合に使用されます。