Doc/library/filecmp.rst

   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    Compare the files in the two directories *dir1* and *dir2* whose names are
  35    given by *common*.
  36
  37    Returns three lists of file names: *match*, *mismatch*,
  38    *errors*.  *match* contains the list of files that match, *mismatch* contains
  39    the names of those that don't, and *errors* lists the names of files which
  40    could not be compared.  Files are listed in *errors* if they don't exist in
  41    one of the directories, the user lacks permission to read them or if the
  42    comparison could not be done for some other reason.
  43
  44    The *shallow* parameter has the same meaning and default value as for
  45    :func:`filecmp.cmp`.
  46
  47    For example, ``cmpfiles('a', 'b', ['c', 'd/e'])`` will compare ``a/c`` with
  48    ``b/c`` and ``a/d/e`` with ``b/d/e``.  ``'c'`` and ``'d/e'`` will each be in
  49    one of the three returned lists.
  50
  51
  52 Example::
  53
  54    >>> import filecmp
  55    >>> filecmp.cmp('undoc.rst', 'undoc.rst')
  56    True
  57    >>> filecmp.cmp('undoc.rst', 'index.rst')
  58    False
  59
  60
  61 .. _dircmp-objects:
  62
  63 The :class:`dircmp` class
  64 -------------------------
  65
  66 :class:`dircmp` instances are built using this constructor:
  67
  68
  69 .. class:: dircmp(a, b[, ignore[, hide]])
  70
  71    Construct a new directory comparison object, to compare the directories *a* and
  72    *b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS',
  73    'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir,
  74    os.pardir]``.
  75
  76    The :class:`dircmp` class provides the following methods:
  77
  78
  79    .. method:: report()
  80
  81       Print (to ``sys.stdout``) a comparison between *a* and *b*.
  82
  83
  84    .. method:: report_partial_closure()
  85
  86       Print a comparison between *a* and *b* and common immediate
  87       subdirectories.
  88
  89
  90    .. method:: report_full_closure()
  91
  92       Print a comparison between *a* and *b* and common subdirectories
  93       (recursively).
  94
  95    The :class:`dircmp` offers a number of interesting attributes that may be
  96    used to get various bits of information about the directory trees being
  97    compared.
  98
  99    Note that via :meth:`__getattr__` hooks, all attributes are computed lazily,
 100    so there is no speed penalty if only those attributes which are lightweight
 101    to compute are used.
 102
 103
 104    .. attribute:: left_list
 105
 106       Files and subdirectories in *a*, filtered by *hide* and *ignore*.
 107
 108
 109    .. attribute:: right_list
 110
 111       Files and subdirectories in *b*, filtered by *hide* and *ignore*.
 112
 113
 114    .. attribute:: common
 115
 116       Files and subdirectories in both *a* and *b*.
 117
 118
 119    .. attribute:: left_only
 120
 121       Files and subdirectories only in *a*.
 122
 123
 124    .. attribute:: right_only
 125
 126       Files and subdirectories only in *b*.
 127
 128
 129    .. attribute:: common_dirs
 130
 131       Subdirectories in both *a* and *b*.
 132
 133
 134    .. attribute:: common_files
 135
 136       Files in both *a* and *b*
 137
 138
 139    .. attribute:: common_funny
 140
 141       Names in both *a* and *b*, such that the type differs between the
 142       directories, or names for which :func:`os.stat` reports an error.
 143
 144
 145    .. attribute:: same_files
 146
 147       Files which are identical in both *a* and *b*.
 148
 149
 150    .. attribute:: diff_files
 151
 152       Files which are in both *a* and *b*, whose contents differ.
 153
 154
 155    .. attribute:: funny_files
 156
 157       Files which are in both *a* and *b*, but could not be compared.
 158
 159
 160    .. attribute:: subdirs
 161
 162       A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.
 163