(original) (raw)

changeset: 71591:6bf168b55d07 branch: 2.7 user: Éric Araujo merwok@netwok.org date: Fri Jul 29 12:10:53 2011 +0200 files: Doc/ACKS.txt Doc/library/shutil.rst description: 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 -r 4e5127874adf -r 6bf168b55d07 Doc/ACKS.txt --- a/Doc/ACKS.txt Fri Jul 29 12:07:31 2011 +0200 +++ b/Doc/ACKS.txt Fri Jul 29 12:10:53 2011 +0200 @@ -199,6 +199,7 @@ * Kalle Svensson * Jim Tittsler * David Turner + * Sandro Tosi * Ville Vainio * Martijn Vries * Charles G. Waldman diff -r 4e5127874adf -r 6bf168b55d07 Doc/library/shutil.rst --- a/Doc/library/shutil.rst Fri Jul 29 12:07:31 2011 +0200 +++ b/Doc/library/shutil.rst Fri Jul 29 12:10:53 2011 +0200 @@ -161,24 +161,31 @@ .. function:: move(src, dst) - Recursively move a file or directory to another location. + Recursively move a file or directory (*src*) to another location (*dst*). + + If the destination is a directory or a symlink to a directory, then *src* is + moved inside that directory. - 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*. + 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 @@ .. 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 @@ .. 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 /merwok@netwok.org