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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
# Licensed under the LGPL: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html
# For details: https://github.com/pylint-dev/astroid/blob/main/LICENSE
# Copyright (c) https://github.com/pylint-dev/astroid/blob/main/CONTRIBUTORS.txt
"""A few useful function/method decorators."""
from __future__ import annotations
import functools
import inspect
import sys
import warnings
from collections.abc import Callable, Generator
from typing import TypeVar
from astroid import util
from astroid.context import InferenceContext
from astroid.exceptions import InferenceError
from astroid.typing import InferenceResult
if sys.version_info >= (3, 10):
from typing import ParamSpec
else:
from typing_extensions import ParamSpec
_R = TypeVar("_R")
_P = ParamSpec("_P")
def path_wrapper(func):
"""Return the given infer function wrapped to handle the path.
Used to stop inference if the node has already been looked
at for a given `InferenceContext` to prevent infinite recursion
"""
@functools.wraps(func)
def wrapped(
node, context: InferenceContext | None = None, _func=func, **kwargs
) -> Generator:
"""Wrapper function handling context."""
if context is None:
context = InferenceContext()
if context.push(node):
return
yielded = set()
for res in _func(node, context, **kwargs):
# unproxy only true instance, not const, tuple, dict...
if res.__class__.__name__ == "Instance":
ares = res._proxied
else:
ares = res
if ares not in yielded:
yield res
yielded.add(ares)
return wrapped
def yes_if_nothing_inferred(
func: Callable[_P, Generator[InferenceResult, None, None]]
) -> Callable[_P, Generator[InferenceResult, None, None]]:
def inner(
*args: _P.args, **kwargs: _P.kwargs
) -> Generator[InferenceResult, None, None]:
generator = func(*args, **kwargs)
try:
yield next(generator)
except StopIteration:
# generator is empty
yield util.Uninferable
return
yield from generator
return inner
def raise_if_nothing_inferred(
func: Callable[_P, Generator[InferenceResult, None, None]],
) -> Callable[_P, Generator[InferenceResult, None, None]]:
def inner(
*args: _P.args, **kwargs: _P.kwargs
) -> Generator[InferenceResult, None, None]:
generator = func(*args, **kwargs)
try:
yield next(generator)
except StopIteration as error:
# generator is empty
if error.args:
raise InferenceError(**error.args[0]) from error
raise InferenceError(
"StopIteration raised without any error information."
) from error
except RecursionError as error:
raise InferenceError(
f"RecursionError raised with limit {sys.getrecursionlimit()}."
) from error
yield from generator
return inner
# Expensive decorators only used to emit Deprecation warnings.
# If no other than the default DeprecationWarning are enabled,
# fall back to passthrough implementations.
if util.check_warnings_filter(): # noqa: C901
def deprecate_default_argument_values(
astroid_version: str = "3.0", **arguments: str
) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]:
"""Decorator which emits a DeprecationWarning if any arguments specified
are None or not passed at all.
Arguments should be a key-value mapping, with the key being the argument to check
and the value being a type annotation as string for the value of the argument.
To improve performance, only used when DeprecationWarnings other than
the default one are enabled.
"""
# Helpful links
# Decorator for DeprecationWarning: https://stackoverflow.com/a/49802489
# Typing of stacked decorators: https://stackoverflow.com/a/68290080
def deco(func: Callable[_P, _R]) -> Callable[_P, _R]:
"""Decorator function."""
@functools.wraps(func)
def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
"""Emit DeprecationWarnings if conditions are met."""
keys = list(inspect.signature(func).parameters.keys())
for arg, type_annotation in arguments.items():
try:
index = keys.index(arg)
except ValueError:
raise ValueError(
f"Can't find argument '{arg}' for '{args[0].__class__.__qualname__}'"
) from None
if (
# Check kwargs
# - if found, check it's not None
(arg in kwargs and kwargs[arg] is None)
# Check args
# - make sure not in kwargs
# - len(args) needs to be long enough, if too short
# arg can't be in args either
# - args[index] should not be None
or arg not in kwargs
and (
index == -1
or len(args) <= index
or (len(args) > index and args[index] is None)
)
):
warnings.warn(
f"'{arg}' will be a required argument for "
f"'{args[0].__class__.__qualname__}.{func.__name__}'"
f" in astroid {astroid_version} "
f"('{arg}' should be of type: '{type_annotation}')",
DeprecationWarning,
stacklevel=2,
)
return func(*args, **kwargs)
return wrapper
return deco
def deprecate_arguments(
astroid_version: str = "3.0", **arguments: str
) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]:
"""Decorator which emits a DeprecationWarning if any arguments specified
are passed.
Arguments should be a key-value mapping, with the key being the argument to check
and the value being a string that explains what to do instead of passing the argument.
To improve performance, only used when DeprecationWarnings other than
the default one are enabled.
"""
def deco(func: Callable[_P, _R]) -> Callable[_P, _R]:
@functools.wraps(func)
def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
keys = list(inspect.signature(func).parameters.keys())
for arg, note in arguments.items():
try:
index = keys.index(arg)
except ValueError:
raise ValueError(
f"Can't find argument '{arg}' for '{args[0].__class__.__qualname__}'"
) from None
if arg in kwargs or len(args) > index:
warnings.warn(
f"The argument '{arg}' for "
f"'{args[0].__class__.__qualname__}.{func.__name__}' is deprecated "
f"and will be removed in astroid {astroid_version} ({note})",
DeprecationWarning,
stacklevel=2,
)
return func(*args, **kwargs)
return wrapper
return deco
else:
def deprecate_default_argument_values(
astroid_version: str = "3.0", **arguments: str
) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]:
"""Passthrough decorator to improve performance if DeprecationWarnings are
disabled.
"""
def deco(func: Callable[_P, _R]) -> Callable[_P, _R]:
"""Decorator function."""
return func
return deco
def deprecate_arguments(
astroid_version: str = "3.0", **arguments: str
) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]:
"""Passthrough decorator to improve performance if DeprecationWarnings are
disabled.
"""
def deco(func: Callable[_P, _R]) -> Callable[_P, _R]:
"""Decorator function."""
return func
return deco
|
