Doc/lib/libfilecmp.tex

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