[docs] [issue16278] os.rename documentation slightly inaccurate

[Todd Rovito]

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.

   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.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue16278>
_______________________________________