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

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

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

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

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

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

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

   If *shallow* is true and the "os.stat()" signatures (file type,
   size, and modification time) of both files are identical, the files
   are taken to be equal.

   Otherwise, the files are treated as different if their sizes or
   contents differ.

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

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

filecmp.cmpfiles(dir1, dir2, common, shallow=True)

   *dir1* と *dir2* ディレクトリの中の、*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
   分解能未満でのファイル変更後にすぐに比較するような場合に有用です。

   バージョン 3.4 で追加.


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

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

   ディレクトリ *a* および *b* を比較するための新しいディレクトリ比較
   オブジェクトを生成します。 *ignore* は比較の際に無視するファイル名
   のリストで、標準の設定では "filecmp.DEFAULT_IGNORES" です。 *hide*
   は表示しない名前のリストで、標準の設定では "[os.curdir, os.pardir]"
   です。

   "dircmp" クラスは、 "filecmp.cmp()" で説明されているような *浅い*
   比較を行うことによりファイルを比較します。

   "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

      A dictionary mapping names in "common_dirs" to "dircmp"
      instances (or MyDirCmp instances if this instance is of type
      MyDirCmp, a subclass of "dircmp").

      バージョン 3.10 で変更: Previously entries were always "dircmp"
      instances. Now entries are the same type as *self*, if *self* is
      a subclass of "dircmp".

filecmp.DEFAULT_IGNORES

   バージョン 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) 
