Clarify os.path.join documentation

[hauntsaninja]

https://docs.python.org/3/library/os.path.html#os.path.join

On Windows, the drive letter is not reset when an absolute path component (e.g., r'\foo') is encountered. If a component contains a drive letter, all previous components are thrown away and the drive letter is reset. Note that since there is a current directory for each drive, os.path.join("c:", "foo") represents a path relative to the current directory on drive C: (c:foo), not c:\foo.

There are a couple potential issues here.

First, it should be "drive", not "drive letter":

>>> ntpath.join("thrownaway", "//host/computer/dir", "/asdf")  # unc is not a letter
'//host/computer/asdf'

Second, it should be "if a component is from a different drive or an absolute path, all previous components are thrown away and the drive is reset":

>>> ntpath.join("C:", "foo", "C:", "bar")  # previous components are not thrown away
'C:foo\\bar'
>>> ntpath.join("C:", "foo", "D:", "bar")
'D:bar'

Third, as a nit, maybe "component" should be replaced with "segment", since arguments can contain path separators. This would improve consistency with the pathlib docs.

cc @barneygale @JelleZijlstra

These came up in #100782

Linked PRs

• gh-100783: fix os.path.join documentation #100811
• [3.11] gh-100783: fix os.path.join documentation (GH-100811) #100843
• [3.10] gh-100783: fix os.path.join documentation (GH-100811) #100844