Issue #8828: Add new function os.replace(), for cross-platform renaming with overwriting.
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 @@
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 @@
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