Title: Misleading sentence in doc for shutil.move
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, docs@python, newbie, python-dev, r.david.murray
Priority: normal Keywords: easy, patch

Created on 2014-11-24 17:10 by newbie, last changed 2015-03-22 14:15 by python-dev. This issue is now closed.

File name Uploaded Description Edit
shutil_2.7.patch Mike.Short, 2015-03-22 01:54 review
shutil_latest.patch Mike.Short, 2015-03-22 01:54 review
Messages (3)
msg231612 - (view) Author: newbie (newbie) Date: 2014-11-24 17:10
First sentence of 3rd paragraph of 10.10. "shutil" documentation for shutil.move command, "The destination directory must not already exist", is misleading and contradicts other information in the entry.  I took it to mean that if dst did not exist, python would create it as a directory.  What actually happens is that python renames src to dst. In my test, I was moving several files to a new directory, and the result was a file with the pathname dst and contents matching the last move command, consistent with the behavior described in the rest of the paragraph and the following one. When I changed the code to create the directory with os.mkdirs before calling shutil.move, it worked as I wanted, so obviously there's nothing wrong with the destination directory already existing. The preceding paragraph implies this with its description of behavior when dst refers to a directory.  I suggest removing this sentence, and maybe adding some text indicating what to do if you want to move a file to a new directory.
I was using Python 2.7.5 on Windows, and branch 2.7.8 of the documentation (there does not appear to be a branch 2.7.5 available.)
msg231616 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-11-24 18:32
I think you are correct that that sentence should just be deleted.  The preceding sentence should start "If the destination is an existing directory..."

I also wonder if shutil should be changed to use os.replace, but that is a separate issue.
msg238899 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-03-22 14:15
New changeset e5de4ee6aa4a by Benjamin Peterson in branch '3.4':
clarify behavior of shutil.move when destination exists (closes #22933)

New changeset 4502e598fe26 by Benjamin Peterson in branch '2.7':
clarify behavior of shutil.move when destination exists (closes #22933)

New changeset a9f36ec5d944 by Benjamin Peterson in branch 'default':
merge 3.4 (#22933)
Date User Action Args
2015-03-22 14:15:19python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg238899

resolution: fixed
stage: needs patch -> resolved
2015-03-22 01:54:26Mike.Shortsetfiles: + shutil_latest.patch
2015-03-22 01:54:08Mike.Shortsetfiles: + shutil_2.7.patch
keywords: + patch
2015-03-04 02:41:43berker.peksagsetnosy: + berker.peksag
2015-03-02 08:31:44ezio.melottisetkeywords: + easy
stage: needs patch
2014-11-24 18:32:31r.david.murraysetnosy: + r.david.murray

messages: + msg231616
versions: + Python 3.4, Python 3.5
2014-11-24 17:10:36newbiecreate