# 26 `shutil` -- 高レベルなファイル操作

`shutil`モジュールはファイルやファイルの収集に関する多くの高レベ ルな操作方法を提供します。特にファイルのコピーや削除のための関数が用意さ れています。

注意: MacOSにおいてはリソースフォークや他のメタデータは取り扱う ことができません。

つまり、ファイルをコピーする際にこれらのリソースは失われたり、ファイルタ イプや作成者コードは正しく認識されないことを意味します。

`copyfile`( | src, dst)

  srcで指定されたファイル内容をdstで指定されたファイルへとコ ピーします。 コピー先は書き込み可能である必要があります。そうでなければ `IOError`を発生します。 もしdstが存在したら、置き換えられます。 キャラクタやブロックデバイス、パイプ等の特別なファイルはこの関数ではコ ピーできません。 srcとdstにはパス名を文字列で与えられます。

`copyfileobj`( | fsrc, fdst[, length])

  ファイル形式のオブジェクトfsrcの内容をfdstへコピーします。 整数値lengthはバッファサイズを表します。特に負のlengthは チャンク内のソースデータを繰り返し操作することなくコピーします。 つまり標準ではデータは制御不能なメモリ消費を避けるためにチャンク内 に読み込まれます。

`copymode`( | src, dst)

  srcからdstへパーミッションをコピーします。ファイル内容や所 有者、グループは影響を受けません。 srcとdstには文字列としてパス名を与えられます。

`copystat`( | src, dst)

  srcからdstへパーミッション最終アクセス時間、最終更新時間を コピーします。ファイル内容や所有者、グループは影響を受けません。 srcとdstには文字列としてパス名を与えられます。

`copy`( | src, dst)

  ファイルsrcをファイルまたはディレクトリdistへコピーします。 もし、dstがディレクトリであればファイル名はsrcと同じものが 指定されたディレクトリ内に作成（または上書き）されます。 パーミッションはコピーされます。 srcとdstには文字列としてパス名を与えられます。

`copy2`( | src, dst)

  `copy()`と類似していますが、最終アクセス時間や最終更新時間も同 様にコピーされます。これは Unix コマンドの cp -pと同様の働きをします。

`copytree`( | src, dst[, symlinks])

  srcを起点としてディレクトリツリー全体を再帰的にコピーします。 dstで指定されたディレクトリは既存のものではなく新規に作成されるも のでなくてはなりません。個々のファイルは`copy2()`によってコピー されます。If symlinksが真であれば、元のディレクトリ内の シンボリックリンクはコピー先のディレクトリ内へシンボリックリンクとして コピーされます。偽が与えられたり省略された場合は元のディレクトリ内のリ ンクの対象となっているファイルがコピー先のディレクトリ内へコピーされま す。エラーが発生したときはエラー理由のリストを持った例外を引き起こします。

  この関数のソースコードは道具としてよりも使用例として捉えられるべきでしょう。

  バージョン 2.3 で 変更 された仕様: コピー中にエラーが発生した場合、メッセージを出力するのではなく 例外を引き起こすように変更。

`rmtree`( | path[, ignore_errors[, onerror]])

  ディレクトリツリー全体を削除します。もしignore_errorsが真であれば 削除に失敗したことによるエラーは無視され、偽が与えられたり省略された場 合はこれらのエラーはonerrorで与えられたハンドラを呼び出して処理 され、これが省略された場合は例外を引き起こします。

  onerrorが与えられた場合、それは3つのパラメータfunction, pathおよびexcinfoを受け入れて呼び出し可能のものでなくてはな りません。最初のパラメータfunctionは例外を引き起こす関数で `os.listdir()`、`os.remove()`または `os.rmdir()`が用いられるでしょう。 二番目のパラメータはpathはfunctionへ渡らせるパス名です。 三番目のパラメータexcinfoは`sys.exc_info()`で返されるよ うな例外情報になるでしょう。onerrorが引き起こす例外はキャッチでき ません。

`move`( | src, dst)

  再帰的にファイルやディレクトリを別の場所へ移動します。

  もし移動先が現在のファイルシステム上であれば単純に名前を変更します。 そうでない場合はコピーを行い、その後コピー元は削除されます。

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

exception `Error`
  この例外は複数ファイルの操作を行っているときに生じる例外をまとめたもの です。`copytree`に対しては例外の引数は3つのタプル(srcname, dstname, exception)からなるリストです。

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