1 

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

     3 =================================================

     4 

     5 .. module:: filecmp

     6    :synopsis: Compare files efficiently.

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

     8 

     9 

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

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

    12 see also the :mod:`difflib` module.

    13 

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

    15 

    16 

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

    18 

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

    20    ``False`` otherwise.

    21 

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

    23    signatures are taken to be equal.

    24 

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

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

    27 

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

    29    portability and efficiency.

    30 

    31 

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

    33 

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

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

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

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

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

    39    could not be done for some reason.

    40 

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

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

    43    :func:`filecmp.cmp`.

    44 

    45 Example::

    46 

    47    >>> import filecmp

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

    49    True

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

    51    False

    52 

    53 

    54 .. _dircmp-objects:

    55 

    56 The :class:`dircmp` class

    57 -------------------------

    58 

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

    60 

    61 

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

    63 

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

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

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

    67    os.pardir]``.

    68 

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

    70 

    71 

    72    .. method:: report()

    73 

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

    75 

    76 

    77    .. method:: report_partial_closure()

    78 

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

    80       subdirectories.

    81 

    82 

    83    .. method:: report_full_closure()

    84 

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

    86       (recursively).

    87 

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

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

    90    compared.

    91 

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

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

    94    to compute are used.

    95 

    96 

    97    .. attribute:: left_list

    98 

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

   100 

   101 

   102    .. attribute:: right_list

   103 

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

   105 

   106 

   107    .. attribute:: common

   108 

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

   110 

   111 

   112    .. attribute:: left_only

   113 

   114       Files and subdirectories only in *a*.

   115 

   116 

   117    .. attribute:: right_only

   118 

   119       Files and subdirectories only in *b*.

   120 

   121 

   122    .. attribute:: common_dirs

   123 

   124       Subdirectories in both *a* and *b*.

   125 

   126 

   127    .. attribute:: common_files

   128 

   129       Files in both *a* and *b*

   130 

   131 

   132    .. attribute:: common_funny

   133 

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

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

   136 

   137 

   138    .. attribute:: same_files

   139 

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

   141 

   142 

   143    .. attribute:: diff_files

   144 

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

   146 

   147 

   148    .. attribute:: funny_files

   149 

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

   151 

   152 

   153    .. attribute:: subdirs

   154 

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

   156