mirror of
https://github.com/python/cpython.git
synced 2025-11-03 19:34:08 +00:00
142 lines
4.5 KiB
TeX
142 lines
4.5 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}}
|
|
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.
|
|
|
|
Files that were compared using this function will not be compared again
|
|
unless their \function{os.stat()} signature changes.
|
|
|
|
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}}
|
|
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} parameter has the same
|
|
meaning and default value 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
|
|
subdirectories.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[dircmp]{report_full_closure}{}
|
|
Print a comparison between \var{a} and \var{b} and common
|
|
subdirectories (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 lazily, 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}
|