Issue #8828: Add new function os.replace(), for cross-platform renaming with overwriting.

1 files changed, 16 insertions, 2 deletions

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 3c302a4..617f276 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1889,8 +1889,9 @@ Files and Directories
    Unix flavors if *src* and *dst* are on different filesystems.  If successful,
    the renaming will be an atomic operation (this is a POSIX requirement).  On
    Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
-   file; there may be no way to implement an atomic rename when *dst* names an
-   existing file.
+   file.
+
+   If you want cross-platform overwriting of the destination, use :func:`replace`.
 
    Availability: Unix, Windows.
 
@@ -1908,6 +1909,19 @@ Files and Directories
       permissions needed to remove the leaf directory or file.
 
 
+.. function:: replace(src, dst)
+
+   Rename the file or directory *src* to *dst*.  If *dst* is a directory,
+   :exc:`OSError` will be raised.  If *dst* exists and is a file, it will
+   be replaced silently if the user has permission.  The operation may fail
+   if *src* and *dst* are on different filesystems.  If successful,
+   the renaming will be an atomic operation (this is a POSIX requirement).
+
+   Availability: Unix, Windows
+
+   .. versionadded:: 3.3
+
+
 .. function:: rmdir(path)
 
    Remove (delete) the directory *path*.  Only works when the directory is