pathlib Path.replace raises OSError when target exists

[selik]

BPO	40278
Nosy	@pitrou, @serhiy-storchaka, @selik, @tirkarthi

^{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 = None
created_at = <Date 2020-04-14.03:36:59.214>
labels = ['type-bug', '3.8', 'docs']
title = 'pathlib Path.replace raises OSError when target exists'
updated_at = <Date 2020-04-14.04:45:59.264>
user = 'https://github.com/selik'

bugs.python.org fields:

activity = <Date 2020-04-14.04:45:59.264>
actor = 'selik'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-04-14.03:36:59.214>
creator = 'selik'
dependencies = []
files = []
hgrepos = []
issue_num = 40278
keywords = []
message_count = 3.0
messages = ['366363', '366364', '366365']
nosy_count = 5.0
nosy_names = ['pitrou', 'docs@python', 'serhiy.storchaka', 'selik', 'xtreak']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue40278'
versions = ['Python 3.8']

[selik]

The pathlib module Path.replace(target) states that "If target points to an existing file or directory, it will be unconditionally replaced." However, this does not appear to be true. I experience an OSError [Errno 66] Directory not empty when attempting to replace to an existant target.

https://docs.python.org/3/library/pathlib.html#pathlib.Path.replace

I see that others on StackOverflow encounter the same issue. The top answer ignores the Python documentation and recommends removing the target directory before replacing.

https://stackoverflow.com/questions/50355180/use-pathlib-to-destructively-rename-one-directory-to-another-existing-directory

[tirkarthi]

replace under the hood uses os.replace. The docs for os.replace indicate error for certain scenarios where target is a directory : https://docs.python.org/3/library/os.html#os.replace . See also some difference between os.rename and os.replace : https://bugs.python.org/issue27886

[selik]

The docs for os.replace says "If dst is a directory, OSError will be raised." That's helpful, but the docs for pathlib.Path.replace make it seem like the target will be unconditionally replaced regardless of whether it's a file or directory. Sure, there's the association of the two functions in the correspondence table in the pathlib docs, but that's easy to overlook when looking up pathlib.Path.replace.

If nothing else, I guess this is a request to alter the docstring.