forked from sphinx-doc/sphinx
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathdeprecation.py
More file actions
82 lines (61 loc) · 2.46 KB
/
deprecation.py
File metadata and controls
82 lines (61 loc) · 2.46 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
"""Sphinx deprecation classes and utilities."""
from __future__ import annotations
import warnings
class RemovedInSphinx90Warning(DeprecationWarning):
pass
class RemovedInSphinx10Warning(PendingDeprecationWarning):
pass
RemovedInNextVersionWarning = RemovedInSphinx90Warning
def _deprecation_warning(
module: str,
attribute: str,
canonical_name: str = '',
*,
remove: tuple[int, int],
raises: bool = False,
) -> None:
"""Helper function for module-level deprecations using ``__getattr__``.
: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.
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.
Usage::
# deprecated name -> (object to return, canonical path or empty string, removal version)
_DEPRECATED_OBJECTS = {
'deprecated_name': (
object_to_return,
'fully_qualified_replacement_name',
(9, 0),
),
}
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, remove = _DEPRECATED_OBJECTS[name]
_deprecation_warning(__name__, name, canonical_name, remove=remove)
return deprecated_object
"""
if remove == (9, 0):
warning_class: type[Warning] = RemovedInSphinx90Warning
elif remove == (10, 0):
warning_class = RemovedInSphinx10Warning
else:
msg = f'removal version {remove!r} is invalid!'
raise RuntimeError(msg)
qualname = f'{module}.{attribute}'
if canonical_name:
message = (
f'The alias {qualname!r} is deprecated, use {canonical_name!r} instead.'
)
else:
message = f'{qualname!r} is deprecated.'
if raises:
raise AttributeError(message)
message = f'{message} Check CHANGES for Sphinx API modifications.'
warnings.warn(message, warning_class, stacklevel=3)