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.]

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.

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

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.

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

Thanks, applied in r85453.