Message175133
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.
Unix
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.
Windows
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
requirement).
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
:func:`replace`.
Availability: Unix, Windows.
.. versionadded:: 3.3
The *src_dir_fd* and *dst_dir_fd* arguments. |
|
Date |
User |
Action |
Args |
2012-11-08 04:01:20 | Todd.Rovito | set | recipients:
+ Todd.Rovito, asvetlov, chris.jerdonek, docs@python, David.Benjamin |
2012-11-08 04:01:19 | Todd.Rovito | set | messageid: <1352347279.93.0.861802849409.issue16278@psf.upfronthosting.co.za> |
2012-11-08 04:01:19 | Todd.Rovito | link | issue16278 messages |
2012-11-08 04:01:18 | Todd.Rovito | create | |
|