Skip to content

gh-87691: add an absolute path pathlib example in / operator docs - #100737

Merged
miss-islington merged 3 commits into
python:mainfrom
hauntsaninja:gh-87691
Jan 5, 2023
Merged

gh-87691: add an absolute path pathlib example in / operator docs#100737
miss-islington merged 3 commits into
python:mainfrom
hauntsaninja:gh-87691

Conversation

@hauntsaninja

@hauntsaninjahauntsaninja commented Jan 4, 2023•
edited by miss-islington
Loading

Copy link
Copy Markdown
Contributor

The behaviour is fully explained a couple paragraphs above, but it may be useful to have a brief example to cover the behaviour.

Automerge-Triggered-By: GH:hauntsaninja

@hauntsaninja
pythongh-87691: provide an absolute pathlib example under operator
d866f2b
The behaviour is fully explained a couple paragraphs above, but it may
be useful to have a brief example to cover the behaviour.
@bedevere-botbedevere-bot mentioned this pull request Jan 4, 2023
Closed
@bedevere-botbedevere-bot added docs Documentation in the Doc dir skip news labels Jan 4, 2023
@hauntsaninja

hauntsaninja commented Jan 4, 2023•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

This is meant as a replacement for #24900. If we feel this is still unnecessary, we can just close out the issue.

cc @barneygale

@hauntsaninjahauntsaninja changed the title gh-87691: provide an absolute pathlib example under operatorgh-87691: add an absolute path pathlib example in / operator docsJan 4, 2023
barneygale
barneygale reviewed Jan 4, 2023
View reviewed changes
Comment threadDoc/library/pathlib.rst Outdated
barneygale
barneygale approved these changes Jan 5, 2023
View reviewed changes

@barneygalebarneygale 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.

Looks good to me!

@hauntsaninjahauntsaninja added needs backport to 3.10 only security fixes needs backport to 3.11 only security fixes labels Jan 5, 2023
@JelleZijlstra

JelleZijlstra commented Jan 5, 2023

Copy link
Copy Markdown
Member

Where is this behavior explained? I don't see it in https://docs.python.org/3.10/library/pathlib.html#operators. I think a sentence spelling out the behavior might be useful.

@hauntsaninja

hauntsaninja commented Jan 5, 2023

Copy link
Copy Markdown
ContributorAuthor

It's explained in https://docs.python.org/3.10/library/pathlib.html#pathlib.PurePath , which is a couple paragraphs before Operators. Search for "When several absolute paths are given, the last is taken as an anchor"

@JelleZijlstra

JelleZijlstra commented Jan 5, 2023

Copy link
Copy Markdown
Member

That's about the Path constructor, not the slash operator. I don't think it's obvious to users that these behave the same.

@hauntsaninja

hauntsaninja commented Jan 5, 2023

Copy link
Copy Markdown
ContributorAuthor

Hmm, what would you recommend?

We could copy over just the text or the text and the examples. Also note the Windows drive example, which isn't covered by https://github.com/python/cpython/pull/24900/files

Something like:

The slash operator helps create child paths, mimicking os.path.join()’s behaviour. For instance, when several absolute paths are given, the last is taken as an anchor; for a Windows path, changing the local root doesn’t discard the previous drive setting

@JelleZijlstra

JelleZijlstra commented Jan 5, 2023

Copy link
Copy Markdown
Member

That sounds good to me.

@miss-islington

miss-islington commented Jan 5, 2023

Copy link
Copy Markdown
Contributor

Status check is done, and it's a success ✅.

@miss-islington
miss-islington merged commit 1ae619c into python:mainJan 5, 2023
@miss-islington

miss-islington commented Jan 5, 2023

Copy link
Copy Markdown
Contributor

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

@bedevere-bot

bedevere-bot commented Jan 5, 2023

Copy link
Copy Markdown

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

@bedevere-botbedevere-bot removed the needs backport to 3.11 only security fixes label Jan 5, 2023
@bedevere-bot

bedevere-bot commented Jan 5, 2023

Copy link
Copy Markdown

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jan 5, 2023
@hauntsaninja@miss-islington
pythongh-87691: add an absolute path pathlib example in / operator do…
9c6dcfa
…cs (pythonGH-100737)
The behaviour is fully explained a couple paragraphs above, but it may be useful to have a brief example to cover the behaviour.
(cherry picked from commit 1ae619c)
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Automerge-Triggered-By: GH:hauntsaninja
@bedevere-botbedevere-bot removed the needs backport to 3.10 only security fixes label Jan 5, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Jan 5, 2023
@hauntsaninja@miss-islington
pythongh-87691: add an absolute path pathlib example in / operator do…
37dfd49
…cs (pythonGH-100737)
The behaviour is fully explained a couple paragraphs above, but it may be useful to have a brief example to cover the behaviour.
(cherry picked from commit 1ae619c)
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Automerge-Triggered-By: GH:hauntsaninja
@hauntsaninja
hauntsaninja deleted the gh-87691 branch January 5, 2023 22:59
miss-islington added a commit that referenced this pull request Jan 5, 2023
@miss-islington@hauntsaninja
gh-87691: add an absolute path pathlib example in / operator docs (GH…
7586100
…-100737)
The behaviour is fully explained a couple paragraphs above, but it may be useful to have a brief example to cover the behaviour.
(cherry picked from commit 1ae619c)
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Automerge-Triggered-By: GH:hauntsaninja
miss-islington added a commit that referenced this pull request Jan 5, 2023
@miss-islington@hauntsaninja
gh-87691: add an absolute path pathlib example in / operator docs (GH…
4bdc57a
…-100737)
The behaviour is fully explained a couple paragraphs above, but it may be useful to have a brief example to cover the behaviour.
(cherry picked from commit 1ae619c)
Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Automerge-Triggered-By: GH:hauntsaninja
barneygale
barneygale reviewed Jan 5, 2023
View reviewed changes
Comment threadDoc/library/pathlib.rst
@JelleZijlstra

JelleZijlstra commented Jan 5, 2023

Copy link
Copy Markdown
Member

@barneygale sorry this got merged without your review, I forgot about the automerge label when I approved.

@barneygale

barneygale commented Jan 5, 2023

Copy link
Copy Markdown
Contributor

D'oh, I should have noticed. My feedback is just nits, the patch that went in looks fine.

@hauntsaninja

hauntsaninja commented Jan 5, 2023

Copy link
Copy Markdown
ContributorAuthor

Hmm, I think your point that "anchor" is defined differently in pathlib is more than just a nit. I'll open another PR, sigh

And sorry for my part in the automerge situation!

@hauntsaninjahauntsaninja mentioned this pull request Jan 5, 2023
Merged
hauntsaninja added a commit to hauntsaninja/cpython that referenced this pull request Jan 5, 2023
@hauntsaninja
pythongh-87691: clarify use of anchor and segment in pathlib docs
e5e1b94
This is feedback from python#100737 (comment)
This matches the wording from the `os.path.join` docs better:
https://docs.python.org/3/library/os.path.html#os.path.join
In particular, the previous use of "anchor" was incorrect given the
pathlib definition of "anchor".
While matching wording, I noticed that the constructor section uses the
word "segment". This word does not appear elsewhere in the docs or code;
we already have "part" and "component" to refer to the same concept in the
pathlib context.
hauntsaninja added a commit that referenced this pull request Jan 6, 2023
@hauntsaninja@barneygale
gh-87691: clarify use of anchor in pathlib docs (#100782)
2f2fa03
This is feedback from #100737 (comment)
This matches the wording from the `os.path.join` docs better:
https://docs.python.org/3/library/os.path.html#os.path.join
In particular, the previous use of "anchor" was incorrect given the
pathlib definition of "anchor".
Co-authored-by: Barney Gale <barney.gale@gmail.com>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@barneygalebarneygalebarneygale approved these changes
@JelleZijlstraJelleZijlstraJelleZijlstra approved these changes
@brettcannonbrettcannonAwaiting requested review from brettcannon

Assignees

No one assigned

Labels

docsDocumentation in the Doc dirskip newstopic-pathlib

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

@hauntsaninja@JelleZijlstra@miss-islington@bedevere-bot@barneygale@AlexWaygood