:mod:`filecmp` --- File and Directory Comparisons

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

.. module:: filecmp

   :synopsis: Compare files efficiently.

.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>

The :mod:`filecmp` module defines functions to compare files and directories,

with various optional time/correctness trade-offs. For comparing files,

see also the :mod:`difflib` module.

The :mod:`filecmp` module defines the following functions:

.. function:: cmp(f1, f2[, shallow])

   Compare the files named *f1* and *f2*, returning ``True`` if they seem equal,

   ``False`` otherwise.

   Unless *shallow* is given and is false, files with identical :func:`os.stat`

   signatures are taken to be equal.

   Files that were compared using this function will not be compared again unless

   their :func:`os.stat` signature changes.

   Note that no external programs are called from this function, giving it

   portability and efficiency.

.. function:: cmpfiles(dir1, dir2, common[, shallow])

   Returns three lists of file names: *match*, *mismatch*, *errors*.  *match*

   contains the list of files match in both directories, *mismatch* includes the

   names of those that don't, and *errros* lists the names of files which could not

   be compared.  Files may be listed in *errors* because the user may lack

   permission to read them or many other reasons, but always that the comparison

   could not be done for some reason.

   The *common* parameter is a list of file names found in both directories. The

   *shallow* parameter has the same meaning and default value as for

   :func:`filecmp.cmp`.

Example::

   >>> import filecmp

   >>> filecmp.cmp('undoc.rst', 'undoc.rst')

   True

   >>> filecmp.cmp('undoc.rst', 'index.rst')

   False

.. _dircmp-objects:

The :class:`dircmp` class

-------------------------

:class:`dircmp` instances are built using this constructor:

.. class:: dircmp(a, b[, ignore[, hide]])

   Construct a new directory comparison object, to compare the directories *a* and

   *b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS',

   'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir,

   os.pardir]``.

   The :class:`dircmp` class provides the following methods:

   .. method:: report()

      Print (to ``sys.stdout``) a comparison between *a* and *b*.

   .. method:: report_partial_closure()

      Print a comparison between *a* and *b* and common immediate

      subdirectories.

   .. method:: report_full_closure()

      Print a comparison between *a* and *b* and common subdirectories

      (recursively).

   The :class:`dircmp` offers a number of interesting attributes that may be

   used to get various bits of information about the directory trees being

   compared.

   Note that via :meth:`__getattr__` hooks, all attributes are computed lazily,

   so there is no speed penalty if only those attributes which are lightweight

   to compute are used.

   .. attribute:: left_list

      Files and subdirectories in *a*, filtered by *hide* and *ignore*.

   .. attribute:: right_list

      Files and subdirectories in *b*, filtered by *hide* and *ignore*.

   .. attribute:: common

      Files and subdirectories in both *a* and *b*.

   .. attribute:: left_only

      Files and subdirectories only in *a*.

   .. attribute:: right_only

      Files and subdirectories only in *b*.

   .. attribute:: common_dirs

      Subdirectories in both *a* and *b*.

   .. attribute:: common_files

      Files in both *a* and *b*

   .. attribute:: common_funny

      Names in both *a* and *b*, such that the type differs between the

      directories, or names for which :func:`os.stat` reports an error.

   .. attribute:: same_files

      Files which are identical in both *a* and *b*.

   .. attribute:: diff_files

      Files which are in both *a* and *b*, whose contents differ.

   .. attribute:: funny_files

      Files which are in both *a* and *b*, but could not be compared.

   .. attribute:: subdirs

      A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.