classification
Title: os.path.relpath does not document ValueError on Windows with different drives
Type: enhancement Stage: resolved
Components: Documentation, Windows Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: ZackerySpytz, andymaier, docs@python, eryksun, lukasz.langa, miss-islington, paul.moore, steve.dower, tim.golden, zach.ware
Priority: normal Keywords: patch

Created on 2020-08-29 06:15 by andymaier, last changed 2021-04-26 19:46 by lukasz.langa. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 25346 merged ZackerySpytz, 2021-04-11 14:29
PR 25366 merged miss-islington, 2021-04-12 15:39
PR 25367 merged miss-islington, 2021-04-12 15:39
Messages (5)
msg376057 - (view) Author: Andy Maier (andymaier) * Date: 2020-08-29 06:15
I found that os.path.relpath() on Windows raises ValueError when the path and the start path are on different drives. This is to be expected, as there is no single root on Windows.

On Python 3.7, the behavior is:

>>> os.path.relpath('c:/abc', 'a:/')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "...\Python\Python37\lib\ntpath.py", line 564, in relpath
    path_drive, start_drive))
ValueError: path is on mount 'c:', start on mount 'a:'

The issue is that this ValueError and the reasons for it are not mentioned at all in the documentation for os.path.relpath(). Other os.path functions do document specific behaviors for different drives on Windows, for example os.path.commonpath(), so there is a precedence for documenting this. Also, it should be normal to document the possible exceptions that can be raised.

I did read https://bugs.python.org/issue7195 from 2009 where the original issue discussed also lead to a request to update the documentation of os.path.relpath() to show the ValueError for this case, but that angle of the issue ended up being ignored back then, unfortunately.

My suggestion is to add something like the following sentence the documentation:

"On Windows, ValueError is raised when path and start are on different drives."
msg389589 - (view) Author: Eryk Sun (eryksun) * (Python triager) Date: 2021-03-27 04:56
The suggested documentation change looks good to me.
msg390857 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2021-04-12 15:39
New changeset 67c0b3d89c4da9750fdb43fc66d3924681b22d2e by Zackery Spytz in branch 'master':
bpo-41661: Document os.path.relpath() exception on Windows with different drives (GH-25346)
https://github.com/python/cpython/commit/67c0b3d89c4da9750fdb43fc66d3924681b22d2e
msg390863 - (view) Author: miss-islington (miss-islington) Date: 2021-04-12 16:03
New changeset de06baa9de109a00c26de0dc5a248fe7aafe09f5 by Miss Islington (bot) in branch '3.9':
bpo-41661: Document os.path.relpath() exception on Windows with different drives (GH-25346)
https://github.com/python/cpython/commit/de06baa9de109a00c26de0dc5a248fe7aafe09f5
msg391981 - (view) Author: Ɓukasz Langa (lukasz.langa) * (Python committer) Date: 2021-04-26 19:46
New changeset b570feaa9c6039b9d89cdf854a5fb388872eb38e by Miss Islington (bot) in branch '3.8':
bpo-41661: Document os.path.relpath() exception on Windows with different drives (GH-25346) (#25367)
https://github.com/python/cpython/commit/b570feaa9c6039b9d89cdf854a5fb388872eb38e
History
Date User Action Args
2021-04-26 19:46:17lukasz.langasetnosy: + lukasz.langa
messages: + msg391981
2021-04-12 16:03:16miss-islingtonsetmessages: + msg390863
2021-04-12 15:42:18steve.dowersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2021-04-12 15:39:55miss-islingtonsetpull_requests: + pull_request24101
2021-04-12 15:39:46miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request24100
2021-04-12 15:39:38steve.dowersetmessages: + msg390857
2021-04-11 14:29:44ZackerySpytzsetkeywords: + patch
nosy: + ZackerySpytz

pull_requests: + pull_request24080
stage: patch review
2021-03-27 04:56:07eryksunsettype: behavior -> enhancement
messages: + msg389589
versions: + Python 3.8, Python 3.9, Python 3.10, - Python 3.7
2020-08-29 12:47:44xtreaksetnosy: + eryksun, paul.moore, tim.golden, zach.ware, steve.dower
type: behavior
components: + Windows
2020-08-29 06:15:05andymaiercreate