Deprecate sphinx.util.osutil.movefile() in favor of os.replace()

The utility function movefile() was added in
677d096393 to handle existing files on
Windows. Since Python 3.3, the stdlib function os.replace() fills this
role.

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

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

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.fileutil import copy_asset
 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 @@ class StandaloneHTMLBuilder(Builder):
             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:

sphinx/transforms/post_transforms/images.py

@@ -20,7 +20,7 @@ from sphinx.locale import __
 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 @@ class ImageDownloader(BaseImageConverter):
                     # 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

sphinx/util/osutil.py

@@ -20,7 +20,7 @@ from io import StringIO
 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)