filecmp.cmp() doesn't seem to do what it says in the documentation

[Terry Reedy]

On 9/6/2010 1:18 PM, tinnews at isbd.co.uk wrote:
> I'm using filecmp.cmp() to compare some files (surprise!).
>
> The documentation says:-
>      Unless shallow is given and is false, files with identical
>      os.stat() signatures are taken to be equal.

Reword and read carefully: if shallow == True and signatures are 
identical, then files are taken to be equal.

Here is the corresponding code from Lib/filecmp.py:
     if shallow and s1 == s2:
         return True

Does not say the result for non-identical signatures ;-).

> I'm not setting shallow explicitly so it's True, thus the function
> should be comparing the os.stat() results.  However this doesn't seem
> to be the case as even if I touch one of the files to change it's
> access/modification date filecmp.cmp() still returns True.

Because it goes on to actually compare the files, and they are equal.

...
     result = _cache.get((f1, f2))
     if result and (s1, s2) == result[:2]:
         return result[2]
     outcome = _do_cmp(f1, f2)
     _cache[f1, f2] = s1, s2, outcome
     return outcome

Most of the stdlib files in Python are quite readable. I recommend it 
when you have questions.

-- 
Terry Jan Reedy