Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/parso/python/tree.py: 38%
628 statements
« prev ^ index » next coverage.py v7.2.2, created at 2023-03-26 06:07 +0000
1"""
2This is the syntax tree for Python 3 syntaxes. The classes represent
3syntax elements like functions and imports.
5All 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
7a tree is structured, just analyse that file (for each Python version it's a
8bit different).
10There's a lot of logic here that makes it easier for Jedi (and other libraries)
11to deal with a Python syntax tree.
13By using :py:meth:`parso.tree.NodeOrLeaf.get_code` on a module, you can get
14back the 1-to-1 representation of the input given to the parser. This is
15important if you want to refactor a parser tree.
17>>> from parso import parse
18>>> parser = parse('import os')
19>>> module = parser.get_root_node()
20>>> module
21<Module: @1-1>
23Any subclasses of :class:`Scope`, including :class:`Module` has an attribute
24:attr:`iter_imports <Scope.iter_imports>`:
26>>> list(module.iter_imports())
27[<ImportName: import os@1,0>]
29Changes to the Python Grammar
30-----------------------------
32A few things have changed when looking at Python grammar files:
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.
41Parser Tree Classes
42-------------------
43"""
45import re
46try:
47 from collections.abc import Mapping
48except ImportError:
49 from collections import Mapping
50from typing import Tuple
52from parso.tree import Node, BaseNode, Leaf, ErrorNode, ErrorLeaf, search_ancestor # noqa
53from parso.python.prefix import split_prefix
54from parso.utils import split_lines
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
60_FUNC_CONTAINERS = set(
61 ['suite', 'simple_stmt', 'decorated', 'async_funcdef']
62) | _FLOW_CONTAINERS
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'])
71class DocstringMixin:
72 __slots__ = ()
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]
92 if node.type == 'simple_stmt':
93 node = node.children[0]
94 if node.type == 'string':
95 return node
96 return None
99class PythonMixin:
100 """
101 Some Python specific utilities.
102 """
103 __slots__ = ()
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
121class PythonLeaf(PythonMixin, Leaf):
122 __slots__ = ()
124 def _split_prefix(self):
125 return split_prefix(self, self.get_start_pos_of_prefix())
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()
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
145class _LeafWithoutNewlines(PythonLeaf):
146 """
147 Simply here to optimize performance.
148 """
149 __slots__ = ()
151 @property
152 def end_pos(self) -> Tuple[int, int]:
153 return self.line, self.column + len(self.value)
156# Python base classes
157class PythonBaseNode(PythonMixin, BaseNode):
158 __slots__ = ()
161class PythonNode(PythonMixin, Node):
162 __slots__ = ()
165class PythonErrorNode(PythonMixin, ErrorNode):
166 __slots__ = ()
169class PythonErrorLeaf(ErrorLeaf, PythonLeaf):
170 __slots__ = ()
173class EndMarker(_LeafWithoutNewlines):
174 __slots__ = ()
175 type = 'endmarker'
177 def __repr__(self):
178 return "<%s: prefix=%s end_pos=%s>" % (
179 type(self).__name__, repr(self.prefix), self.end_pos
180 )
183class Newline(PythonLeaf):
184 """Contains NEWLINE and ENDMARKER tokens."""
185 __slots__ = ()
186 type = 'newline'
188 def __repr__(self):
189 return "<%s: %s>" % (type(self).__name__, repr(self.value))
192class 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__ = ()
200 def __repr__(self):
201 return "<%s: %s@%s,%s>" % (type(self).__name__, self.value,
202 self.line, self.column)
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
210 def get_definition(self, import_name_always=False, include_setitem=False):
211 """
212 Returns None if there's no definition for a name.
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
221 if type_ in ('funcdef', 'classdef'):
222 if self == node.name:
223 return node
224 return None
226 if type_ == 'except_clause':
227 if self.get_previous_sibling() == 'as':
228 return node.parent # The try_stmt.
229 return None
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
244class Literal(PythonLeaf):
245 __slots__ = ()
248class Number(Literal):
249 type = 'number'
250 __slots__ = ()
253class String(Literal):
254 type = 'string'
255 __slots__ = ()
257 @property
258 def string_prefix(self):
259 return re.match(r'\w*(?=[\'"])', self.value).group(0)
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))]
270class 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__ = ()
279class 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__ = ()
288class 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__ = ()
297class _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
306 return self is other
308 def __hash__(self):
309 return hash(self.value)
312class Operator(_LeafWithoutNewlines, _StringComparisonMixin):
313 type = 'operator'
314 __slots__ = ()
317class Keyword(_LeafWithoutNewlines, _StringComparisonMixin):
318 type = 'keyword'
319 __slots__ = ()
322class 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__ = ()
330 def __init__(self, children):
331 super().__init__(children)
333 def iter_funcdefs(self):
334 """
335 Returns a generator of `funcdef` nodes.
336 """
337 return self._search_in_scope('funcdef')
339 def iter_classdefs(self):
340 """
341 Returns a generator of `classdef` nodes.
342 """
343 return self._search_in_scope('classdef')
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')
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)
359 return scan(self.children)
361 def get_suite(self):
362 """
363 Returns the part that is executed by the function.
364 """
365 return self.children[-1]
367 def __repr__(self):
368 try:
369 name = self.name.value
370 except AttributeError:
371 name = ''
373 return "<%s: %s@%s-%s>" % (type(self).__name__, name,
374 self.start_pos[0], self.end_pos[0])
377class 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'
386 def __init__(self, children):
387 super().__init__(children)
388 self._used_names = None
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]
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 = {}
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)
426 recurse(self)
427 self._used_names = UsedNamesMapping(dct)
428 return self._used_names
431class Decorator(PythonBaseNode):
432 type = 'decorator'
433 __slots__ = ()
436class ClassOrFunc(Scope):
437 __slots__ = ()
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]
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
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 []
463class Class(ClassOrFunc):
464 """
465 Used to store the parsed contents of a python class.
466 """
467 type = 'classdef'
468 __slots__ = ()
470 def __init__(self, children):
471 super().__init__(children)
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]
487def _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 []
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
532class Function(ClassOrFunc):
533 """
534 Used to store the parsed contents of a python function.
536 Children::
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'
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)
557 def _get_param_nodes(self):
558 return self.children[2].children
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']
566 @property
567 def name(self):
568 return self.children[1] # First token after `def`
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
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)
590 return scan(self.children)
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)
604 return scan(self.children)
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)
618 return scan(self.children)
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
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
640class Lambda(Function):
641 """
642 Lambdas are basically trimmed functions, so give it the same interface.
644 Children::
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__ = ()
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)
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.")
671 def _get_param_nodes(self):
672 return self.children[1:-2]
674 @property
675 def annotation(self):
676 """
677 Returns `None`, lambdas don't have annotations.
678 """
679 return None
681 def __repr__(self):
682 return "<%s@%s>" % (self.__class__.__name__, self.start_pos)
685class Flow(PythonBaseNode):
686 __slots__ = ()
689class IfStmt(Flow):
690 type = 'if_stmt'
691 __slots__ = ()
693 def get_test_nodes(self):
694 """
695 E.g. returns all the `test` nodes that are named as x, below:
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]
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
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
734class WhileStmt(Flow):
735 type = 'while_stmt'
736 __slots__ = ()
739class ForStmt(Flow):
740 type = 'for_stmt'
741 __slots__ = ()
743 def get_testlist(self):
744 """
745 Returns the input node ``y`` from: ``for x in y:``.
746 """
747 return self.children[3]
749 def get_defined_names(self, include_setitem=False):
750 return _defined_names(self.children[1], include_setitem)
753class TryStmt(Flow):
754 type = 'try_stmt'
755 __slots__ = ()
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
769class WithStmt(Flow):
770 type = 'with_stmt'
771 __slots__ = ()
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
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]
792class Import(PythonBaseNode):
793 __slots__ = ()
795 def get_path_for_name(self, name):
796 """
797 The path is the list of names that leads to the searched name.
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
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')
812 def is_nested(self):
813 return False # By default, sub classes may overwrite this behavior
815 def is_star_import(self):
816 return self.children[-1] == '*'
819class ImportFrom(Import):
820 type = 'import_from'
821 __slots__ = ()
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()]
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)
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]
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
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.
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``
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>]``.
880 :return list of list of Name:
881 """
882 dotted = self.get_from_names()
884 if self.children[-1] == '*':
885 return [dotted]
886 return [dotted + [name] for name, alias in self._as_name_tuples()]
889class ImportName(Import):
890 """For ``import_name`` nodes. Covers normal imports without ``from``."""
891 type = 'import_name'
892 __slots__ = ()
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()]
902 @property
903 def level(self):
904 """The level parameter of ``__import__``."""
905 return 0 # Obviously 0 for imports without from.
907 def get_paths(self):
908 return [path for path, alias in self._dotted_as_names()]
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]
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
930 def is_nested(self):
931 """
932 This checks for the special case of nested imports, without aliases and
933 from statement::
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])
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)
948class KeywordStatement(PythonBaseNode):
949 """
950 For the following statements: `assert`, `del`, `global`, `nonlocal`,
951 `raise`, `return`, `yield`.
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__ = ()
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
966 @property
967 def keyword(self):
968 return self.children[0].value
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 []
979class AssertStmt(KeywordStatement):
980 __slots__ = ()
982 @property
983 def assertion(self):
984 return self.children[1]
987class GlobalStmt(KeywordStatement):
988 __slots__ = ()
990 def get_global_names(self):
991 return self.children[1::2]
994class ReturnStmt(KeywordStatement):
995 __slots__ = ()
998class YieldExpr(PythonBaseNode):
999 type = 'yield_expr'
1000 __slots__ = ()
1003def _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
1032class ExprStmt(PythonBaseNode, DocstringMixin):
1033 type = 'expr_stmt'
1034 __slots__ = ()
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
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
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.
1069 first = first.children[2]
1070 yield first
1072 yield from self.children[3::2]
1075class NamedExpr(PythonBaseNode):
1076 type = 'namedexpr_test'
1078 def get_defined_names(self, include_setitem=False):
1079 return _defined_names(self.children[0], include_setitem)
1082class 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'
1090 def __init__(self, children, parent=None):
1091 super().__init__(children)
1092 self.parent = parent
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
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
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
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]
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()
1150 def get_defined_names(self, include_setitem=False):
1151 return [self.name]
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
1175 def get_parent_function(self):
1176 """
1177 Returns the function/lambda of a parameter.
1178 """
1179 return self.search_ancestor('funcdef', 'lambdef')
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`.
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)
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 )
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)
1204class SyncCompFor(PythonBaseNode):
1205 type = 'sync_comp_for'
1206 __slots__ = ()
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)
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.
1218CompFor = SyncCompFor
1221class 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
1228 def __getitem__(self, key):
1229 return self._dict[key]
1231 def __len__(self):
1232 return len(self._dict)
1234 def __iter__(self):
1235 return iter(self._dict)
1237 def __hash__(self):
1238 return id(self)
1240 def __eq__(self, other):
1241 # Comparing these dicts does not make sense.
1242 return self is other