[Python-checkins] CVS: python/dist/src/Doc/lib libfilecmp.tex,1.1,1.2

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory slayer.i.sourceforge.net:/tmp/cvs-serv9125/lib

Modified Files:
	libfilecmp.tex 
Log Message:

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.


Index: libfilecmp.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libfilecmp.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -r1.1 -r1.2
*** libfilecmp.tex	1999/10/29 17:23:15	1.1
--- libfilecmp.tex	2000/07/03 08:24:49	1.2
***************
*** 1,4 ****
  \section{\module{filecmp} ---
!          File Comparisons}
  
  \declaremodule{standard}{filecmp}
--- 1,4 ----
  \section{\module{filecmp} ---
!          File and Directory Comparisons}
  
  \declaremodule{standard}{filecmp}
***************
*** 6,22 ****
  \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 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.
  
  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 \var{os.stat()}.
  
  Files that were compared using this function will not be compared again
--- 6,24 ----
  \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 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.
  
  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
***************
*** 26,33 ****
  cache.
  
! Note that no external programs are called from this module giving it
  portability and efficiency.
  \end{funcdesc}
  
  Example:
  
--- 28,49 ----
  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:
  
***************
*** 39,40 ****
--- 55,138 ----
  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.