[docs] [issue16278] os.rename documentation slightly inaccurate
report at bugs.python.org
Thu Nov 8 05:01:20 CET 2012
Todd Rovito added the comment:
Here is a draft suggestion for the documentation change, not all the formatting is worked out:
.. function:: rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)
Rename the file or directory *src* to *dst*. If *src* exists as either
a file or directory and *dst* does not exist the rename will occur with
no error raised. In some cases the rename function will behave
differently across platforms which are noted below. In all cases
if *src* does not exist :exc: 'OSError' will be raised.
If *dst* exists and is a file, it will be replaced silently if the user
has permission and src is a file. If *src* is a directory and *dst* is a
file :exc: 'OSError' will be raised. In the case where *src* is a
directory and *dst* is a empty directory the rename will occur and the
*src* directory name will overwrite the *dst* directory name.Yet a special
case is noted where *src* is a directory and *dst* is a non-empty directory
the rename will not occur and :exc: `OSError` will be raised.
If *src* is a file and *dst* exists either as a file or directory :exc:
'OSError` will be raised and the rename will not occur. In the case where
*src* is a directory, either empty or not empty, and *dst* exists as a
file or not empty directory :exc: `OSError` will be raised. If *src* is
a directory, either empty or not empty, and *dst* is a empty directory
then :exc: `FileExistsError` will be raised.
If successful, the renaming will be an atomic operation (this is a POSIX
This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to
supply :ref:`paths relative to directory descriptors <dir_fd>`.
If you want cross-platform overwriting of the destination, use
Availability: Unix, Windows.
.. versionadded:: 3.3
The *src_dir_fd* and *dst_dir_fd* arguments.
Python tracker <report at bugs.python.org>
More information about the docs