Skip to content
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

gh-98240: Updated Path.rename docs, when it is atomic #98245

Merged
merged 1 commit into from
Oct 28, 2022
Merged

gh-98240: Updated Path.rename docs, when it is atomic #98245

merged 1 commit into from
Oct 28, 2022

Conversation

mateka
Copy link
Contributor

@mateka mateka commented Oct 13, 2022 •
edited by miss-islington
Loading

Automerge-Triggered-By: GH:brettcannon

@mateka mateka requested a review from brettcannon as a code owner October 13, 2022 18:22
@bedevere-bot bedevere-bot added awaiting review docs Documentation in the Doc dir skip news labels Oct 13, 2022
@cpython-cla-bot
Copy link

cpython-cla-bot bot commented Oct 13, 2022 •
edited
Loading

All commit authors signed the Contributor License Agreement.
CLA signed

AA-Turner
AA-Turner reviewed Oct 13, 2022
View reviewed changes
Doc/library/pathlib.rst Outdated
it will be replaced silently if the user has permission.
it will be replaced silently if the user has permission. The operation may
fail on some Unix flavors if *src* and *dst* are on different filesystems.
If successful, the renaming will be an atomic operation (this is a POSIX requirement).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do these two lines only apply to Unix? If so, I would phrase similar to the Windows specific line below.

A

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not know, what happens on Windows. I have checked, that Path.rename is implemented with os.rename and checked its documentation. So, I believe, that this line is POSIX specific. I have copied it from `os.rename' docs. Should it be written:

On Unix, if successful, the renaming will be an atomic operation (this is a POSIX requirement).

Should I change it in `os.rename' docs also?

brettcannon
brettcannon requested changes Oct 14, 2022
View reviewed changes
Copy link
Member

@brettcannon brettcannon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't want to make promises that are not consistent across OSs which we will be expected to keep.

Doc/library/pathlib.rst Outdated
it will be replaced silently if the user has permission.
it will be replaced silently if the user has permission. The operation may
fail on some Unix flavors if *src* and *dst* are on different filesystems.
If successful, the renaming will be an atomic operation (this is a POSIX requirement).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't want to make this promise as part of the API as there is no explicit guarantee the OS is POSIX-compliant.

Suggested change
If successful, the renaming will be an atomic operation (this is a POSIX requirement).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, in order to create a file in an atomic way, do I have to use os.rename (which is used in Path.rename)?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point as os.rename() makes that promise. 🤔 I guess it's a question of whether we think it's reasonable to assume we will rely on os.rename() going forward. At which point it might sense to link to the os.rename() docs and say those guarantees hold rather than duplicate them here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have linked it (and deleted my previous commit).

@bedevere-bot
Copy link

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

@kwsp
Copy link
Contributor

kwsp commented Oct 18, 2022

I don't like copying the docs of os.rename verbatim here. Should we just instead link to the docs of os.rename and say that's what Path.rename uses internally?

@mateka mateka closed this Oct 19, 2022
@mateka mateka reopened this Oct 19, 2022
@mateka
Copy link
Contributor Author

mateka commented Oct 19, 2022

I don't like copying the docs of os.rename verbatim here. Should we just instead link to the docs of os.rename and say that's what Path.rename uses internally?

I have changed PR to point to os.rename.

@mateka mateka requested a review from brettcannon October 19, 2022 08:42
@mateka
Copy link
Contributor Author

mateka commented Oct 25, 2022

I have made the requested changes; please review again

@bedevere-bot
Copy link

Thanks for making the requested changes!

@brettcannon: please review the changes made to this pull request.

@miss-islington miss-islington merged commit 0023f51 into python:main Oct 28, 2022
@hauntsaninja hauntsaninja added needs backport to 3.10 only security fixes needs backport to 3.11 only security fixes labels Jan 30, 2023
@miss-islington
Copy link
Contributor

Thanks @mateka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.10.
🐍🍒⛏🤖

@miss-islington
Copy link
Contributor

Thanks @mateka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jan 30, 2023
@mateka @miss-islington
pythongh-98240: Updated Path.rename docs, when it is atomic (pythonGH…
743db18 
…-98245)

(cherry picked from commit 0023f51)

Co-authored-by: Mateusz <mateka@users.noreply.github.com>
@bedevere-bot
Copy link

GH-101414 is a backport of this pull request to the 3.10 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.10 only security fixes label Jan 30, 2023
@bedevere-bot
Copy link

GH-101415 is a backport of this pull request to the 3.11 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Jan 30, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jan 30, 2023
@mateka @miss-islington
pythongh-98240: Updated Path.rename docs, when it is atomic (pythonGH…
1fe72c4 
…-98245)

(cherry picked from commit 0023f51)

Co-authored-by: Mateusz <mateka@users.noreply.github.com>
miss-islington added a commit that referenced this pull request Jan 30, 2023
@miss-islington @mateka
gh-98240: Updated Path.rename docs, when it is atomic (GH-98245)
3bcb630 
(cherry picked from commit 0023f51)

Co-authored-by: Mateusz <mateka@users.noreply.github.com>
miss-islington added a commit that referenced this pull request Jan 30, 2023
@miss-islington @mateka
gh-98240: Updated Path.rename docs, when it is atomic (GH-98245)
efcab4d 
(cherry picked from commit 0023f51)

Co-authored-by: Mateusz <mateka@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@AA-Turner AA-Turner AA-Turner left review comments

@brettcannon brettcannon brettcannon approved these changes

Assignees
No one assigned
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
7 participants
@mateka @bedevere-bot @kwsp @miss-islington @brettcannon @AA-Turner @hauntsaninja