Incorrect details for `os.path.abspath()` documentation

[calestyo]

Documentation

cpython/Doc/library/os.path.rst

Lines 59 to 61 in 3a555f0

	Return a normalized absolutized version of the pathname *path*. On most
	platforms, this is equivalent to calling the function :func:`normpath` as
	follows: ``normpath(join(os.getcwd(), path))``.

claim is wrong, because normpath(join(os.getcwd(), path)) is only called when the pathname is not absolute.

If the claim would be true, every absolute pathname would get the cwd prepended.

Cheers,
Chris.

[picnixz]

AFAICT, we could amend the docs by adding "For non-absolute paths, on most platforms, [...]".

EDIT: See #130527 (comment)

cc @barneygale

[calestyo]

Even that would then still be a bit wrong or at least misleading, cause normpath() is indeed called for the absolute pathnames, too.

[calestyo]

Oh and one should probably cross check that with what the non POSIX versions of this function actually do, cause the POSIX one makes the check for absoluteness via checking for a leading / only, not via abspath().

[picnixz]

Actually, I think I was wrong. os.path.join() takes care of absolute paths:

If a segment is an absolute path (which on Windows requires both a drive and a root), then all previous segments are ignored and joining continues from the absolute path segment.

So, os.path.join(cwd, absolute) gives absolute. It doesn't matter whether os.getcwd() is prepended or not as it would be ignored.

[picnixz]

So, we wouldn't have "every absolute pathname would get the cwd prepended."

[calestyo]

Actually, I think I was wrong. os.path.join() takes care of absolute paths:

Indeed. But then the original text is actually correct (albeit still confusing IMO, though mainly because join()’s behaviour seems odd to me).

[picnixz]

albeit still confusing IMO, though mainly because join()’s behaviour seems odd to me

Yes, but that's how it's been for years so I don't think we can change this =/ So while it could be confusing, we shouldn't forget about join ignoring all segments preceededing an absolute segment.

Now, what we could however do is highlight more that part on the os.path.join docs. We could also add a link to os.path.join in os.path.abspath because the function appears after abspath and not before, so whatever is said in os.path.join is not known to the reader when they read about os.path.abspath.

WDYT @barneygale? Also, do you know why it was chosen that absolute segments make previous segments ignored?

[calestyo]

Yes, but that's how it's been for years so I don't think we can change this =/

Sure.

The only alternative would be a join2() or maybe concatenate(), which behaves differently, or that allows to be configured via params from the beginning (e.g. one that makes it behave like join() another, which throws an exception if any but the first argument is absolute).

I guess from the abspath() doc PoV, nothing needs to be done in the strict sense:

It does behave as one would expect it to. And if people like me get confused because of the details, that seemingly differ, they either properly read up join() or - the kind of lazy gits like me - file a bug. ;-)

[picnixz]

The only alternative would be a join2() or maybe concatenate(), which behaves differently, or that allows to be configured via params from the beginning (e.g. one that makes it behave like join() another, which throws an exception if any but the first argument is absolute).

I'm not sure we need this kind of function in the stdlib, at least not until someone demonstrates that it's a common pattern that well-known libraries would want. It can be implemented by a utility helper but I don't think it's a function to include.

[picnixz]

I'm however still concerned about the fact that we refer to a function in the docs before it has been documented and without any clickable link to it so I guess we can still update the docs of os.path.