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

Sandro Tosi sandro.tosi at gmail.com
Mon Oct 31 11:05:46 CET 2011


Hello Jim,
I've mentioned your message into http://bugs.python.org/issue1234674
that seems related to the problem you pointed out.

Regards,
Sandro

On Sun, Oct 23, 2011 at 23:32, Jim Peak <jpeak at futurepointsystems.com> wrote:
> 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() 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.
>
> Note that no external programs are called from this function, giving it
> portability and efficiency.
>
> ---------------------------------------------------
>
> (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://www.velocityreviews.com/forums/t732652-filecmp-cmp-doesnt-seem-to-do-what-it-says-in-the-documentation.html
>
>
>
> 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 knows
> about this being wrong, now: sent him a note just today):
>
> (taken from http://www.doughellmann.com/PyMOTW/filecmp/ )
>
>
>
> 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.
>
>
>
> I believe that the addition of a single sentence can tighten up our doc to
> help eliminate this confusion / these errors.
>
>
>
> Thanks for all of your work on Python!
>
>
>
> Jim Peak
>
> Software Test Engineer
>
> Future Point Systems, Inc.
>
> (509) 619-2517 cell
>
> _______________________________________________
> docs mailing list
> docs at python.org
> http://mail.python.org/mailman/listinfo/docs
>
>



-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi


More information about the docs mailing list