From cb4f76fca28348cbf9410410dcac7bcfd2359a53 Mon Sep 17 00:00:00 2001
From: Jon Dufresne <jon.dufresne@gmail.com>
Date: Sun, 13 Dec 2020 09:30:00 -0800
Subject: [PATCH] Deprecate sphinx.util.osutil.movefile() in favor of
 os.replace()

The utility function movefile() was added in
677d096393bca948eea8fad252bd859ed8142309 to handle existing files on
Windows. Since Python 3.3, the stdlib function os.replace() fills this
role.
---
 CHANGES                                     | 1 +
 doc/extdev/deprecated.rst                   | 5 +++++
 sphinx/builders/html/__init__.py            | 5 +++--
 sphinx/transforms/post_transforms/images.py | 4 ++--
 sphinx/util/osutil.py                       | 5 ++++-
 5 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/CHANGES b/CHANGES
index c6a38a7015c..ea26fd9eda6 100644
--- a/CHANGES
+++ b/CHANGES
@@ -24,6 +24,7 @@ Deprecated
 * ``sphinx.ext.autodoc.TypeVarDocumenter``
 * ``sphinx.ext.autodoc.importer._getannotations()``
 * ``sphinx.pycode.ModuleAnalyzer.parse()``
+* ``sphinx.util.osutil.movefile()``
 * ``sphinx.util.requests.is_ssl_error()``
 
 Features added
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index cbdf3135069..c167e509c18 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -77,6 +77,11 @@ The following is a list of deprecated interfaces.
      - 5.0
      - ``sphinx.pycode.ModuleAnalyzer.analyze()``
 
+   * - ``sphinx.util.osutil.movefile()``
+     - 3.4
+     - 5.0
+     - ``os.replace()``
+
    * - ``sphinx.util.requests.is_ssl_error()``
      - 3.4
      - 5.0
diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py
index ad575c08611..641d0eda2ca 100644
--- a/sphinx/builders/html/__init__.py
+++ b/sphinx/builders/html/__init__.py
@@ -9,6 +9,7 @@
 """
 
 import html
+import os
 import posixpath
 import re
 import sys
@@ -44,7 +45,7 @@
 from sphinx.util.i18n import format_date
 from sphinx.util.inventory import InventoryFile
 from sphinx.util.matching import DOTFILES, Matcher, patmatch
-from sphinx.util.osutil import copyfile, ensuredir, movefile, os_path, relative_uri
+from sphinx.util.osutil import copyfile, ensuredir, os_path, relative_uri
 from sphinx.util.tags import Tags
 from sphinx.writers.html import HTMLTranslator, HTMLWriter
 
@@ -1070,7 +1071,7 @@ def dump_search_index(self) -> None:
             else:
                 with open(searchindexfn + '.tmp', 'wb') as fb:
                     self.indexer.dump(fb, self.indexer_format)
-            movefile(searchindexfn + '.tmp', searchindexfn)
+            os.replace(searchindexfn + '.tmp', searchindexfn)
 
 
 def convert_html_css_files(app: Sphinx, config: Config) -> None:
diff --git a/sphinx/transforms/post_transforms/images.py b/sphinx/transforms/post_transforms/images.py
index 4865aa61536..a7002343686 100644
--- a/sphinx/transforms/post_transforms/images.py
+++ b/sphinx/transforms/post_transforms/images.py
@@ -20,7 +20,7 @@
 from sphinx.transforms import SphinxTransform
 from sphinx.util import epoch_to_rfc1123, logging, requests, rfc1123_to_epoch, sha1
 from sphinx.util.images import get_image_extension, guess_mimetype, parse_data_uri
-from sphinx.util.osutil import ensuredir, movefile
+from sphinx.util.osutil import ensuredir
 
 logger = logging.getLogger(__name__)
 
@@ -99,7 +99,7 @@ def handle(self, node: nodes.image) -> None:
                     # append a suffix if URI does not contain suffix
                     ext = get_image_extension(mimetype)
                     newpath = os.path.join(self.imagedir, dirname, basename + ext)
-                    movefile(path, newpath)
+                    os.replace(path, newpath)
                     self.app.env.original_image_uri.pop(path)
                     self.app.env.original_image_uri[newpath] = node['uri']
                     path = newpath
diff --git a/sphinx/util/osutil.py b/sphinx/util/osutil.py
index 59fd059e65e..abbb0617a6b 100644
--- a/sphinx/util/osutil.py
+++ b/sphinx/util/osutil.py
@@ -20,7 +20,7 @@
 from os import path
 from typing import Any, Generator, Iterator, List, Optional, Tuple
 
-from sphinx.deprecation import RemovedInSphinx40Warning
+from sphinx.deprecation import RemovedInSphinx40Warning, RemovedInSphinx50Warning
 
 try:
     # for ALT Linux (#6712)
@@ -103,6 +103,9 @@ def mtimes_of_files(dirnames: List[str], suffix: str) -> Iterator[float]:
 
 def movefile(source: str, dest: str) -> None:
     """Move a file, removing the destination if it exists."""
+    warnings.warn('sphinx.util.osutil.movefile() is deprecated for removal. '
+                  'Please use os.replace() instead.',
+                  RemovedInSphinx50Warning, stacklevel=2)
     if os.path.exists(dest):
         try:
             os.unlink(dest)