pathlib: Highlight pathlib operator behavior with anchored paths

[diegoe]

BPO	43525
Nosy	@diegoe
PRs	bpo-43525: Highlight pathlib operator behavior with anchored paths #24900

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2021-03-17.04:04:55.025>
labels = ['3.9', 'docs']
title = 'pathlib: Highlight pathlib operator behavior with anchored paths'
updated_at = <Date 2021-03-17.04:24:30.717>
user = 'https://github.com/diegoe'

bugs.python.org fields:

activity = <Date 2021-03-17.04:24:30.717>
actor = 'diegoe'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-03-17.04:04:55.025>
creator = 'diegoe'
dependencies = []
files = []
hgrepos = []
issue_num = 43525
keywords = ['patch']
message_count = 1.0
messages = ['388904']
nosy_count = 2.0
nosy_names = ['docs@python', 'diegoe']
pr_nums = ['24900']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue43525'
versions = ['Python 3.9']

Linked PRs

• gh-87691: add an absolute path pathlib example in / operator docs #100737
• [3.11] gh-87691: add an absolute path pathlib example in / operator docs (GH-100737) #100780
• [3.10] gh-87691: add an absolute path pathlib example in / operator docs (GH-100737) #100781
• gh-87691: clarify use of anchor in pathlib docs #100782
• [3.11] gh-87691: clarify use of anchor in pathlib docs (GH-100782) #100786
• [3.10] gh-87691: clarify use of anchor in pathlib docs (GH-100782) #100787

[diegoe]

In the '/' operator documentation for pathlib, the behavior for anchored paths is not described:

https://docs.python.org/3/library/pathlib.html#operators

The behavior (prefer the second/right-hand root/anchor) is only explained in the PurePath class:

https://docs.python.org/3/library/pathlib.html#pathlib.PurePath

I ran into this while helping migrate a code base that was using "naive" concatenation of strings, so this:

PROJECT_DIR = ROOT_DIR + "/project-name"

was migrated to:

PROJECT_DIR = ROOT_DIR / "/project-name"

Note that, of course, we missed the leading "/".

Although the docs _do_ describe the behavior somewhere else, I believe it's worth being redundant in the operator section.

I believe it's a reasonable mistake to warn new users against, specially since "naive" concatenation is a common "ugly" pattern that many would be migrating from. Plus, a leading "/" is easy to miss, which would only compound the confusion if you are seeing your path "omit the (left-hand) Path object" (because the anchored string took precedence).