filecmp.cmp() ignoring differing os.stat() signatures?
<p>From the Python 2.7 docs for <a href="http://docs.python.org/library/filecmp.html" rel="nofollow">filecmp</a> it sounds like when two files which are identical except for their <code>os.stat()</code> signature will be considered unequal, however this does not seem to be the case, as illustrated by the following:</p>

<pre><code>import filecmp
import os
import shutil
import time

with open('test_file_1', 'w') as f:
    f.write('file contents')
shutil.copy('test_file_1', 'test_file_2')
time.sleep(5)  # pause to get a different time-stamp
os.utime('test_file_2', None)  # change copied file's time-stamp

print 'test_file_1:', os.stat('test_file_1')
print 'test_file_2:', os.stat('test_file_2')
print 'filecmp.cmp():', filecmp.cmp('test_file_1', 'test_file_2')
</code></pre>

<p>Output:</p>

<pre><code>test_file_1: nt.stat_result(st_mode=33206, st_ino=0L, st_dev=0, st_nlink=0,
  st_uid=0, st_gid=0, st_size=13L, st_atime=1320719522L, st_mtime=1320720444L, 
  st_ctime=1320719522L)
test_file_2: nt.stat_result(st_mode=33206, st_ino=0L, st_dev=0, st_nlink=0, 
  st_uid=0, st_gid=0, st_size=13L, st_atime=1320720504L, st_mtime=1320720504L, 
  st_ctime=1320719539L)
filecmp.cmp(): True
</code></pre>

<p>As you can see the two files' time stamps  -- <code>st_atime</code>, <code>st_mtime</code>, <code>st_ctime</code> -- are clearly not the same, yet <code>filecmp.cmp()</code> indicates that the two files are identical.  Am I misunderstanding something or is there a bug in either <code>filecmp.cmp()</code>'s implentation, its documentation?</p>

<p>Update:</p>

<p>In Python 3.3, the documentation has been rephrased and now says the following, which IMHO is an improvement only in the sense that it better implies that files with different time stamps might still be considered equal even when <code>shallow</code> is True.</p>

<blockquote>
  <p>If <em>shallow</em> is true, files with identical <a href="http://docs.python.org/3.3/library/os.html#os.stat" rel="nofollow">os.stat()</a> signatures are
  taken to be equal. Otherwise, the contents of the files are compared.</p>
</blockquote>

<p>I think it would be better to have stated it some like this:</p>

<blockquote>
  <p>If <em>shallow</em> is true, file content is compared only when
  <a href="http://docs.python.org/3.3/library/os.html#os.stat" rel="nofollow">os.stat()</a>
  signatures are unequal.</p>
</blockquote>
