summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorFred Drake <fdrake@acm.org>2000-07-03 08:24:49 (GMT)
committerFred Drake <fdrake@acm.org>2000-07-03 08:24:49 (GMT)
commit353aaadd9be62e2fa075a1da5771b31d1f0e7046 (patch)
tree46b44c222fd75a84714d835af452f1c134bb5acb /Doc
parent2b0d98bc7ff1b998b155b71ca54d70e345ac6bbc (diff)
downloadcpython-353aaadd9be62e2fa075a1da5771b31d1f0e7046.zip
cpython-353aaadd9be62e2fa075a1da5771b31d1f0e7046.tar.gz
cpython-353aaadd9be62e2fa075a1da5771b31d1f0e7046.tar.bz2
Moshe Zadka <moshez@math.huji.ac.il>:
Substantial updates to reflect Moshe's Gordon's enhancements to the module. Additional changes from Fred to reflect his changes to the module as well.
Diffstat (limited to 'Doc')
-rw-r--r--Doc/lib/libfilecmp.tex114
1 files changed, 106 insertions, 8 deletions
diff --git a/Doc/lib/libfilecmp.tex b/Doc/lib/libfilecmp.tex
index 3d56e30..d96c741 100644
--- a/Doc/lib/libfilecmp.tex
+++ b/Doc/lib/libfilecmp.tex
@@ -1,23 +1,25 @@
\section{\module{filecmp} ---
- File Comparisons}
+ File and Directory Comparisons}
\declaremodule{standard}{filecmp}
\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
\modulesynopsis{Compare files efficiently.}
-The \module{filecmp} module defines a function to compare files, taking all
-sort of short-cuts to make it a highly efficient operation.
+
+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 function:
\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.
+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
+\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 \var{os.stat()}.
+\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
@@ -25,10 +27,24 @@ unless their \function{os.stat()} signature changes. Note that using
fail --- the stale stat value will be used from \refmodule{statcache}'s
cache.
-Note that no external programs are called from this module giving it
+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}
@@ -38,3 +54,85 @@ Example:
>>> filecmp.cmp('libundoc.tex', 'lib.tex')
0
\end{verbatim}
+
+
+\subsection{The \protect\class{dircmp} class \label{dircmp-objects}}
+
+\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 hid, and defaults to \code{[os.curdir, os.pardir]}.
+\end{classdesc}
+
+\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}
+
+\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}
+
+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.