[cleanup] remove deprecated objects and improve deprecation private i…

…nterface (sphinx-doc#12185)

This removes the deprecated objects that should have been removed in 7.x.

sphinx/addnodes.py

@@ -14,24 +14,6 @@
  from sphinx.application import Sphinx
  from sphinx.util.typing import ExtensionMetadata
 
-# deprecated name -> (object to return, canonical path or empty string)
-_DEPRECATED_OBJECTS = {
- 'meta': (nodes.meta, 'docutils.nodes.meta'),
- 'docutils_meta': (nodes.meta, 'docutils.nodes.meta'),
-}
-
-
-def __getattr__(name: str) -> Any:
- 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 = _DEPRECATED_OBJECTS[name]
- _deprecation_warning(__name__, name, canonical_name, remove=(7, 0))
- return deprecated_object
-
 
 class document(nodes.document):
  """The document root element patched by Sphinx.

sphinx/builders/html/__init__.py

@@ -307,8 +307,7 @@ def init_highlighter(self) -> None:
 
  @property
  def css_files(self) -> list[_CascadingStyleSheet]:
- _deprecation_warning(__name__, f'{self.__class__.__name__}.css_files', '',
- remove=(9, 0))
+ _deprecation_warning(__name__, f'{self.__class__.__name__}.css_files', remove=(9, 0))
  return self._css_files
 
  def init_css_files(self) -> None:
@@ -334,8 +333,8 @@ def add_css_file(self, filename: str, **kwargs: Any) -> None:
 
  @property
  def script_files(self) -> list[_JavaScript]:
- _deprecation_warning(__name__, f'{self.__class__.__name__}.script_files', '',
-   remove=(9, 0))
+ canonical_name = f'{self.__class__.__name__}.script_files'
+ _deprecation_warning(__name__, canonical_name, remove=(9, 0))
  return self._js_files
 
  def init_js_files(self) -> None:
@@ -1340,7 +1339,8 @@ def setup(app: Sphinx) -> ExtensionMetadata:
  app.add_config_value('html_search_scorer', '', '')
  app.add_config_value('html_scaled_image_link', True, 'html')
  app.add_config_value('html_baseurl', '', 'html')
- app.add_config_value('html_codeblock_linenos_style', 'inline', 'html', # RemovedInSphinx70Warning # NoQA: E501
+ # removal is indefinitely on hold (ref: https://github.com/sphinx-doc/sphinx/issues/10265)
+ app.add_config_value('html_codeblock_linenos_style', 'inline', 'html',
  ENUM('table', 'inline'))
  app.add_config_value('html_math_renderer', None, 'env')
  app.add_config_value('html4_writer', False, 'html')
@@ -1373,8 +1373,8 @@ def setup(app: Sphinx) -> ExtensionMetadata:
  }
 
 
-# deprecated name -> (object to return, canonical path or empty string)
-_DEPRECATED_OBJECTS = {
+# deprecated name -> (object to return, canonical path or empty string, removal version)
+_DEPRECATED_OBJECTS: dict[str, tuple[Any, str, tuple[int, int]]] = {
  'Stylesheet': (_CascadingStyleSheet, 'sphinx.builders.html._assets._CascadingStyleSheet', (9, 0)), # NoQA: E501
  'JavaScript': (_JavaScript, 'sphinx.builders.html._assets._JavaScript', (9, 0)),
 }

sphinx/deprecation.py

@@ -19,17 +19,26 @@ class RemovedInSphinx90Warning(PendingDeprecationWarning):
 def _deprecation_warning(
  module: str,
  attribute: str,
- canonical_name: str,
+ canonical_name: str = '',
  *,
  remove: tuple[int, int],
+ raises: bool = False,
 ) -> None:
- """Helper function for module-level deprecations using __getattr__
+ """Helper function for module-level deprecations using ``__getattr__``.
 
- Exemplar usage:
+ :param module: The module containing a deprecated object.
+ :param attribute: The name of the deprecated object.
+ :param canonical_name: Optional fully-qualified name for its replacement.
+ :param remove: Target version for removal.
+ :param raises: Indicate whether to raise an exception instead of a warning.
 
- .. code:: python
+ When *raises* is ``True``, an :exc:`AttributeError` is raised instead
+ of emitting a warning so that it is easy to locate deprecated objects
+ in tests that could suppress deprecation warnings.
 
- # deprecated name -> (object to return, canonical path or empty string)
+ Usage::
+
+ # deprecated name -> (object to return, canonical path or empty string, removal version)
  _DEPRECATED_OBJECTS = {
  'deprecated_name': (object_to_return, 'fully_qualified_replacement_name', (8, 0)),
  }
@@ -54,14 +63,14 @@ def __getattr__(name: str) -> Any:
  msg = f'removal version {remove!r} is invalid!'
  raise RuntimeError(msg)
 
- qualified_name = f'{module}.{attribute}'
+ qualname = f'{module}.{attribute}'
  if canonical_name:
- message = (
- f'The alias {qualified_name!r} is deprecated, use {canonical_name!r} instead.'
- )
+ message = f'The alias {qualname!r} is deprecated, use {canonical_name!r} instead.'
  else:
- message = f'{qualified_name!r} is deprecated.'
+ message = f'{qualname!r} is deprecated.'
+
+ if raises:
+ raise AttributeError(message)
 
- warnings.warn(
- message + ' Check CHANGES for Sphinx API modifications.', warning_class, stacklevel=3
- )
+ message = f'{message} Check CHANGES for Sphinx API modifications.'
+ warnings.warn(message, warning_class, stacklevel=3)

sphinx/testing/util.py

@@ -24,7 +24,7 @@
 if TYPE_CHECKING:
  from collections.abc import Mapping
  from pathlib import Path
- from typing import Any, Final
+ from typing import Any
  from xml.etree.ElementTree import ElementTree
 
  from docutils.nodes import Node
@@ -242,7 +242,8 @@ def _clean_up_global_state() -> None:
  sphinx.pycode.ModuleAnalyzer.cache.clear()
 
 
-_DEPRECATED_OBJECTS: Final[dict[str, tuple[object, str, tuple[int, int]]]] = {
+# deprecated name -> (object to return, canonical path or '', removal version)
+_DEPRECATED_OBJECTS: dict[str, tuple[Any, str, tuple[int, int]]] = {
  'strip_escseq': (strip_colors, 'sphinx.util.console.strip_colors', (9, 0)),
 }
 

sphinx/util/__init__.py

@@ -266,7 +266,7 @@ def _xml_name_checker() -> re.Pattern[str]:
 
 
 # deprecated name -> (object to return, canonical path or empty string)
-_DEPRECATED_OBJECTS = {
+_DEPRECATED_OBJECTS: dict[str, tuple[Any, str] | tuple[Any, str, tuple[int, int]]] = {
  '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'),
@@ -294,6 +294,8 @@ def __getattr__(name: str) -> Any:
 
  from sphinx.deprecation import _deprecation_warning
 
- deprecated_object, canonical_name = _DEPRECATED_OBJECTS[name]
- _deprecation_warning(__name__, name, canonical_name, remove=(8, 0))
+ info = _DEPRECATED_OBJECTS[name]
+ deprecated_object, canonical_name = info[:2]
+ remove = info[2] if len(info) == 3 else (8, 0)
+ _deprecation_warning(__name__, name, canonical_name, remove=remove)
  return deprecated_object

sphinx/util/docutils.py

@@ -38,23 +38,6 @@
  from sphinx.environment import BuildEnvironment
  from sphinx.util.typing import RoleFunction
 
-# deprecated name -> (object to return, canonical path or empty string)
-_DEPRECATED_OBJECTS = {
- '__version_info__': (docutils.__version_info__, 'docutils.__version_info__'),
-}
-
-
-def __getattr__(name: str) -> Any:
- 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 = _DEPRECATED_OBJECTS[name]
- _deprecation_warning(__name__, name, canonical_name, remove=(7, 0))
- return deprecated_object
-
 
 additional_nodes: set[type[Element]] = set()
 

sphinx/util/typing.py

@@ -434,9 +434,9 @@ def _format_literal_enum_arg(arg: enum.Enum, /, *, mode: str) -> str:
  return f':py:attr:`{enum_cls.__module__}.{enum_cls.__qualname__}.{arg.name}`'
 
 
-# deprecated name -> (object to return, canonical path or empty string)
-_DEPRECATED_OBJECTS = {
- 'stringify': (stringify_annotation, 'sphinx.util.typing.stringify_annotation'),
+# deprecated name -> (object to return, canonical path or empty string, removal version)
+_DEPRECATED_OBJECTS: dict[str, tuple[Any, str, tuple[int, int]]] = {
+ 'stringify': (stringify_annotation, 'sphinx.util.typing.stringify_annotation', (8, 0)),
 }
 
 
@@ -447,6 +447,6 @@ def __getattr__(name: str) -> Any:
 
  from sphinx.deprecation import _deprecation_warning
 
- deprecated_object, canonical_name = _DEPRECATED_OBJECTS[name]
- _deprecation_warning(__name__, name, canonical_name, remove=(8, 0))
+ deprecated_object, canonical_name, remove = _DEPRECATED_OBJECTS[name]
+ _deprecation_warning(__name__, name, canonical_name, remove=remove)
  return deprecated_object