13.6. "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()" メソッドが取得したバッファーが不正だったときに
   送出されます。

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

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

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

参考:

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

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

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


13.6.1. 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=0)

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

   *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"
   のいずれかである必要があります。

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

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

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

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

   *errorlevel* が "0" の場合、"TarFile.extract()" 使用時にすべてのエ
   ラーが無視されます。エラーが無視された場合でも、*debug* が有効であ
   れば、エラーメッセージは出力されます。"1" の場合、すべての *致命的
   な(fatal)* エラーは "OSError" を送出します。"2" の場合、すべての *
   致命的でない(non-fatal)* エラーも "TarError" 例外として送出されます
   。

   引数 *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)

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

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

   警告:

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

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

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

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

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

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

   注釈:

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

   警告:

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

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

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

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

TarFile.extractfile(member)

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

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

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

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

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

   バージョン 3.2 で非推奨: パラメーター *exclude* は廃止されます。
   *filter* を使用してください。

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 ペアの辞書です。


13.6.2. TarInfo オブジェクト
============================

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

"TarInfo" オブジェクトは "TarFile" のメソッド "getmember()"、
"getmembers()" および "gettarinfo()" によって返されます。

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

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

TarInfo.size

   バイト単位でのサイズ。

TarInfo.mtime

   最後に変更された時刻。

TarInfo.mode

   許可ビット。

TarInfo.type

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

TarInfo.linkname

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

TarInfo.uid

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

TarInfo.gid

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

TarInfo.uname

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

TarInfo.gname

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

TarInfo.pax_headers

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

"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" を返します。


13.6.3. コマンドラインインターフェイス
======================================

バージョン 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


13.6.3.1. コマンドラインオプション
----------------------------------

-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

   詳細も出力します。


13.6.4. 使用例
==============

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


13.6.5. サポートしている tar フォーマット
=========================================

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

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

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

* POSIX.1-2001 pax フォーマット ("PAX_FORMAT")。最も柔軟性があり、ほぼ
  制限が無いフォーマットです。長いファイル名やリンク名、大きいファイル
  をサポートし、パス名をポータブルな方法で保存します。しかし、現在のと
  ころ、すべての tar の実装が pax フォーマットを正しく扱えるわけではあ
  りません。

  *pax* フォーマットは既存の *ustar* フォーマットの拡張です。*ustar*
  では保存できない情報を追加のヘッダーを利用して保存します。*pax* には
  2 種類のヘッダーがあります。1 つ目は拡張ヘッダーで、その次のファイル
  ヘッダーに影響します。2 つ目はグローバルヘッダーで、アーカイブ全体に
  対して有効で、それ以降のすべてのファイルに影響します。すべての pax
  ヘッダーの内容は、ポータブル性のために *UTF-8* で保存されます。

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

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

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


13.6.6. 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 ヘッダーがデコードされた場合、あるいはサロゲート
文字を含む文字列が格納されていた場合に使用されます。
