1 :mod:`filecmp` --- File and Directory Comparisons 2 ================================================= 3 4 .. module:: filecmp 5 :synopsis: Compare files efficiently. 6 7 .. sectionauthor:: Moshe Zadka <moshez (a] zadka.site.co.il> 8 9 **Source code:** :source:`Lib/filecmp.py` 10 11 -------------- 12 13 The :mod:`filecmp` module defines functions to compare files and directories, 14 with various optional time/correctness trade-offs. For comparing files, 15 see also the :mod:`difflib` module. 16 17 The :mod:`filecmp` module defines the following functions: 18 19 20 .. function:: cmp(f1, f2, shallow=True) 21 22 Compare the files named *f1* and *f2*, returning ``True`` if they seem equal, 23 ``False`` otherwise. 24 25 If *shallow* is true, files with identical :func:`os.stat` signatures are 26 taken to be equal. Otherwise, the contents of the files are compared. 27 28 Note that no external programs are called from this function, giving it 29 portability and efficiency. 30 31 This function uses a cache for past comparisons and the results, 32 with cache entries invalidated if the :func:`os.stat` information for the 33 file changes. The entire cache may be cleared using :func:`clear_cache`. 34 35 36 .. function:: cmpfiles(dir1, dir2, common, shallow=True) 37 38 Compare the files in the two directories *dir1* and *dir2* whose names are 39 given by *common*. 40 41 Returns three lists of file names: *match*, *mismatch*, 42 *errors*. *match* contains the list of files that match, *mismatch* contains 43 the names of those that don't, and *errors* lists the names of files which 44 could not be compared. Files are listed in *errors* if they don't exist in 45 one of the directories, the user lacks permission to read them or if the 46 comparison could not be done for some other reason. 47 48 The *shallow* parameter has the same meaning and default value as for 49 :func:`filecmp.cmp`. 50 51 For example, ``cmpfiles('a', 'b', ['c', 'd/e'])`` will compare ``a/c`` with 52 ``b/c`` and ``a/d/e`` with ``b/d/e``. ``'c'`` and ``'d/e'`` will each be in 53 one of the three returned lists. 54 55 56 .. function:: clear_cache() 57 58 Clear the filecmp cache. This may be useful if a file is compared so quickly 59 after it is modified that it is within the mtime resolution of 60 the underlying filesystem. 61 62 .. versionadded:: 3.4 63 64 65 .. _dircmp-objects: 66 67 The :class:`dircmp` class 68 ------------------------- 69 70 .. class:: dircmp(a, b, ignore=None, hide=None) 71 72 Construct a new directory comparison object, to compare the directories *a* 73 and *b*. *ignore* is a list of names to ignore, and defaults to 74 :attr:`filecmp.DEFAULT_IGNORES`. *hide* is a list of names to hide, and 75 defaults to ``[os.curdir, os.pardir]``. 76 77 The :class:`dircmp` class compares files by doing *shallow* comparisons 78 as described for :func:`filecmp.cmp`. 79 80 The :class:`dircmp` class provides the following methods: 81 82 .. method:: report() 83 84 Print (to :data:`sys.stdout`) a comparison between *a* and *b*. 85 86 .. method:: report_partial_closure() 87 88 Print a comparison between *a* and *b* and common immediate 89 subdirectories. 90 91 .. method:: report_full_closure() 92 93 Print a comparison between *a* and *b* and common subdirectories 94 (recursively). 95 96 The :class:`dircmp` class offers a number of interesting attributes that may be 97 used to get various bits of information about the directory trees being 98 compared. 99 100 Note that via :meth:`__getattr__` hooks, all attributes are computed lazily, 101 so there is no speed penalty if only those attributes which are lightweight 102 to compute are used. 103 104 105 .. attribute:: left 106 107 The directory *a*. 108 109 110 .. attribute:: right 111 112 The directory *b*. 113 114 115 .. attribute:: left_list 116 117 Files and subdirectories in *a*, filtered by *hide* and *ignore*. 118 119 120 .. attribute:: right_list 121 122 Files and subdirectories in *b*, filtered by *hide* and *ignore*. 123 124 125 .. attribute:: common 126 127 Files and subdirectories in both *a* and *b*. 128 129 130 .. attribute:: left_only 131 132 Files and subdirectories only in *a*. 133 134 135 .. attribute:: right_only 136 137 Files and subdirectories only in *b*. 138 139 140 .. attribute:: common_dirs 141 142 Subdirectories in both *a* and *b*. 143 144 145 .. attribute:: common_files 146 147 Files in both *a* and *b*. 148 149 150 .. attribute:: common_funny 151 152 Names in both *a* and *b*, such that the type differs between the 153 directories, or names for which :func:`os.stat` reports an error. 154 155 156 .. attribute:: same_files 157 158 Files which are identical in both *a* and *b*, using the class's 159 file comparison operator. 160 161 162 .. attribute:: diff_files 163 164 Files which are in both *a* and *b*, whose contents differ according 165 to the class's file comparison operator. 166 167 168 .. attribute:: funny_files 169 170 Files which are in both *a* and *b*, but could not be compared. 171 172 173 .. attribute:: subdirs 174 175 A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` 176 objects. 177 178 .. attribute:: DEFAULT_IGNORES 179 180 .. versionadded:: 3.4 181 182 List of directories ignored by :class:`dircmp` by default. 183 184 185 Here is a simplified example of using the ``subdirs`` attribute to search 186 recursively through two directories to show common different files:: 187 188 >>> from filecmp import dircmp 189 >>> def print_diff_files(dcmp): 190 ... for name in dcmp.diff_files: 191 ... print("diff_file %s found in %s and %s" % (name, dcmp.left, 192 ... dcmp.right)) 193 ... for sub_dcmp in dcmp.subdirs.values(): 194 ... print_diff_files(sub_dcmp) 195 ... 196 >>> dcmp = dircmp('dir1', 'dir2') # doctest: +SKIP 197 >>> print_diff_files(dcmp) # doctest: +SKIP 198 199
