[docs] filecmp.cmp- confusion allowed by what we do NOT say

[Jim Peak]

Hi!  While tracking down a problem, I came across a source of confusion
that our docs leave open concerning filecmp.cmp.

 

I believe that with the addition of a single sentence, we can resolve
it.

 

Problem: 

Currently, we have the text that's in black font, shown between the
lines of hyphens, below.  Our text specs what happens when os.stat()
signatures are equal, but does not spec what happens when they're
unequal.  

 

Because of this, it's easy for readers to assume that unequal os.stat()
signatures are treated as UNequal: but that's not true:

 

Suggested Solution:

I suggest the addition of the sentence (or one like it) in green (and
italics).

 

---------------------------------------------------

filecmp.cmp(f1, f2[, shallow])

 

Compare the files named f1 and f2, returning True if they seem equal,
False otherwise.

 

Unless shallow is given and is false, files with identical os.stat
<http://docs.python.org/library/os.html#os.stat> () signatures are taken
to be equal. When os.stat() signatures differ, the contents of files are
compared, regardless of the value of shallow.

Files that were compared using this function will not be compared again
unless their os.stat()signature changes.
<http://docs.python.org/library/os.html#os.stat> 

Note that no external programs are called from this function, giving it
portability and efficiency.
<http://docs.python.org/library/os.html#os.stat> 

---------------------------------------------------
<http://docs.python.org/library/os.html#os.stat> 

(taken from the 2.7.2 doc, section 10.5, here:
http://docs.python.org/library/filecmp.html- but our 3.1.3 doc, in
section 10.4, reads identically)

 

 

We're not "technically" incorrect, but people can easily conclude from
our verbiage that since "identical os.stat() signatures are taken to be
equal," that different signatures are taken to be different.   See, for
example, the confusion of the user here:
<http://docs.python.org/library/os.html#os.stat> 

http://www.velocityreviews.com/forums/t732652-filecmp-cmp-doesnt-seem-to
-do-what-it-says-in-the-documentation.html
<http://docs.python.org/library/os.html#os.stat> 

 

Here's another example of confusion.  This is from Doug Hellman's site:
he's actually written a book on the Std Lib (The Python Standard Library
by Example), and has another in development, which is quoted here:  (He
<http://www.velocityreviews.com/forums/t732652-filecmp-cmp-doesnt-seem-t
o-do-what-it-says-in-the-documentation.html>  knows about this being
wrong, now: sent him a note just today):

(taken from http://www.doughellmann.com/PyMOTW/filecmp/ )
<http://www.velocityreviews.com/forums/t732652-filecmp-cmp-doesnt-seem-t
o-do-what-it-says-in-the-documentation.html> 

 

By default, cmp() looks only at the information available from
os.stat(). The shallow argument tells cmp() whether to look at the
contents of the file, as well. The default is to perform a shallow
comparison, without looking inside the files. Notice that files of the
same size created at the same time seem to be the same if their contents
are not compared.
<http://www.velocityreviews.com/forums/t732652-filecmp-cmp-doesnt-seem-t
o-do-what-it-says-in-the-documentation.html> 

 

I believe that the addition of a single sentence can tighten up our doc
to help eliminate this confusion / these errors.
<http://www.doughellmann.com/PyMOTW/filecmp/> 

 

Thanks for all of your work on Python!
<http://www.doughellmann.com/PyMOTW/filecmp/> 

 

Jim Peak <http://www.doughellmann.com/PyMOTW/filecmp/> 

Software Test Engineer <http://www.doughellmann.com/PyMOTW/filecmp/> 

Future Point Systems, Inc. <http://www.doughellmann.com/PyMOTW/filecmp/>


(509) 619-2517 cell <http://www.doughellmann.com/PyMOTW/filecmp/> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20111023/2e4270f3/attachment.html>