"filecmp" --- ファイルとディレクトリの比較
******************************************

**ソースコード:** Lib/filecmp.py

======================================================================

"filecmp" モジュールはファイルとディレクトリを比較する関数を定義してい
ます。 オプションによって、処理時間と正確性のさまざまなバランスを選べ
ます。 ファイルの比較については "difflib" モジュールも参照してください
。

"filecmp" モジュールは以下の関数を定義しています:

filecmp.cmp(f1, f2, shallow=True)

   名前が *f1* および *f2* のファイルを比較し、二つのファイルが同じら
   しければ "True" を返し、そうでなければ "False" を返します。

   *shallow* が真で、両方のファイルの "os.stat()" による特徴 (ファイル
   の種類、サイズ、更新時刻) が同一であれば、ファイルは同じとみなされ
   ます。

   それ以外の場合は、サイズまたは内容が異なればファイルを異なるものと
   して扱います。

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

   この関数は過去の比較と結果のキャッシュを使用します。ファイルの
   "os.stat()" 情報が変更された場合、キャッシュの項目は無効化されます
   。"clear_cache()" を使用して全キャッシュを削除することが出来ます。

filecmp.cmpfiles(a, b, common, shallow=True)

   ディレクトリ *a* と *b* の間で、*common* に名前を指定したファイルを
   比較します。

   ファイル名からなる3つのリスト: *match*, *mismatch*, *errors* を返し
   ます。*match* には双方のディレクトリで一致したファイルのリストが含
   まれ、*mismatch* にはそうでないファイル名のリストが入ります。そして
   *errors* は比較されなかったファイルが列挙されます。*errors* になる
   のは、片方あるいは両方のディレクトリに存在しなかった、ユーザーにそ
   のファイルを読む権限がなかった、その他何らかの理由で比較を完了する
   ことができなかった場合です。

   引数 *shallow* はその意味も標準の設定も "filecmp.cmp()" と同じです
   。

   例えば、"cmpfiles('a', 'b', ['c', 'd/e'])" は "a/c" を "b/c" と、
   "a/d/e" を "b/d/e" と、それぞれ比較します。"'c'" と "'d/e'" はそれ
   ぞれ、返される3つのリストのいずれかに登録されます。

filecmp.clear_cache()

   filecmp のキャッシュをクリアします。背後のファイルシステムの mtime
   分解能未満でのファイル変更後にすぐに比較するような場合に有用です。

   Added in version 3.4.


"dircmp" クラス
===============

class filecmp.dircmp(a, b, ignore=None, hide=None, *, shallow=True)

   ディレクトリ *a* と *b* を比較する、新しいディレクトリ比較オブジェ
   クトを作成します。 *ignore* は無視する名前のリストで、デフォルトは
   "filecmp.DEFAULT_IGNORES" です。 *hide* は隠す名前のリストで、デフ
   ォルトは "[os.curdir, os.pardir]" です。

   "dircmp" クラスは *shallow* パラメータを使い、デフォルトでは
   "filecmp.cmp()" で説明した浅い比較を行います。

   バージョン 3.13 で変更: *shallow* パラメータが追加されました。

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

   report()

      *a* と *b* の比較を ("sys.stdout" に) 表示します。

   report_partial_closure()

      *a* および *b* およびそれらの直下にある共通のサブディレクトリ間
      での比較結果を出力します。

   report_full_closure()

      *a* および *b* およびそれらの共通のサブディレクトリ間での比較結
      果を (再帰的に比較して) 出力します。

   "dircmp" クラスには、比較するディレクトリツリーについてさまざまな情
   報を取得できる便利な属性が用意されています。

   "__getattr__()" フックによって、すべての属性は必要になるまで計算さ
   れません。 そのため計算が軽い属性だけを使う場合、重い計算による速度
   の低下はありません。

   left

      ディレクトリ *a*  です。

   right

      ディレクトリ *b*  です。

   left_list

      *a* にあるファイルおよびサブディレクトリです。*hide* および
      *ignore* でフィルタされています。

   right_list

      *b* にあるファイルおよびサブディレクトリです。*hide* および
      *ignore* でフィルタされています。

   common

      *a* および *b* の両方にあるファイルおよびサブディレクトリです。

   left_only

      *a* だけにあるファイルおよびサブディレクトリです。

   right_only

      *b* だけにあるファイルおよびサブディレクトリです。

   common_dirs

      *a* および *b* の両方にあるサブディレクトリです。

   common_files

      *a* および *b* の両方にあるファイルです。

   common_funny

      *a* および *b* の両方にあり、ディレクトリ間でタイプが異なるか、
      "os.stat()" がエラーを報告するような名前です。

   same_files

      クラスのファイル比較オペレータを用いて *a* と *b* の両方において
      同一のファイルです。

   diff_files

      *a* と *b* の両方に存在し、クラスのファイル比較オペレータに基づ
      いて内容が異なるファイルです。

   funny_files

      *a* と *b* の両方に存在するものの、比較できなかったファイルです
      。

   subdirs

      "common_dirs" 内の名前を "dircmp" インスタンスに対応付ける辞書で
      す (このインスタンスの型が "dircmp" のサブクラス "MyDirCmp" であ
      れば、値も "MyDirCmp" インスタンスになります)。

      バージョン 3.10 で変更: 以前は各項目が常に "dircmp" インスタンス
      でした。 現在は *self* が "dircmp" のサブクラスのインスタンスで
      あれば、各項目も *self* と同じ型になります。

filecmp.DEFAULT_IGNORES

   Added in version 3.4.

   デフォルトで "dircmp" に無視されるディレクトリのリストです。

これは "subdirs" 属性を使用して 2 つのディレクトリを再帰的に探索して、
共通の異なるファイルを示すための単純化された例です:

   >>> from filecmp import dircmp
   >>> def print_diff_files(dcmp):
   ...     for name in dcmp.diff_files:
   ...         print("diff_file %s found in %s and %s" % (name, dcmp.left,
   ...               dcmp.right))
   ...     for sub_dcmp in dcmp.subdirs.values():
   ...         print_diff_files(sub_dcmp)
   ...
   >>> dcmp = dircmp('dir1', 'dir2')
   >>> print_diff_files(dcmp)
