| """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) |
