\section{\module{shutil} ---
         高レベルなファイル操作}

\declaremodule{standard}{shutil}
\modulesynopsis{コピーを含む高レベルなファイル操作。}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
% partly based on the docstrings


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

\index{file!copying}
\index{copying files}

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

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

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

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

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

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

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

\begin{funcdesc}{copy2}{src, dst}
 \function{copy()}と類似していますが、最終アクセス時間や最終更新時間も同
 様にコピーされます。これは  \UNIX{} コマンドの \program{cp}
 \programopt{-p}と同様の働きをします。
\end{funcdesc}

\begin{funcdesc}{copytree}{src, dst\optional{, symlinks}}
 \var{src}を起点としてディレクトリーに既存のものは使えません。
 存在しない親ディレクトリも含めて作成されます。
 パーミッションと時刻は \function{copystat()}関数でコピーされます。
 個々のファイルは\function{copy2()}によってコピー
 されます。If \var{symlinks}が真であれば、元のディレクトリ内の
 シンボリックリンクはコピー先のディレクトリ内へシンボリックリンクとして
 コピーされます。偽が与えられたり省略された場合は元のディレクトリ内のリ
 ンクの対象となっているファイルがコピー先のディレクトリ内へコピーされま
 す。エラーが発生したときはエラー理由のリストを持った\exception{Error}を起こします。

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

\versionchanged[コピー中にエラーが発生した場合、メッセージを出力するのではなく
\exception{Error}を起こす。]{2.3}

\versionchanged[\var{dst}を作成する際に中間のディレクトリ作成が必要な場合、
エラーを起こすのではなく作成する。
ディレクトリのパーミッションと時刻を \function{copystat()} を利用してコピーする。
]{2.5}

\end{funcdesc}

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

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

\begin{funcdesc}{move}{src, dst}
 再帰的にファイルやディレクトリを別の場所へ移動します。

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

\versionadded{2.3}
\end{funcdesc}

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

\versionadded{2.3}
\end{excdesc}

\subsection{使用例 \label{shutil-example}}

以下は前述の\function{copytree()}関数のドキュメント文字列を省略した実装
例です。
本モジュールで提供される他の関数の使い方を示しています。

\begin{verbatim}
def copytree(src, dst, symlinks=0):
    names = os.listdir(src)
    os.mkdir(dst)
    for name in names:
        srcname = os.path.join(src, name)
        dstname = os.path.join(dst, name)
        try:
            if symlinks and os.path.islink(srcname):
                linkto = os.readlink(srcname)
                os.symlink(linkto, dstname)
            elif os.path.isdir(srcname):
                copytree(srcname, dstname, symlinks)
            else:
                copy2(srcname, dstname)
        except (IOError, os.error), why:
            print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why))
\end{verbatim}
