title: filecmp.cmp() ignoring differing os.stat() signatures?
body: <p>The Python 2 docs for <a href="https://docs.python.org/2/library/filecmp.html#module-filecmp" rel="noreferrer"><code>filecmp()</code></a> say:</p>
  
  <blockquote>
    <p>Unless <em>shallow</em> is given and is false, files with identical <a href="https://docs.python.org/2/library/os.html#os.stat" rel="noreferrer"><code>os.stat()</code></a> signatures are taken to be equal.</p>
  </blockquote>
  
  <p>Which sounds like 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 running the following code snippet:</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 class="lang-none prettyprint-override"><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 &mdash; <code>st_atime</code>, <code>st_mtime</code>, and <code>st_ctime</code>&mdash; are clearly not the same, yet <code>filecmp.cmp()</code> indicates that the two are identical.  Am I misunderstanding something or is there a bug in either <code>filecmp.cmp()</code>'s implementation or its documentation?</p>
  
  <p><strong>Update</strong></p>
  
  <p>The Python 3 <a href="https://docs.python.org/3/library/filecmp.html#module-filecmp" rel="noreferrer">documentation</a> has been rephrased and currently 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="https://docs.python.org/3/library/os.html#os.stat" rel="noreferrer"><code>os.stat()</code></a> signatures are
    taken to be equal. Otherwise, the contents of the files are compared.</p>
  </blockquote>
  
  <p>FWIW I think it would have been better to simply have said something like this:</p>
  
  <blockquote>
    <p>If <em>shallow</em> is true, file content is compared only when
    <a href="https://docs.python.org/3/library/os.html#os.stat" rel="noreferrer"><code>os.stat()</code></a>
    signatures are unequal.</p>
  </blockquote>