bpo-42958: Align docstring and filecmp.cmp() for shallow compare by AlexVndnblcke · Pull Request #24246 · python/cpython

@AlexVndnblcke

The docstring for filecmp mentions that, with a shallow copy, the
signature of the file is compared rather than a bit-by-bit comparison.

As external user it is not clear what is meant by this signature. Is it
a comparison of a stat between 2 files? If so, what about inode which
would only be identical for a hard link. And so on...

This clarification describes which parts of a stat are compared to give
the end user more info when to use shallow compares and when not to.

@AlexVndnblcke

State the actual interpretation of the `shallow` keyword argument to
minimize possible confusion for the end user.

This include:
- clarify which info of `os.stat()` is used during shallow compare
  (file type, size and modification time)
- clarify that `shallow=True` doesn't imply no deep compare can be
  performed under the hood.