Doc/lib/libfilecmp.tex

\section{\module{filecmp} ---
         File and Directory Comparisons}

\declaremodule{standard}{filecmp}
\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
\modulesynopsis{Compare files efficiently.}


The \module{filecmp} module defines functions to compare files and
directories, with various optional time/correctness trade-offs.

The \module{filecmp} module defines the following functions:

\begin{funcdesc}{cmp}{f1, f2\optional{, shallow\optional{, use_statcache}}}
Compare the files named \var{f1} and \var{f2}, returning \code{True} if
they seem equal, \code{False} otherwise.

Unless \var{shallow} is given and is false, files with identical
\function{os.stat()} signatures are taken to be equal.  If
\var{use_statcache} is given and is true,
\function{statcache.stat()} will be called rather then
\function{os.stat()}; the default is to use \function{os.stat()}.

Files that were compared using this function will not be compared again
unless their \function{os.stat()} signature changes. Note that using
\var{use_statcache} true will cause the cache invalidation mechanism to 
fail --- the stale stat value will be used from \refmodule{statcache}'s 
cache.

Note that no external programs are called from this function, giving it
portability and efficiency.
\end{funcdesc}

\begin{funcdesc}{cmpfiles}{dir1, dir2, common\optional{,
                           shallow\optional{, use_statcache}}}
Returns three lists of file names: \var{match}, \var{mismatch},
\var{errors}.  \var{match} contains the list of files match in both
directories, \var{mismatch} includes the names of those that don't,
and \var{errros} lists the names of files which could not be
compared.  Files may be listed in \var{errors} because the user may
lack permission to read them or many other reasons, but always that
the comparison could not be done for some reason.

The \var{common} parameter is a list of file names found in both directories.
The \var{shallow} and \var{use_statcache} parameters have the same
meanings and default values as for \function{filecmp.cmp()}.
\end{funcdesc}

Example:

\begin{verbatim}
>>> import filecmp
>>> filecmp.cmp('libundoc.tex', 'libundoc.tex')
True
>>> filecmp.cmp('libundoc.tex', 'lib.tex')
False
\end{verbatim}


\subsection{The \protect\class{dircmp} class \label{dircmp-objects}}

\class{dircmp} instances are built using this constructor:

\begin{classdesc}{dircmp}{a, b\optional{, ignore\optional{, hide}}}
Construct a new directory comparison object, to compare the
directories \var{a} and \var{b}. \var{ignore} is a list of names to
ignore, and defaults to \code{['RCS', 'CVS', 'tags']}. \var{hide} is a
list of names to hide, and defaults to \code{[os.curdir, os.pardir]}.
\end{classdesc}

The \class{dircmp} class provides the following methods:

\begin{methoddesc}[dircmp]{report}{}
Print (to \code{sys.stdout}) a comparison between \var{a} and \var{b}.
\end{methoddesc}

\begin{methoddesc}[dircmp]{report_partial_closure}{}
Print a comparison between \var{a} and \var{b} and common immediate
subdirctories.
\end{methoddesc}

\begin{methoddesc}[dircmp]{report_full_closure}{}
Print a comparison between \var{a} and \var{b} and common 
subdirctories (recursively).
\end{methoddesc}


The \class{dircmp} offers a number of interesting attributes that may
be used to get various bits of information about the directory trees
being compared.

Note that via \method{__getattr__()} hooks, all attributes are
computed lazilly, so there is no speed penalty if only those
attributes which are lightweight to compute are used.

\begin{memberdesc}[dircmp]{left_list}
Files and subdirectories in \var{a}, filtered by \var{hide} and
\var{ignore}.
\end{memberdesc}

\begin{memberdesc}[dircmp]{right_list}
Files and subdirectories in \var{b}, filtered by \var{hide} and
\var{ignore}.
\end{memberdesc}

\begin{memberdesc}[dircmp]{common}
Files and subdirectories in both \var{a} and \var{b}.
\end{memberdesc}

\begin{memberdesc}[dircmp]{left_only}
Files and subdirectories only in \var{a}.
\end{memberdesc}

\begin{memberdesc}[dircmp]{right_only}
Files and subdirectories only in \var{b}.
\end{memberdesc}

\begin{memberdesc}[dircmp]{common_dirs}
Subdirectories in both \var{a} and \var{b}.
\end{memberdesc}

\begin{memberdesc}[dircmp]{common_files}
Files in both \var{a} and \var{b}
\end{memberdesc}

\begin{memberdesc}[dircmp]{common_funny}
Names in both \var{a} and \var{b}, such that the type differs between
the directories, or names for which \function{os.stat()} reports an
error.
\end{memberdesc}

\begin{memberdesc}[dircmp]{same_files}
Files which are identical in both \var{a} and \var{b}.
\end{memberdesc}

\begin{memberdesc}[dircmp]{diff_files}
Files which are in both \var{a} and \var{b}, whose contents differ.
\end{memberdesc}

\begin{memberdesc}[dircmp]{funny_files}
Files which are in both \var{a} and \var{b}, but could not be
compared.
\end{memberdesc}

\begin{memberdesc}[dircmp]{subdirs}
A dictionary mapping names in \member{common_dirs} to
\class{dircmp} objects.
\end{memberdesc}