Replace deprecation tooling with module level ``__getattr__`` (#11054)

3 files changed, 61 insertions, 50 deletions

diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py
index 3c64acf1c..a330cfc2f 100644
--- a/sphinx/util/__init__.py
+++ b/sphinx/util/__init__.py
@@ -13,11 +13,7 @@ from os import path
 from typing import IO, Any, Iterable
 from urllib.parse import parse_qsl, quote_plus, urlencode, urlsplit, urlunsplit
 
-from sphinx.deprecation import (
-    RemovedInSphinx70Warning,
-    RemovedInSphinx80Warning,
-    deprecated_alias,
-)
+from sphinx.deprecation import RemovedInSphinx70Warning
 from sphinx.errors import ExtensionError, FiletypeNotFoundError
 from sphinx.locale import __
 from sphinx.util import display as _display
@@ -388,29 +384,29 @@ def _xml_name_checker():
     return _XML_NAME_PATTERN
 
 
-deprecated_alias('sphinx.util',
-                 {
-                     'path_stabilize': _osutil.path_stabilize,
-                     'display_chunk': _display.display_chunk,
-                     'status_iterator': _display.status_iterator,
-                     'SkipProgressMessage': _display.SkipProgressMessage,
-                     'progress_message': _display.progress_message,
-                     'epoch_to_rfc1123': _http_date.epoch_to_rfc1123,
-                     'rfc1123_to_epoch': _http_date.rfc1123_to_epoch,
-                     'save_traceback': _exceptions.save_traceback,
-                     'format_exception_cut_frames': _exceptions.format_exception_cut_frames,
-                     'xmlname_checker': _xml_name_checker,
-                 },
-                 RemovedInSphinx80Warning,
-                 {
-                     'path_stabilize': 'sphinx.util.osutil.path_stabilize',
-                     'display_chunk': 'sphinx.util.display.display_chunk',
-                     'status_iterator': 'sphinx.util.display.status_iterator',
-                     'SkipProgressMessage': 'sphinx.util.display.SkipProgressMessage',
-                     'progress_message': 'sphinx.util.display.progress_message',
-                     'epoch_to_rfc1123': 'sphinx.http_date.epoch_to_rfc1123',
-                     'rfc1123_to_epoch': 'sphinx.http_date.rfc1123_to_epoch',
-                     'save_traceback': 'sphinx.exceptions.save_traceback',
-                     'format_exception_cut_frames': 'sphinx.exceptions.format_exception_cut_frames',  # NoQA: E501
-                     'xmlname_checker': 'sphinx.builders.epub3._XML_NAME_PATTERN',
-                 })
+# deprecated name -> (object to return, canonical path or empty string)
+_DEPRECATED_OBJECTS = {
+    'path_stabilize': (_osutil.path_stabilize, 'sphinx.util.osutil.path_stabilize'),
+    'display_chunk': (_display.display_chunk, 'sphinx.util.display.display_chunk'),
+    'status_iterator': (_display.status_iterator, 'sphinx.util.display.status_iterator'),
+    'SkipProgressMessage': (_display.SkipProgressMessage,
+                            'sphinx.util.display.SkipProgressMessage'),
+    'progress_message': (_display.progress_message, 'sphinx.http_date.epoch_to_rfc1123'),
+    'epoch_to_rfc1123': (_http_date.epoch_to_rfc1123, 'sphinx.http_date.rfc1123_to_epoch'),
+    'rfc1123_to_epoch': (_http_date.rfc1123_to_epoch, 'sphinx.http_date.rfc1123_to_epoch'),
+    'save_traceback': (_exceptions.save_traceback, 'sphinx.exceptions.save_traceback'),
+    'format_exception_cut_frames': (_exceptions.format_exception_cut_frames,
+                                    'sphinx.exceptions.format_exception_cut_frames'),
+    'xmlname_checker': (_xml_name_checker, 'sphinx.builders.epub3._XML_NAME_PATTERN'),
+}
+
+
+def __getattr__(name):
+    if name not in _DEPRECATED_OBJECTS:
+        raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+    from sphinx.deprecation import _deprecation_warning
+
+    deprecated_object, canonical_name = _DEPRECATED_OBJECTS[name]
+    _deprecation_warning(__name__, name, canonical_name, remove=(8, 0))
+    return deprecated_object
diff --git a/sphinx/util/docutils.py b/sphinx/util/docutils.py
index 66670d764..b2a8f2a06 100644
--- a/sphinx/util/docutils.py
+++ b/sphinx/util/docutils.py
@@ -21,7 +21,6 @@ from docutils.statemachine import State, StateMachine, StringList
 from docutils.utils import Reporter, unescape
 from docutils.writers._html_base import HTMLTranslator
 
-from sphinx.deprecation import RemovedInSphinx70Warning, deprecated_alias
 from sphinx.errors import SphinxError
 from sphinx.locale import _, __
 from sphinx.util import logging
@@ -37,14 +36,23 @@ if TYPE_CHECKING:
     from sphinx.config import Config
     from sphinx.environment import BuildEnvironment
 
-deprecated_alias('sphinx.util.docutils',
-                 {
-                     '__version_info__': docutils.__version_info__,
-                 },
-                 RemovedInSphinx70Warning,
-                 {
-                     '__version_info__': 'docutils.__version_info__',
-                 })
+# deprecated name -> (object to return, canonical path or empty string)
+_DEPRECATED_OBJECTS = {
+    '__version_info__': (docutils.__version_info__, 'docutils.__version_info__'),
+}
+
+
+def __getattr__(name):
+    if name not in _DEPRECATED_OBJECTS:
+        raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+    from sphinx.deprecation import _deprecation_warning
+
+    deprecated_object, canonical_name = _DEPRECATED_OBJECTS[name]
+    _deprecation_warning(__name__, name, canonical_name, remove=(7, 0))
+    return deprecated_object
+
+
 additional_nodes: set[type[Element]] = set()
 
 
@@ -361,6 +369,8 @@ class NullReporter(Reporter):
 
 
 def is_html5_writer_available() -> bool:
+    from sphinx.deprecation import RemovedInSphinx70Warning
+
     warnings.warn('is_html5_writer_available() is deprecated.',
                   RemovedInSphinx70Warning)
     return True
diff --git a/sphinx/util/typing.py b/sphinx/util/typing.py
index 282230e0c..cb571e420 100644
--- a/sphinx/util/typing.py
+++ b/sphinx/util/typing.py
@@ -11,8 +11,6 @@ from typing import Any, Callable, Dict, ForwardRef, List, Tuple, TypeVar, Union
 from docutils import nodes
 from docutils.parsers.rst.states import Inliner
 
-from sphinx.deprecation import RemovedInSphinx80Warning, deprecated_alias
-
 try:
     from types import UnionType  # type: ignore  # python 3.10 or above
 except ImportError:
@@ -342,11 +340,18 @@ def stringify_annotation(
     return module_prefix + qualname
 
 
-deprecated_alias(__name__,
-                 {
-                     'stringify': stringify_annotation,
-                 },
-                 RemovedInSphinx80Warning,
-                 {
-                     'stringify': 'sphinx.util.typing.stringify_annotation',
-                 })
+# deprecated name -> (object to return, canonical path or empty string)
+_DEPRECATED_OBJECTS = {
+    'stringify': (stringify_annotation, 'sphinx.util.typing.stringify_annotation'),
+}
+
+
+def __getattr__(name):
+    if name not in _DEPRECATED_OBJECTS:
+        raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+    from sphinx.deprecation import _deprecation_warning
+
+    deprecated_object, canonical_name = _DEPRECATED_OBJECTS[name]
+    _deprecation_warning(__name__, name, canonical_name, remove=(8, 0))
+    return deprecated_object