classification
Title: shutil.copyfile() documentation is vague
Type: Stage:
Components: Documentation Versions: Python 2.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: georg.brandl, roysmith
Priority: normal Keywords:

Created on 2008-04-15 16:11 by roysmith, last changed 2008-04-19 16:57 by georg.brandl. This issue is now closed.

Messages (3)
msg65521 - (view) Author: Roy Smith (roysmith) Date: 2008-04-15 16:11
The current doc says, "Copy the contents of the file named src to a file 
named dst".  Anybody used to the unix shell "cp" command would assume that 
dst could be a directory, in which case the true destination is a file in 
that directory with the same basename as src.  Experimentation shows that 
this is not true.  A note something like the following would help:

Note: unlike the "cp" shell command, dst may not be a directory; it must 
be a path to a file in that directory.

True, there's no place in the docs which actually says a directory is 
valid for dst, but the name of the module is shutil, so it's reasonable 
for people to assume that these act the same way as the corresponding unix 
shell commands.  It should be stated up front that this is not true, to 
avoid confusion.
msg65522 - (view) Author: Roy Smith (roysmith) Date: 2008-04-15 16:24
Reading closer, I see that copy() has the shell-like semantics I was 
expecting copyfile() to have.  Perhaps the right fix is to include a note in 
the copyfile() docs saying, "dst must be a file path; see also copy() for a 
version which allows dst to be a directory".

It might also make sense to move copy() to the top of the list, because it 
is the one which has the most shell-like semantics.
msg65631 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-04-19 16:57
Fixed in r62389.
History
Date User Action Args
2008-04-19 16:57:55georg.brandlsetstatus: open -> closed
resolution: fixed
messages: + msg65631
2008-04-15 16:24:43roysmithsetmessages: + msg65522
2008-04-15 16:11:05roysmithcreate