[issue29688] Document Path.absolute
New submission from Jim Fasarakis-Hilliard:
Method absolute of Path objects lacked documentation, proposed PR adds relevant method to docs.
----------
assignee: docs@python
components: Documentation
messages: 288767
nosy: Jim Fasarakis-Hilliard, docs@python
priority: normal
severity: normal
status: open
title: Document Path.absolute
versions: Python 3.5, Python 3.6, Python 3.7
_______________________________________
Python tracker
Changes by Jim Fasarakis-Hilliard
Changes by Brett Cannon
Brett Cannon added the comment:
As brought up on the PR, it turns out Path.absolute() is extremely under-tested.
Perhaps we should deprecate Path.absolute() instead of document it and properly test it (and the testing will be necessary to move forward with the documentation)? Path.resolve() handles absolute paths already while also resolving '.' and '..': https://docs.python.org/3/library/pathlib.html#pathlib.Path.resolve. It also works with non-existent paths so unless there's some performance issue I'm not aware of for resolving '.' and '..', then I say we deprecate Path.absolute().
----------
_______________________________________
Python tracker
Brett Cannon added the comment:
I've closed the PR on GitHub until we decide whether we just want to deprecate Path.absolute() in favour of Path.resolve().
----------
_______________________________________
Python tracker
Changes by Serhiy Storchaka
Brett Cannon added the comment:
I'm still thinking about this but I'm still leaning towards deprecating pathlib.absolute().
----------
_______________________________________
Python tracker
Eryk Sun added the comment:
resolve() can't replace absolute(). They serve different purposes. Sometimes one wants an absolute path, but without resolving symbolic links.
absolute() processes a path as a string, which will continue to be true if it's updated to call nt._getfullpathname (GetFullPathName) on Windows. OTOH, resolve() can outright fail on Windows. I can write up a list of examples (I can think of 5 or 6 unhandled error codes), but it's not directly relevant to this issue.
----------
nosy: +eryksun
_______________________________________
Python tracker
Brett Cannon added the comment:
I know it has it's uses (avoiding stat calls is one of them), but it is still undocumented, untested, and has two comments in it saying it needs work. Because of all that it might as well not exist since it doesn't meet our standards of quality.
If someone wants to fix all those issues then we can properly document it as supported, but if no one is willing to then I don't think we should leave unsupported code lying around that people might discover through dir().
And it doesn't serve a _different_ purpose compared to resolve(), it serves a _subset_ of resolve()'s purpose since resolve() calls absolute() unconditionally.
----------
_______________________________________
Python tracker
Changes by Brett Cannon
Changes by Brett Cannon
Eryk Sun added the comment:
What's the rationale for not calling self._flavour.pathmod.abspath() to implement absolute()? For example:
>>> p = pathlib.Path('C:/con')
>>> p._flavour.pathmod.abspath(p)
'\\\\.\\con'
>>> p._from_parts((p._flavour.pathmod.abspath(p),), init=False)
WindowsPath('//./con/')
That's almost right except for an unrelated problem that pathlib shouldn't append a trailing slash for \\.\ local device paths. Doing so creates a different path, which may be invalid. \\.\con is a symbolic link to \Device\ConDrv\Console, and adding a trailing backslash after the "Console" filename is invalid. An example where the resulting path is valid but wrong is the volume device \\.\C:, which is a link to something like \Device\HarddiskVolume2. Appending a backslash refers to the root directory of the file system on the volume.
----------
_______________________________________
Python tracker
Brett Cannon added the comment:
"What's the rationale for not calling self._flavour.pathmod.abspath() to implement absolute()?" Beats me. :) It's just how Antoine wrote it and that's all I know.
----------
_______________________________________
Python tracker
Serhiy Storchaka added the comment:
posixpath.abspath() collapses "<path>/<symlink>/.." to "<path>", this is not correct. Not sure about ntpath.abspath().
----------
nosy: +serhiy.storchaka
_______________________________________
Python tracker
Eryk Sun added the comment:
It's the same with ntpath.abspath since the underlying GetFullPathName function processes the path only as a string. OK, so it seems we're requiring that p.absolute().resolve() is the same as p.resolve().
Consider the following example:
>>> p = Path('C:/symlink/../nul .eggs & spam')
>>> print(p.absolute())
C:\symlink\..\nul .eggs & spam
>>> print(os.path.abspath(p))
\\.\nul
If the current absolute() result is fine, then I think resolve() should return \\.\nul, which means it needs to be expanded to handle device-path cases for which _getfinalpathname fails. We should be able to handle these cases by falling back on _getfullpathname. It's a separate issue, but here are some concrete examples that currently cause resolve() to fail.
GetFinalPathNameByHandle will fail with ERROR_INVALID_FUNCTION or ERROR_INVALID_PARAMETER for devices that aren't file systems and thus do not support the particular NtQueryInformationFile and NtDeviceIoControlFile information classes and IOCTLs that it requests. Also, getting a handle via CreateFile can fail with ERROR_INVALID_PARAMETER for devices that require either read or write access such as CON. It can also fail with ERROR_ACCESS_DENIED for exclusive devices that are already open such as COM1.
ERROR_ACCESS_DENIED can also be due to the file security denying the right to read attributes or synchronize since CreateFile implicitly requests those rights. There's also ERROR_SHARING_VIOLATION when trying to open a system paging file. These non-device PermissionError cases can be handled the same way that resolve() currently handles FileNotFoundError by trying to resolve the parent directory.
----------
_______________________________________
Python tracker
INADA Naoki added the comment:
posixpath.abspath() collapses "<path>/<symlink>/.." to "<path>", this is not correct. Not sure about ntpath.abspath().
I feel this is reasonable limitation, and expected behavior for some cases.
So I think adding note about this in document is enough.
----------
nosy: +inada.naoki
_______________________________________
Python tracker
Changes by Brett Cannon
Brett Cannon
Change by 4-launchpad-kalvdans-no-ip-org
Change by Eryk Sun
Change by Eryk Sun
participants (6)
-
4-launchpad-kalvdans-no-ip-org
-
Brett Cannon
-
Eryk Sun
-
INADA Naoki
-
Jim Fasarakis-Hilliard
-
Serhiy Storchaka