Debian Codegraph @

Doc/library/filecmp.rst

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