\section{\module{filecmp} ---
         ファイルおよびディレクトリの比較}

\declaremodule{standard}{filecmp}
\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
\modulesynopsis{ファイル群を効率的に比較します。}


\module{filecmp} モジュールでは、ファイルおよびディレクトリを
比較するため、様々な時間／正確性のトレードオフに関するオプションを
備えた関数を定義しています。

\module{filecmp} モジュールでは以下の関数を定義しています:
\begin{funcdesc}{cmp}{f1, f2\optional{, shallow}}
名前が \var{f1} および \var{f2} のファイルを比較し、二つのファイルが
同じらしければ \code{True} を返し、そうでなければ \code{false} を
返します。

\var{shallow} が与えられておりかつ偽でなければ、\function{os.stat()}
の返すシグネチャが一致するファイルは同じであると見なされます。

この関数で比較されたファイルは \function{os.stat()} シグネチャが
変更されるまで再び比較されることはありません。\var{use_statcache}
を真にすると、キャッシュ無効化機構を失敗させます --- そのため、
\refmodule{statcache} のキャッシュから古いファイル stat 値が
使われます。

可搬性と効率のために、個の関数は外部プログラムを一切呼び出さないので
注意してください。
\end{funcdesc}

\begin{funcdesc}{cmpfiles}{dir1, dir2, common\optional{,
                           shallow}}
ファイル名からなる 3つのリスト: \var{match}、\var{mismatch}、
\var{errors} を返します。\var{match} には双方のディレクトリで
一致したファイルのリストが含まれ、\var{mismatch} にはそうでない
ファイル名のリストが入ります。そして \var{errors} は比較されなかった
ファイルが列挙されます。ファイルによっては、ユーザにそのファイル
を読む権限がなかったり、比較を完了することができなかった場合以外
のその他諸々の理由により、 \var{errors} に列挙されることがあります。

引数 \var{common} は両方のディレクトリにあるファイルのリストです。
引数 \var{shallow} はその意味も標準
の設定も \function{filecmp.cmp()} と同じです。
\end{funcdesc}

例:

\begin{verbatim}
>>> import filecmp
>>> filecmp.cmp('libundoc.tex', 'libundoc.tex')
True
>>> filecmp.cmp('libundoc.tex', 'lib.tex')
False
\end{verbatim}


\subsection{\protect\class{dircmp} クラス \label{dircmp-objects}}

\class{dircmp} のインスタンスは以下のコンストラクタで生成されます:

\begin{classdesc}{dircmp}{a, b\optional{, ignore\optional{, hide}}}
ディレクトリ \var{a} および \var{b} を比較するための新しいディレクトリ
比較オブジェクトを生成します。\var{ignore} は比較の際に無視する
ファイル名のリストで、標準の設定では \code{['RCS', 'CVS', 'tags']}
です。\var{hide} は表示しない名前のリストで、標準の設定では
\code{[os.curdir, os.pardir]} です。
\end{classdesc}

\class{dircmp} クラスは以下のメソッドを提供しています:

\begin{methoddesc}[dircmp]{report}{}
\var{a} および \var{b} の間の比較結果を (\code{sys.stdout} に) 出力します。
\end{methoddesc}

\begin{methoddesc}[dircmp]{report_partial_closure}{}
\var{a} および \var{b} およびそれらの直下にある共通のサブディレクトリ
間での比較結果を出力します。
\end{methoddesc}

\begin{methoddesc}[dircmp]{report_full_closure}{}
\var{a} および \var{b} およびそれらの共通のサブディレクトリ間での
比較結果を (再帰的に比較して) 出力します。
\end{methoddesc}

\class{dircmp} は、比較しているディレクトリツリーに関する様々な
種類の情報を取得するために使えるような、多くの興味深い属性を提供
しています。

\method{__getattr__()} フックを経由すると、全ての属性を
のろのろと計算するため、速度上のペナルティを受けないのは
計算処理の軽い属性を使ったときだけなので注意してください。

\begin{memberdesc}[dircmp]{left_list}
\var{a} にあるファイルおよびサブディレクトリです。
\var{hide} および \var{ignore} でフィルタされています。
\end{memberdesc}

\begin{memberdesc}[dircmp]{right_list}
\var{b} にあるファイルおよびサブディレクトリです。
\var{hide} および \var{ignore} でフィルタされています。
\end{memberdesc}

\begin{memberdesc}[dircmp]{common}
\var{a} および \var{b} の両方にあるファイルおよびサブディレクトリです。
\end{memberdesc}

\begin{memberdesc}[dircmp]{left_only}
\var{a} だけにあるファイルおよびサブディレクトリです。
\end{memberdesc}

\begin{memberdesc}[dircmp]{right_only}
\var{b} だけにあるファイルおよびサブディレクトリです。
\end{memberdesc}

\begin{memberdesc}[dircmp]{common_dirs}
\var{a} および \var{b} の両方にあるサブディレクトリです。
\end{memberdesc}

\begin{memberdesc}[dircmp]{common_files}
\var{a} および \var{b} の両方にあるファイルです。
\end{memberdesc}

\begin{memberdesc}[dircmp]{common_funny}
\var{a} および \var{b} の両方にあり、ディレクトリ間で
タイプが異なるか、\function{os.stat()} がエラーを報告するような
名前です。
\end{memberdesc}

\begin{memberdesc}[dircmp]{same_files}
\var{a} および \var{b} 両方にあり、一致するファイルです。
\end{memberdesc}

\begin{memberdesc}[dircmp]{diff_files}
\var{a} および \var{b} 両方にあるが、一致しないファイルです。
\end{memberdesc}

\begin{memberdesc}[dircmp]{funny_files}
\var{a} および \var{b} 両方にあるが、比較されなかったファイルです。
\end{memberdesc}

\begin{memberdesc}[dircmp]{subdirs}
\member{common_dirs} のファイル名を \class{dircmp} オブジェクトに
対応付けた辞書です。
\end{memberdesc}
