バージョン 2.3 で追加.
tarfile モジュールは、gzipやbz2圧縮されたものも含めて、tarアーカイブの読み書きができます。 (.zip ファイルの読み書きは zipfile モジュールで可能です。)
いくつかの事実と外観:
POSIX.1-1988 (ustar) フォーマットの読み書きをサポートしています。
longname, longlink 拡張を含めた、GNU tarフォーマットの読み書きをサポートしています。 sparse 拡張は読み込みのみサポートしています。
POSIX.1-2001 (pax) フォーマットの読み書きをサポートしています。
バージョン 2.6 で追加.
ディレクトリ、普通のファイル、ハードリンク、シンボリックリンク、fifo、キャラクタデバイスおよびブロックデバイスを処理します。また、タイムスタンプ、 アクセス許可およびオーナーのようなファイル情報の取得および保存が可能です。
パス名 name の TarFile オブジェクトを返します。 TarFile オブジェクトと、利用出来るキーワード引数に関する詳細な情報については、 TarFile オブジェクト 節を参照してください。
mode は 'filemode[:compression]' の形式をとる文字列でなければなりません。デフォルトの値は 'r' です。以下に mode のとりうる組み合わせ全てを示します。
mode | 動作 |
---|---|
'r' または 'r:*' | 透過な圧縮つきで読み込むためにオープンします(推奨)。 |
'r:' | 圧縮なしで排他的に読み込むためにオープンします。 |
'r:gz' | gzip 圧縮で読み込むためにオープンします。 |
'r:bz2' | bzip2 圧縮で読み込むためにオープンします。 |
'a' または 'a:' | 圧縮なしで追加するためにオープンします。ファイルが存在しない 場合は新たに作成されます。 |
'w' または 'w:' | 非圧縮で書き込むためにオープンします。 |
'w:gz' | gzip 圧縮で書き込むためにオープンします。 |
'w:bz2' | bzip2 圧縮で書き込むためにオープンします。 |
'a:gz' あるいは 'a:bz2' は可能ではないことに注意して下さい。もし mode が、ある(圧縮した)ファイルを読み込み用にオープンするのに、適していないなら、 ReadError が発生します。これを防ぐには mode 'r' を使って下さい。もし圧縮メソッドがサポートされていなければ、 CompressionError が発生します。
もし fileobj が指定されていれば、それは name でオープンされたファイルオブジェクトの代替として使うことができます。 そのファイルオブジェクトの、ファイルポジションが0であることを前提に動作します。
特別な目的のために、 mode の2番目の形式: 'ファイルモード|[圧縮]' があります。この形式を使うと、 tarfile.open() が返すのはデータをブロックからなるストリームとして扱う TarFile オブジェクトになります。この場合、ファイルに対して ランダムな seek を行えなくなります。 fileobj を指定する場合、 read() および write() メソッドを持つ任意のオブジェクトにできます。 bufsize にはブロックサイズを指定します。デフォルトは 20 * 512 バイトです。 sys.stdin 、ソケットファイルオブジェクト、テープデバイスと組み合わせる場合にはこの形式を 使ってください。ただし、このような TarFile オブジェクトにはランダムアクセスを行えないという制限があります。 例 節を参照してください。現在可能なモードは:
モード | 動作 |
---|---|
'r|*' | tar ブロックの ストリーム を透過な読み込みにオープンします。 |
'r|' | 非圧縮 tar ブロックの ストリーム を読み込みにオープンします。 |
'r|gz' | gzip 圧縮 ストリーム を読み込みにオープンします。 |
'r|bz2' | bzip2 圧縮 ストリーム を読み込みにオープンします。 |
'w|' | 非圧縮 ストリーム を書き込みにオープンします。 |
'w|gz' | gzip 圧縮 ストリーム を書き込みにオープンします。 |
'w|bz2' | bzip2 圧縮 ストリーム を書き込みにオープンします。 |
tar アーカイブを読んだり、書いたりするためのクラスです。このクラスを直接使わず、代わりに tarfile.open() を使ってください。 TarFile オブジェクト を参照してください。
zipfile -風なインターフェースを持つ tar アーカイブへの制限されたアクセスのためのクラスです。詳細は zipfile のドキュメントを参照してください。 compression は、以下の定数のどれかでなければなりません:
非圧縮 tar アーカイブのための定数。
バージョン 2.6 で撤廃: TarFileCompat クラスは、 Python 3.0 で削除されるので、非推奨になりました。
圧縮方法がサポートされていないか、あるいはデータを正しくデコードできない時に発生します。
TarFile.extract() を使った時、もし TarFile.errorlevel== 2 の フェータルでない エラーに対してだけ発生します。
TarInfo.frombuf() メソッドが、バッファが不正だったときに送出します。
バージョン 2.6 で追加.
以下の各定数は、 tarfile モジュールが作成できるtarアーカイブフォーマットを定義しています。 詳細は、 tar-formats を参照してください。
POSIX.1-1988 (ustar) フォーマット
GNU tar フォーマット
POSIX.1-2001 (pax) フォーマット
アーカイブを作成する際のデフォルトのフォーマット。 現在は GNU_FORMAT
以下のモジュールレベル変数が利用できます。
デフォルト文字エンコーディング。 sys.getfilesystemencoding() か sys.getdefaultencoding() のどちらかの値。
参考
TarFile オブジェクトは、tar アーカイブへのインターフェースを提供します。 tar アーカイブは一連のブロックです。アーカイブメンバー(保存されたファイル)は、ヘッダーブロックとそれに続くデータブロックから構成されています。ある tar アーカイブにファイルを何回も保存することができます。各アーカイブメンバーは、 TarInfo オブジェクトによって表わされます、詳細については TarInfo オブジェクト を参照してください。
以下の全ての引数はオプションで、インスタンス属性としてもアクセスすることができます。
name はアーカイブのパス名。 fileobj が渡された場合は省略可能。 その場合、ファイルオブジェクトの name 属性があれば、それを利用します。
mode は、既存のアーカイブファールから読み込むための 'r', 既存のアーカイブファイルに追記するための 'a', 既存のファイルがあれば上書きし、新しいファイルを作成する 'w' のいずれかです。
もし fileobj が与えられていれば、それを使ってデータを読み書きします。もしそれが決定できれば、 mode は fileobj のモードで上書きされます。 fileobj はポジション0から利用されます。
ノート
fileobj は、 TarFile をクローズする時にクローズされません。
format はアーカイブのフォーマットを制御します。 モジュールレベルで定義されている、 USTAR_FORMAT, GNU_FORMAT, PAX_FORMAT のいずれかである必要があります。
バージョン 2.6 で追加.
tarinfo 引数を利用して、デフォルトの TarInfo クラスを別のクラスで置き換えられます。
バージョン 2.6 で追加.
dereference が False だった場合、シンボリックリンクやハードリンクがアーカイブに追加されます。 True だった場合、リンクのターゲットとなるファイルの内容がアーカイブに追加されます。 シンボリックリンクをサポートしていないシステムでは効果がありません。
ignore_zeros が False だった場合、空ブロックをアーカイブの終端だと扱います。 True だった場合、空の(無効な)ブロックをスキップして、可能な限り多くのメンバを取得しようとします。 このオプションは、連結(concatenate)されたり、壊れたアーカイブファイルを扱うときにのみ、意味があります。
debug は 0 (デバッグメッセージ無し)から 3 (全デバッグメッセージ) まで設定できます。このメッセージは sys.stderr に書き込まれます。
errorlevel が 0 の場合、 TarFile.extract() 使用時に全てのエラーが無視されます。 エラーが無視された場合でも、 debug が有効であれば、エラーメッセージは出力されます。 1 の場合、全ての 致命的な(fatal) エラーは OSError か IOError を送出します。 2 の場合、全ての 致命的でない(non-fatal) エラーも TarError 例外として送出されます。
encoding と errors 引数は、文字列と unicode オブジェクトとの間の相互変換方法を指定します。 デフォルトの設定で、ほとんどのユーザーでうまく動作するでしょう。 詳しい情報は、 Unicode に関する問題 節を参照してください。
バージョン 2.6 で追加.
pax_headers 引数は、オプションの、 unicode 文字列の辞書で、 format が PAX_FORMAT だった場合に pax グローバルヘッダに追加されます。
バージョン 2.6 で追加.
代替コンストラクタです。モジュールレベルでの tarfile.open() 関数は、実際はこのクラスメソッドへのショートカットです。
メンバー name に対する TarInfo オブジェクトを返します。もし name がアーカイブに見つからなければ、 KeyError が発生します。
ノート
もしメンバーがアーカイブに1つ以上あれば、その最後に出現するものが、最新のバージョンであるとみなされます。
メンバーをその名前のリストとして返します。これは getmembers() で返されるリストと同じ順番です。
コンテンツの表を sys.stdout に印刷します。もし verbose が False であれば、メンバー名のみ印刷します。もしそれが True であれば、 "ls -l" に似た出力を生成します。
TarFile が読み込み用にオープンされている時、アーカイブの次のメンバーを TarInfo オブジェクトとして返します。もしそれ以上利用可能なものがなければ、 None を返します。
全てのメンバーをアーカイブから現在の作業ディレクトリーまたは path に抽出します。オプションの members が与えられるときには、 getmembers() で返されるリストの一部でなければなりません。 所有者、変更時刻、許可のようなディレクトリー情報は全てのメンバーが抽出された後にセットされます。これは二つの問題を回避するためです。一つはディレクトリー の変更時刻はその中にファイルが作成されるたびにリセットされるということ。もう一つは、ディレクトリーに書き込み許可がなければその中のファイル抽出は 失敗してしまうということです。
警告
内容を信頼できないtarアーカイブを、事前の内部チェック前に展開してはいけません。 ファイルが path の外側に作られる可能性があります。 例えば、 "/" で始まる絶対パスのファイル名や、2重ドット ".." で始まるパスのファイル名です。
バージョン 2.5 で追加.
メンバーをアーカイブから現在の作業ディレクトリに、そのフル名を使って、抽出します。そのファイル情報はできるだけ正確に抽出されます。 member は、ファイル名でも TarInfo オブジェクトでも構いません。 path を使って、異なるディレクトリを指定することができます。
ノート
extract() メソッドは幾つかの展開に関する問題を扱いません。 殆どの場合、 extractall() メソッドの利用を考慮するべきです。
警告
extractall() の警告(warning)を参照
アーカイブからメンバーをオブジェクトとして抽出します。 member は、ファイル名あるいは TarInfo オブジェクトです。もし member が普通のファイルであれば、ファイル風のオブジェクトを返します。もし member がリンクであれば、ファイル風のオブジェクトをリンクのターゲットから構成します。もし member が上のどれでもなければ、 :const:None が返されます。
ノート
ファイル風のオブジェクトは読み出し専用で以下のメソッドを提供します: read(), readline(), readlines(), seek(), tell().
ファイル name をアーカイブに追加します。 name は、任意のファイルタイプ (ディレクトリ、fifo、シンボリックリンク等)です。 もし arcname が与えられていれば、それはアーカイブ内のファイルの代替名を指定します。デフォールトではディレクトリは再帰的に追加されます。 これは、 recursive を False に設定することで避けることができます。 exclude を指定する場合、それは1つのファイル名を引数にとって、ブール値を返す関数である必要があります。 この関数の戻り値が True の場合、そのファイルが除外されます。 False の場合、そのファイルは追加されます。
バージョン 2.6 で変更: exclude 引数が追加されました。
TarInfo オブジェクト tarinfo をアーカイブに追加します。もし fileobj が与えられていれば、 tarinfo.size バイトがそれから読まれ、アーカイブに追加されます。 gettarinfo() を使って TarInfo オブジェクトを作成することができます。
ノート
Windows プラットフォームでは、 fileobj は、ファイルサイズに関する問題を避けるために、常に、モード 'rb' でオープンされるべきです。
TarInfo オブジェクトをファイル name あるいは (そのファイル記述子に os.fstat() を使って) ファイルオブジェクト fileobj のどちらか用に作成します。 TarInfo の属性のいくつかは、 addfile() を使って追加する前に修正することができます。 arcname がもし与えられていれば、アーカイブ内のファイルの 代替名を指定します。
この値を True にすることは、 format を USTAR_FORMAT にすることと同じです。 この値を False にすることは、 format を GNU_FORMAT にすることと同じです。
バージョン 2.4 で変更: posix のデフォルト値が False になりました.
バージョン 2.6 で撤廃: .. Use the format attribute instead. 代わりに format 属性を利用してください。
pax グローバルヘッダに含まれる key-value ペアの辞書
バージョン 2.6 で追加.
TarInfo オブジェクトは TarFile の一つのメンバーを表します。ファイルに 必要な(ファイルタイプ、ファイルサイズ、時刻、許可、所有者等のような)すべての属性を保存する他に、 そのタイプを決定するのに役に立ついくつかのメソッドを提供します。これにはファイルのデータそのものは含まれま せん 。
TarInfo オブジェクトは TarFile のメソッド getmember() 、 getmembers() および gettarinfo() によって返されます。
TarInfo オブジェクトを文字列バッファ buf から作成して返します。
バージョン 2.6 で追加: バッファが不正な場合は、 HeaderError を送出します。
TarFile オブジェクトの tarfile から、次のメンバを読み込んで、それを TarInfo オブジェクトとして返します。
バージョン 2.6 で追加.
TarInfo オブジェクトから文字列バッファを作成します。 引数についての情報は、 TarFile クラスのコンストラクタを参照してください。
バージョン 2.6 で変更: 引数が追加されました。
TarInfo オブジェクトには以下の public なデータ属性があります:
アーカイブメンバーの名前。
バイト単位でのサイズ。
最終更新時刻。
許可ビット。
ファイルタイプです。 type は普通、以下の定数: REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE のいずれかです。 TarInfo オブジェクトのタイプをもっと便利に決定するには、下記の is_*() メソッドを使って下さい。
ファイルメンバを保存した元のユーザのユーザ ID です。
ファイルメンバを保存した元のユーザのグループ ID です。
ファイルメンバを保存した元のユーザのユーザ名です。
ファイルメンバを保存した元のユーザのグループ名です。
pax 拡張ヘッダに関連付けられた、 key-value ペアの辞書。
バージョン 2.6 で追加.
TarInfo オブジェクトは便利な照会用のメソッドもいくつか提供しています:
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()
gzip 圧縮 tar アーカイブを作成してメンバー情報のいくつかを表示する方法:
import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
for tarinfo in tar:
print tarinfo.name, " は大きさが ", tarinfo.size, "バイトで ",
if tarinfo.isreg():
print "普通のファイルです。"
elif tarinfo.isdir():
print "ディレクトリです。"
else:
print "ファイル・ディレクトリ以外のものです。"
tar.close()
tarfile モジュールは、3つの tar フォーマットを作成することができます。
The POSIX.1-2001 pax format (PAX_FORMAT). 一番柔軟性があり、ほぼ制限が無いフォーマットです。 長いファイル名やリンク名、大きいファイルをサポートし、パス名をポータブルな方法で保存します。 しかし、現在のところ、全ての tar の実装が pax フォーマットを正しく扱えるわけではありません。
pax フォーマットは既存の ustar フォーマットの拡張です。 ustar では保存できない情報を追加のヘッダを利用して保存します。 pax には2種類のヘッダがあります。 1つ目は拡張ヘッダで、その次のファイルヘッダに影響します。 2つ目はグローバルヘッダで、アーカイブ全体に対して有効で、それ以降の全てのファイルに影響します。 全ての pax ヘッダの内容は、ポータブル性のために UTF-8 で保存されます。
他にも、読み込みのみサポートしている tar フォーマットが幾つかあります。
tarフォーマットはもともと、テープドライブにファイルシステムのバックアップを取る目的で設計されました。 現在、tarアーカイブはファイルを配布する場合に一般的に用いられ、ネットワークごしに送受信されます。 オリジナルのフォーマットの抱える1つの問題(ほか多くのフォーマットも同じですが)は、 文字エンコーディングが異なる環境を考慮していないことです。 例えば、通常の UTF-8 の環境で作成されたアーカイブは、非ASCII文字を含んでいた場合 Latin-1 のシステムでは正しく読み込むことができません。 非ASCII文字を含む名前(ファイル名、リンク名、ユーザー/グループ名)が破壊されます。 不幸なことに、アーカイブのエンコーディングを自動検出する方法はありません。
pax フォーマットはこの問題を解決するように設計されました。 このフォーマットは、非ASCII文字の名前を UTF-8 で保存します。 pax アーカイブを読み込むときに、この UTF-8 の名前がローカルのファイルシステムのエンコーディングに変換されます。
unicode 変換の動作は、 TarFile クラスの encoding と errors キーワード引数によって制御されます。
encoding のデフォルト値はローカルの文字エンコーディングです。 これは sys.getfilesystemencoding() と sys.getdefaultencoding() から取得されます。 読み込みモードでは、 encoding は pax フォーマット内の unicode の名前をローカルの文字エンコーディングに変換するために利用されます。 書き込みモードでは、 encoding の扱いは選択されたアーカイブフォーマットに依存します。 PAX_FORMAT の場合、入力された非ASCII文字を含む文字は UTF-8 文字列として保存する前に一旦デコードする必要があるので、そこで encoding が利用されます。 それ以外のフォーマットでは、 encoding は、入力された名前に unicode が含まれない限りは利用されません。unicodeが含まれている場合、アーカイブに保存する前に encoding でエンコードされます。
errors 引数は、 encoding を利用して変換できない文字の扱いを指定します。 利用可能な値は、 Codec 基底クラス 節でリストアップされています。 読み込みモードでは、追加の値として 'utf-8' を選択することができ、エラーが発生したときは UTF-8 を利用することができます。(これがデフォルトです) 書き込みモードでは、 errors のデフォルト値は 'strict' になっていて、名前が気づかないうちに変化することが無いようにしています。