Skip to content

gh-91317: Document that Path does not collapse initial // - #32193

Merged
miss-islington merged 10 commits into
python:mainfrom
arhadthedev:bpo-47161
Jun 10, 2022
Merged

miss-islington merged 10 commits into
python:mainfrom
arhadthedev:bpo-47161

Conversation

@arhadthedev

@arhadthedev arhadthedev commented Mar 30, 2022 •

Copy link
Copy Markdown
Member

Documentation for pathlib says:

Spurious slashes and single dots are collapsed, but double dots ('..') are not, since this would change the meaning of a path in the face of symbolic links:

However, it omits that initial double slashes also aren't collapsed.

Later, in documentation of PurePath.drive, PurePath.root, and PurePath.name it mentions UNC but:

  • this abbreviation says nothing to a person who is unaware about existence of UNC (Wikipedia doesn't help either by giving a disambiguation page)
  • it shows up only if a person needs to use a specific property or decides to fully learn what the module provides.

For context, see the BPO entry.

https://bugs.python.org/issue47161

Automerge-Triggered-By: GH:brettcannon

@bedevere-bot bedevere-bot added the docs Documentation in the Doc dir label Mar 30, 2022
@brettcannon

brettcannon commented Mar 31, 2022 •

Copy link
Copy Markdown
Member

/cc @barneygale

@barneygale

barneygale commented Apr 1, 2022 •

Copy link
Copy Markdown
Contributor

The present documentation is technically correct, but could be more complete. The word "spurious" does a lot of work.

On POSIX paths:

According to POSIX path resolution:

A pathname that begins with two successive slashes may be interpreted in an implementation-defined manner, although more than two leading slashes shall be treated as a single slash".

You can try it for yourself in a shell:

$ cd /etc
$ pwd
/etc
$ cd //etc
$ pwd
//etc
$ cd ///etc
$ pwd
/etc

This isn't mentioned anywhere in the pathlib docs, but it could be! I think this would best addressed by a new paragraph and repl example in the documentation for PurePath.root.

Note that this has nothing to do with UNC paths! :-)

On Windows paths:

The docs for UNC paths sit at about the right place for me - in the details for PurePath.drive and PurePath.root. We could give UNC paths a namecheck in the docs for pathlib.PureWindowsPath, something like:

A subclass of PurePath, this path flavour represents Windows filesystem paths, including UNC paths:

>>> PureWindowsPath('c:/Program Files/')
PureWindowsPath('c:/Program Files')
>>> PureWindowsPath('//server/share/file')
PureWindowsPath('//server/share/file')

@MaxwellDupre MaxwellDupre left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

It would have been better to spilt the sentence in two for non-English readers for clarity.

Comment thread Doc/library/pathlib.rst Resolved
@bedevere-bot

ghost commented Jun 7, 2022

Copy link
Copy Markdown

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.

Oleg Iarygin and others added 2 commits June 8, 2022 15:07
@arhadthedev arhadthedev changed the title bpo-47161: Document that Path does not collapse initial // gh-91317: Document that Path does not collapse initial // Jun 8, 2022
@arhadthedev

ghost commented Jun 8, 2022

Copy link
Copy Markdown
Member Author

I'm working on the barneygale's review.

@arhadthedev

ghost commented Jun 8, 2022

Copy link
Copy Markdown
Member Author

@barneygale I have made the requested changes; please review again.

I hope I didn't make grammar mistakes there.

@bedevere-bot

ghost commented Jun 8, 2022

Copy link
Copy Markdown

Thanks for making the requested changes!

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

@bedevere-bot
bedevere-bot requested a review from brettcannon June 8, 2022 15:38
@miss-islington

ghost commented Jun 10, 2022

Copy link
Copy Markdown
Contributor

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

@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Jun 10, 2022
@bedevere-bot

ghost commented Jun 10, 2022

Copy link
Copy Markdown

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

@bedevere-bot

ghost commented Jun 10, 2022

Copy link
Copy Markdown

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

@brettcannon

ghost commented Jun 10, 2022

Copy link
Copy Markdown
Member

@arhadthedev thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation in the Doc dir

Projects

None yet

Development

Successfully merging this pull request may close these issues.

8 participants