properly define what "canonical" means in `os.path.realpath`

Documentation

The documentation says:
https://github.com/python/cpython/blob/2fd09b011031f3c00c342b44e02e2817010e507c/Doc/library/os.path.rst?plain=1#L406-L409

So it merely mentions symlink resolution, but not what else it means (if anything).

It does however mention that whatever it does is OS dependent:
https://github.com/python/cpython/blob/2fd09b011031f3c00c342b44e02e2817010e507c/Doc/library/os.path.rst?plain=1#L416-L418

IMO, it should be clearly documented what it does or at least:

• what it guarantees to the least (For example will the pathname be absolute? Will it be normalised?)
  and/or:
• which OS function it’s identical to, like on POSIX where that would probably realpath(), and whether there are differences to that

Especially since IMO "canonical" pathname (though I think it has no formal definition, or is there anything in POSIX?) means rather just that there are no symlinks left, i.e. that the file is "reached" by its true (=canonical) name.

But that could still be a relative pathname, and perhaps even one that is not normalised.

Cheers,
Chris.

Linked PRs

• gh-134755

Start in Doc/library/os.path.rst at the cited lines 406-409 and 416-418, then compare the POSIX realpath() reference linked in the issue. Document the minimum guarantees of os.path.realpath and any OS-specific behavior or differences, with the wording making clear what “canonical” means.