Update documentation for shutil.move (#12043) and fix a few typos.

Adding Sandro Tosi to Doc/ACKS for this patch and all his work on the
docs mailing list and on the bug tracker.

diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt
index 774192e812fc22f5e6cf9a999f23751a52e01210..1e44cf7d0275e99f4476803204020351a244203d 100644 (file)
--- a/Doc/ACKS.txt
+++ b/Doc/ACKS.txt
@@ -199,6 +199,7 @@ docs@python.org), and we'll be glad to correct the problem.
    * Kalle Svensson
    * Jim Tittsler
    * David Turner
+   * Sandro Tosi
    * Ville Vainio
    * Martijn Vries
    * Charles G. Waldman

diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index ed622addc9b70fb7426e0d5681403ac78d171563..1082d2a37b4e559c65aba893254f164add136cc5 100644 (file)
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -161,24 +161,31 @@ Directory and files operations
 
 .. function:: move(src, dst)
 
-   Recursively move a file or directory to another location.
+   Recursively move a file or directory (*src*) to another location (*dst*).
 
-   Uses :func:`os.rename` to perform the move. If it fails, for reasons such as
-   when *src* and *dst* are on different filesystems or in case of windows where
-   rename is not supported when *dst* exists, fallback to copying *src* (with
-   :func:`copy2`) to the *dst* and then remove *src*.
+   If the destination is a directory or a symlink to a directory, then *src* is
+   moved inside that directory.
+
+   The destination directory must not already exist.  If the destination already
+   exists but is not a directory, it may be overwritten depending on
+   :func:`os.rename` semantics.
+
+   If the destination is on the current filesystem, then :func:`os.rename` is
+   used.  Otherwise, *src* is copied (using :func:`copy2`) to *dst* and then
+   removed.
 
    .. versionadded:: 2.3
 
 
 .. exception:: Error
 
-   This exception collects exceptions that raised during a multi-file operation. For
-   :func:`copytree`, the exception argument is a list of 3-tuples (*srcname*,
-   *dstname*, *exception*).
+   This exception collects exceptions that are raised during a multi-file
+   operation. For :func:`copytree`, the exception argument is a list of 3-tuples
+   (*srcname*, *dstname*, *exception*).
 
    .. versionadded:: 2.3
 
+
 .. _shutil-example:
 
 copytree example
@@ -277,7 +284,7 @@ Archives operations
 
 .. function:: get_archive_formats()
 
-   Returns a list of supported formats for archiving.
+   Return a list of supported formats for archiving.
    Each element of the returned sequence is a tuple ``(name, description)``
 
    By default :mod:`shutil` provides these formats:
@@ -295,7 +302,7 @@ Archives operations
 
 .. function:: register_archive_format(name, function, [extra_args, [description]])
 
-   Registers an archiver for the format *name*. *function* is a callable that
+   Register an archiver for the format *name*. *function* is a callable that
    will be used to invoke the archiver.
 
    If given, *extra_args* is a sequence of ``(name, value)`` that will be