Doc/lib/libfilecmp.tex

   1 \section{\module{filecmp} ---
   2          File and Directory Comparisons}
   3
   4 \declaremodule{standard}{filecmp}
   5 \sectionauthor{Moshe Zadka}{mzadka@geocities.com}
   6 \modulesynopsis{Compare files efficiently.}
   7
   8
   9 The \module{filecmp} module defines functions to compare files and directories,
  10 with various optional time/correctness trade-offs.
  11
  12 The \module{filecmp} module defines the following function:
  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{shallow} and \var{use_statcache} parameters have the same
  45 meanings and default values as for \function{filecmp.cmp()}.
  46 \end{funcdesc}
  47
  48 Example:
  49
  50 \begin{verbatim}
  51 >>> import filecmp
  52 >>> filecmp.cmp('libundoc.tex', 'libundoc.tex')
  53 1
  54 >>> filecmp.cmp('libundoc.tex', 'lib.tex')
  55 0
  56 \end{verbatim}
  57
  58
  59 \subsection{The \protect\class{dircmp} class \label{dircmp-objects}}
  60
  61 \begin{classdesc}{dircmp}{a, b\optional{, ignore\optional{, hide}}}
  62 Construct a new directory comparison object, to compare the
  63 directories \var{a} and \var{b}. \var{ignore} is a list of names to
  64 ignore, and defaults to \code{['RCS', 'CVS', 'tags']}. \var{hide} is a
  65 list of names to hid, and defaults to \code{[os.curdir, os.pardir]}.
  66 \end{classdesc}
  67
  68 \begin{methoddesc}[dircmp]{report}{}
  69 Print (to \code{sys.stdout}) a comparison between \var{a} and \var{b}.
  70 \end{methoddesc}
  71
  72 \begin{methoddesc}[dircmp]{report_partial_closure}{}
  73 Print a comparison between \var{a} and \var{b} and common immediate
  74 subdirctories.
  75 \end{methoddesc}
  76
  77 \begin{methoddesc}[dircmp]{report_full_closure}{}
  78 Print a comparison between \var{a} and \var{b} and common
  79 subdirctories (recursively).
  80 \end{methoddesc}
  81
  82 \begin{memberdesc}[dircmp]{left_list}
  83 Files and subdirectories in \var{a}, filtered by \var{hide} and
  84 \var{ignore}.
  85 \end{memberdesc}
  86
  87 \begin{memberdesc}[dircmp]{right_list}
  88 Files and subdirectories in \var{b}, filtered by \var{hide} and
  89 \var{ignore}.
  90 \end{memberdesc}
  91
  92 \begin{memberdesc}[dircmp]{common}
  93 Files and subdirectories in both \var{a} and \var{b}.
  94 \end{memberdesc}
  95
  96 \begin{memberdesc}[dircmp]{left_only}
  97 Files and subdirectories only in \var{a}.
  98 \end{memberdesc}
  99
 100 \begin{memberdesc}[dircmp]{right_only}
 101 Files and subdirectories only in \var{b}.
 102 \end{memberdesc}
 103
 104 \begin{memberdesc}[dircmp]{common_dirs}
 105 Subdirectories in both \var{a} and \var{b}.
 106 \end{memberdesc}
 107
 108 \begin{memberdesc}[dircmp]{common_files}
 109 Files in both \var{a} and \var{b}
 110 \end{memberdesc}
 111
 112 \begin{memberdesc}[dircmp]{common_funny}
 113 Names in both \var{a} and \var{b}, such that the type differs between
 114 the directories, or names for which \function{os.stat()} reports an
 115 error.
 116 \end{memberdesc}
 117
 118 \begin{memberdesc}[dircmp]{same_files}
 119 Files which are identical in both \var{a} and \var{b}.
 120 \end{memberdesc}
 121
 122 \begin{memberdesc}[dircmp]{diff_files}
 123 Files which are in both \var{a} and \var{b}, whose contents differ.
 124 \end{memberdesc}
 125
 126 \begin{memberdesc}[dircmp]{funny_files}
 127 Files which are in both \var{a} and \var{b}, but could not be
 128 compared.
 129 \end{memberdesc}
 130
 131 \begin{memberdesc}[dircmp]{subdirs}
 132 A dictionary mapping names in \member{common_dirs} to
 133 \class{dircmp} objects.
 134 \end{memberdesc}
 135
 136 Note that via \method{__getattr__()} hooks, all attributes are
 137 computed lazilly, so there is no speed penalty if only those
 138 attributes which are lightweight to compute are used.