# 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 は `'filemode[:compression]'` の形式をとる文字列で なければなりません．デフォルトの値は `'r'` です．以下に modeのとりうる組み合わせ全てを示します．

  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` オブジェクトになります．この場合，ファイルに対して ランダムな seek を行えなくなります．fileobj を指定する場合， `read()`および`write()` メソッドを持つ任意のオブジェクトに できます． bufsize にはブロックサイズを指定します．デフォルトは `20 * 512` バイトです。`sys.stdin` ，ソケットファイル オブジェクト，テーブデバイスと組み合わせる場合にはこの形式を 使ってください．ただし，このような`TarFile` オブジェクトには ランダムアクセスを行えないという制限があります． 例 (セクション 7.19.3)を参照してください。 現在可能なモードは：

  モード | 動作
  --- | ---
  `'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 アーカイブファイルであり，`tarfile` モジュールで読み出せる場合に`True`を返します．

クラス `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 アーカイブファイルのためのドキュメント。