Misleading shutil.move docs regarding when os.rename is used

[cataliniacob]

BPO	12577
Nosy	@orsenthil
Files	clarify-shutil.move-docs.patch

^{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 2011-07-19.00:06:05.244>
created_at = <Date 2011-07-17.08:59:21.222>
labels = ['docs']
title = 'Misleading shutil.move docs regarding when os.rename is used'
updated_at = <Date 2011-07-19.00:06:05.242>
user = 'https://bugs.python.org/cataliniacob'

bugs.python.org fields:

activity = <Date 2011-07-19.00:06:05.242>
actor = 'python-dev'
assignee = 'docs@python'
closed = True
closed_date = <Date 2011-07-19.00:06:05.244>
closer = 'python-dev'
components = ['Documentation']
creation = <Date 2011-07-17.08:59:21.222>
creator = 'catalin.iacob'
dependencies = []
files = ['22679']
hgrepos = []
issue_num = 12577
keywords = ['patch']
message_count = 5.0
messages = ['140520', '140521', '140543', '140567', '140636']
nosy_count = 4.0
nosy_names = ['orsenthil', 'docs@python', 'catalin.iacob', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue12577'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3']

[cataliniacob]

I recently tried to answer the question: "When moving a file to a destination that is an already existing file, is the destination overwritten?"

From the current docs I understood that if src and dst are on the same filesystem then os.rename is used, if they are on different filesystems then copy + remove is used instead. Since os.rename fails on Windows if the destination exists I concluded that shutil.move would fail on Windows and overwrite dst on Unix.

[cataliniacob]

Attached patch which clarifies that the copy fallback is used whenever os.rename fails not just for the different filesystems case.

[orsenthil]

Should information on Windows behavior, which you experienced be included too?

How about -

It uses :func:`os.rename` to perform the move. If that fails, for example
because src and dst are on different filesystems or in case of Windows where rename cannot be done if dst exists, fallback to copying src (with :func:`copy2`) to the dst and then removing src.

[cataliniacob]

Senthil's proposal in msg140543 has +1 from me.

[python-dev]

New changeset 62048a6eb43c by Senthil Kumaran in branch '3.2':
Fix closes bpo-12577 - clarify shutil.move documentation. Patch suggestion by Catalin Iacob
http://hg.python.org/cpython/rev/62048a6eb43c

New changeset 912b97ee40a7 by Senthil Kumaran in branch 'default':
merge from 3.2 - Fix closes bpo-12577 - clarify shutil.move documentation. Patch suggestion by Catalin Iacob
http://hg.python.org/cpython/rev/912b97ee40a7

New changeset 33f09733612e by Senthil Kumaran in branch '2.7':
merge from 3.2 - Fix closes bpo-12577 - clarify shutil.move documentation. Patch suggestion by Catalin Iacob
http://hg.python.org/cpython/rev/33f09733612e