1 files changed, 66 insertions, 0 deletions
diff --git a/sphinx/deprecation.py b/sphinx/deprecation.py
new file mode 100644
index 0000000..8a242d7
--- /dev/null
+++ b/sphinx/deprecation.py
@@ -0,0 +1,66 @@
+"""Sphinx deprecation classes and utilities."""
+
+from __future__ import annotations
+
+import warnings
+
+
+class RemovedInSphinx80Warning(DeprecationWarning):
+    pass
+
+
+class RemovedInSphinx90Warning(PendingDeprecationWarning):
+    pass
+
+
+RemovedInNextVersionWarning = RemovedInSphinx80Warning
+
+
+def _deprecation_warning(
+    module: str,
+    attribute: str,
+    canonical_name: str,
+    *,
+    remove: tuple[int, int],
+) -> None:
+    """Helper function for module-level deprecations using __getattr__
+
+    Exemplar usage:
+
+    .. code:: python
+
+       # deprecated name -> (object to return, canonical path or empty string)
+       _DEPRECATED_OBJECTS = {
+           'deprecated_name': (object_to_return, 'fully_qualified_replacement_name', (8, 0)),
+       }
+
+
+       def __getattr__(name):
+           if name not in _DEPRECATED_OBJECTS:
+               msg = f'module {__name__!r} has no attribute {name!r}'
+               raise AttributeError(msg)
+
+           from sphinx.deprecation import _deprecation_warning
+
+           deprecated_object, canonical_name, remove = _DEPRECATED_OBJECTS[name]
+           _deprecation_warning(__name__, name, canonical_name, remove=remove)
+           return deprecated_object
+    """
+
+    if remove == (8, 0):
+        warning_class: type[Warning] = RemovedInSphinx80Warning
+    elif remove == (9, 0):
+        warning_class = RemovedInSphinx90Warning
+    else:
+        msg = f'removal version {remove!r} is invalid!'
+        raise RuntimeError(msg)
+
+    qualified_name = f'{module}.{attribute}'
+    if canonical_name:
+        message = (f'The alias {qualified_name!r} is deprecated, '
+                   f'use {canonical_name!r} instead.')
+    else:
+        message = f'{qualified_name!r} is deprecated.'
+
+    warnings.warn(message + " Check CHANGES for Sphinx API modifications.",
+                  warning_class, stacklevel=3)