Fred Drake | c7b5b3c | 1999-10-29 17:23:15 +0000 | [diff] [blame] | 1 | \section{\module{filecmp} --- |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 2 | File and Directory Comparisons} |
Fred Drake | c7b5b3c | 1999-10-29 17:23:15 +0000 | [diff] [blame] | 3 | |
| 4 | \declaremodule{standard}{filecmp} |
Fred Drake | 57657bc | 2000-12-01 15:25:23 +0000 | [diff] [blame] | 5 | \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} |
Fred Drake | c7b5b3c | 1999-10-29 17:23:15 +0000 | [diff] [blame] | 6 | \modulesynopsis{Compare files efficiently.} |
| 7 | |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 8 | |
Fred Drake | ba7e2c8 | 2001-05-11 17:01:32 +0000 | [diff] [blame] | 9 | The \module{filecmp} module defines functions to compare files and |
| 10 | directories, with various optional time/correctness trade-offs. |
Fred Drake | c7b5b3c | 1999-10-29 17:23:15 +0000 | [diff] [blame] | 11 | |
Fred Drake | ba7e2c8 | 2001-05-11 17:01:32 +0000 | [diff] [blame] | 12 | The \module{filecmp} module defines the following functions: |
Fred Drake | c7b5b3c | 1999-10-29 17:23:15 +0000 | [diff] [blame] | 13 | |
Raymond Hettinger | f3fa946 | 2004-12-05 01:58:09 +0000 | [diff] [blame] | 14 | \begin{funcdesc}{cmp}{f1, f2\optional{, shallow}} |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 15 | Compare the files named \var{f1} and \var{f2}, returning \code{True} if |
| 16 | they seem equal, \code{False} otherwise. |
Fred Drake | c7b5b3c | 1999-10-29 17:23:15 +0000 | [diff] [blame] | 17 | |
| 18 | Unless \var{shallow} is given and is false, files with identical |
Neal Norwitz | 694d9b3 | 2003-02-06 21:17:17 +0000 | [diff] [blame] | 19 | \function{os.stat()} signatures are taken to be equal. |
Fred Drake | c7b5b3c | 1999-10-29 17:23:15 +0000 | [diff] [blame] | 20 | |
| 21 | Files that were compared using this function will not be compared again |
Neal Norwitz | 694d9b3 | 2003-02-06 21:17:17 +0000 | [diff] [blame] | 22 | unless their \function{os.stat()} signature changes. |
Fred Drake | c7b5b3c | 1999-10-29 17:23:15 +0000 | [diff] [blame] | 23 | |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 24 | Note that no external programs are called from this function, giving it |
Fred Drake | c7b5b3c | 1999-10-29 17:23:15 +0000 | [diff] [blame] | 25 | portability and efficiency. |
| 26 | \end{funcdesc} |
| 27 | |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 28 | \begin{funcdesc}{cmpfiles}{dir1, dir2, common\optional{, |
Raymond Hettinger | f3fa946 | 2004-12-05 01:58:09 +0000 | [diff] [blame] | 29 | shallow}} |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 30 | Returns three lists of file names: \var{match}, \var{mismatch}, |
| 31 | \var{errors}. \var{match} contains the list of files match in both |
| 32 | directories, \var{mismatch} includes the names of those that don't, |
| 33 | and \var{errros} lists the names of files which could not be |
| 34 | compared. Files may be listed in \var{errors} because the user may |
| 35 | lack permission to read them or many other reasons, but always that |
| 36 | the comparison could not be done for some reason. |
| 37 | |
Neal Norwitz | 1abca4a | 2002-03-20 18:55:09 +0000 | [diff] [blame] | 38 | The \var{common} parameter is a list of file names found in both directories. |
Raymond Hettinger | f3fa946 | 2004-12-05 01:58:09 +0000 | [diff] [blame] | 39 | The \var{shallow} parameter has the same |
| 40 | meaning and default value as for \function{filecmp.cmp()}. |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 41 | \end{funcdesc} |
| 42 | |
Fred Drake | c7b5b3c | 1999-10-29 17:23:15 +0000 | [diff] [blame] | 43 | Example: |
| 44 | |
| 45 | \begin{verbatim} |
| 46 | >>> import filecmp |
| 47 | >>> filecmp.cmp('libundoc.tex', 'libundoc.tex') |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 48 | True |
Fred Drake | c7b5b3c | 1999-10-29 17:23:15 +0000 | [diff] [blame] | 49 | >>> filecmp.cmp('libundoc.tex', 'lib.tex') |
Neal Norwitz | d3dab2b | 2002-04-05 02:21:09 +0000 | [diff] [blame] | 50 | False |
Fred Drake | c7b5b3c | 1999-10-29 17:23:15 +0000 | [diff] [blame] | 51 | \end{verbatim} |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 52 | |
| 53 | |
| 54 | \subsection{The \protect\class{dircmp} class \label{dircmp-objects}} |
| 55 | |
Fred Drake | ba7e2c8 | 2001-05-11 17:01:32 +0000 | [diff] [blame] | 56 | \class{dircmp} instances are built using this constructor: |
| 57 | |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 58 | \begin{classdesc}{dircmp}{a, b\optional{, ignore\optional{, hide}}} |
| 59 | Construct a new directory comparison object, to compare the |
| 60 | directories \var{a} and \var{b}. \var{ignore} is a list of names to |
| 61 | ignore, and defaults to \code{['RCS', 'CVS', 'tags']}. \var{hide} is a |
Skip Montanaro | 9483bed | 2001-01-18 10:44:08 +0000 | [diff] [blame] | 62 | list of names to hide, and defaults to \code{[os.curdir, os.pardir]}. |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 63 | \end{classdesc} |
| 64 | |
Fred Drake | ba7e2c8 | 2001-05-11 17:01:32 +0000 | [diff] [blame] | 65 | The \class{dircmp} class provides the following methods: |
| 66 | |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 67 | \begin{methoddesc}[dircmp]{report}{} |
| 68 | Print (to \code{sys.stdout}) a comparison between \var{a} and \var{b}. |
| 69 | \end{methoddesc} |
| 70 | |
| 71 | \begin{methoddesc}[dircmp]{report_partial_closure}{} |
| 72 | Print a comparison between \var{a} and \var{b} and common immediate |
Raymond Hettinger | 6880431 | 2005-01-01 00:28:46 +0000 | [diff] [blame] | 73 | subdirectories. |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 74 | \end{methoddesc} |
| 75 | |
| 76 | \begin{methoddesc}[dircmp]{report_full_closure}{} |
| 77 | Print a comparison between \var{a} and \var{b} and common |
Raymond Hettinger | 6880431 | 2005-01-01 00:28:46 +0000 | [diff] [blame] | 78 | subdirectories (recursively). |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 79 | \end{methoddesc} |
| 80 | |
Fred Drake | ba7e2c8 | 2001-05-11 17:01:32 +0000 | [diff] [blame] | 81 | |
| 82 | The \class{dircmp} offers a number of interesting attributes that may |
| 83 | be used to get various bits of information about the directory trees |
| 84 | being compared. |
| 85 | |
| 86 | Note that via \method{__getattr__()} hooks, all attributes are |
Raymond Hettinger | 6880431 | 2005-01-01 00:28:46 +0000 | [diff] [blame] | 87 | computed lazily, so there is no speed penalty if only those |
Fred Drake | ba7e2c8 | 2001-05-11 17:01:32 +0000 | [diff] [blame] | 88 | attributes which are lightweight to compute are used. |
| 89 | |
Fred Drake | 353aaad | 2000-07-03 08:24:49 +0000 | [diff] [blame] | 90 | \begin{memberdesc}[dircmp]{left_list} |
| 91 | Files and subdirectories in \var{a}, filtered by \var{hide} and |
| 92 | \var{ignore}. |
| 93 | \end{memberdesc} |
| 94 | |
| 95 | \begin{memberdesc}[dircmp]{right_list} |
| 96 | Files and subdirectories in \var{b}, filtered by \var{hide} and |
| 97 | \var{ignore}. |
| 98 | \end{memberdesc} |
| 99 | |
| 100 | \begin{memberdesc}[dircmp]{common} |
| 101 | Files and subdirectories in both \var{a} and \var{b}. |
| 102 | \end{memberdesc} |
| 103 | |
| 104 | \begin{memberdesc}[dircmp]{left_only} |
| 105 | Files and subdirectories only in \var{a}. |
| 106 | \end{memberdesc} |
| 107 | |
| 108 | \begin{memberdesc}[dircmp]{right_only} |
| 109 | Files and subdirectories only in \var{b}. |
| 110 | \end{memberdesc} |
| 111 | |
| 112 | \begin{memberdesc}[dircmp]{common_dirs} |
| 113 | Subdirectories in both \var{a} and \var{b}. |
| 114 | \end{memberdesc} |
| 115 | |
| 116 | \begin{memberdesc}[dircmp]{common_files} |
| 117 | Files in both \var{a} and \var{b} |
| 118 | \end{memberdesc} |
| 119 | |
| 120 | \begin{memberdesc}[dircmp]{common_funny} |
| 121 | Names in both \var{a} and \var{b}, such that the type differs between |
| 122 | the directories, or names for which \function{os.stat()} reports an |
| 123 | error. |
| 124 | \end{memberdesc} |
| 125 | |
| 126 | \begin{memberdesc}[dircmp]{same_files} |
| 127 | Files which are identical in both \var{a} and \var{b}. |
| 128 | \end{memberdesc} |
| 129 | |
| 130 | \begin{memberdesc}[dircmp]{diff_files} |
| 131 | Files which are in both \var{a} and \var{b}, whose contents differ. |
| 132 | \end{memberdesc} |
| 133 | |
| 134 | \begin{memberdesc}[dircmp]{funny_files} |
| 135 | Files which are in both \var{a} and \var{b}, but could not be |
| 136 | compared. |
| 137 | \end{memberdesc} |
| 138 | |
| 139 | \begin{memberdesc}[dircmp]{subdirs} |
| 140 | A dictionary mapping names in \member{common_dirs} to |
| 141 | \class{dircmp} objects. |
| 142 | \end{memberdesc} |