/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
 10The :mod:`filecmp` module defines functions to compare files and directories,
 11with various optional time/correctness trade-offs. For comparing files,
 12see also the :mod:`difflib` module.
 13
 14The :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
 52Example::
 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
 63The :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