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

Comece em Doc/library/os.path.rst nas linhas citadas 406-409 e 416-418 e, em seguida, compare com a referência POSIX de realpath() vinculada na issue. Documente as garantias mínimas de os.path.realpath e qualquer comportamento ou diferença específica do sistema operacional, fazendo com que a redação deixe claro o que “canonical” significa.