IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

[cleanup] remove deprecated objects and improve deprecation private interface (#12185)

Browse Source 
This removes the deprecated objects that should have been removed in 7.x.
This commit is contained in:
Bénédikt Tran
2024-03-25 12:45:45 +01:00
committed by GitHub
parent 0ef96a7d52
commit 2e05fd2ffe
7 changed files with 42 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
sphinx/addnodes.py
View File

@@ -14,24 +14,6 @@ if TYPE_CHECKING:
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.

14
sphinx/builders/html/__init__.py
View File

@@ -307,8 +307,7 @@ class StandaloneHTMLBuilder(Builder):
@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 @@ class StandaloneHTMLBuilder(Builder):
@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)),
}

35
sphinx/deprecation.py
View File

@@ -19,17 +19,26 @@ RemovedInNextVersionWarning = RemovedInSphinx80Warning
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 _deprecation_warning(
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.'
warnings.warn(
message + ' Check CHANGES for Sphinx API modifications.', warning_class, stacklevel=3
)
if raises:
raise AttributeError(message)
message = f'{message} Check CHANGES for Sphinx API modifications.'
warnings.warn(message, warning_class, stacklevel=3)

5
sphinx/testing/util.py
View File

@@ -24,7 +24,7 @@ from sphinx.util.docutils import additional_nodes
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)),
}

8
sphinx/util/__init__.py
View File

@@ -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

17
sphinx/util/docutils.py
View File

@@ -38,23 +38,6 @@ if TYPE_CHECKING:
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()

10
sphinx/util/typing.py
View File

@@ -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