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

バージョン2.3 以降で新規追加された 仕様です。

`tarfile` モジュールは、tar アーカイブを読んで作成することができるようにします。 いくつかの事実と外観：

- `gzip` と `bzip2` で圧縮されたアーカイブを読み書きします。
- POSIX 1003.1-1990 準拠あるいは GNU tar 互換のアーカイブを作成します。
- GNU tar 拡張機能 長い名前、 longlink および sparse を読みます。
- GNU tar 拡張機能を使って、無制限長さのパス名を保存します。
- ディレクトリ、普通のファイル、ハードリンク、シンボリックリンク、fifo、 キャラクタデバイスおよびブロックデバイスを処理します。また、タイムスタンプ、 アクセス許可およびオーナーのようなファイル情報の取得および保存が可能です。
- テープデバイスを取り扱うことができます。

`open`( | [name[, mode [, fileobj[, bufsize]]]])

  パス名 nameに `TarFile` オブジェクトを返します。 `TarFile` オブジェクトに関する詳細な情報については、 TarFile オブジェクト (セクション 7.19.1)を見て下さい。

  mode has to be a string of the form `'filemode[:compression]'`, it defaults to `'r'`. Here is a full list of mode combinations: mode は、`'ファイルモード[:圧縮]'`の形の文字列でなければならず、 そのデフォールトは `'r'`です。以下にモードの組み合わせの完全な一覧を示します。

  mode | 動作
  --- | ---
  `'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でオープンされた ファイルオブジェクトの代替として使うことができます。

  特別な目的のために、modeの2番目のフォーマット: `'ファイルモード|[圧縮]'` があります。`open` は、そのデータを ブロックのストリームとして処理する `TarFile` オブジェクトを返します。 ランダムシーキングはそのファイルにはなされません。もし fileobj が与えられていれば、 それは、それぞれ `read()`、`write()` メソッドを持つ、任意の オブジェクトで構いません。 bufsize は、ブロックサイズを指定し、デフォールトでは `20 * 512` バイト です。例えば `sys.stdin` とソケットファイルオブジェクトやテーブデバイスの 組み合わせでは、これを変更して使って下さい。 しかし、そのような `TarFile` オブジェクトには、ランダムにアクセスされることを 許さないという制限があります、 例 (セクション 7.19.3)を見て下さい。 現在可能なモードは：

  mode | 動作
  --- | ---
  `'r|'` | 非圧縮 tar ブロックの ストリーム を読み込みにオープンします。
  `'r|gz'` | gzip 圧縮 ストリームを読み込みにオープンします。
  `'r|bz2'` | bzip2 圧縮 ストリーム を読み込みにオープンします。
  `'w|'` | 非圧縮 ストリームを書き込みにオープンします。
  `'w|gz'` | gzip 圧縮 ストリーム を書き込みにオープンします。
  `'w|bz2'` | bzip2 圧縮 ストリームを書き込みにオープンします。

class `TarFile`
  tar アーカイブを読んだり、書いたりするためのクラスです。このクラスを 直接使わないで下さい、その代わりに `open()` を使った方が良いです。 TarFile オブジェクト (セクション 7.19.1)を見て下さい。

`is_tarfile`( | name)

  もし nameが tar アーカイブファイルであれば、`True`を返し、 その `tarfile` モジュールで読むことができます。

class `TarFileCompat`( | filename[, mode[, compression]])

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

  `TAR_PLAIN`
    非圧縮 tar アーカイブのための定数。
  `TAR_GZIPPED`
    `gzip`圧縮 tar アーカイブのための定数。

exception `TarError`
  すべての `tarfile` 例外のための基本クラスです。

exception `ReadError`
  tar アーカイブがオープンされた時、`tarfile` モジュールで操作 できないか、あるいは何か無効であるとき発生します。

exception `CompressionError`
  圧縮方法がサポートされていないか、あるいはデータを正しくデコードできない 時に発生します。

exception `StreamError`
  ストリーム風の `TarFile` オブジェクトで典型的な制限の ために発生します。

exception `ExtractError`
  `extract()`を使った時、もし`TarFile.errorlevel``== 2` の フェータルでない エラーに対してだけ発生します。

参考資料:

`zipfile`モジュール:
  `zipfile` 標準モジュールのドキュメント。.

GNU tar マニュアル、標準セクション
  GNU tar 拡張機能を含む、 tar アーカイブファイルのためのドキュメント。