[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 <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
Changes by Jim Fasarakis-Hilliard <d.f.hilliard@gmail.com>: ---------- pull_requests: +321 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
Changes by Brett Cannon <brett@python.org>: ---------- assignee: docs@python -> brett.cannon nosy: +brett.cannon _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
Changes by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
Brett Cannon added the comment: I'm still thinking about this but I'm still leaning towards deprecating pathlib.absolute(). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
Changes by Brett Cannon <brett@python.org>: ---------- title: Document Path.absolute -> Add support for Path.absolute _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
Changes by Brett Cannon <brett@python.org>: ---------- title: Add support for Path.absolute -> Add support for Path.absolute() _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
Changes by Brett Cannon <brett@python.org>: ---------- assignee: brett.cannon -> _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________
Brett Cannon <brett@python.org> added the comment: I have opened https://bugs.python.org/issue39090 to track updating the pathlib docs to have a section on getting the absolute path in various ways along with what the trade-offs are for each approach. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue29688> _______________________________________
Change by 4-launchpad-kalvdans-no-ip-org <launchpad@kalvdans.no-ip.org>: ---------- nosy: +4-launchpad-kalvdans-no-ip-org _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue29688> _______________________________________
Change by Eryk Sun <eryksun@gmail.com>: ---------- assignee: -> docs@python components: +Library (Lib) type: -> enhancement versions: +Python 3.10, Python 3.8, Python 3.9 -Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue29688> _______________________________________
Change by Eryk Sun <eryksun@gmail.com>: ---------- Removed message: https://bugs.python.org/msg289517 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue29688> _______________________________________
participants (6)
-
4-launchpad-kalvdans-no-ip-org -
Brett Cannon
-
Eryk Sun
-
INADA Naoki
-
Jim Fasarakis-Hilliard
-
Serhiy Storchaka