Source

python-doc-ja / library / tarfile.rst

Full commit

:mod:`tarfile` --- tar アーカイブファイルを読み書きする

:mod:`tarfile` モジュールは、gzipやbz2圧縮されたものも含めて、tarアーカイブの読み書きができます。 (:file:`.zip` ファイルの読み書きは :mod:`zipfile` モジュールで可能です。)

いくつかの事実と外観:

  • POSIX.1-1988 (ustar) フォーマットの読み書きをサポートしています。
  • longname, longlink 拡張を含めた、GNU tarフォーマットの読み書きをサポートしています。 sparse 拡張は読み込みのみサポートしています。
  • POSIX.1-2001 (pax) フォーマットの読み書きをサポートしています。
  • ディレクトリ、普通のファイル、ハードリンク、シンボリックリンク、fifo、キャラクタデバイスおよびブロックデバイスを処理します。また、タイムスタンプ、 アクセス許可およびオーナーのようなファイル情報の取得および保存が可能です。

tar アーカイブを読んだり、書いたりするためのクラスです。このクラスを直接使わず、代わりに :func:`tarfile.open` を使ってください。 :ref:`tarfile-objects` を参照してください。

zipfile -風なインターフェースを持つ tar アーカイブへの制限されたアクセスのためのクラスです。詳細は zipfile のドキュメントを参照してください。 compression は、以下の定数のどれかでなければなりません:

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

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

TarFile オブジェクト

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

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

name はアーカイブのパス名。 fileobj が渡された場合は省略可能。 その場合、ファイルオブジェクトの :attr:`name` 属性があれば、それを利用します。

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

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

Note

fileobj は、 :class:`TarFile` をクローズする時にクローズされません。

format はアーカイブのフォーマットを制御します。 モジュールレベルで定義されている、 :const:`USTAR_FORMAT`, :const:`GNU_FORMAT`, :const:`PAX_FORMAT` のいずれかである必要があります。

tarinfo 引数を利用して、デフォルトの :class:`TarInfo` クラスを別のクラスで置き換えられます。

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

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

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

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

encodingerrors 引数は、文字列と unicode オブジェクトとの間の相互変換方法を指定します。 デフォルトの設定で、ほとんどのユーザーでうまく動作するでしょう。 詳しい情報は、 :ref:`tar-unicode` 節を参照してください。

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

TarInfo オブジェクト

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

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

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

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

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

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

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

tarアーカイブの一部を、リストの代わりにジェネレータ関数を利用して、 :meth:`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()

サポートされる tar のフォーマット

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

  • POSIX.1-1988 ustar format (:const:`USTAR_FORMAT`). ファイル名の長さは256文字までで、 リンク名の長さは100文字までです。最大のファイルサイズは8GBです。 このフォーマットは古くて制限が多いですが、広くサポートされています。
  • GNU tar format (:const:`GNU_FORMAT`). 長いファイル名とリンク名、8GBを超えるファイルやスパース(sparse)ファイルをサポートしています。 これは GNU/Linux システムにおいて、デ・ファクト・スタンダードになっています。 :mod:`tarfile` モジュールは長いファイル名を完全にサポートしています。 スパースファイルは読み込みのみサポートしています。
  • The POSIX.1-2001 pax format (:const:`PAX_FORMAT`). 一番柔軟性があり、ほぼ制限が無いフォーマットです。 長いファイル名やリンク名、大きいファイルをサポートし、パス名をポータブルな方法で保存します。 しかし、現在のところ、全ての tar の実装が pax フォーマットを正しく扱えるわけではありません。

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

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

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

Unicode に関する問題

tarフォーマットはもともと、テープドライブにファイルシステムのバックアップを取る目的で設計されました。 現在、tarアーカイブはファイルを配布する場合に一般的に用いられ、ネットワークごしに送受信されます。 オリジナルのフォーマットの抱える1つの問題(ほか多くのフォーマットも同じですが)は、 文字エンコーディングが異なる環境を考慮していないことです。 例えば、通常の UTF-8 の環境で作成されたアーカイブは、非ASCII文字を含んでいた場合 Latin-1 のシステムでは正しく読み込むことができません。 非ASCII文字を含む名前(ファイル名、リンク名、ユーザー/グループ名)が破壊されます。 不幸なことに、アーカイブのエンコーディングを自動検出する方法はありません。

pax フォーマットはこの問題を解決するように設計されました。 このフォーマットは、非ASCII文字の名前を UTF-8 で保存します。 pax アーカイブを読み込むときに、この UTF-8 の名前がローカルのファイルシステムのエンコーディングに変換されます。

unicode 変換の動作は、 :class:`TarFile` クラスの encodingerrors キーワード引数によって制御されます。

encoding のデフォルト値はローカルの文字エンコーディングです。 これは :func:`sys.getfilesystemencoding`:func:`sys.getdefaultencoding` から取得されます。 読み込みモードでは、 encoding は pax フォーマット内の unicode の名前をローカルの文字エンコーディングに変換するために利用されます。 書き込みモードでは、 encoding の扱いは選択されたアーカイブフォーマットに依存します。 :const:`PAX_FORMAT` の場合、入力された非ASCII文字を含む文字は UTF-8 文字列として保存する前に一旦デコードする必要があるので、そこで encoding が利用されます。 それ以外のフォーマットでは、 encoding は、入力された名前に unicode が含まれない限りは利用されません。unicodeが含まれている場合、アーカイブに保存する前に encoding でエンコードされます。

errors 引数は、 encoding を利用して変換できない文字の扱いを指定します。 利用可能な値は、 :ref:`codec-base-classes` 節でリストアップされています。 読み込みモードでは、追加の値として 'utf-8' を選択することができ、エラーが発生したときは UTF-8 を利用することができます。(これがデフォルトです) 書き込みモードでは、 errors のデフォルト値は 'strict' になっていて、名前が気づかないうちに変化することが無いようにしています。