1# Licensed under the LGPL: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html
2# For details: https://github.com/pylint-dev/astroid/blob/main/LICENSE
3# Copyright (c) https://github.com/pylint-dev/astroid/blob/main/CONTRIBUTORS.txt
4
5"""This module contains some base nodes that can be inherited for the different nodes.
6
7Previously these were called Mixin nodes.
8"""
9
10from __future__ import annotations
11
12import itertools
13from collections.abc import Callable, Generator, Iterator
14from functools import cached_property, lru_cache, partial
15from typing import TYPE_CHECKING, Any, ClassVar
16
17from astroid import bases, nodes, util
18from astroid.context import (
19 CallContext,
20 InferenceContext,
21 bind_context_to_node,
22)
23from astroid.exceptions import (
24 AttributeInferenceError,
25 InferenceError,
26)
27from astroid.interpreter import dunder_lookup
28from astroid.nodes.node_ng import NodeNG
29from astroid.typing import InferenceResult
30
31if TYPE_CHECKING:
32 from astroid.nodes.node_classes import LocalsDictNodeNG
33
34 GetFlowFactory = Callable[
35 [
36 InferenceResult,
37 InferenceResult | None,
38 nodes.AugAssign | nodes.BinOp,
39 InferenceResult,
40 InferenceResult | None,
41 InferenceContext,
42 InferenceContext,
43 ],
44 list[partial[Generator[InferenceResult]]],
45 ]
46
47
48class Statement(NodeNG):
49 """Statement node adding a few attributes.
50
51 NOTE: This class is part of the public API of 'astroid.nodes'.
52 """
53
54 is_statement = True
55 """Whether this node indicates a statement."""
56
57 def next_sibling(self) -> NodeNG | None:
58 """The next sibling statement node.
59
60 :returns: The next sibling statement node.
61 """
62 stmts = self.parent.child_sequence(self)
63 index = stmts.index(self)
64 try:
65 return stmts[index + 1]
66 except IndexError:
67 return None
68
69 def previous_sibling(self) -> NodeNG | None:
70 """The previous sibling statement.
71
72 :returns: The previous sibling statement node.
73 """
74 stmts = self.parent.child_sequence(self)
75 index = stmts.index(self)
76 if index >= 1:
77 return stmts[index - 1]
78 return None
79
80
81class NoChildrenNode(NodeNG):
82 """Base nodes for nodes with no children, e.g. Pass."""
83
84 def get_children(self) -> Iterator[NodeNG]:
85 yield from ()
86
87
88class FilterStmtsBaseNode(NodeNG):
89 """Base node for statement filtering and assignment type."""
90
91 def _get_filtered_stmts(self, _, node, _stmts, mystmt: Statement | None):
92 """Method used in _filter_stmts to get statements and trigger break."""
93 if self.statement() is mystmt:
94 # original node's statement is the assignment, only keep
95 # current node (gen exp, list comp)
96 return [node], True
97 return _stmts, False
98
99 def assign_type(self):
100 return self
101
102
103class AssignTypeNode(NodeNG):
104 """Base node for nodes that can 'assign' such as AnnAssign."""
105
106 def assign_type(self):
107 return self
108
109 def _get_filtered_stmts(self, lookup_node, node, _stmts, mystmt: Statement | None):
110 """Method used in filter_stmts."""
111 if self is mystmt:
112 return _stmts, True
113 if self.statement() is mystmt:
114 # original node's statement is the assignment, only keep
115 # current node (gen exp, list comp)
116 return [node], True
117 return _stmts, False
118
119
120class ParentAssignNode(AssignTypeNode):
121 """Base node for nodes whose assign_type is determined by the parent node."""
122
123 def assign_type(self):
124 return self.parent.assign_type()
125
126
127class ImportNode(FilterStmtsBaseNode, NoChildrenNode, Statement):
128 """Base node for From and Import Nodes."""
129
130 modname: str | None
131 """The module that is being imported from.
132
133 This is ``None`` for relative imports.
134 """
135
136 names: list[tuple[str, str | None]]
137 """What is being imported from the module.
138
139 Each entry is a :class:`tuple` of the name being imported,
140 and the alias that the name is assigned to (if any).
141 """
142
143 def _infer_name(self, frame, name):
144 try:
145 return self.real_name(name)
146 except AttributeInferenceError:
147 return None
148
149 def do_import_module(self, modname: str | None = None) -> nodes.Module:
150 """Return the ast for a module whose name is <modname> imported by <self>."""
151 mymodule = self.root()
152 level: int | None = getattr(self, "level", None) # Import has no level
153 if modname is None:
154 modname = self.modname
155 # If the module ImportNode is importing is a module with the same name
156 # as the file that contains the ImportNode we don't want to use the cache
157 # to make sure we use the import system to get the correct module.
158 if (
159 modname
160 # pylint: disable-next=no-member # pylint doesn't recognize type of mymodule
161 and mymodule.relative_to_absolute_name(modname, level) == mymodule.name
162 ):
163 use_cache = False
164 else:
165 use_cache = True
166
167 # pylint: disable-next=no-member # pylint doesn't recognize type of mymodule
168 return mymodule.import_module(
169 modname,
170 level=level,
171 relative_only=bool(level and level >= 1),
172 use_cache=use_cache,
173 )
174
175 def real_name(self, asname: str) -> str:
176 """Get name from 'as' name."""
177 for name, _asname in self.names:
178 if name == "*":
179 return asname
180 if not _asname:
181 name = name.split(".", 1)[0]
182 _asname = name
183 if asname == _asname:
184 return name
185 raise AttributeInferenceError(
186 "Could not find original name for {attribute} in {target!r}",
187 target=self,
188 attribute=asname,
189 )
190
191
192class MultiLineBlockNode(NodeNG):
193 """Base node for multi-line blocks, e.g. For and FunctionDef.
194
195 Note that this does not apply to every node with a `body` field.
196 For instance, an If node has a multi-line body, but the body of an
197 IfExpr is not multi-line, and hence cannot contain Return nodes,
198 Assign nodes, etc.
199 """
200
201 _multi_line_block_fields: ClassVar[tuple[str, ...]] = ()
202
203 @cached_property
204 def _multi_line_blocks(self):
205 return tuple(getattr(self, field) for field in self._multi_line_block_fields)
206
207 def _get_return_nodes_skip_functions(self):
208 for block in self._multi_line_blocks:
209 for child_node in block:
210 if child_node.is_function:
211 continue
212 yield from child_node._get_return_nodes_skip_functions()
213
214 def _get_yield_nodes_skip_functions(self):
215 for block in self._multi_line_blocks:
216 for child_node in block:
217 if child_node.is_function:
218 continue
219 yield from child_node._get_yield_nodes_skip_functions()
220
221 def _get_yield_nodes_skip_lambdas(self):
222 for block in self._multi_line_blocks:
223 for child_node in block:
224 if child_node.is_lambda:
225 continue
226 yield from child_node._get_yield_nodes_skip_lambdas()
227
228 @cached_property
229 def _assign_nodes_in_scope(self) -> list[nodes.Assign]:
230 children_assign_nodes = (
231 child_node._assign_nodes_in_scope
232 for block in self._multi_line_blocks
233 for child_node in block
234 )
235 return list(itertools.chain.from_iterable(children_assign_nodes))
236
237
238class MultiLineWithElseBlockNode(MultiLineBlockNode):
239 """Base node for multi-line blocks that can have else statements."""
240
241 body: list[NodeNG]
242 """The contents of the block."""
243
244 orelse: list[NodeNG]
245 """The contents of the ``else`` block."""
246
247 @cached_property
248 def blockstart_tolineno(self):
249 return self.lineno
250
251 def block_range(self, lineno: int) -> tuple[int, int]:
252 """Get a range from the given line number to where this node ends.
253
254 :param lineno: The line number to start the range at.
255
256 :returns: The range of line numbers that this node belongs to,
257 starting at the given line number.
258 """
259 if lineno < self.fromlineno:
260 return lineno, self.tolineno
261 if lineno == self.body[0].fromlineno:
262 return lineno, lineno
263 if lineno <= self.body[-1].tolineno:
264 return lineno, self.body[-1].tolineno
265 return self._elsed_block_range(lineno, self.orelse, self.body[0].fromlineno - 1)
266
267 def _elsed_block_range(
268 self, lineno: int, orelse: list[nodes.NodeNG], last: int | None = None
269 ) -> tuple[int, int]:
270 """Handle block line numbers range for try/finally, for, if and while
271 statements.
272 """
273 # If at the end of the node, return same line
274 if lineno == self.tolineno:
275 return lineno, lineno
276 if orelse:
277 # If the lineno is beyond the body of the node we check the orelse
278 if lineno >= self.body[-1].tolineno + 1:
279 # If the orelse has a scope of its own we determine the block range there
280 if isinstance(orelse[0], MultiLineWithElseBlockNode):
281 return orelse[0]._elsed_block_range(lineno, orelse[0].orelse)
282 # Return last line of orelse
283 return lineno, orelse[-1].tolineno
284 # If the lineno is within the body we take the last line of the body
285 return lineno, self.body[-1].tolineno
286 return lineno, last or self.tolineno
287
288
289class LookupMixIn(NodeNG):
290 """Mixin to look up a name in the right scope."""
291
292 @lru_cache # noqa
293 def lookup(self, name: str) -> tuple[LocalsDictNodeNG, list[NodeNG]]:
294 """Lookup where the given variable is assigned.
295
296 The lookup starts from self's scope. If self is not a frame itself
297 and the name is found in the inner frame locals, statements will be
298 filtered to remove ignorable statements according to self's location.
299
300 :param name: The name of the variable to find assignments for.
301
302 :returns: The scope node and the list of assignments associated to the
303 given name according to the scope where it has been found (locals,
304 globals or builtin).
305 """
306 return self.scope().scope_lookup(self, name)
307
308 def ilookup(self, name: str) -> Generator[InferenceResult]:
309 """Lookup the inferred values of the given variable.
310
311 :param name: The variable name to find values for.
312
313 :returns: The inferred values of the statements returned from
314 :meth:`lookup`.
315 """
316 frame, stmts = self.lookup(name)
317 context = InferenceContext()
318 return bases._infer_stmts(stmts, context, frame)
319
320
321def _reflected_name(name) -> str:
322 return "__r" + name[2:]
323
324
325def _augmented_name(name) -> str:
326 return "__i" + name[2:]
327
328
329BIN_OP_METHOD = {
330 "+": "__add__",
331 "-": "__sub__",
332 "/": "__truediv__",
333 "//": "__floordiv__",
334 "*": "__mul__",
335 "**": "__pow__",
336 "%": "__mod__",
337 "&": "__and__",
338 "|": "__or__",
339 "^": "__xor__",
340 "<<": "__lshift__",
341 ">>": "__rshift__",
342 "@": "__matmul__",
343}
344
345REFLECTED_BIN_OP_METHOD = {
346 key: _reflected_name(value) for (key, value) in BIN_OP_METHOD.items()
347}
348AUGMENTED_OP_METHOD = {
349 key + "=": _augmented_name(value) for (key, value) in BIN_OP_METHOD.items()
350}
351
352
353class OperatorNode(NodeNG):
354 @staticmethod
355 def _filter_operation_errors(
356 infer_callable: Callable[
357 [InferenceContext | None],
358 Generator[InferenceResult | util.BadOperationMessage],
359 ],
360 context: InferenceContext | None,
361 error: type[util.BadOperationMessage],
362 ) -> Generator[InferenceResult]:
363 for result in infer_callable(context):
364 if isinstance(result, error):
365 # For the sake of .infer(), we don't care about operation
366 # errors, which is the job of a linter. So return something
367 # which shows that we can't infer the result.
368 yield util.Uninferable
369 else:
370 yield result
371
372 @staticmethod
373 def _is_not_implemented(const) -> bool:
374 """Check if the given const node is NotImplemented."""
375 return isinstance(const, nodes.Const) and const.value is NotImplemented
376
377 @staticmethod
378 def _infer_old_style_string_formatting(
379 instance: nodes.Const, other: nodes.NodeNG, context: InferenceContext
380 ) -> tuple[util.UninferableBase | nodes.Const]:
381 """Infer the result of '"string" % ...'.
382
383 TODO: Instead of returning Uninferable we should rely
384 on the call to '%' to see if the result is actually uninferable.
385 """
386 if isinstance(other, nodes.Tuple):
387 if util.Uninferable in other.elts:
388 return (util.Uninferable,)
389 inferred_positional = [util.safe_infer(i, context) for i in other.elts]
390 if all(isinstance(i, nodes.Const) for i in inferred_positional):
391 values = tuple(i.value for i in inferred_positional)
392 else:
393 values = None
394 elif isinstance(other, nodes.Dict):
395 values: dict[Any, Any] = {}
396 for pair in other.items:
397 key = util.safe_infer(pair[0], context)
398 if not isinstance(key, nodes.Const):
399 return (util.Uninferable,)
400 value = util.safe_infer(pair[1], context)
401 if not isinstance(value, nodes.Const):
402 return (util.Uninferable,)
403 values[key.value] = value.value
404 elif isinstance(other, nodes.Const):
405 values = other.value
406 else:
407 return (util.Uninferable,)
408
409 # pylint: disable-next=import-outside-toplevel
410 from astroid.protocols import _old_style_format_too_large
411
412 if _old_style_format_too_large(instance.value, values):
413 return (util.Uninferable,)
414
415 try:
416 return (nodes.const_factory(instance.value % values),)
417 except (TypeError, KeyError, ValueError, OverflowError):
418 # OverflowError: a "%c" conversion with an out-of-range code point,
419 # e.g. "%c" % 0x110000, which the size guard above does not catch.
420 return (util.Uninferable,)
421
422 @staticmethod
423 def _invoke_binop_inference(
424 instance: InferenceResult,
425 opnode: nodes.AugAssign | nodes.BinOp,
426 op: str,
427 other: InferenceResult,
428 context: InferenceContext,
429 method_name: str,
430 ) -> Generator[InferenceResult]:
431 """Invoke binary operation inference on the given instance."""
432 methods = dunder_lookup.lookup(instance, method_name)
433 context = bind_context_to_node(context, instance)
434 method = methods[0]
435 context.callcontext.callee = method
436
437 if (
438 isinstance(instance, nodes.Const)
439 and isinstance(instance.value, (str, bytes))
440 and op == "%"
441 ):
442 return iter(
443 OperatorNode._infer_old_style_string_formatting(
444 instance, other, context
445 )
446 )
447
448 try:
449 inferred = next(method.infer(context=context))
450 except StopIteration as e:
451 raise InferenceError(node=method, context=context) from e
452 if isinstance(inferred, util.UninferableBase):
453 raise InferenceError
454 if not isinstance(
455 instance,
456 (nodes.Const, nodes.Tuple, nodes.List, nodes.ClassDef, bases.Instance),
457 ):
458 raise InferenceError # pragma: no cover # Used as a failsafe
459 return instance.infer_binary_op(opnode, op, other, context, inferred)
460
461 @staticmethod
462 def _aug_op(
463 instance: InferenceResult,
464 opnode: nodes.AugAssign,
465 op: str,
466 other: InferenceResult,
467 context: InferenceContext,
468 reverse: bool = False,
469 ) -> partial[Generator[InferenceResult]]:
470 """Get an inference callable for an augmented binary operation."""
471 method_name = AUGMENTED_OP_METHOD[op]
472 return partial(
473 OperatorNode._invoke_binop_inference,
474 instance=instance,
475 op=op,
476 opnode=opnode,
477 other=other,
478 context=context,
479 method_name=method_name,
480 )
481
482 @staticmethod
483 def _bin_op(
484 instance: InferenceResult,
485 opnode: nodes.AugAssign | nodes.BinOp,
486 op: str,
487 other: InferenceResult,
488 context: InferenceContext,
489 reverse: bool = False,
490 ) -> partial[Generator[InferenceResult]]:
491 """Get an inference callable for a normal binary operation.
492
493 If *reverse* is True, then the reflected method will be used instead.
494 """
495 if reverse:
496 method_name = REFLECTED_BIN_OP_METHOD[op]
497 else:
498 method_name = BIN_OP_METHOD[op]
499 return partial(
500 OperatorNode._invoke_binop_inference,
501 instance=instance,
502 op=op,
503 opnode=opnode,
504 other=other,
505 context=context,
506 method_name=method_name,
507 )
508
509 @staticmethod
510 def _bin_op_or_union_type(
511 left: bases.UnionType | nodes.ClassDef | nodes.Const,
512 right: bases.UnionType | nodes.ClassDef | nodes.Const,
513 ) -> Generator[InferenceResult]:
514 """Create a new UnionType instance for binary or, e.g. int | str."""
515 yield bases.UnionType(left, right)
516
517 @staticmethod
518 def _get_binop_contexts(context, left, right):
519 """Get contexts for binary operations.
520
521 This will return two inference contexts, the first one
522 for x.__op__(y), the other one for y.__rop__(x), where
523 only the arguments are inversed.
524 """
525 # The order is important, since the first one should be
526 # left.__op__(right).
527 for arg in (right, left):
528 new_context = context.clone()
529 new_context.callcontext = CallContext(args=[arg])
530 new_context.boundnode = None
531 yield new_context
532
533 @staticmethod
534 def _same_type(type1, type2) -> bool:
535 """Check if type1 is the same as type2."""
536 return type1.qname() == type2.qname()
537
538 @staticmethod
539 def _get_aug_flow(
540 left: InferenceResult,
541 left_type: InferenceResult | None,
542 aug_opnode: nodes.AugAssign,
543 right: InferenceResult,
544 right_type: InferenceResult | None,
545 context: InferenceContext,
546 reverse_context: InferenceContext,
547 ) -> list[partial[Generator[InferenceResult]]]:
548 """Get the flow for augmented binary operations.
549
550 The rules are a bit messy:
551
552 * if left and right have the same type, then left.__augop__(right)
553 is first tried and then left.__op__(right).
554 * if left and right are unrelated typewise, then
555 left.__augop__(right) is tried, then left.__op__(right)
556 is tried and then right.__rop__(left) is tried.
557 * if left is a subtype of right, then left.__augop__(right)
558 is tried and then left.__op__(right).
559 * if left is a supertype of right, then left.__augop__(right)
560 is tried, then right.__rop__(left) and then
561 left.__op__(right)
562 """
563 from astroid import helpers # pylint: disable=import-outside-toplevel
564
565 bin_op = aug_opnode.op.strip("=")
566 aug_op = aug_opnode.op
567 if OperatorNode._same_type(left_type, right_type):
568 methods = [
569 OperatorNode._aug_op(left, aug_opnode, aug_op, right, context),
570 OperatorNode._bin_op(left, aug_opnode, bin_op, right, context),
571 ]
572 elif helpers.is_subtype(left_type, right_type):
573 methods = [
574 OperatorNode._aug_op(left, aug_opnode, aug_op, right, context),
575 OperatorNode._bin_op(left, aug_opnode, bin_op, right, context),
576 ]
577 elif helpers.is_supertype(left_type, right_type):
578 methods = [
579 OperatorNode._aug_op(left, aug_opnode, aug_op, right, context),
580 OperatorNode._bin_op(
581 right, aug_opnode, bin_op, left, reverse_context, reverse=True
582 ),
583 OperatorNode._bin_op(left, aug_opnode, bin_op, right, context),
584 ]
585 else:
586 methods = [
587 OperatorNode._aug_op(left, aug_opnode, aug_op, right, context),
588 OperatorNode._bin_op(left, aug_opnode, bin_op, right, context),
589 OperatorNode._bin_op(
590 right, aug_opnode, bin_op, left, reverse_context, reverse=True
591 ),
592 ]
593 return methods
594
595 @staticmethod
596 def _get_binop_flow(
597 left: InferenceResult,
598 left_type: InferenceResult | None,
599 binary_opnode: nodes.AugAssign | nodes.BinOp,
600 right: InferenceResult,
601 right_type: InferenceResult | None,
602 context: InferenceContext,
603 reverse_context: InferenceContext,
604 ) -> list[partial[Generator[InferenceResult]]]:
605 """Get the flow for binary operations.
606
607 The rules are a bit messy:
608
609 * if left and right have the same type, then only one
610 method will be called, left.__op__(right)
611 * if left and right are unrelated typewise, then first
612 left.__op__(right) is tried and if this does not exist
613 or returns NotImplemented, then right.__rop__(left) is tried.
614 * if left is a subtype of right, then only left.__op__(right)
615 is tried.
616 * if left is a supertype of right, then right.__rop__(left)
617 is first tried and then left.__op__(right)
618 """
619 from astroid import helpers # pylint: disable=import-outside-toplevel
620
621 op = binary_opnode.op
622 if OperatorNode._same_type(left_type, right_type):
623 methods = [OperatorNode._bin_op(left, binary_opnode, op, right, context)]
624 elif helpers.is_subtype(left_type, right_type):
625 methods = [OperatorNode._bin_op(left, binary_opnode, op, right, context)]
626 elif helpers.is_supertype(left_type, right_type):
627 methods = [
628 OperatorNode._bin_op(
629 right, binary_opnode, op, left, reverse_context, reverse=True
630 ),
631 OperatorNode._bin_op(left, binary_opnode, op, right, context),
632 ]
633 else:
634 methods = [
635 OperatorNode._bin_op(left, binary_opnode, op, right, context),
636 OperatorNode._bin_op(
637 right, binary_opnode, op, left, reverse_context, reverse=True
638 ),
639 ]
640
641 # pylint: disable = too-many-boolean-expressions
642 if (
643 op == "|"
644 and (
645 isinstance(left, (bases.UnionType, nodes.ClassDef))
646 or (isinstance(left, nodes.Const) and left.value is None)
647 )
648 and (
649 isinstance(right, (bases.UnionType, nodes.ClassDef))
650 or (isinstance(right, nodes.Const) and right.value is None)
651 )
652 ):
653 methods.extend([partial(OperatorNode._bin_op_or_union_type, left, right)])
654 return methods
655
656 @staticmethod
657 def _infer_binary_operation(
658 left: InferenceResult,
659 right: InferenceResult,
660 binary_opnode: nodes.AugAssign | nodes.BinOp,
661 context: InferenceContext,
662 flow_factory: GetFlowFactory,
663 ) -> Generator[InferenceResult | util.BadBinaryOperationMessage]:
664 """Infer a binary operation between a left operand and a right operand.
665
666 This is used by both normal binary operations and augmented binary
667 operations, the only difference is the flow factory used.
668 """
669 from astroid import helpers # pylint: disable=import-outside-toplevel
670
671 context, reverse_context = OperatorNode._get_binop_contexts(
672 context, left, right
673 )
674 left_type = helpers.object_type(left)
675 right_type = helpers.object_type(right)
676 methods = flow_factory(
677 left, left_type, binary_opnode, right, right_type, context, reverse_context
678 )
679 for method in methods:
680 try:
681 results = list(method())
682 except AttributeError:
683 continue
684 except AttributeInferenceError:
685 continue
686 except InferenceError:
687 yield util.Uninferable
688 return
689 else:
690 if any(isinstance(result, util.UninferableBase) for result in results):
691 yield util.Uninferable
692 return
693
694 if all(map(OperatorNode._is_not_implemented, results)):
695 continue
696 not_implemented = sum(
697 1 for result in results if OperatorNode._is_not_implemented(result)
698 )
699 if not_implemented and not_implemented != len(results):
700 # Can't infer yet what this is.
701 yield util.Uninferable
702 return
703
704 yield from results
705 return
706
707 # The operation doesn't seem to be supported so let the caller know about it
708 yield util.BadBinaryOperationMessage(left_type, binary_opnode.op, right_type)