Skip to content

bpo-42958: Align docstring and filecmp.cmp() for shallow compare #24246

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
wants to merge 2 commits into from
Closed

bpo-42958: Align docstring and filecmp.cmp() for shallow compare #24246

wants to merge 2 commits into from

Conversation

AlexVndnblcke
Copy link
Contributor

@AlexVndnblcke AlexVndnblcke commented Jan 18, 2021 •
edited by bedevere-bot
Loading

@the-knights-who-say-ni
Copy link

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept this contribution by verifying everyone involved has signed the PSF contributor agreement (CLA).

CLA Missing

Our records indicate the following people have not signed the CLA:

@AlexVndnblcke

For legal reasons we need all the people listed to sign the CLA before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

If you have recently signed the CLA, please wait at least one business day
before our records are updated.

You can check yourself to see if the CLA has been received.

Thanks again for the contribution, we look forward to reviewing it!

@AlexVndnblcke AlexVndnblcke force-pushed the fix-issue-42958 branch 2 times, most recently from ab00232 to ccb5414 Compare January 19, 2021 21:04
@MojoVampire
Copy link
Contributor

This makes backwards incompatible changes to filecmp.cmp to make it match its (inaccurate) docstring. The solution is to fix the docstring, not change the behavior.

@AlexVndnblcke
bpo-42958: Clarify the docstring for filecmp.cmp()
b8a1e3e 
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
bpo-42958: Clarify doc for filecmp.cmp()
b294ac3 
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.
@AlexVndnblcke AlexVndnblcke marked this pull request as ready for review February 10, 2021 08:38
@github-actions
Copy link

This PR is stale because it has been open for 30 days with no activity.

@github-actions github-actions bot added the stale Stale PR or inactive for long period of time. label Mar 13, 2021
@ambv
Copy link
Contributor

ambv commented Aug 4, 2021

Closing in favor of GH-27166 where we integrated some of your suggestions and credited you. Thanks, AlexVndnblcke!

@ambv ambv closed this Aug 4, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
awaiting review stale Stale PR or inactive for long period of time.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@AlexVndnblcke @the-knights-who-say-ni @MojoVampire @ambv @bedevere-bot