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