12.5.1 TarFile オブジェクト

TarFile オブジェクトは、tar アーカイブへのインターフェースを提供します。 tar アーカイブは一連のブロックです。アーカイブメンバー(保存されたファイル)は、ヘッダーブロックとそれに続くデータブロックから構成されています。ある tar アーカイブにファイルを何回も保存することができます。各アーカイブメンバーは、 TarInfo オブジェクトによって表わされます、詳細については TarInfo オブジェクト (セクション 12.5.2)を見て下さい。

クラス TarFile( [name[, mode[, fileobj]]]): (非圧縮の) tar アーカイブ nameをオープンします。 mode は、既存のアーカイブから読み込むには 'r' 、既存のファイルにデータを追加するには 'a'、あるいは既存のファイルを上書きして新しいファイルを作成するには 'w' のどれかです。mode のデフォールトは 'r'です。
もし fileobjが与えられていれば、それを使ってデータを読み書きします。もしそれが決定できれば、modeは fileobj のモードで上書きされます。.
注意: fileobj は、TarFileをクローズする時は、クローズされません。

open( ...): 代替コンストラクタです。モジュールレベルでの open() 関数は、実際はこのクラスメソッドへのショートカットです。詳細についてはセクション 12.5 を見て下さい。

getmember( name): メンバー name に対する TarInfo オブジェクトを返します。もし nameがアーカイブに見つからなければ、KeyErrorが発生します。
注意: もしメンバーがアーカイブに1つ以上あれば、その最後に出現するものが、最新のバージョンであるとみなされます。

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

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

list( verbose=True): コンテンツの表を sys.stdout に印刷します。もし verbose が False であれば、メンバー名のみ印刷します。もしそれが True であれば、"ls -l" に似た出力を生成します．

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

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

extract( member[, path]): メンバーをアーカイブから現在の作業ディレクトリに、そのフル名を使って、抽出します。そのファイル情報はできるだけ正確に抽出されます。 memberは、ファイル名でもTarInfo オブジェクトでも構いません。 pathを使って、異なるディレクトリを指定することができます。
注意: extract() メソッドでは tar アーカイブにランダムアクセスすることが許されるので、これを使う場合には使用者自身が気をつけなければならない問題があります。上の extractall() の説明を参照してください。

extractfile( member): アーカイブからメンバーをオブジェクトとして抽出します。 memberは、ファイル名あるいは TarInfo オブジェクトです。もし memberが普通のファイルであれば、ファイル風のオブジェクトを返します。もし memberがリンクであれば、ファイル風のオブジェクトをリンクのターゲットから構成します。もし memberが上のどれでもなければ、None が返されます。
注意: ファイル風のオブジェクトは読み出し専用で以下のメソッドを提供します： read(), readline(), readlines(), seek(), tell().

add( name[, arcname[, recursive]]): ファイル nameをアーカイブに追加します。name は、任意のファイルタイプ (ディレクトリ、fifo、シンボリックリンク等)です。もしarcname が与えられていれば、それはアーカイブ内のファイルの代替名を指定します。デフォールトではディレクトリは再帰的に追加されます。これは、recursive を False に設定することで避けることができます。デフォルトは True です．

addfile( tarinfo[, fileobj]): TarInfoオブジェクトtarinfoをアーカイブに追加します。もし fileobj が与えられていれば、tarinfo.size バイトがそれから読まれ、アーカイブに追加されます。gettarinfo()を使って TarInfo オブジェクトを作成することができます。
注意: Windows プラットフォームでは、fileobjは、ファイルサイズに関する問題を避けるために、常に、モード 'rb' でオープンされるべきです。

gettarinfo( [name[, arcname[, fileobj]]]): TarInfoオブジェクトをファイル name あるいは (そのファイル記述子に os.fstat()を使って) ファイルオブジェクトfileobjのどちらか用に作成します。 TarInfoの属性のいくつかは、 addfile()を使って追加する前に修正することができます。 arcnameがもし与えられていれば、アーカイブ内のファイルの代替名を指定します。

close( ): TarFileをクローズします。書き出しモードでは、完了ゼロブロックが 2つ、アーカイブに追加されます。

posix: この値が真なら、POSIX 1003.1-1990 準拠のアーカイブを作成します。GNU 拡張機能はは POSIX 標準の一部ではないため使いません． POSIX 準拠のアーカイブでは，ファイル名の長さは最大 256 ，リンク名の最大長は100文字に制限されており，ファイルの最大長は 8 ギガバイト以下です．ファイルがこれらの制限を超えた場合， ValueErrorを送出します．この値が偽の場合，GNU tar 互換のアーカイブを作成します． POSIX 仕様には準拠しませんが，上記の制約を受けずにファイルを保存できます．バージョン 2.4 で変更された仕様: posix のデフォルト値が False になりました

dereference: この値が偽の場合，シンボリックリンクとハードリンクをアーカイブに追加します。真の場合，ターゲットファイルの内容をアーカイブに追加します。この値はリンクをサポートしないシステムには影響しません。

ignore_zeros: この値が偽の場合，空のブロックをアーカイブの終わりとして処理します。真の場合，空(で無効な)ブロックを飛ばして、できるだけ多くのメンバを取得しようとします。これはアーカイブを連結している場合やアーカイブが損傷している場合に役に立ちます。

debug=0: 0(デバッグメッセージなし、デフォルト)から 3(すべてのデバッグメッセージあり)までの値に設定します．メッセージは sys.stderr に出力されます．

errorlevel=0: この値が0 (デフォルトの値です) の場合， extract() 実行時の全てのエラーを無視します．ただし，デバッグが有効になっている場合には，デバッグ出力にエラーメッセージとして出力します．値を1 にした場合，すべての致命的な エラーに対して OSErrorまたはIOError 例外を送出します．値を2 にした場合、致命的でないエラーもまた，全て TarError 例外として送出します．

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。