The shutil.copytree() function aknowledges symlinks when given
the symlink=True argument. Other shutil functions should do this
too:

copymode(src, dst, symlinks=True)
   If both src and dst are symlinks, copy the source symlink mode
   to the destination symlink. If only one of them is a symlink,
   dereference it normally.

copystat(src, dst, symlinks=True)
   If both src and dst are symlinks, copy the statinfo of the
   source symlink to the destination symlink. If only one of them
   is a symlink, dereference it normally.

copy(src, dst, symlinks=True)
   If the src argument is a symlink, copy the source symlink
   instead of dereferencing it.

   Problem: What if dst is a symlink to a directory? Should it be
   replaced or should the symlink copied inside that directory?

copy2(src, dst, symlinks=True)
   Like copy(src, dst, symlinks=True), but copy the metadata too.
   The same problem applies.

We could also have symlinks='require' to have copymode() and copystat() raise an error unless both src and dst are symlinks.

Additionally copyfile() might be fixed to understand symlinks=True too.

Currently working on a patch for all 5 of them.

> Problem: What if dst is a symlink to a directory? Should it be
> replaced or should the symlink copied inside that directory?

Doing what UNIX’ cp program does would be best here.

> Doing what UNIX’ cp program does would be best here.

$ cp --version
cp (GNU coreutils) 8.5

$ touch file
$ ln -s file link_to_file 
$ mkdir directory
$ ln -s directory link_to_directory
$ cp -a link_to_file link_to_directory
$ ls -l directory
lrwxrwxrwx 1 user user 4 2011-08-09 17:46 link_to_file -> file

So at least cp from GNU coreutils seems to copy the link into the directory, dereferencing the dst link.

JFTR, my implementation is ready, but I can't/don't want to start writing tests, as long as #12721 is open.

Other reports related to shutil and symlinks: #9993, #4489, #12461.

We have an edge case when the caller calls copymode with symlinks=True on an OS that doesn't have lchmod (ie any other than FreeBSD).

Should it be a nop (as in copystat), use chmod or raise an Exception?

I Personally (and some people on #python-dev) believe it should raise an Exception as the caller made the effort to say that (s)he wants the link _not_ to be followed and it's just one operation (contrary to copystat that does several things).

What started as a 2 lines fix, grew to a patch of ~400 lines. :)

It's mostly tests though:

Lib/shutil.py           |  102 +++++++++++++++++++++++++++++----------
Lib/test/test_shutil.py |  220 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Misc/ACKS               |    1 +
3 files changed, 297 insertions(+), 26 deletions(-)

I've AFAIS implemented the desired behavior and hope for feedback/bug reports.

It's tested on Linux & FreeBSD 8.2 and applies cleanly against default/tip.

Please let me know if I've done something stupid.

I have updated the patch to latest default/tip and would appreciate a review.

I've done a review at http://bugs.python.org/review/12715

Thanks to Antoine & Charles-François for their reviews! I think I've incorporated all desired changes.

Please let me know if I have missed something, meanwhile I'll tackle the docs.

The patch contains also the necessary changes for the docs now.

Please let me know, if I can do anything else.

Added another patch fixing the issues pointed out by Antoine and Charles-François.

Added new patch with protection for the remaining UF_NODUMPs in the test case. All raised issues should be fixed now. :)

I've checked the latest patch to work fine under Windows 7 (and Linux, of course).

New changeset cf57ef65bcd0 by Antoine Pitrou in branch 'default':
Issue #12715: Add an optional symlinks argument to shutil functions (copyfile, copymode, copystat, copy, copy2).
http://hg.python.org/cpython/rev/cf57ef65bcd0

Patch is now applied to 3.3, thank you for your patience :)