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    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