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

ソースコード: 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 files, or the higher-level functions in shutil.

いくつかの事実と形態:

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

  If any of these optional modules are missing from your copy of CPython, look for documentation from your distributor (that is, whoever provided Python to you). If you are the distributor, see オプションのモジュールの要件.

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

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

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

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

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

バージョン 3.12 で変更: Archives are extracted using a filter, which makes it possible to either limit surprising/dangerous features, or to acknowledge that they are expected and the archive is fully trusted.

バージョン 3.14 で変更: Set the default extraction filter to data, which disallows some dangerous features such as links to absolute paths or paths outside of the destination. Previously, the filter strategy was equivalent to fully_trusted.

バージョン 3.14 で変更: Added support for Zstandard compression using compression.zstd.

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 圧縮で読み込み用にオープンします。
'r:zst'	Zstandard 圧縮で読み込み用にオープンします。
'x' or 'x:'	圧縮せずに tarfile を排他的に作成します。tarfile が既存の場合 FileExistsError 例外を送出します。
'x:gz'	gzip 圧縮で tarfile を作成します。tarfile が既存の場合 FileExistsError 例外を送出します。
'x:bz2'	bzip2 圧縮で tarfile を作成します。tarfile が既存の場合 FileExistsError 例外を送出します。
'x:xz'	lzma 圧縮で tarfile を作成します。tarfile が既存の場合 FileExistsError 例外を送出します。
'x:zst'	Zstandard 圧縮で tarfile を作成します。tarfile が既存の場合 FileExistsError 例外を送出します。
'a' または 'a:'	非圧縮で追記用にオープンします。ファイルが存在しない場合は新たに作成されます。
'w' または 'w:'	非圧縮で書き込み用にオープンします。
'w:gz'	gzip 圧縮で書き込み用にオープンします。
'w:bz2'	bzip2 圧縮で書き込み用にオープンします。
'w:xz'	lzma 圧縮で書き込み用にオープンします。
'w:zst'	Zstandard 圧縮で書き込み用にオープンします。

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

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

For modes 'w:gz', 'x:gz', 'w|gz', 'w:bz2', 'x:bz2', 'w|bz2', tarfile.open() accepts the keyword argument compresslevel (default 9) to specify the compression level of the file.

'w:xz'、'x:xz' および 'w|xz' モードの場合、tarfile.open() はファイルの圧縮レベルを指定するキーワード引数 preset を受け付けます。

For modes 'w:zst', 'x:zst' and 'w|zst', tarfile.open() accepts the keyword argument level to specify the compression level of the file. The keyword argument options may also be passed, providing advanced Zstandard compression parameters described by CompressionParameter. The keyword argument zstd_dict can be passed to provide a ZstdDict, a Zstandard dictionary used to improve compression of smaller amounts of data.

For special purposes, there is a second format for mode: 'filemode|[compression]'. tarfile.open() will return a TarFile object that processes its data as a stream of blocks. No random seeking will be done on the file. If given, fileobj may be any object that has a read() or write() method (depending on the mode) that works with bytes. bufsize specifies the blocksize and defaults to 20 * 512 bytes. Use this variant in combination with e.g. sys.stdin.buffer, a socket file object or a tape device. However, such a TarFile object is limited in that it does not allow random access, see 使用例. The currently possible modes:

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

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

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

バージョン 3.12 で変更: The compresslevel keyword argument also works for streams.

バージョン 3.14 で変更: The preset keyword argument also works for streams.

class tarfile.TarFile

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

tarfile.is_tarfile(name)

Return True if name is a tar archive file, that the tarfile module can read. name may be a str, file, or file-like object.

バージョン 3.9 で変更: ファイルおよびファイルライクオブジェクトをサポートしました。

The tarfile module defines the following exceptions:

exception tarfile.TarError

Base class for all tarfile exceptions.

exception tarfile.ReadError

Is raised when a tar archive is opened, that either cannot be handled by the tarfile module or is somehow invalid.

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.

exception tarfile.LinkFallbackError

Raised to refuse emulating a link (hard or symbolic) by extracting another archive member, when that member would be rejected by the filter location. The exception that was raised to reject the replacement member is available as BaseException.__context__.

Added in version 3.14.

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

tarfile.ENCODING

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

tarfile.REGTYPE

tarfile.AREGTYPE

A regular file type.

tarfile.LNKTYPE

A link (inside tarfile) type.

tarfile.SYMTYPE

A symbolic link type.

tarfile.CHRTYPE

A character special device type.

tarfile.BLKTYPE

A block special device type.

tarfile.DIRTYPE

A directory type.

tarfile.FIFOTYPE

A FIFO special device type.

tarfile.CONTTYPE

A contiguous file type.

tarfile.GNUTYPE_LONGNAME

A GNU tar longname type.

tarfile.GNUTYPE_LONGLINK

A GNU tar longlink type.

tarfile.GNUTYPE_SPARSE

A GNU tar sparse file type.

Each of the following constants defines a tar archive format that the tarfile module is able to create. See section サポートしている tar フォーマット for details.

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 ブロックが終了したときにオブジェクトはクローズされます。例外が発生した時、内部で利用されているファイルオブジェクトのみがクローズされ、書き込み用にオープンされたアーカイブのファイナライズは行われないことに注意してください。使用例 節のユースケースを参照してください。

Added in version 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, stream=False)

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

name is the pathname of the archive. name may be a path-like object. It can be omitted if fileobj is given. In this case, the file object's name attribute is used if it exists.

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 グローバルヘッダーに追加されます。

If stream is set to True then while reading the archive info about files in the archive are not cached, saving memory.

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

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

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

バージョン 3.13 で変更: Add the stream parameter.

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 specifies how members are modified or rejected before extraction. See Extraction filters for details. It is recommended to set this explicitly only if specific tar features are required, or as filter='data' to support Python versions with a less secure default (3.13 and lower).

警告

Never extract archives from untrusted sources without prior inspection.

Since Python 3.14, the default (data) will prevent the most dangerous security issues. However, it will not prevent all unintended or insecure behavior. Read the Extraction filters section for details.

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

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

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

バージョン 3.14 で変更: The filter parameter now defaults to 'data'.

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() メソッドの利用を考慮するべきです。

警告

Never extract archives from untrusted sources without prior inspection. See the warning for extractall() for details.

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

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

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

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

TarFile.extractfile(member)

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

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

バージョン 3.13 で変更: The returned io.BufferedReader object has the mode attribute which is always equal to 'rb'.

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

Added in version 3.12.

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), extraction methods will 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.

バージョン 3.14 で変更: The default filter is set to data, which disallows some dangerous features such as links to absolute paths or paths outside of the destination. Previously, the default was equivalent to fully_trusted.

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)

Add the TarInfo object tarinfo to the archive. If tarinfo represents a non zero-size regular file, the fileobj argument should be a binary file, and tarinfo.size bytes are read from it and added to the archive. You can create TarInfo objects directly, or by using gettarinfo().

バージョン 3.13 で変更: fileobj must be given for non-zero-sized regular files.

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

os.stat() の結果か、既存のファイルに相当するものから、TarInfo オブジェクトを作成します。このファイルは、name で名付けられるか、ファイル記述子を持つ file object fileobj として指定されます。name は 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: dict

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.

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.12 で変更: 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.12 で変更: 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.12 で変更: Can be set to None for extract() and extractall(), causing extraction to skip applying this attribute.

TarInfo.gid: int

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

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

TarInfo.uname: str

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

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

TarInfo.gname: str

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

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

TarInfo.chksum: int

Header checksum.

TarInfo.devmajor: int

Device major number.

TarInfo.devminor: int

Device minor number.

TarInfo.offset: int

The tar header starts here.

TarInfo.offset_data: int

The file's data starts here.

TarInfo.sparse

Sparse member information.

TarInfo.pax_headers: dict

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

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

Added in version 3.12.

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()

Return True if the TarInfo object is a regular file.

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

Added in version 3.12.

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.

警告

None of the available filters blocks all dangerous archive features. Never extract archives from untrusted sources without prior inspection. See also Hints for further verification.

参考

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 'data' filter will be used.

  バージョン 3.14 で変更: The default filter is set to data. Previously, the default was equivalent to fully_trusted.

• 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.

• Normalize filenames (TarInfo.name) that contain .. components using os.path.normpath(). Note that this removes internal .. components, which may change the meaning of the name if it traverses symbolic links.

• 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_IWGRP | S_IWOTH).

Return the modified TarInfo member.

バージョン 3.14.8 で変更: Filenames containing .. components are now normalized.

tarfile.data_filter(member, path)

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

• Normalize link targets (TarInfo.linkname) using os.path.normpath(). Note that this removes internal .. components, which may change the meaning of the link if the path in TarInfo.linkname traverses symbolic links.

• 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_IRUSR | S_IWUSR).

  • Remove the group & other executable permission (S_IXGRP | 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.

Note that this filter does not block all dangerous archive features. See Hints for further verification for details.

バージョン 3.14 で変更: Link targets are now normalized.

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.

• Disallow symbolic links if you do not need the functionality.

• 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, and so on).

• 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, but may be 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)
  

  もしくは:

  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')

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

Added in version 3.4.

The tarfile module provides a simple command-line interface to interact with tar archives.

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).

使用例

Reading examples

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

import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall(filter='data')
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()

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()

Writing examples

非圧縮 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)

How to create and write an archive to stdout using sys.stdout.buffer in the fileobj parameter in TarFile.add():

import sys
import tarfile
with tarfile.open("sample.tar.gz", "w|gz", fileobj=sys.stdout.buffer) as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)

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 フォーマット

There are three tar formats that can be created with the tarfile module:

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

• The GNU tar format (GNU_FORMAT). It supports long filenames and linknames, files bigger than 8 GiB and sparse files. It is the de facto standard on GNU/Linux systems. tarfile fully supports the GNU tar extensions for long names, sparse file support is read-only.

• 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 を使用して格納します。

The details of character conversion in tarfile are controlled by the encoding and errors keyword arguments of the TarFile class.

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

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

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