2 :mod:`filecmp` --- File and Directory Comparisons
3 =================================================
6 :synopsis: Compare files efficiently.
7 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
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.
14 The :mod:`filecmp` module defines the following functions:
17 .. function:: cmp(f1, f2[, shallow])
19 Compare the files named *f1* and *f2*, returning ``True`` if they seem equal,
22 Unless *shallow* is given and is false, files with identical :func:`os.stat`
23 signatures are taken to be equal.
25 Files that were compared using this function will not be compared again unless
26 their :func:`os.stat` signature changes.
28 Note that no external programs are called from this function, giving it
29 portability and efficiency.
32 .. function:: cmpfiles(dir1, dir2, common[, shallow])
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.
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
48 >>> filecmp.cmp('undoc.rst', 'undoc.rst')
50 >>> filecmp.cmp('undoc.rst', 'index.rst')
56 The :class:`dircmp` class
57 -------------------------
59 :class:`dircmp` instances are built using this constructor:
62 .. class:: dircmp(a, b[, ignore[, hide]])
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,
69 The :class:`dircmp` class provides the following methods:
74 Print (to ``sys.stdout``) a comparison between *a* and *b*.
77 .. method:: report_partial_closure()
79 Print a comparison between *a* and *b* and common immediate
83 .. method:: report_full_closure()
85 Print a comparison between *a* and *b* and common subdirectories
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
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
97 .. attribute:: left_list
99 Files and subdirectories in *a*, filtered by *hide* and *ignore*.
102 .. attribute:: right_list
104 Files and subdirectories in *b*, filtered by *hide* and *ignore*.
107 .. attribute:: common
109 Files and subdirectories in both *a* and *b*.
112 .. attribute:: left_only
114 Files and subdirectories only in *a*.
117 .. attribute:: right_only
119 Files and subdirectories only in *b*.
122 .. attribute:: common_dirs
124 Subdirectories in both *a* and *b*.
127 .. attribute:: common_files
129 Files in both *a* and *b*
132 .. attribute:: common_funny
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.
138 .. attribute:: same_files
140 Files which are identical in both *a* and *b*.
143 .. attribute:: diff_files
145 Files which are in both *a* and *b*, whose contents differ.
148 .. attribute:: funny_files
150 Files which are in both *a* and *b*, but could not be compared.
153 .. attribute:: subdirs
155 A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.