[docs] [issue12183] Document behaviour of shutil.copy2 and copystat with symlinks

[Petri Lehtinen]

Petri Lehtinen <petri at digip.org> added the comment:

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.

----------
Added file: http://bugs.python.org/file22812/copy2_copytree_symlinks_2.7_v2.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12183>
_______________________________________
-------------- next part --------------
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index 1b160d8..99ee111 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -105,8 +108,9 @@ Directory and files operations
    :func:`copy2`.
 
    If *symlinks* is true, symbolic links in the source tree are represented as
-   symbolic links in the new tree; if false or omitted, the contents of the
-   linked files are copied to the new tree.
+   symbolic links in the new tree, but the metadata of the original links is NOT
+   copied; if false or omitted, the contents and metadata of the linked files
+   are copied to the new tree.
 
    If *ignore* is given, it must be a callable that will receive as its
    arguments the directory being visited by :func:`copytree`, and a list of its