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 | |
| 8 | |
| 9 | The :mod:`filecmp` module defines functions to compare files and directories, |
Georg Brandl | 9afde1c | 2007-11-01 20:32:30 +0000 | [diff] [blame] | 10 | with various optional time/correctness trade-offs. For comparing files, |
| 11 | see also the :mod:`difflib` module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 12 | |
| 13 | The :mod:`filecmp` module defines the following functions: |
| 14 | |
| 15 | |
Georg Brandl | 71515ca | 2009-05-17 12:29:12 +0000 | [diff] [blame] | 16 | .. function:: cmp(f1, f2, shallow=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | |
| 18 | Compare the files named *f1* and *f2*, returning ``True`` if they seem equal, |
| 19 | ``False`` otherwise. |
| 20 | |
| 21 | Unless *shallow* is given and is false, files with identical :func:`os.stat` |
| 22 | signatures are taken to be equal. |
| 23 | |
| 24 | Files that were compared using this function will not be compared again unless |
| 25 | their :func:`os.stat` signature changes. |
| 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 | Example:: |
| 52 | |
| 53 | >>> import filecmp |
| 54 | >>> filecmp.cmp('undoc.rst', 'undoc.rst') |
| 55 | True |
| 56 | >>> filecmp.cmp('undoc.rst', 'index.rst') |
| 57 | False |
| 58 | |
| 59 | |
| 60 | .. _dircmp-objects: |
| 61 | |
| 62 | The :class:`dircmp` class |
| 63 | ------------------------- |
| 64 | |
| 65 | :class:`dircmp` instances are built using this constructor: |
| 66 | |
| 67 | |
Georg Brandl | 71515ca | 2009-05-17 12:29:12 +0000 | [diff] [blame] | 68 | .. class:: dircmp(a, b, ignore=None, hide=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
| 70 | Construct a new directory comparison object, to compare the directories *a* and |
| 71 | *b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS', |
| 72 | 'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir, |
| 73 | os.pardir]``. |
| 74 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 75 | The :class:`dircmp` class provides the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | |
| 77 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 78 | .. method:: report() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 80 | Print (to ``sys.stdout``) a comparison between *a* and *b*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 81 | |
| 82 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 83 | .. method:: report_partial_closure() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 85 | Print a comparison between *a* and *b* and common immediate |
| 86 | subdirectories. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | |
| 88 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 89 | .. method:: report_full_closure() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 91 | Print a comparison between *a* and *b* and common subdirectories |
| 92 | (recursively). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 93 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 94 | The :class:`dircmp` offers a number of interesting attributes that may be |
| 95 | used to get various bits of information about the directory trees being |
| 96 | compared. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 97 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 98 | Note that via :meth:`__getattr__` hooks, all attributes are computed lazily, |
| 99 | so there is no speed penalty if only those attributes which are lightweight |
| 100 | to compute are used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 101 | |
| 102 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 103 | .. attribute:: left_list |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 104 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 105 | Files and subdirectories in *a*, filtered by *hide* and *ignore*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | |
| 107 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 108 | .. attribute:: right_list |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 109 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 110 | Files and subdirectories in *b*, filtered by *hide* and *ignore*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 111 | |
| 112 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 113 | .. attribute:: common |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 115 | Files and subdirectories in both *a* and *b*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
| 117 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 118 | .. attribute:: left_only |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 120 | Files and subdirectories only in *a*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | |
| 122 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 123 | .. attribute:: right_only |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 124 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 125 | Files and subdirectories only in *b*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 128 | .. attribute:: common_dirs |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 129 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 130 | Subdirectories in both *a* and *b*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 131 | |
| 132 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 133 | .. attribute:: common_files |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 134 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 135 | Files in both *a* and *b* |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 136 | |
| 137 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 138 | .. attribute:: common_funny |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 139 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 140 | Names in both *a* and *b*, such that the type differs between the |
| 141 | directories, or names for which :func:`os.stat` reports an error. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
| 143 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 144 | .. attribute:: same_files |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 145 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 146 | Files which are identical in both *a* and *b*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 147 | |
| 148 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 149 | .. attribute:: diff_files |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 151 | Files which are in both *a* and *b*, whose contents differ. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 152 | |
| 153 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 154 | .. attribute:: funny_files |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 155 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 156 | 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] | 157 | |
| 158 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 159 | .. attribute:: subdirs |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 160 | |
Georg Brandl | 71515ca | 2009-05-17 12:29:12 +0000 | [diff] [blame] | 161 | A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` |
| 162 | objects. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 163 | |