[Python-checkins] cpython (3.2): Update documentation for shutil.move (#12043) and fix a few typos.

Fri Jul 29 14:35:25 CEST 2011

http://hg.python.org/cpython/rev/836548ce4cd2
changeset: 71563:836548ce4cd2
branch: 3.2
user: Éric Araujo <merwok at netwok.org>
date: Thu Jul 28 22:49:11 2011 +0200
summary:
 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.
files:
 Doc/ACKS.txt | 1 +
 Doc/library/shutil.rst | 26 ++++++++++++++++----------
 2 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt
--- a/Doc/ACKS.txt
+++ b/Doc/ACKS.txt
@@ -203,6 +203,7 @@
 * 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
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -159,19 +159,25 @@
 
 .. 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.
 
 
 .. 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*).
 
 
 .. _shutil-example:
@@ -269,7 +275,7 @@
 
 .. 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:
@@ -287,7 +293,7 @@
 
 .. 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)`` pairs that will be
-- 
Repository URL: http://hg.python.org/cpython
