mirror of
https://github.com/python/cpython.git
synced 2025-10-31 02:15:10 +00:00
147 lines
4.8 KiB
TeX
147 lines
4.8 KiB
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{1} if
|
|
they seem equal, \code{0} 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{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')
|
|
1
|
|
>>> filecmp.cmp('libundoc.tex', 'lib.tex')
|
|
0
|
|
\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}
|