This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Document behaviour of shutil.copy2 and copystat with symlinks
Type: enhancement Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ezio.melotti, orsenthil, petri.lehtinen, python-dev, rosslagerwall, socketpair, tarek
Priority: normal Keywords: needs review, patch

Created on 2011-05-26 04:41 by socketpair, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
copy2_copytree_symlinks_2.7.patch petri.lehtinen, 2011-07-07 18:59 documentation patch for 2.7
copy2_copytree_symlinks_2.7_v2.patch petri.lehtinen, 2011-07-31 18:08 documentation patch for 2.7
Messages (12)
msg136928 - (view) Author: Марк Коренберг (socketpair) * Date: 2011-05-26 04:41
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.
msg136932 - (view) Author: Ross Lagerwall (rosslagerwall) (Python committer) Date: 2011-05-26 05:35
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.
msg139991 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2011-07-07 18:48
Shouldn't at least shutil.copytree() use lutimes in Python 3.3 to copy symlink metadata if symlinks=True?
msg139992 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2011-07-07 18:59
Attached a patch that documents the behavior of copy2() and copytree() for symlinks.
msg141444 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2011-07-30 15:37
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.
msg141474 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2011-07-31 18:08
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.
msg141555 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-08-02 10:53
New changeset 209ad8920b03 by Senthil Kumaran in branch '2.7':
Fix closes Issue12183 - Explain the Symlink copy behavior in shutil.copytree. Patch by Petri Lehtinen.
http://hg.python.org/cpython/rev/209ad8920b03
msg141556 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-08-02 10:55
New changeset 299992730c87 by Senthil Kumaran in branch '3.2':
Fix closes Issue12183 - Explain the Symlink copy behavior in shutil.copytree. Patch by Petri Lehtinen.
http://hg.python.org/cpython/rev/299992730c87
msg141557 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2011-08-02 10:57
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!.
msg141564 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-08-02 14:42
New changeset 746dc0a2398e by Ezio Melotti in branch 'default':
#12183: merge with 3.2.
http://hg.python.org/cpython/rev/746dc0a2398e
msg141566 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2011-08-02 14:50
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.
msg141567 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-08-02 14:52
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.
History
Date User Action Args
2022-04-11 14:57:17adminsetgithub: 56392
2011-08-02 14:52:16ezio.melottisetnosy: + ezio.melotti
messages: + msg141567
2011-08-02 14:50:08orsenthilsetmessages: + msg141566
2011-08-02 14:42:40python-devsetmessages: + msg141564
2011-08-02 10:57:12orsenthilsetmessages: + msg141557
2011-08-02 10:55:23python-devsetmessages: + msg141556
2011-08-02 10:53:22python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg141555

resolution: fixed
stage: patch review -> resolved
2011-07-31 18:08:32petri.lehtinensetfiles: + copy2_copytree_symlinks_2.7_v2.patch

messages: + msg141474
2011-07-30 15:37:59orsenthilsetnosy: + orsenthil
messages: + msg141444
2011-07-07 19:00:00petri.lehtinensetnosy: + tarek
2011-07-07 18:59:13petri.lehtinensetkeywords: + patch, needs review
files: + copy2_copytree_symlinks_2.7.patch
messages: + msg139992

stage: patch review
2011-07-07 18:48:22petri.lehtinensetmessages: + msg139991
versions: - Python 3.1, Python 3.2
2011-05-26 05:52:58petri.lehtinensetnosy: + petri.lehtinen
2011-05-26 05:35:02rosslagerwallsetnosy: + rosslagerwall
title: Python does not support lutime() function -> Document behaviour of shutil.copy2 and copystat with symlinks
messages: + msg136932

versions: + Python 3.1, Python 3.2, Python 3.3, - Python 3.4
2011-05-26 04:41:59socketpaircreate