classification
Title: os.path.join behavior on Windows (ntpath.join) is not well documented
Type: behavior Stage: resolved
Components: Documentation, Windows Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: BreamoreBoy, christian.heimes, docs@python, dsawyer, eckhardt, ezio.melotti, jorend, mdengler, mhammond, python-dev, r.david.murray, terry.reedy, tim.golden, zach.ware
Priority: normal Keywords: easy, needs review, patch

Created on 2012-07-21 20:41 by r.david.murray, last changed 2014-10-10 21:10 by zach.ware. This issue is now closed.

Files
File name Uploaded Description Edit
joindoc.patch dsawyer, 2014-04-17 22:31
issue15414.diff zach.ware, 2014-10-10 20:12 review
Messages (7)
msg166065 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-07-21 20:41
In looking at another os.path.join documentation issue I tried the Windows join to see if it matched the docs, and found that it was very unclear.   I searched the tracker and found Issue 1669539, which contains much relevant discussion but also much discussion of possible enhancements.  So I'm opening a new issue *just* about what I see as the current bugs in the os.path.join docs and ntpath.join implementation.

I'm not qualified to fix this, not being a Windows user, but it is clear to me that the documentation of os.path.join for Windows is unclear (it does not indicate what is considered an absolute path on Windows) and wrong (\foo will *not* restart the path if it is the second element and follows a drive specification, but it does any other time), and that the current behavior may have a bug if, as seems to be implied by the issue 1669539 discussion, something that looks like a drive specification in the middle of a path is invalid on Windows.  If this last is not a bug, it should be mentioned in the documentation, since the actual behavior is counter-intuitive.
msg216755 - (view) Author: Dave Sawyer (dsawyer) * Date: 2014-04-17 21:47
http://bugs.python.org/issue1669539 has been partially fixed. On Windows os.path.join('foo', 'a:bar') gives 'a:bar' not 'foo\\a:bar'. However os.path.isabs('a:bar') returns False yet it causes a reset in the join like an absolute path.

'\foo' is considered an absolute path even though calling os.path.abspath on it can yield different results - as if it were a relative path. At minimum we should amend the wording about what resets the join.
msg222854 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-07-12 16:51
ntpath.join() was fixed in issue19456 so I think all we need here is a commit review of the attached documentation patch.
msg229032 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-10-10 20:12
Dave, your patch is a significant improvement on the accuracy of the current doc, but the whole paragraph seems somewhat haphazard and confusing to me.  Here's my own attempt to clean it up, though I'm not certain just how much improvement it is :)
msg229034 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-10-10 20:24
I'd say it was definitely an improvement in terms of comprehensibility.
msg229039 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-10-10 21:06
New changeset 05274a517b37 by Zachary Ware in branch '2.7':
Issue #15414: Clean and correct the os.path.join docs.
https://hg.python.org/cpython/rev/05274a517b37

New changeset c9c6082d4f9b by Zachary Ware in branch '3.4':
Issue #15414: Clean and correct the os.path.join docs.
https://hg.python.org/cpython/rev/c9c6082d4f9b

New changeset e57f93c681a6 by Zachary Ware in branch 'default':
Closes #15414: Merge with 3.4
https://hg.python.org/cpython/rev/e57f93c681a6
msg229040 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-10-10 21:10
Committed, with better line wrapping.

Thank you Dave Sawyer for the initial patch, and RDM for the review.
History
Date User Action Args
2014-10-10 21:10:00zach.waresetmessages: + msg229040
2014-10-10 21:06:24python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg229039

resolution: fixed
stage: patch review -> resolved
2014-10-10 20:24:53r.david.murraysetmessages: + msg229034
2014-10-10 20:13:13zach.waresettitle: os.path.join behavior on Windows (ntpath.join) is unexpected and not well documented -> os.path.join behavior on Windows (ntpath.join) is not well documented
2014-10-10 20:12:06zach.waresetfiles: + issue15414.diff
nosy: + zach.ware
messages: + msg229032

2014-09-27 14:32:21serhiy.storchakasetkeywords: + needs review
stage: patch review
versions: + Python 2.7
2014-07-12 16:56:51brian.curtinsetnosy: - brian.curtin
2014-07-12 16:51:50BreamoreBoysetnosy: + BreamoreBoy
messages: + msg222854
2014-04-17 22:46:06dsawyersetversions: + Python 3.4, Python 3.5, - Python 2.7, Python 3.2, Python 3.3
2014-04-17 22:31:40dsawyersetfiles: + joindoc.patch
keywords: + patch
2014-04-17 21:47:16dsawyersetnosy: + dsawyer
messages: + msg216755
2014-04-16 15:20:40mdenglersetnosy: + mdengler
2012-07-21 20:45:50r.david.murraylinkissue1669539 dependencies
2012-07-21 20:41:07r.david.murraycreate