Document behaviour of shutil.copy2 and copystat with symlinks

[socketpair]

BPO	12183
Nosy	@orsenthil, @tarekziade, @ezio-melotti, @socketpair, @akheron
Files	copy2_copytree_symlinks_2.7.patch: documentation patch for 2.7 copy2_copytree_symlinks_2.7_v2.patch: documentation patch for 2.7

^{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-08-02.10:53:22.526>
created_at = <Date 2011-05-26.04:41:59.882>
labels = ['type-feature', 'library', 'docs']
title = 'Document behaviour of shutil.copy2 and copystat with symlinks'
updated_at = <Date 2011-08-02.14:52:16.306>
user = 'https://github.com/socketpair'

bugs.python.org fields:

activity = <Date 2011-08-02.14:52:16.306>
actor = 'ezio.melotti'
assignee = 'docs@python'
closed = True
closed_date = <Date 2011-08-02.10:53:22.526>
closer = 'python-dev'
components = ['Documentation', 'Library (Lib)']
creation = <Date 2011-05-26.04:41:59.882>
creator = 'socketpair'
dependencies = []
files = ['22607', '22812']
hgrepos = []
issue_num = 12183
keywords = ['patch', 'needs review']
message_count = 12.0
messages = ['136928', '136932', '139991', '139992', '141444', '141474', '141555', '141556', '141557', '141564', '141566', '141567']
nosy_count = 8.0
nosy_names = ['orsenthil', 'tarek', 'ezio.melotti', 'docs@python', 'rosslagerwall', 'socketpair', 'python-dev', 'petri.lehtinen']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue12183'
versions = ['Python 2.7', 'Python 3.3']

[socketpair]

see
http://www.linuxquestions.org/questions/programming-9/utime-on-a-symbolic-link-743085/:
----------
Hello,
The API utime() is not available for symbolic links.
However, with kernel 2.6.22 lutimes() API allowed setting times on atime and mtime on symbolic links.
----------

Neither python 2.7 nor 3.4 support lutime() syscall.
So imlpementation of shutil.copy2() and shutil.copystat() under question for symlinks. Also it's not clear in documentation behaviour of these functions on symlinks.

[rosslagerwall]

Python 3.3 (as yet unreleased) supports the lutimes function:
http://docs.python.org/dev/py3k/library/os.html#os.lutimes
Python 2.7 is not getting any more features so it will not be added.

I'm changing the title to the second part of your question, documenting the behaviour of shutil.copy2 and copytree.

[akheron]

Shouldn't at least shutil.copytree() use lutimes in Python 3.3 to copy symlink metadata if symlinks=True?

[akheron]

Attached a patch that documents the behavior of copy2() and copytree() for symlinks.

[orsenthil]

When shutil.copy2 already says that it's behavior is equivalent to cp -p, will adding this sentence

+ Symbolic links are not preserved. The contents and metadata of the
+ linked files are copied instead.

Not actively confuse the user? Because cp -p's behavior includes that and I dont see a special mention without giving more details is going to help.

The other portion of the patch seems okay to me.

[akheron]

Senthil Kumaran wrote:

When shutil.copy2 already says that it's behavior is equivalent to cp -p, will adding this sentence

• Symbolic links are not preserved. The contents and metadata of the
• linked files are copied instead.

Not actively confuse the user? Because cp -p's behavior includes
that and I dont see a special mention without giving more details is
going to help.

You're right. Only copytree() seems to understand symlinks, so
deferencing symlinks is the "default" mode of operation.

I updated the patch to remove the first hunk.

[python-dev]

New changeset 209ad8920b03 by Senthil Kumaran in branch '2.7':
Fix closes bpo-12183 - Explain the Symlink copy behavior in shutil.copytree. Patch by Petri Lehtinen.
http://hg.python.org/cpython/rev/209ad8920b03

[python-dev]

New changeset 299992730c87 by Senthil Kumaran in branch '3.2':
Fix closes bpo-12183 - Explain the Symlink copy behavior in shutil.copytree. Patch by Petri Lehtinen.
http://hg.python.org/cpython/rev/299992730c87

[orsenthil]

Petri, Thanks for the patch. It would also be helpful to track - "shutil.copytree() use lutimes in Python 3.3 to copy symlink metadata if symlinks=True". You can raise a feature request if it is not already raised. Thanks!.

[python-dev]

New changeset 746dc0a2398e by Ezio Melotti in branch 'default':
bpo-12183: merge with 3.2.
http://hg.python.org/cpython/rev/746dc0a2398e

[orsenthil]

Hi Ezio,

It was intentional that I did not merge it to default. We want
shutil.copystat to use lutimes which is available in 3.3 and in which
case, we will have to remove this once that change is done.

[ezio-melotti]

I applied it because the patch is valid on 3.3 too until we actually change copystat to use lutimes. If/when shutil is changed the doc can be updated accordingly.