os.path.relpath does not document ValueError on Windows with different drives

[andy-maier]

BPO	41661
Nosy	@pfmoore, @tjguk, @ambv, @zware, @eryksun, @zooba, @andy-maier, @ZackerySpytz, @miss-islington
PRs	bpo-41661: Document os.path.relpath() behavior on Windows with different drives #25346 [3.9] bpo-41661: Document os.path.relpath() exception on Windows with different drives (GH-25346) #25366 [3.8] bpo-41661: Document os.path.relpath() exception on Windows with different drives (GH-25346) #25367

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2021-04-12.15:42:18.907>
created_at = <Date 2020-08-29.06:15:05.527>
labels = ['3.8', '3.9', '3.10', 'type-feature', 'OS-windows', 'docs']
title = 'os.path.relpath does not document ValueError on Windows with different drives'
updated_at = <Date 2021-04-26.19:46:17.940>
user = 'https://github.com/andy-maier'

bugs.python.org fields:

activity = <Date 2021-04-26.19:46:17.940>
actor = 'lukasz.langa'
assignee = 'docs@python'
closed = True
closed_date = <Date 2021-04-12.15:42:18.907>
closer = 'steve.dower'
components = ['Documentation', 'Windows']
creation = <Date 2020-08-29.06:15:05.527>
creator = 'andymaier'
dependencies = []
files = []
hgrepos = []
issue_num = 41661
keywords = ['patch']
message_count = 5.0
messages = ['376057', '389589', '390857', '390863', '391981']
nosy_count = 10.0
nosy_names = ['paul.moore', 'tim.golden', 'docs@python', 'lukasz.langa', 'zach.ware', 'eryksun', 'steve.dower', 'andymaier', 'ZackerySpytz', 'miss-islington']
pr_nums = ['25346', '25366', '25367']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue41661'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[andy-maier]

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."

[eryksun]

The suggested documentation change looks good to me.

[zooba]

New changeset 67c0b3d by Zackery Spytz in branch 'master':
bpo-41661: Document os.path.relpath() exception on Windows with different drives (GH-25346)
67c0b3d

[miss-islington]

New changeset de06baa by Miss Islington (bot) in branch '3.9':
bpo-41661: Document os.path.relpath() exception on Windows with different drives (GH-25346)
de06baa

[ambv]

New changeset b570fea by Miss Islington (bot) in branch '3.8':
bpo-41661: Document os.path.relpath() exception on Windows with different drives (GH-25346) (bpo-25367)
b570fea