djavu-asus/elpy/rpc-venv/lib/python3.11/site-packages/parso/python/tree.py

   1 """
   2 This is the syntax tree for Python 3 syntaxes. The classes represent
   3 syntax elements like functions and imports.
   4
   5 All of the nodes can be traced back to the `Python grammar file
   6 <https://docs.python.org/3/reference/grammar.html>`_. If you want to know how
   7 a tree is structured, just analyse that file (for each Python version it's a
   8 bit different).
   9
  10 There's a lot of logic here that makes it easier for Jedi (and other libraries)
  11 to deal with a Python syntax tree.
  12
  13 By using :py:meth:`parso.tree.NodeOrLeaf.get_code` on a module, you can get
  14 back the 1-to-1 representation of the input given to the parser. This is
  15 important if you want to refactor a parser tree.
  16
  17 >>> from parso import parse
  18 >>> parser = parse('import os')
  19 >>> module = parser.get_root_node()
  20 >>> module
  21 <Module: @1-1>
  22
  23 Any subclasses of :class:`Scope`, including :class:`Module` has an attribute
  24 :attr:`iter_imports <Scope.iter_imports>`:
  25
  26 >>> list(module.iter_imports())
  27 [<ImportName: import os@1,0>]
  28
  29 Changes to the Python Grammar
  30 -----------------------------
  31
  32 A few things have changed when looking at Python grammar files:
  33
  34 - :class:`Param` does not exist in Python grammar files. It is essentially a
  35   part of a ``parameters`` node.  |parso| splits it up to make it easier to
  36   analyse parameters. However this just makes it easier to deal with the syntax
  37   tree, it doesn't actually change the valid syntax.
  38 - A few nodes like `lambdef` and `lambdef_nocond` have been merged in the
  39   syntax tree to make it easier to do deal with them.
  40
  41 Parser Tree Classes
  42 -------------------
  43 """
  44
  45 import re
  46 try:
  47     from collections.abc import Mapping
  48 except ImportError:
  49     from collections import Mapping
  50 from typing import Tuple
  51
  52 from parso.tree import Node, BaseNode, Leaf, ErrorNode, ErrorLeaf, search_ancestor  # noqa
  53 from parso.python.prefix import split_prefix
  54 from parso.utils import split_lines
  55
  56 _FLOW_CONTAINERS = set(['if_stmt', 'while_stmt', 'for_stmt', 'try_stmt',
  57                         'with_stmt', 'async_stmt', 'suite'])
  58 _RETURN_STMT_CONTAINERS = set(['suite', 'simple_stmt']) | _FLOW_CONTAINERS
  59
  60 _FUNC_CONTAINERS = set(
  61     ['suite', 'simple_stmt', 'decorated', 'async_funcdef']
  62 ) | _FLOW_CONTAINERS
  63
  64 _GET_DEFINITION_TYPES = set([
  65     'expr_stmt', 'sync_comp_for', 'with_stmt', 'for_stmt', 'import_name',
  66     'import_from', 'param', 'del_stmt', 'namedexpr_test',
  67 ])
  68 _IMPORTS = set(['import_name', 'import_from'])
  69
  70
  71 class DocstringMixin:
  72     __slots__ = ()
  73
  74     def get_doc_node(self):
  75         """
  76         Returns the string leaf of a docstring. e.g. ``r'''foo'''``.
  77         """
  78         if self.type == 'file_input':
  79             node = self.children[0]
  80         elif self.type in ('funcdef', 'classdef'):
  81             node = self.children[self.children.index(':') + 1]
  82             if node.type == 'suite':  # Normally a suite
  83                 node = node.children[1]  # -> NEWLINE stmt
  84         else:  # ExprStmt
  85             simple_stmt = self.parent
  86             c = simple_stmt.parent.children
  87             index = c.index(simple_stmt)
  88             if not index:
  89                 return None
  90             node = c[index - 1]
  91
  92         if node.type == 'simple_stmt':
  93             node = node.children[0]
  94         if node.type == 'string':
  95             return node
  96         return None
  97
  98
  99 class PythonMixin:
 100     """
 101     Some Python specific utilities.
 102     """
 103     __slots__ = ()
 104
 105     def get_name_of_position(self, position):
 106         """
 107         Given a (line, column) tuple, returns a :py:class:`Name` or ``None`` if
 108         there is no name at that position.
 109         """
 110         for c in self.children:
 111             if isinstance(c, Leaf):
 112                 if c.type == 'name' and c.start_pos <= position <= c.end_pos:
 113                     return c
 114             else:
 115                 result = c.get_name_of_position(position)
 116                 if result is not None:
 117                     return result
 118         return None
 119
 120
 121 class PythonLeaf(PythonMixin, Leaf):
 122     __slots__ = ()
 123
 124     def _split_prefix(self):
 125         return split_prefix(self, self.get_start_pos_of_prefix())
 126
 127     def get_start_pos_of_prefix(self):
 128         """
 129         Basically calls :py:meth:`parso.tree.NodeOrLeaf.get_start_pos_of_prefix`.
 130         """
 131         # TODO it is really ugly that we have to override it. Maybe change
 132         #   indent error leafs somehow? No idea how, though.
 133         previous_leaf = self.get_previous_leaf()
 134         if previous_leaf is not None and previous_leaf.type == 'error_leaf' \
 135                 and previous_leaf.token_type in ('INDENT', 'DEDENT', 'ERROR_DEDENT'):
 136             previous_leaf = previous_leaf.get_previous_leaf()
 137
 138         if previous_leaf is None:  # It's the first leaf.
 139             lines = split_lines(self.prefix)
 140             # + 1 is needed because split_lines always returns at least [''].
 141             return self.line - len(lines) + 1, 0  # It's the first leaf.
 142         return previous_leaf.end_pos
 143
 144
 145 class _LeafWithoutNewlines(PythonLeaf):
 146     """
 147     Simply here to optimize performance.
 148     """
 149     __slots__ = ()
 150
 151     @property
 152     def end_pos(self) -> Tuple[int, int]:
 153         return self.line, self.column + len(self.value)
 154
 155
 156 # Python base classes
 157 class PythonBaseNode(PythonMixin, BaseNode):
 158     __slots__ = ()
 159
 160
 161 class PythonNode(PythonMixin, Node):
 162     __slots__ = ()
 163
 164
 165 class PythonErrorNode(PythonMixin, ErrorNode):
 166     __slots__ = ()
 167
 168
 169 class PythonErrorLeaf(ErrorLeaf, PythonLeaf):
 170     __slots__ = ()
 171
 172
 173 class EndMarker(_LeafWithoutNewlines):
 174     __slots__ = ()
 175     type = 'endmarker'
 176
 177     def __repr__(self):
 178         return "<%s: prefix=%s end_pos=%s>" % (
 179             type(self).__name__, repr(self.prefix), self.end_pos
 180         )
 181
 182
 183 class Newline(PythonLeaf):
 184     """Contains NEWLINE and ENDMARKER tokens."""
 185     __slots__ = ()
 186     type = 'newline'
 187
 188     def __repr__(self):
 189         return "<%s: %s>" % (type(self).__name__, repr(self.value))
 190
 191
 192 class Name(_LeafWithoutNewlines):
 193     """
 194     A string. Sometimes it is important to know if the string belongs to a name
 195     or not.
 196     """
 197     type = 'name'
 198     __slots__ = ()
 199
 200     def __repr__(self):
 201         return "<%s: %s@%s,%s>" % (type(self).__name__, self.value,
 202                                    self.line, self.column)
 203
 204     def is_definition(self, include_setitem=False):
 205         """
 206         Returns True if the name is being defined.
 207         """
 208         return self.get_definition(include_setitem=include_setitem) is not None
 209
 210     def get_definition(self, import_name_always=False, include_setitem=False):
 211         """
 212         Returns None if there's no definition for a name.
 213
 214         :param import_name_always: Specifies if an import name is always a
 215             definition. Normally foo in `from foo import bar` is not a
 216             definition.
 217         """
 218         node = self.parent
 219         type_ = node.type
 220
 221         if type_ in ('funcdef', 'classdef'):
 222             if self == node.name:
 223                 return node
 224             return None
 225
 226         if type_ == 'except_clause':
 227             if self.get_previous_sibling() == 'as':
 228                 return node.parent  # The try_stmt.
 229             return None
 230
 231         while node is not None:
 232             if node.type == 'suite':
 233                 return None
 234             if node.type in _GET_DEFINITION_TYPES:
 235                 if self in node.get_defined_names(include_setitem):
 236                     return node
 237                 if import_name_always and node.type in _IMPORTS:
 238                     return node
 239                 return None
 240             node = node.parent
 241         return None
 242
 243
 244 class Literal(PythonLeaf):
 245     __slots__ = ()
 246
 247
 248 class Number(Literal):
 249     type = 'number'
 250     __slots__ = ()
 251
 252
 253 class String(Literal):
 254     type = 'string'
 255     __slots__ = ()
 256
 257     @property
 258     def string_prefix(self):
 259         return re.match(r'\w*(?=[\'"])', self.value).group(0)
 260
 261     def _get_payload(self):
 262         match = re.search(
 263             r'''('{3}|"{3}|'|")(.*)$''',
 264             self.value,
 265             flags=re.DOTALL
 266         )
 267         return match.group(2)[:-len(match.group(1))]
 268
 269
 270 class FStringString(PythonLeaf):
 271     """
 272     f-strings contain f-string expressions and normal python strings. These are
 273     the string parts of f-strings.
 274     """
 275     type = 'fstring_string'
 276     __slots__ = ()
 277
 278
 279 class FStringStart(PythonLeaf):
 280     """
 281     f-strings contain f-string expressions and normal python strings. These are
 282     the string parts of f-strings.
 283     """
 284     type = 'fstring_start'
 285     __slots__ = ()
 286
 287
 288 class FStringEnd(PythonLeaf):
 289     """
 290     f-strings contain f-string expressions and normal python strings. These are
 291     the string parts of f-strings.
 292     """
 293     type = 'fstring_end'
 294     __slots__ = ()
 295
 296
 297 class _StringComparisonMixin:
 298     def __eq__(self, other):
 299         """
 300         Make comparisons with strings easy.
 301         Improves the readability of the parser.
 302         """
 303         if isinstance(other, str):
 304             return self.value == other
 305
 306         return self is other
 307
 308     def __hash__(self):
 309         return hash(self.value)
 310
 311
 312 class Operator(_LeafWithoutNewlines, _StringComparisonMixin):
 313     type = 'operator'
 314     __slots__ = ()
 315
 316
 317 class Keyword(_LeafWithoutNewlines, _StringComparisonMixin):
 318     type = 'keyword'
 319     __slots__ = ()
 320
 321
 322 class Scope(PythonBaseNode, DocstringMixin):
 323     """
 324     Super class for the parser tree, which represents the state of a python
 325     text file.
 326     A Scope is either a function, class or lambda.
 327     """
 328     __slots__ = ()
 329
 330     def __init__(self, children):
 331         super().__init__(children)
 332
 333     def iter_funcdefs(self):
 334         """
 335         Returns a generator of `funcdef` nodes.
 336         """
 337         return self._search_in_scope('funcdef')
 338
 339     def iter_classdefs(self):
 340         """
 341         Returns a generator of `classdef` nodes.
 342         """
 343         return self._search_in_scope('classdef')
 344
 345     def iter_imports(self):
 346         """
 347         Returns a generator of `import_name` and `import_from` nodes.
 348         """
 349         return self._search_in_scope('import_name', 'import_from')
 350
 351     def _search_in_scope(self, *names):
 352         def scan(children):
 353             for element in children:
 354                 if element.type in names:
 355                     yield element
 356                 if element.type in _FUNC_CONTAINERS:
 357                     yield from scan(element.children)
 358
 359         return scan(self.children)
 360
 361     def get_suite(self):
 362         """
 363         Returns the part that is executed by the function.
 364         """
 365         return self.children[-1]
 366
 367     def __repr__(self):
 368         try:
 369             name = self.name.value
 370         except AttributeError:
 371             name = ''
 372
 373         return "<%s: %s@%s-%s>" % (type(self).__name__, name,
 374                                    self.start_pos[0], self.end_pos[0])
 375
 376
 377 class Module(Scope):
 378     """
 379     The top scope, which is always a module.
 380     Depending on the underlying parser this may be a full module or just a part
 381     of a module.
 382     """
 383     __slots__ = ('_used_names',)
 384     type = 'file_input'
 385
 386     def __init__(self, children):
 387         super().__init__(children)
 388         self._used_names = None
 389
 390     def _iter_future_import_names(self):
 391         """
 392         :return: A list of future import names.
 393         :rtype: list of str
 394         """
 395         # In Python it's not allowed to use future imports after the first
 396         # actual (non-future) statement. However this is not a linter here,
 397         # just return all future imports. If people want to scan for issues
 398         # they should use the API.
 399         for imp in self.iter_imports():
 400             if imp.type == 'import_from' and imp.level == 0:
 401                 for path in imp.get_paths():
 402                     names = [name.value for name in path]
 403                     if len(names) == 2 and names[0] == '__future__':
 404                         yield names[1]
 405
 406     def get_used_names(self):
 407         """
 408         Returns all the :class:`Name` leafs that exist in this module. This
 409         includes both definitions and references of names.
 410         """
 411         if self._used_names is None:
 412             # Don't directly use self._used_names to eliminate a lookup.
 413             dct = {}
 414
 415             def recurse(node):
 416                 try:
 417                     children = node.children
 418                 except AttributeError:
 419                     if node.type == 'name':
 420                         arr = dct.setdefault(node.value, [])
 421                         arr.append(node)
 422                 else:
 423                     for child in children:
 424                         recurse(child)
 425
 426             recurse(self)
 427             self._used_names = UsedNamesMapping(dct)
 428         return self._used_names
 429
 430
 431 class Decorator(PythonBaseNode):
 432     type = 'decorator'
 433     __slots__ = ()
 434
 435
 436 class ClassOrFunc(Scope):
 437     __slots__ = ()
 438
 439     @property
 440     def name(self):
 441         """
 442         Returns the `Name` leaf that defines the function or class name.
 443         """
 444         return self.children[1]
 445
 446     def get_decorators(self):
 447         """
 448         :rtype: list of :class:`Decorator`
 449         """
 450         decorated = self.parent
 451         if decorated.type == 'async_funcdef':
 452             decorated = decorated.parent
 453
 454         if decorated.type == 'decorated':
 455             if decorated.children[0].type == 'decorators':
 456                 return decorated.children[0].children
 457             else:
 458                 return decorated.children[:1]
 459         else:
 460             return []
 461
 462
 463 class Class(ClassOrFunc):
 464     """
 465     Used to store the parsed contents of a python class.
 466     """
 467     type = 'classdef'
 468     __slots__ = ()
 469
 470     def __init__(self, children):
 471         super().__init__(children)
 472
 473     def get_super_arglist(self):
 474         """
 475         Returns the `arglist` node that defines the super classes. It returns
 476         None if there are no arguments.
 477         """
 478         if self.children[2] != '(':  # Has no parentheses
 479             return None
 480         else:
 481             if self.children[3] == ')':  # Empty parentheses
 482                 return None
 483             else:
 484                 return self.children[3]
 485
 486
 487 def _create_params(parent, argslist_list):
 488     """
 489     `argslist_list` is a list that can contain an argslist as a first item, but
 490     most not. It's basically the items between the parameter brackets (which is
 491     at most one item).
 492     This function modifies the parser structure. It generates `Param` objects
 493     from the normal ast. Those param objects do not exist in a normal ast, but
 494     make the evaluation of the ast tree so much easier.
 495     You could also say that this function replaces the argslist node with a
 496     list of Param objects.
 497     """
 498     try:
 499         first = argslist_list[0]
 500     except IndexError:
 501         return []
 502
 503     if first.type in ('name', 'fpdef'):
 504         return [Param([first], parent)]
 505     elif first == '*':
 506         return [first]
 507     else:  # argslist is a `typedargslist` or a `varargslist`.
 508         if first.type == 'tfpdef':
 509             children = [first]
 510         else:
 511             children = first.children
 512         new_children = []
 513         start = 0
 514         # Start with offset 1, because the end is higher.
 515         for end, child in enumerate(children + [None], 1):
 516             if child is None or child == ',':
 517                 param_children = children[start:end]
 518                 if param_children:  # Could as well be comma and then end.
 519                     if param_children[0] == '*' \
 520                             and (len(param_children) == 1
 521                                  or param_children[1] == ',') \
 522                             or param_children[0] == '/':
 523                         for p in param_children:
 524                             p.parent = parent
 525                         new_children += param_children
 526                     else:
 527                         new_children.append(Param(param_children, parent))
 528                     start = end
 529         return new_children
 530
 531
 532 class Function(ClassOrFunc):
 533     """
 534     Used to store the parsed contents of a python function.
 535
 536     Children::
 537
 538         0. <Keyword: def>
 539         1. <Name>
 540         2. parameter list (including open-paren and close-paren <Operator>s)
 541         3. or 5. <Operator: :>
 542         4. or 6. Node() representing function body
 543         3. -> (if annotation is also present)
 544         4. annotation (if present)
 545     """
 546     type = 'funcdef'
 547
 548     def __init__(self, children):
 549         super().__init__(children)
 550         parameters = self.children[2]  # After `def foo`
 551         parameters_children = parameters.children[1:-1]
 552         # If input parameters list already has Param objects, keep it as is;
 553         # otherwise, convert it to a list of Param objects.
 554         if not any(isinstance(child, Param) for child in parameters_children):
 555             parameters.children[1:-1] = _create_params(parameters, parameters_children)
 556
 557     def _get_param_nodes(self):
 558         return self.children[2].children
 559
 560     def get_params(self):
 561         """
 562         Returns a list of `Param()`.
 563         """
 564         return [p for p in self._get_param_nodes() if p.type == 'param']
 565
 566     @property
 567     def name(self):
 568         return self.children[1]  # First token after `def`
 569
 570     def iter_yield_exprs(self):
 571         """
 572         Returns a generator of `yield_expr`.
 573         """
 574         def scan(children):
 575             for element in children:
 576                 if element.type in ('classdef', 'funcdef', 'lambdef'):
 577                     continue
 578
 579                 try:
 580                     nested_children = element.children
 581                 except AttributeError:
 582                     if element.value == 'yield':
 583                         if element.parent.type == 'yield_expr':
 584                             yield element.parent
 585                         else:
 586                             yield element
 587                 else:
 588                     yield from scan(nested_children)
 589
 590         return scan(self.children)
 591
 592     def iter_return_stmts(self):
 593         """
 594         Returns a generator of `return_stmt`.
 595         """
 596         def scan(children):
 597             for element in children:
 598                 if element.type == 'return_stmt' \
 599                         or element.type == 'keyword' and element.value == 'return':
 600                     yield element
 601                 if element.type in _RETURN_STMT_CONTAINERS:
 602                     yield from scan(element.children)
 603
 604         return scan(self.children)
 605
 606     def iter_raise_stmts(self):
 607         """
 608         Returns a generator of `raise_stmt`. Includes raise statements inside try-except blocks
 609         """
 610         def scan(children):
 611             for element in children:
 612                 if element.type == 'raise_stmt' \
 613                         or element.type == 'keyword' and element.value == 'raise':
 614                     yield element
 615                 if element.type in _RETURN_STMT_CONTAINERS:
 616                     yield from scan(element.children)
 617
 618         return scan(self.children)
 619
 620     def is_generator(self):
 621         """
 622         :return bool: Checks if a function is a generator or not.
 623         """
 624         return next(self.iter_yield_exprs(), None) is not None
 625
 626     @property
 627     def annotation(self):
 628         """
 629         Returns the test node after `->` or `None` if there is no annotation.
 630         """
 631         try:
 632             if self.children[3] == "->":
 633                 return self.children[4]
 634             assert self.children[3] == ":"
 635             return None
 636         except IndexError:
 637             return None
 638
 639
 640 class Lambda(Function):
 641     """
 642     Lambdas are basically trimmed functions, so give it the same interface.
 643
 644     Children::
 645
 646          0. <Keyword: lambda>
 647          *. <Param x> for each argument x
 648         -2. <Operator: :>
 649         -1. Node() representing body
 650     """
 651     type = 'lambdef'
 652     __slots__ = ()
 653
 654     def __init__(self, children):
 655         # We don't want to call the Function constructor, call its parent.
 656         super(Function, self).__init__(children)
 657         # Everything between `lambda` and the `:` operator is a parameter.
 658         parameters_children = self.children[1:-2]
 659         # If input children list already has Param objects, keep it as is;
 660         # otherwise, convert it to a list of Param objects.
 661         if not any(isinstance(child, Param) for child in parameters_children):
 662             self.children[1:-2] = _create_params(self, parameters_children)
 663
 664     @property
 665     def name(self):
 666         """
 667         Raises an AttributeError. Lambdas don't have a defined name.
 668         """
 669         raise AttributeError("lambda is not named.")
 670
 671     def _get_param_nodes(self):
 672         return self.children[1:-2]
 673
 674     @property
 675     def annotation(self):
 676         """
 677         Returns `None`, lambdas don't have annotations.
 678         """
 679         return None
 680
 681     def __repr__(self):
 682         return "<%s@%s>" % (self.__class__.__name__, self.start_pos)
 683
 684
 685 class Flow(PythonBaseNode):
 686     __slots__ = ()
 687
 688
 689 class IfStmt(Flow):
 690     type = 'if_stmt'
 691     __slots__ = ()
 692
 693     def get_test_nodes(self):
 694         """
 695         E.g. returns all the `test` nodes that are named as x, below:
 696
 697             if x:
 698                 pass
 699             elif x:
 700                 pass
 701         """
 702         for i, c in enumerate(self.children):
 703             if c in ('elif', 'if'):
 704                 yield self.children[i + 1]
 705
 706     def get_corresponding_test_node(self, node):
 707         """
 708         Searches for the branch in which the node is and returns the
 709         corresponding test node (see function above). However if the node is in
 710         the test node itself and not in the suite return None.
 711         """
 712         start_pos = node.start_pos
 713         for check_node in reversed(list(self.get_test_nodes())):
 714             if check_node.start_pos < start_pos:
 715                 if start_pos < check_node.end_pos:
 716                     return None
 717                     # In this case the node is within the check_node itself,
 718                     # not in the suite
 719                 else:
 720                     return check_node
 721
 722     def is_node_after_else(self, node):
 723         """
 724         Checks if a node is defined after `else`.
 725         """
 726         for c in self.children:
 727             if c == 'else':
 728                 if node.start_pos > c.start_pos:
 729                     return True
 730         else:
 731             return False
 732
 733
 734 class WhileStmt(Flow):
 735     type = 'while_stmt'
 736     __slots__ = ()
 737
 738
 739 class ForStmt(Flow):
 740     type = 'for_stmt'
 741     __slots__ = ()
 742
 743     def get_testlist(self):
 744         """
 745         Returns the input node ``y`` from: ``for x in y:``.
 746         """
 747         return self.children[3]
 748
 749     def get_defined_names(self, include_setitem=False):
 750         return _defined_names(self.children[1], include_setitem)
 751
 752
 753 class TryStmt(Flow):
 754     type = 'try_stmt'
 755     __slots__ = ()
 756
 757     def get_except_clause_tests(self):
 758         """
 759         Returns the ``test`` nodes found in ``except_clause`` nodes.
 760         Returns ``[None]`` for except clauses without an exception given.
 761         """
 762         for node in self.children:
 763             if node.type == 'except_clause':
 764                 yield node.children[1]
 765             elif node == 'except':
 766                 yield None
 767
 768
 769 class WithStmt(Flow):
 770     type = 'with_stmt'
 771     __slots__ = ()
 772
 773     def get_defined_names(self, include_setitem=False):
 774         """
 775         Returns the a list of `Name` that the with statement defines. The
 776         defined names are set after `as`.
 777         """
 778         names = []
 779         for with_item in self.children[1:-2:2]:
 780             # Check with items for 'as' names.
 781             if with_item.type == 'with_item':
 782                 names += _defined_names(with_item.children[2], include_setitem)
 783         return names
 784
 785     def get_test_node_from_name(self, name):
 786         node = name.search_ancestor("with_item")
 787         if node is None:
 788             raise ValueError('The name is not actually part of a with statement.')
 789         return node.children[0]
 790
 791
 792 class Import(PythonBaseNode):
 793     __slots__ = ()
 794
 795     def get_path_for_name(self, name):
 796         """
 797         The path is the list of names that leads to the searched name.
 798
 799         :return list of Name:
 800         """
 801         try:
 802             # The name may be an alias. If it is, just map it back to the name.
 803             name = self._aliases()[name]
 804         except KeyError:
 805             pass
 806
 807         for path in self.get_paths():
 808             if name in path:
 809                 return path[:path.index(name) + 1]
 810         raise ValueError('Name should be defined in the import itself')
 811
 812     def is_nested(self):
 813         return False  # By default, sub classes may overwrite this behavior
 814
 815     def is_star_import(self):
 816         return self.children[-1] == '*'
 817
 818
 819 class ImportFrom(Import):
 820     type = 'import_from'
 821     __slots__ = ()
 822
 823     def get_defined_names(self, include_setitem=False):
 824         """
 825         Returns the a list of `Name` that the import defines. The
 826         defined names are set after `import` or in case an alias - `as` - is
 827         present that name is returned.
 828         """
 829         return [alias or name for name, alias in self._as_name_tuples()]
 830
 831     def _aliases(self):
 832         """Mapping from alias to its corresponding name."""
 833         return dict((alias, name) for name, alias in self._as_name_tuples()
 834                     if alias is not None)
 835
 836     def get_from_names(self):
 837         for n in self.children[1:]:
 838             if n not in ('.', '...'):
 839                 break
 840         if n.type == 'dotted_name':  # from x.y import
 841             return n.children[::2]
 842         elif n == 'import':  # from . import
 843             return []
 844         else:  # from x import
 845             return [n]
 846
 847     @property
 848     def level(self):
 849         """The level parameter of ``__import__``."""
 850         level = 0
 851         for n in self.children[1:]:
 852             if n in ('.', '...'):
 853                 level += len(n.value)
 854             else:
 855                 break
 856         return level
 857
 858     def _as_name_tuples(self):
 859         last = self.children[-1]
 860         if last == ')':
 861             last = self.children[-2]
 862         elif last == '*':
 863             return  # No names defined directly.
 864
 865         if last.type == 'import_as_names':
 866             as_names = last.children[::2]
 867         else:
 868             as_names = [last]
 869         for as_name in as_names:
 870             if as_name.type == 'name':
 871                 yield as_name, None
 872             else:
 873                 yield as_name.children[::2]  # yields x, y -> ``x as y``
 874
 875     def get_paths(self):
 876         """
 877         The import paths defined in an import statement. Typically an array
 878         like this: ``[<Name: datetime>, <Name: date>]``.
 879
 880         :return list of list of Name:
 881         """
 882         dotted = self.get_from_names()
 883
 884         if self.children[-1] == '*':
 885             return [dotted]
 886         return [dotted + [name] for name, alias in self._as_name_tuples()]
 887
 888
 889 class ImportName(Import):
 890     """For ``import_name`` nodes. Covers normal imports without ``from``."""
 891     type = 'import_name'
 892     __slots__ = ()
 893
 894     def get_defined_names(self, include_setitem=False):
 895         """
 896         Returns the a list of `Name` that the import defines. The defined names
 897         is always the first name after `import` or in case an alias - `as` - is
 898         present that name is returned.
 899         """
 900         return [alias or path[0] for path, alias in self._dotted_as_names()]
 901
 902     @property
 903     def level(self):
 904         """The level parameter of ``__import__``."""
 905         return 0  # Obviously 0 for imports without from.
 906
 907     def get_paths(self):
 908         return [path for path, alias in self._dotted_as_names()]
 909
 910     def _dotted_as_names(self):
 911         """Generator of (list(path), alias) where alias may be None."""
 912         dotted_as_names = self.children[1]
 913         if dotted_as_names.type == 'dotted_as_names':
 914             as_names = dotted_as_names.children[::2]
 915         else:
 916             as_names = [dotted_as_names]
 917
 918         for as_name in as_names:
 919             if as_name.type == 'dotted_as_name':
 920                 alias = as_name.children[2]
 921                 as_name = as_name.children[0]
 922             else:
 923                 alias = None
 924             if as_name.type == 'name':
 925                 yield [as_name], alias
 926             else:
 927                 # dotted_names
 928                 yield as_name.children[::2], alias
 929
 930     def is_nested(self):
 931         """
 932         This checks for the special case of nested imports, without aliases and
 933         from statement::
 934
 935             import foo.bar
 936         """
 937         return bool([1 for path, alias in self._dotted_as_names()
 938                     if alias is None and len(path) > 1])
 939
 940     def _aliases(self):
 941         """
 942         :return list of Name: Returns all the alias
 943         """
 944         return dict((alias, path[-1]) for path, alias in self._dotted_as_names()
 945                     if alias is not None)
 946
 947
 948 class KeywordStatement(PythonBaseNode):
 949     """
 950     For the following statements: `assert`, `del`, `global`, `nonlocal`,
 951     `raise`, `return`, `yield`.
 952
 953     `pass`, `continue` and `break` are not in there, because they are just
 954     simple keywords and the parser reduces it to a keyword.
 955     """
 956     __slots__ = ()
 957
 958     @property
 959     def type(self):
 960         """
 961         Keyword statements start with the keyword and end with `_stmt`. You can
 962         crosscheck this with the Python grammar.
 963         """
 964         return '%s_stmt' % self.keyword
 965
 966     @property
 967     def keyword(self):
 968         return self.children[0].value
 969
 970     def get_defined_names(self, include_setitem=False):
 971         keyword = self.keyword
 972         if keyword == 'del':
 973             return _defined_names(self.children[1], include_setitem)
 974         if keyword in ('global', 'nonlocal'):
 975             return self.children[1::2]
 976         return []
 977
 978
 979 class AssertStmt(KeywordStatement):
 980     __slots__ = ()
 981
 982     @property
 983     def assertion(self):
 984         return self.children[1]
 985
 986
 987 class GlobalStmt(KeywordStatement):
 988     __slots__ = ()
 989
 990     def get_global_names(self):
 991         return self.children[1::2]
 992
 993
 994 class ReturnStmt(KeywordStatement):
 995     __slots__ = ()
 996
 997
 998 class YieldExpr(PythonBaseNode):
 999     type = 'yield_expr'
1000     __slots__ = ()
1001
1002
1003 def _defined_names(current, include_setitem):
1004     """
1005     A helper function to find the defined names in statements, for loops and
1006     list comprehensions.
1007     """
1008     names = []
1009     if current.type in ('testlist_star_expr', 'testlist_comp', 'exprlist', 'testlist'):
1010         for child in current.children[::2]:
1011             names += _defined_names(child, include_setitem)
1012     elif current.type in ('atom', 'star_expr'):
1013         names += _defined_names(current.children[1], include_setitem)
1014     elif current.type in ('power', 'atom_expr'):
1015         if current.children[-2] != '**':  # Just if there's no operation
1016             trailer = current.children[-1]
1017             if trailer.children[0] == '.':
1018                 names.append(trailer.children[1])
1019             elif trailer.children[0] == '[' and include_setitem:
1020                 for node in current.children[-2::-1]:
1021                     if node.type == 'trailer':
1022                         names.append(node.children[1])
1023                         break
1024                     if node.type == 'name':
1025                         names.append(node)
1026                         break
1027     else:
1028         names.append(current)
1029     return names
1030
1031
1032 class ExprStmt(PythonBaseNode, DocstringMixin):
1033     type = 'expr_stmt'
1034     __slots__ = ()
1035
1036     def get_defined_names(self, include_setitem=False):
1037         """
1038         Returns a list of `Name` defined before the `=` sign.
1039         """
1040         names = []
1041         if self.children[1].type == 'annassign':
1042             names = _defined_names(self.children[0], include_setitem)
1043         return [
1044             name
1045             for i in range(0, len(self.children) - 2, 2)
1046             if '=' in self.children[i + 1].value
1047             for name in _defined_names(self.children[i], include_setitem)
1048         ] + names
1049
1050     def get_rhs(self):
1051         """Returns the right-hand-side of the equals."""
1052         node = self.children[-1]
1053         if node.type == 'annassign':
1054             if len(node.children) == 4:
1055                 node = node.children[3]
1056             else:
1057                 node = node.children[1]
1058         return node
1059
1060     def yield_operators(self):
1061         """
1062         Returns a generator of `+=`, `=`, etc. or None if there is no operation.
1063         """
1064         first = self.children[1]
1065         if first.type == 'annassign':
1066             if len(first.children) <= 2:
1067                 return  # No operator is available, it's just PEP 484.
1068
1069             first = first.children[2]
1070         yield first
1071
1072         yield from self.children[3::2]
1073
1074
1075 class NamedExpr(PythonBaseNode):
1076     type = 'namedexpr_test'
1077
1078     def get_defined_names(self, include_setitem=False):
1079         return _defined_names(self.children[0], include_setitem)
1080
1081
1082 class Param(PythonBaseNode):
1083     """
1084     It's a helper class that makes business logic with params much easier. The
1085     Python grammar defines no ``param`` node. It defines it in a different way
1086     that is not really suited to working with parameters.
1087     """
1088     type = 'param'
1089
1090     def __init__(self, children, parent=None):
1091         super().__init__(children)
1092         self.parent = parent
1093
1094     @property
1095     def star_count(self):
1096         """
1097         Is `0` in case of `foo`, `1` in case of `*foo` or `2` in case of
1098         `**foo`.
1099         """
1100         first = self.children[0]
1101         if first in ('*', '**'):
1102             return len(first.value)
1103         return 0
1104
1105     @property
1106     def default(self):
1107         """
1108         The default is the test node that appears after the `=`. Is `None` in
1109         case no default is present.
1110         """
1111         has_comma = self.children[-1] == ','
1112         try:
1113             if self.children[-2 - int(has_comma)] == '=':
1114                 return self.children[-1 - int(has_comma)]
1115         except IndexError:
1116             return None
1117
1118     @property
1119     def annotation(self):
1120         """
1121         The default is the test node that appears after `:`. Is `None` in case
1122         no annotation is present.
1123         """
1124         tfpdef = self._tfpdef()
1125         if tfpdef.type == 'tfpdef':
1126             assert tfpdef.children[1] == ":"
1127             assert len(tfpdef.children) == 3
1128             annotation = tfpdef.children[2]
1129             return annotation
1130         else:
1131             return None
1132
1133     def _tfpdef(self):
1134         """
1135         tfpdef: see e.g. grammar36.txt.
1136         """
1137         offset = int(self.children[0] in ('*', '**'))
1138         return self.children[offset]
1139
1140     @property
1141     def name(self):
1142         """
1143         The `Name` leaf of the param.
1144         """
1145         if self._tfpdef().type == 'tfpdef':
1146             return self._tfpdef().children[0]
1147         else:
1148             return self._tfpdef()
1149
1150     def get_defined_names(self, include_setitem=False):
1151         return [self.name]
1152
1153     @property
1154     def position_index(self):
1155         """
1156         Property for the positional index of a paramter.
1157         """
1158         index = self.parent.children.index(self)
1159         try:
1160             keyword_only_index = self.parent.children.index('*')
1161             if index > keyword_only_index:
1162                 # Skip the ` *, `
1163                 index -= 2
1164         except ValueError:
1165             pass
1166         try:
1167             keyword_only_index = self.parent.children.index('/')
1168             if index > keyword_only_index:
1169                 # Skip the ` /, `
1170                 index -= 2
1171         except ValueError:
1172             pass
1173         return index - 1
1174
1175     def get_parent_function(self):
1176         """
1177         Returns the function/lambda of a parameter.
1178         """
1179         return self.search_ancestor('funcdef', 'lambdef')
1180
1181     def get_code(self, include_prefix=True, include_comma=True):
1182         """
1183         Like all the other get_code functions, but includes the param
1184         `include_comma`.
1185
1186         :param include_comma bool: If enabled includes the comma in the string output.
1187         """
1188         if include_comma:
1189             return super().get_code(include_prefix)
1190
1191         children = self.children
1192         if children[-1] == ',':
1193             children = children[:-1]
1194         return self._get_code_for_children(
1195             children,
1196             include_prefix=include_prefix
1197         )
1198
1199     def __repr__(self):
1200         default = '' if self.default is None else '=%s' % self.default.get_code()
1201         return '<%s: %s>' % (type(self).__name__, str(self._tfpdef()) + default)
1202
1203
1204 class SyncCompFor(PythonBaseNode):
1205     type = 'sync_comp_for'
1206     __slots__ = ()
1207
1208     def get_defined_names(self, include_setitem=False):
1209         """
1210         Returns the a list of `Name` that the comprehension defines.
1211         """
1212         # allow async for
1213         return _defined_names(self.children[1], include_setitem)
1214
1215
1216 # This is simply here so an older Jedi version can work with this new parso
1217 # version. Can be deleted in the next release.
1218 CompFor = SyncCompFor
1219
1220
1221 class UsedNamesMapping(Mapping):
1222     """
1223     This class exists for the sole purpose of creating an immutable dict.
1224     """
1225     def __init__(self, dct):
1226         self._dict = dct
1227
1228     def __getitem__(self, key):
1229         return self._dict[key]
1230
1231     def __len__(self):
1232         return len(self._dict)
1233
1234     def __iter__(self):
1235         return iter(self._dict)
1236
1237     def __hash__(self):
1238         return id(self)
1239
1240     def __eq__(self, other):
1241         # Comparing these dicts does not make sense.
1242         return self is other