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
5from __future__ import annotations
6
7from collections.abc import Generator, Iterator, Sequence
8from functools import cached_property
9from functools import singledispatch as _singledispatch
10from typing import (
11 TYPE_CHECKING,
12 ClassVar,
13 Self,
14 TypeVar,
15 cast,
16 overload,
17)
18
19from astroid import nodes, util
20from astroid.context import InferenceContext
21from astroid.exceptions import (
22 AstroidError,
23 InferenceError,
24 ParentMissingError,
25 StatementMissing,
26 UseInferenceDefault,
27)
28from astroid.manager import AstroidManager
29from astroid.nodes.as_string import AsStringVisitor
30from astroid.nodes.const import OP_PRECEDENCE
31from astroid.nodes.utils import Position
32from astroid.typing import (
33 InferenceErrorInfo,
34 InferenceResult,
35 InferFn,
36 SuccessfulInferenceResult,
37)
38
39if TYPE_CHECKING:
40 from astroid.nodes import _base_nodes
41
42 FrameType = nodes.FunctionDef | nodes.Module | nodes.ClassDef | nodes.Lambda
43
44
45# Types for 'NodeNG.nodes_of_class()'
46_NodesT = TypeVar("_NodesT", bound="NodeNG")
47_NodesT2 = TypeVar("_NodesT2", bound="NodeNG")
48_NodesT3 = TypeVar("_NodesT3", bound="NodeNG")
49SkipKlassT = None | type["NodeNG"] | tuple[type["NodeNG"], ...]
50
51
52class NodeNG:
53 """A node of the new Abstract Syntax Tree (AST).
54
55 This is the base class for all Astroid node classes.
56 """
57
58 is_statement: ClassVar[bool] = False
59 """Whether this node indicates a statement."""
60 optional_assign: ClassVar[bool] = False # True for For
61 """Whether this node optionally assigns a variable.
62
63 This is for loop assignments because loop won't necessarily perform an
64 assignment if the loop has no iterations.
65 """
66 is_function: ClassVar[bool] = False # True for FunctionDef nodes
67 """Whether this node indicates a function."""
68 is_lambda: ClassVar[bool] = False
69
70 # Attributes below are set by the builder module or by raw factories
71 _astroid_fields: ClassVar[tuple[str, ...]] = ()
72 """Node attributes that contain child nodes.
73
74 This is redefined in most concrete classes.
75 """
76 _other_fields: ClassVar[tuple[str, ...]] = ()
77 """Node attributes that do not contain child nodes."""
78 _other_other_fields: ClassVar[tuple[str, ...]] = ()
79 """Attributes that contain AST-dependent fields."""
80 # instance specific inference function infer(node, context)
81 _explicit_inference: InferFn[Self] | None = None
82
83 def __init__(
84 self,
85 lineno: int | None,
86 col_offset: int | None,
87 parent: NodeNG | None,
88 *,
89 end_lineno: int | None,
90 end_col_offset: int | None,
91 ) -> None:
92 self.lineno = lineno
93 """The line that this node appears on in the source code."""
94
95 self.col_offset = col_offset
96 """The column that this node appears on in the source code."""
97
98 self.parent = parent
99 """The parent node in the syntax tree."""
100
101 self.end_lineno = end_lineno
102 """The last line this node appears on in the source code."""
103
104 self.end_col_offset = end_col_offset
105 """The end column this node appears on in the source code.
106
107 Note: This is after the last symbol.
108 """
109
110 self.position: Position | None = None
111 """Position of keyword(s) and name.
112
113 Used as fallback for block nodes which might not provide good
114 enough positional information. E.g. ClassDef, FunctionDef.
115 """
116
117 def infer(
118 self, context: InferenceContext | None = None
119 ) -> Generator[InferenceResult]:
120 """Get a generator of the inferred values.
121
122 This is the main entry point to the inference system.
123
124 .. seealso:: :ref:`inference`
125
126 If the instance has some explicit inference function set, it will be
127 called instead of the default interface.
128
129 :returns: The inferred values.
130 """
131 if context is None:
132 context = InferenceContext()
133 else:
134 context = context.extra_context.get(self, context)
135 if self._explicit_inference is not None:
136 # explicit_inference is not bound, give it self explicitly
137 try:
138 for result in self._explicit_inference(
139 self, # type: ignore[arg-type]
140 context,
141 ):
142 context.nodes_inferred += 1
143 yield result
144 return
145 except UseInferenceDefault:
146 pass
147
148 key = (self, context.lookupname, context.callcontext, context.boundnode)
149 if key in context.inferred:
150 yield from context.inferred[key]
151 return
152
153 results = []
154
155 # Limit inference amount to help with performance issues with
156 # exponentially exploding possible results.
157 limit = AstroidManager().max_inferable_values
158 for i, result in enumerate(self._infer(context=context)):
159 if i >= limit or (context.nodes_inferred > context.max_inferred):
160 results.append(util.Uninferable)
161 yield util.Uninferable
162 break
163 results.append(result)
164 yield result
165 context.nodes_inferred += 1
166
167 # Cache generated results for subsequent inferences of the
168 # same node using the same context
169 context.inferred[key] = tuple(results)
170 return
171
172 def repr_name(self) -> str:
173 """Get a name for nice representation.
174
175 This is either ``name``, ``attrname``, or the empty string.
176 """
177 if all(name not in self._astroid_fields for name in ("name", "attrname")):
178 return getattr(self, "name", "") or getattr(self, "attrname", "")
179 return ""
180
181 def __str__(self) -> str:
182 import pprint # pylint: disable=import-outside-toplevel
183
184 rname = self.repr_name()
185 cname = type(self).__name__
186 if rname:
187 string = "%(cname)s.%(rname)s(%(fields)s)"
188 alignment = len(cname) + len(rname) + 2
189 else:
190 string = "%(cname)s(%(fields)s)"
191 alignment = len(cname) + 1
192 result = []
193 for field in self._other_fields + self._astroid_fields:
194 value = getattr(self, field, "Unknown")
195 width = max(80 - len(field) - alignment, 1)
196 try:
197 lines = pprint.pformat(value, indent=2, width=width).splitlines(True)
198 except ValueError:
199 lines = [f"<{type(value).__name__}>"]
200
201 inner = [lines[0]]
202 for line in lines[1:]:
203 inner.append(" " * alignment + line)
204 result.append(f"{field}={''.join(inner)}")
205
206 return string % {
207 "cname": cname,
208 "rname": rname,
209 "fields": (",\n" + " " * alignment).join(result),
210 }
211
212 def __repr__(self) -> str:
213 rname = self.repr_name()
214 # The dependencies used to calculate fromlineno (if not cached) may not exist at the time
215 try:
216 lineno = self.fromlineno
217 except AttributeError:
218 lineno = 0
219 if rname:
220 string = "<%(cname)s.%(rname)s l.%(lineno)s at 0x%(id)x>"
221 else:
222 string = "<%(cname)s l.%(lineno)s at 0x%(id)x>"
223 return string % {
224 "cname": type(self).__name__,
225 "rname": rname,
226 "lineno": lineno,
227 "id": id(self),
228 }
229
230 def accept(self, visitor: AsStringVisitor) -> str:
231 """Visit this node using the given visitor."""
232 func = getattr(visitor, "visit_" + self.__class__.__name__.lower())
233 return func(self)
234
235 def get_children(self) -> Iterator[NodeNG]:
236 """Get the child nodes below this node."""
237 for field in self._astroid_fields:
238 attr = getattr(self, field)
239 if attr is None:
240 continue
241 if isinstance(attr, (list, tuple)):
242 yield from attr
243 else:
244 yield attr
245 yield from ()
246
247 def last_child(self) -> NodeNG | None:
248 """An optimized version of list(get_children())[-1]."""
249 for field in self._astroid_fields[::-1]:
250 attr = getattr(self, field)
251 if not attr: # None or empty list / tuple
252 continue
253 if isinstance(attr, (list, tuple)):
254 return attr[-1]
255 return attr
256 return None
257
258 def node_ancestors(self) -> Iterator[NodeNG]:
259 """Yield parent, grandparent, etc until there are no more."""
260 parent = self.parent
261 while parent is not None:
262 yield parent
263 parent = parent.parent
264
265 def parent_of(self, node: SuccessfulInferenceResult) -> bool:
266 """Check if this node is the parent of the given node.
267
268 :param node: The node to check if it is the child.
269
270 :returns: Whether this node is the parent of the given node.
271 """
272 return any(self is parent for parent in node.node_ancestors())
273
274 def statement(self) -> _base_nodes.Statement:
275 """The first parent node, including self, marked as statement node.
276
277 :raises StatementMissing: If self has no parent attribute.
278 """
279 if self.is_statement:
280 return cast("_base_nodes.Statement", self)
281 if not self.parent:
282 raise StatementMissing(target=self)
283 return self.parent.statement()
284
285 def frame(self) -> FrameType:
286 """The first parent frame node.
287
288 A frame node is a :class:`Module`, :class:`FunctionDef`,
289 :class:`ClassDef` or :class:`Lambda`.
290
291 :returns: The first parent frame node.
292 :raises ParentMissingError: If self has no parent attribute.
293 """
294 if self.parent is None:
295 raise ParentMissingError(target=self)
296 return self.parent.frame()
297
298 def scope(self) -> nodes.LocalsDictNodeNG:
299 """The first parent node defining a new scope.
300
301 These can be Module, FunctionDef, ClassDef, Lambda, or GeneratorExp nodes.
302
303 :returns: The first parent scope node.
304 """
305 if not self.parent:
306 raise ParentMissingError(target=self)
307 return self.parent.scope()
308
309 def root(self) -> nodes.Module:
310 """Return the root node of the syntax tree.
311
312 :returns: The root node.
313 """
314 if not (parent := self.parent):
315 assert isinstance(self, nodes.Module)
316 return self
317
318 while parent.parent:
319 parent = parent.parent
320 assert isinstance(parent, nodes.Module)
321 return parent
322
323 def child_sequence(self, child: NodeNG) -> Sequence[NodeNG]:
324 """Search for the sequence that contains this child.
325
326 :param child: The child node to search sequences for.
327
328 :returns: The sequence containing the given child node.
329
330 :raises AstroidError: If no sequence could be found that contains
331 the given child.
332 """
333 for field in self._astroid_fields:
334 node_or_sequence = getattr(self, field)
335 if node_or_sequence is child:
336 return [node_or_sequence]
337 # /!\ compiler.ast Nodes have an __iter__ walking over child nodes
338 if (
339 isinstance(node_or_sequence, (tuple, list))
340 and child in node_or_sequence
341 ):
342 return node_or_sequence
343
344 msg = "Could not find %s in %s's children"
345 raise AstroidError(msg % (repr(child), repr(self)))
346
347 def locate_child(self, child: NodeNG) -> tuple[str, NodeNG | Sequence[NodeNG]]:
348 """Find the field of this node that contains the given child.
349
350 :param child: The child node to search fields for.
351
352 :returns: A tuple of the name of the field that contains the child,
353 and the sequence or node that contains the child node.
354
355 :raises AstroidError: If no field could be found that contains
356 the given child.
357 """
358 for field in self._astroid_fields:
359 node_or_sequence = getattr(self, field)
360 # /!\ compiler.ast Nodes have an __iter__ walking over child nodes
361 if child is node_or_sequence:
362 return field, child
363 if (
364 isinstance(node_or_sequence, (tuple, list))
365 and child in node_or_sequence
366 ):
367 return field, node_or_sequence
368 msg = "Could not find %s in %s's children"
369 raise AstroidError(msg % (repr(child), repr(self)))
370
371 # FIXME : should we merge child_sequence and locate_child ? locate_child
372 # is only used in are_exclusive, child_sequence one time in pylint.
373
374 def next_sibling(self) -> NodeNG | None:
375 """The next sibling statement node.
376
377 :returns: The next sibling statement node.
378 """
379 return self.parent.next_sibling()
380
381 def previous_sibling(self) -> NodeNG | None:
382 """The previous sibling statement.
383
384 :returns: The previous sibling statement node.
385 """
386 return self.parent.previous_sibling()
387
388 # these are lazy because they're relatively expensive to compute for every
389 # single node, and they rarely get looked at
390
391 @cached_property
392 def fromlineno(self) -> int:
393 """The first line that this node appears on in the source code.
394
395 Can also return 0 if the line can not be determined.
396 """
397 if self.lineno is None:
398 return self._fixed_source_line()
399 return self.lineno
400
401 @cached_property
402 def tolineno(self) -> int:
403 """The last line that this node appears on in the source code.
404
405 Can also return 0 if the line can not be determined.
406 """
407 if self.end_lineno is not None:
408 return self.end_lineno
409 if not self._astroid_fields:
410 # can't have children
411 last_child = None
412 else:
413 last_child = self.last_child()
414 if last_child is None:
415 return self.fromlineno
416 return last_child.tolineno
417
418 def _fixed_source_line(self) -> int:
419 """Attempt to find the line that this node appears on.
420
421 We need this method since not all nodes have :attr:`lineno` set.
422 Will return 0 if the line number can not be determined.
423 """
424 line = self.lineno
425 _node = self
426 try:
427 while line is None:
428 _node = next(_node.get_children())
429 line = _node.lineno
430 except StopIteration:
431 parent = self.parent
432 while parent and line is None:
433 line = parent.lineno
434 parent = parent.parent
435 return line or 0
436
437 def block_range(self, lineno: int) -> tuple[int, int]:
438 """Get a range from the given line number to where this node ends.
439
440 :param lineno: The line number to start the range at.
441
442 :returns: The range of line numbers that this node belongs to,
443 starting at the given line number.
444 """
445 return lineno, self.tolineno
446
447 def set_local(self, name: str, stmt: NodeNG) -> None:
448 """Define that the given name is declared in the given statement node.
449
450 This definition is stored on the parent scope node.
451
452 .. seealso:: :meth:`scope`
453
454 :param name: The name that is being defined.
455
456 :param stmt: The statement that defines the given name.
457 """
458 assert self.parent
459 self.parent.set_local(name, stmt)
460
461 @overload
462 def nodes_of_class(
463 self,
464 klass: type[_NodesT],
465 skip_klass: SkipKlassT = ...,
466 ) -> Iterator[_NodesT]: ...
467
468 @overload
469 def nodes_of_class(
470 self,
471 klass: tuple[type[_NodesT], type[_NodesT2]],
472 skip_klass: SkipKlassT = ...,
473 ) -> Iterator[_NodesT] | Iterator[_NodesT2]: ...
474
475 @overload
476 def nodes_of_class(
477 self,
478 klass: tuple[type[_NodesT], type[_NodesT2], type[_NodesT3]],
479 skip_klass: SkipKlassT = ...,
480 ) -> Iterator[_NodesT] | Iterator[_NodesT2] | Iterator[_NodesT3]: ...
481
482 @overload
483 def nodes_of_class(
484 self,
485 klass: tuple[type[_NodesT], ...],
486 skip_klass: SkipKlassT = ...,
487 ) -> Iterator[_NodesT]: ...
488
489 def nodes_of_class( # type: ignore[misc] # mypy doesn't correctly recognize the overloads
490 self,
491 klass: (
492 type[_NodesT]
493 | tuple[type[_NodesT], type[_NodesT2]]
494 | tuple[type[_NodesT], type[_NodesT2], type[_NodesT3]]
495 | tuple[type[_NodesT], ...]
496 ),
497 skip_klass: SkipKlassT = None,
498 ) -> Iterator[_NodesT] | Iterator[_NodesT2] | Iterator[_NodesT3]:
499 """Get the nodes (including this one or below) of the given types.
500
501 :param klass: The types of node to search for.
502
503 :param skip_klass: The types of node to ignore. This is useful to ignore
504 subclasses of ``klass``.
505
506 :returns: The node of the given types.
507 """
508 if isinstance(self, klass):
509 yield self
510
511 if skip_klass is None:
512 for child_node in self.get_children():
513 yield from child_node.nodes_of_class(klass, skip_klass)
514
515 return
516
517 for child_node in self.get_children():
518 if isinstance(child_node, skip_klass):
519 continue
520 yield from child_node.nodes_of_class(klass, skip_klass)
521
522 @cached_property
523 def _assign_nodes_in_scope(self) -> list[nodes.Assign]:
524 return []
525
526 def _get_name_nodes(self):
527 for child_node in self.get_children():
528 yield from child_node._get_name_nodes()
529
530 def _get_return_nodes_skip_functions(self):
531 yield from ()
532
533 def _get_yield_nodes_skip_functions(self):
534 yield from ()
535
536 def _get_yield_nodes_skip_lambdas(self):
537 yield from ()
538
539 def _infer_name(self, frame, name):
540 # overridden for ImportFrom, Import, Global, Try, TryStar and Arguments
541 pass
542
543 def _infer(
544 self, context: InferenceContext | None = None
545 ) -> Generator[InferenceResult, None, InferenceErrorInfo | None]:
546 """We don't know how to resolve a statement by default."""
547 # this method is overridden by most concrete classes
548 raise InferenceError(
549 "No inference function for {node!r}.", node=self, context=context
550 )
551
552 def inferred(self) -> list[InferenceResult]:
553 """Get a list of the inferred values.
554
555 .. seealso:: :ref:`inference`
556
557 :returns: The inferred values.
558 """
559 return list(self.infer())
560
561 def instantiate_class(self) -> SuccessfulInferenceResult:
562 """Instantiate an instance of the defined class.
563
564 .. note::
565
566 On anything other than a :class:`ClassDef` this will return self.
567
568 :returns: An instance of the defined class.
569 """
570 return self
571
572 def has_base(self, node: NodeNG) -> bool:
573 """Check if this node inherits from the given type.
574
575 :param node: The node defining the base to look for.
576 Usually this is a :class:`Name` node.
577 """
578 return False
579
580 def callable(self) -> bool:
581 """Whether this node defines something that is callable.
582
583 :returns: Whether this defines something that is callable.
584 """
585 return False
586
587 def eq(self, value) -> bool:
588 return False
589
590 def as_string(self) -> str:
591 """Get the source code that this node represents."""
592 return AsStringVisitor()(self)
593
594 def repr_tree(
595 self,
596 ids: bool = False,
597 include_linenos: bool = False,
598 ast_state: bool = False,
599 indent: str = " ",
600 max_depth: int = 0,
601 max_width: int = 80,
602 ) -> str:
603 """Get a string representation of the AST from this node.
604
605 :param ids: If true, includes the ids with the node type names.
606
607 :param include_linenos: If true, includes the line numbers and
608 column offsets.
609
610 :param ast_state: If true, includes information derived from
611 the whole AST like local and global variables.
612
613 :param indent: A string to use to indent the output string.
614
615 :param max_depth: If set to a positive integer, won't return
616 nodes deeper than max_depth in the string.
617
618 :param max_width: Attempt to format the output string to stay
619 within this number of characters, but can exceed it under some
620 circumstances. Only positive integer values are valid, the default is 80.
621
622 :returns: The string representation of the AST.
623 """
624
625 # pylint: disable = too-many-statements
626 import pprint # pylint: disable=import-outside-toplevel
627
628 @_singledispatch
629 def _repr_tree(node, result, done, cur_indent="", depth=1):
630 """Outputs a representation of a non-tuple/list, non-node that's
631 contained within an AST, including strings.
632 """
633 lines = pprint.pformat(
634 node, width=max(max_width - len(cur_indent), 1)
635 ).splitlines(True)
636 result.append(lines[0])
637 result.extend([cur_indent + line for line in lines[1:]])
638 return len(lines) != 1
639
640 # pylint: disable=unused-variable,useless-suppression; doesn't understand singledispatch
641 @_repr_tree.register(tuple)
642 @_repr_tree.register(list)
643 def _repr_seq(node, result, done, cur_indent="", depth=1):
644 """Outputs a representation of a sequence that's contained within an
645 AST.
646 """
647 cur_indent += indent
648 result.append("[")
649 if not node:
650 broken = False
651 elif len(node) == 1:
652 broken = _repr_tree(node[0], result, done, cur_indent, depth)
653 elif len(node) == 2:
654 broken = _repr_tree(node[0], result, done, cur_indent, depth)
655 if not broken:
656 result.append(", ")
657 else:
658 result.append(",\n")
659 result.append(cur_indent)
660 broken = _repr_tree(node[1], result, done, cur_indent, depth) or broken
661 else:
662 result.append("\n")
663 result.append(cur_indent)
664 for child in node[:-1]:
665 _repr_tree(child, result, done, cur_indent, depth)
666 result.append(",\n")
667 result.append(cur_indent)
668 _repr_tree(node[-1], result, done, cur_indent, depth)
669 broken = True
670 result.append("]")
671 return broken
672
673 # pylint: disable=unused-variable,useless-suppression; doesn't understand singledispatch
674 @_repr_tree.register(NodeNG)
675 def _repr_node(node, result, done, cur_indent="", depth=1):
676 """Outputs a strings representation of an astroid node."""
677 if node in done:
678 result.append(
679 indent + f"<Recursion on {type(node).__name__} with id={id(node)}"
680 )
681 return False
682 done.add(node)
683
684 if max_depth and depth > max_depth:
685 result.append("...")
686 return False
687 depth += 1
688 cur_indent += indent
689 if ids:
690 result.append(f"{type(node).__name__}<0x{id(node):x}>(\n")
691 else:
692 result.append(f"{type(node).__name__}(")
693 fields = []
694 if include_linenos:
695 fields.extend(("lineno", "col_offset"))
696 fields.extend(node._other_fields)
697 fields.extend(node._astroid_fields)
698 if ast_state:
699 fields.extend(node._other_other_fields)
700 if not fields:
701 broken = False
702 elif len(fields) == 1:
703 result.append(f"{fields[0]}=")
704 broken = _repr_tree(
705 getattr(node, fields[0]), result, done, cur_indent, depth
706 )
707 else:
708 result.append("\n")
709 result.append(cur_indent)
710 for field in fields[:-1]:
711 # TODO: Remove this after removal of the 'doc' attribute
712 if field == "doc":
713 continue
714 result.append(f"{field}=")
715 _repr_tree(getattr(node, field), result, done, cur_indent, depth)
716 result.append(",\n")
717 result.append(cur_indent)
718 result.append(f"{fields[-1]}=")
719 _repr_tree(getattr(node, fields[-1]), result, done, cur_indent, depth)
720 broken = True
721 result.append(")")
722 return broken
723
724 result: list[str] = []
725 _repr_tree(self, result, set())
726 return "".join(result)
727
728 def bool_value(
729 self, context: InferenceContext | None = None
730 ) -> bool | util.UninferableBase:
731 """Determine the boolean value of this node.
732
733 The boolean value of a node can have three
734 possible values:
735
736 * False: For instance, empty data structures,
737 False, empty strings, instances which return
738 explicitly False from the __nonzero__ / __bool__
739 method.
740 * True: Most of constructs are True by default:
741 classes, functions, modules etc
742 * Uninferable: The inference engine is uncertain of the
743 node's value.
744
745 :returns: The boolean value of this node.
746 """
747 return util.Uninferable
748
749 def op_precedence(self) -> int:
750 # Look up by class name or default to highest precedence
751 return OP_PRECEDENCE.get(self.__class__.__name__, len(OP_PRECEDENCE))
752
753 def op_left_associative(self) -> bool:
754 # Everything is left associative except `**` and IfExp
755 return True