[issue6825] Minor documentation bug with os.path.split

[Georg Brandl]

Georg Brandl  added the comment:

Thanks, applied in r85453.

--
resolution:  -> fixed
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue6825] Minor documentation bug with os.path.split

[Sandro Tosi]

Sandro Tosi  added the comment:

Hi Evan,
all your comments make sense, so I prepared a new patch about it.

I decided to go with the first option and adding a note about the possible 
different strings.

Regards,
Sandro

--
versions: +Python 3.2 -Python 2.6
Added file: http://bugs.python.org/file19163/issue6825-py3k-v2.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue6825] Minor documentation bug with os.path.split

[Evan Driscoll]

Evan Driscoll  added the comment:

Hah, I totally forgot about this thing.

I'd suggest a change to the proposed patch. The patched version says:

  "In nearly all cases, ``join(head, tail)`` returns a location
   equivalent to *path* (the only exception being when there were 
   multiple slashes separating *head* from *tail*)."

Except now the parenthetical remark at the end of that sentence is a bit weird, 
because "a//a" != "a/a" is no longer an exception.

I'd suggest a wording such as one of the following, depending on where you want 
the emphasis (on the meaning of the return value of a path or on the actual 
contents of the return value as a string):

  "In all cases, ``join(head, tail)`` returns a location equivalent
   to *path*."

  "In most cases, ``join(head, tail)`` equals *path*; the
   exceptions to this are when there were multiple slashes
   separating *head* from *tail* or when *os.altsep* separators
   are replaced by *os.sep*."

The first suggestion could be followed by a remark "(but the strings may be 
unequal)" if you'd like.

I'd also replace "a location equivalent to" with "a path to the same location 
as" or something like that; "location" doesn't appear anywhere else on that 
page, and it seems slightly out of place to me.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue6825] Minor documentation bug with os.path.split

[Sandro Tosi]

Sandro Tosi  added the comment:

Hello,
I find the proposed text change good, and so here's a patch to add that in a 
bit different format (sorry it's quite of a mess, but I took the occasion to 
wrap that paragraph to 80th column).

Regards,
Sandro

--
keywords: +patch
nosy: +sandro.tosi
Added file: http://bugs.python.org/file19152/issue6825-py3k.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue6825] Minor documentation bug with os.path.split

[Jack Diederich]

Jack Diederich  added the comment:

how about "an equivalent path" instead of "equal path"?  The result of 
ntpath.join(ntpath.split(path)) should point to the same location even if it 
isn't literally the same string.

--
nosy: +jackdied

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue6825] Minor documentation bug with os.path.split

[Evan Driscoll]

New submission from Evan Driscoll :

The documentation for os.path.split says, in part:

  "In nearly all cases, join(head, tail) equals path (the only 
  exception being when there were multiple slashes separating head
  from tail)."

But this is not quite true: that's not the *only* exception, at least
without a somewhat liberal definition of "equals".

This can also happen if os.altsep is used in the path being split, in
which case it will be replaced by os.sep:

>>> import ntpath
>>> path = "a/b"
>>> (head, tail) = ntpath.split(path)
>>> joined = ntpath.join(head, tail)
>>> joined == path
False
>>> joined
'a\\b'


[I only selected the versions that I actually verified, but I would
guess it's present in more.]

--
assignee: georg.brandl
components: Documentation
messages: 92180
nosy: evaned, georg.brandl
severity: normal
status: open
title: Minor documentation bug with os.path.split
versions: Python 2.6, Python 2.7, Python 3.1

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com