Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

shutil.copyfile() documentation is vague #46891

Closed
roysmith mannequin opened this issue Apr 15, 2008 · 3 comments
Closed

shutil.copyfile() documentation is vague #46891

roysmith mannequin opened this issue Apr 15, 2008 · 3 comments
Assignees
@birkenfeld
Labels
docs Documentation in the Doc dir

Comments

@roysmith
Copy link
Mannequin

roysmith mannequin commented Apr 15, 2008

BPO 2639
Nosy @birkenfeld

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 = 'https://github.com/birkenfeld'
closed_at = <Date 2008-04-19.16:57:55.128>
created_at = <Date 2008-04-15.16:11:05.648>
labels = ['docs']
title = 'shutil.copyfile() documentation is vague'
updated_at = <Date 2008-04-19.16:57:55.110>
user = 'https://bugs.python.org/roysmith'

bugs.python.org fields:

activity = <Date 2008-04-19.16:57:55.110>
actor = 'georg.brandl'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2008-04-19.16:57:55.128>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2008-04-15.16:11:05.648>
creator = 'roysmith'
dependencies = []
files = []
hgrepos = []
issue_num = 2639
keywords = []
message_count = 3.0
messages = ['65521', '65522', '65631']
nosy_count = 2.0
nosy_names = ['georg.brandl', 'roysmith']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue2639'
versions = ['Python 2.5']
@roysmith
Copy link
Mannequin Author

roysmith mannequin commented Apr 15, 2008

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.

@roysmith roysmith mannequin assigned birkenfeld Apr 15, 2008
@roysmith roysmith mannequin added the docs Documentation in the Doc dir label Apr 15, 2008
@roysmith
Copy link
Mannequin Author

roysmith mannequin commented Apr 15, 2008

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.

@birkenfeld
Copy link
Member

Fixed in r62389.

@ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@birkenfeld birkenfeld

Labels
docs Documentation in the Doc dir
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@birkenfeld