classification
Title: os.path.join behavior
Type: behavior Stage: resolved
Components: Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: Nosy List: fossilet, ned.deily, python-dev, r.david.murray
Priority: normal Keywords:

Created on 2012-07-13 01:45 by fossilet, last changed 2012-07-21 18:39 by r.david.murray. This issue is now closed.

Messages (7)
msg165348 - (view) Author: Yongzhi Pan (fossilet) * Date: 2012-07-13 01:45
I am constructing a source directory argument to rsync. It has to end with slash due to rsync behavior. I use:

os.path.join('/src/dir', os.path.sep)

And run it and realized the source directory becomes '/'. Luckily it is not the destination.

Why should join discard all previous path components if any component is an absoulute path? This is such a surprise and renders this function useless.
msg165363 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2012-07-13 06:58
os.path.join is working as documented. See http://docs.python.org/library/os.path.html#os.path.join

"If any component is an absolute path, all previous components (on Windows, including the previous drive letter, if there was one) are thrown away, and joining continues." ... "This means that an empty last part will result in a path that ends with a separator."  So, to have the path end with a separator, use an empty string rather than '/' as the last component.

>>> import os
>>> os.path.join('/','Users', 'nad')
'/Users/nad'
>>> os.path.join('/','Users', 'nad', '')
'/Users/nad/'
msg165373 - (view) Author: Yongzhi Pan (fossilet) * Date: 2012-07-13 08:00
I know this is working as documented. But working as documented does not mean it is not a bug.

I cannot deduce that it will append a separator if joining with an empty string from the documentation. Also, this behavior is implicit, and have to guess. Either the document or the behaivor have to be changed.

I think it is not only me:

http://stackoverflow.com/questions/1945920/os-path-join-python
msg165387 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-07-13 14:47
Whatever the good or bad points of the API design, it is what it is and has been for a very long time.  It is not something that is going to change, because the break in backward compatibility would be too large.

What is unclear about the documentation that Ned quoted ("This means that an empty last part will result in a path that ends with a separator.")?  How would you suggest improving the documentation?
msg165565 - (view) Author: Yongzhi Pan (fossilet) * Date: 2012-07-16 04:29
I suggest append "An empty last part will result in a path that ends with a separator" or something similar to the docstring, though it is already in the HTML documentation. 

Suppose someone does this like me:

In [10]: join('a', sep)
Out[10]: '/'

He must be surprised. He has to guess how to append a separator if he does not look at the code, or fiddle around until he finds the soultion. 

Given it explained in the docstring, after he sees:

In [10]: join('a', sep)
Out[10]: '/'

He will probably look at the docstring:

In [16]: join?
Type:       function
Base Class: <type 'function'>
String Form:<function join at 0x7f053fc93ed8>
Namespace:  Interactive
File:       /usr/lib/python2.7/posixpath.py
Definition: join(a, *p)
Docstring:
Join two or more pathname components, inserting '/' as needed.
If any component is an absolute path, all previous path components
will be discarded. An empty last part will result in a path that
ends with a separator.

Ok, he immediately knows he has to supply an empty string instead of a separator.
msg166052 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-07-21 18:38
New changeset 61d0e3526a51 by R David Murray in branch '3.2':
#15342: Add clarifying sentence to posixpath.join docstring.
http://hg.python.org/cpython/rev/61d0e3526a51

New changeset 30d4d1528b58 by R David Murray in branch 'default':
Merge #15342: Add clarifying sentence to posixpath.join docstring.
http://hg.python.org/cpython/rev/30d4d1528b58

New changeset f3cc7626a621 by R David Murray in branch '2.7':
#15342: Add clarifying sentence to posixpath.join docstring.
http://hg.python.org/cpython/rev/f3cc7626a621
msg166053 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-07-21 18:39
I've added the sentence to the docstring, as you suggested.  Thanks for the suggestion.
History
Date User Action Args
2012-07-21 18:39:56r.david.murraysetmessages: + msg166053
versions: + Python 3.2, Python 3.3
2012-07-21 18:38:35python-devsetnosy: + python-dev
messages: + msg166052
2012-07-16 04:29:28fossiletsetmessages: + msg165565
2012-07-13 14:47:37r.david.murraysetnosy: + r.david.murray
messages: + msg165387
2012-07-13 08:00:50fossiletsetmessages: + msg165373
2012-07-13 06:58:36ned.deilysetstatus: open -> closed

nosy: + ned.deily
messages: + msg165363

resolution: not a bug
stage: resolved
2012-07-13 01:45:30fossiletcreate