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{True} if
  16 they seem equal, \code{False} otherwise.
  17
  18 Unless \var{shallow} is given and is false, files with identical
  19 \function{os.stat()} signatures are taken to be equal.
  20 \versionchanged[\var{use_statcache} is obsolete and ignored.]{2.3}
  21
  22 Files that were compared using this function will not be compared again
  23 unless their \function{os.stat()} signature changes.
  24
  25 Note that no external programs are called from this function, giving it
  26 portability and efficiency.
  27 \end{funcdesc}
  28
  29 \begin{funcdesc}{cmpfiles}{dir1, dir2, common\optional{,
  30                            shallow\optional{, use_statcache}}}
  31 Returns three lists of file names: \var{match}, \var{mismatch},
  32 \var{errors}.  \var{match} contains the list of files match in both
  33 directories, \var{mismatch} includes the names of those that don't,
  34 and \var{errros} lists the names of files which could not be
  35 compared.  Files may be listed in \var{errors} because the user may
  36 lack permission to read them or many other reasons, but always that
  37 the comparison could not be done for some reason.
  38
  39 The \var{common} parameter is a list of file names found in both directories.
  40 The \var{shallow} and \var{use_statcache} parameters have the same
  41 meanings and default values as for \function{filecmp.cmp()}.
  42 \end{funcdesc}
  43
  44 Example:
  45
  46 \begin{verbatim}
  47 >>> import filecmp
  48 >>> filecmp.cmp('libundoc.tex', 'libundoc.tex')
  49 True
  50 >>> filecmp.cmp('libundoc.tex', 'lib.tex')
  51 False
  52 \end{verbatim}
  53
  54
  55 \subsection{The \protect\class{dircmp} class \label{dircmp-objects}}
  56
  57 \class{dircmp} instances are built using this constructor:
  58
  59 \begin{classdesc}{dircmp}{a, b\optional{, ignore\optional{, hide}}}
  60 Construct a new directory comparison object, to compare the
  61 directories \var{a} and \var{b}. \var{ignore} is a list of names to
  62 ignore, and defaults to \code{['RCS', 'CVS', 'tags']}. \var{hide} is a
  63 list of names to hide, and defaults to \code{[os.curdir, os.pardir]}.
  64 \end{classdesc}
  65
  66 The \class{dircmp} class provides the following methods:
  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
  83 The \class{dircmp} offers a number of interesting attributes that may
  84 be used to get various bits of information about the directory trees
  85 being compared.
  86
  87 Note that via \method{__getattr__()} hooks, all attributes are
  88 computed lazilly, so there is no speed penalty if only those
  89 attributes which are lightweight to compute are used.
  90
  91 \begin{memberdesc}[dircmp]{left_list}
  92 Files and subdirectories in \var{a}, filtered by \var{hide} and
  93 \var{ignore}.
  94 \end{memberdesc}
  95
  96 \begin{memberdesc}[dircmp]{right_list}
  97 Files and subdirectories in \var{b}, filtered by \var{hide} and
  98 \var{ignore}.
  99 \end{memberdesc}
 100
 101 \begin{memberdesc}[dircmp]{common}
 102 Files and subdirectories in both \var{a} and \var{b}.
 103 \end{memberdesc}
 104
 105 \begin{memberdesc}[dircmp]{left_only}
 106 Files and subdirectories only in \var{a}.
 107 \end{memberdesc}
 108
 109 \begin{memberdesc}[dircmp]{right_only}
 110 Files and subdirectories only in \var{b}.
 111 \end{memberdesc}
 112
 113 \begin{memberdesc}[dircmp]{common_dirs}
 114 Subdirectories in both \var{a} and \var{b}.
 115 \end{memberdesc}
 116
 117 \begin{memberdesc}[dircmp]{common_files}
 118 Files in both \var{a} and \var{b}
 119 \end{memberdesc}
 120
 121 \begin{memberdesc}[dircmp]{common_funny}
 122 Names in both \var{a} and \var{b}, such that the type differs between
 123 the directories, or names for which \function{os.stat()} reports an
 124 error.
 125 \end{memberdesc}
 126
 127 \begin{memberdesc}[dircmp]{same_files}
 128 Files which are identical in both \var{a} and \var{b}.
 129 \end{memberdesc}
 130
 131 \begin{memberdesc}[dircmp]{diff_files}
 132 Files which are in both \var{a} and \var{b}, whose contents differ.
 133 \end{memberdesc}
 134
 135 \begin{memberdesc}[dircmp]{funny_files}
 136 Files which are in both \var{a} and \var{b}, but could not be
 137 compared.
 138 \end{memberdesc}
 139
 140 \begin{memberdesc}[dircmp]{subdirs}
 141 A dictionary mapping names in \member{common_dirs} to
 142 \class{dircmp} objects.
 143 \end{memberdesc}