Parser Tree

The parser tree is returned by calling parso.Grammar.parse().


Note that parso positions are always 1 based for lines and zero based for columns. This means the first position in a file is (1, 0).

Parser Tree Base Classes

Generally there are two types of classes you will deal with: parso.tree.Leaf and parso.tree.BaseNode.

class parso.tree.BaseNode(children)[source]

Bases: parso.tree.NodeOrLeaf

The super class for all nodes. A node has children, a type and possibly a parent node.


A list of NodeOrLeaf child nodes.


The parent BaseNode of this leaf. None if this is the root node.

get_leaf_for_position(position, include_prefixes=False)[source]

Get the parso.tree.Leaf at position

  • position (tuple) – A position tuple, row, column. Rows start from 1
  • include_prefixes (bool) – If False, None will be returned if position falls on whitespace or comments before a leaf

parso.tree.Leaf at position, or None

class parso.tree.Leaf(value, start_pos, prefix='')[source]

Bases: parso.tree.NodeOrLeaf

Leafs are basically tokens with a better API. Leafs exactly know where they were defined and what text preceeds them.


str() The value of the current token.


str() Typically a mixture of whitespace and comments. Stuff that is syntactically irrelevant for the syntax tree.


The parent BaseNode of this leaf.

All nodes and leaves have these methods/properties:

class parso.tree.NodeOrLeaf[source]

Bases: object

The base class for nodes and leaves.

type = None

The type is a string that typically matches the types of the grammar file.


Returns the root node of a parser tree. The returned node doesn’t have a parent node like all the other nodes/leaves.


Returns the node immediately following this node in this parent’s children list. If this node does not have a next sibling, it is None


Returns the node immediately preceding this node in this parent’s children list. If this node does not have a previous sibling, it is None.


Returns the previous leaf in the parser tree. Returns None if this is the first element in the parser tree.


Returns the next leaf in the parser tree. Returns None if this is the last element in the parser tree.


Returns the starting position of the prefix as a tuple, e.g. (3, 4).

Return tuple of int:
 (line, column)

Returns the end position of the prefix as a tuple, e.g. (3, 4).

Return tuple of int:
 (line, column)

Returns the start_pos of the prefix. This means basically it returns the end_pos of the last prefix. The get_start_pos_of_prefix() of the prefix + in 2 + 1 would be (1, 1), while the start_pos is (1, 2).

Return tuple of int:
 (line, column)

Returns the first leaf of a node or itself if this is a leaf.


Returns the last leaf of a node or itself if this is a leaf.


Returns the code that was input the input for the parser for this node.

Parameters:include_prefix – Removes the prefix (whitespace and comments) of e.g. a statement.

Python Parser Tree

This is the syntax tree for Python syntaxes (2 & 3). The classes represent syntax elements like functions and imports.

All of the nodes can be traced back to the Python grammar file. If you want to know how a tree is structured, just analyse that file (for each Python version it’s a bit different).

There’s a lot of logic here that makes it easier for Jedi (and other libraries) to deal with a Python syntax tree.

By using parso.tree.NodeOrLeaf.get_code() on a module, you can get back the 1-to-1 representation of the input given to the parser. This is important if you want to refactor a parser tree.

>>> from parso import parse
>>> parser = parse('import os')
>>> module = parser.get_root_node()
>>> module
<Module: @1-1>

Any subclasses of Scope, including Module has an attribute iter_imports:

>>> list(module.iter_imports())
[<ImportName: import os@1,0>]

Changes to the Python Grammar

A few things have changed when looking at Python grammar files:

  • Param does not exist in Python grammar files. It is essentially a part of a parameters node. parso splits it up to make it easier to analyse parameters. However this just makes it easier to deal with the syntax tree, it doesn’t actually change the valid syntax.
  • A few nodes like lambdef and lambdef_nocond have been merged in the syntax tree to make it easier to do deal with them.

Parser Tree Classes

class parso.python.tree.DocstringMixin[source]

Bases: object


Returns the string leaf of a docstring. e.g. r'''foo'''.

class parso.python.tree.PythonMixin[source]

Bases: object

Some Python specific utitilies.


Given a (line, column) tuple, returns a Name or None if there is no name at that position.

class parso.python.tree.PythonLeaf(value, start_pos, prefix='')[source]

Bases: parso.python.tree.PythonMixin, parso.tree.Leaf


Basically calls parso.tree.NodeOrLeaf.get_start_pos_of_prefix().

class parso.python.tree.PythonBaseNode(children)[source]

Bases: parso.python.tree.PythonMixin, parso.tree.BaseNode

class parso.python.tree.PythonNode(type, children)[source]

Bases: parso.python.tree.PythonMixin, parso.tree.Node

class parso.python.tree.PythonErrorNode(children)[source]

Bases: parso.python.tree.PythonMixin, parso.tree.ErrorNode

class parso.python.tree.PythonErrorLeaf(original_type, value, start_pos, prefix='')[source]

Bases: parso.tree.ErrorLeaf, parso.python.tree.PythonLeaf

class parso.python.tree.EndMarker(value, start_pos, prefix='')[source]

Bases: parso.python.tree._LeafWithoutNewlines

type = 'endmarker'
class parso.python.tree.Newline(value, start_pos, prefix='')[source]

Bases: parso.python.tree.PythonLeaf

Contains NEWLINE and ENDMARKER tokens.

type = 'newline'
class parso.python.tree.Name(value, start_pos, prefix='')[source]

Bases: parso.python.tree._LeafWithoutNewlines

A string. Sometimes it is important to know if the string belongs to a name or not.

type = 'name'

Returns True if the name is being defined.


Returns None if there’s on definition for a name.

Parameters:import_name_alway – Specifies if an import name is always a definition. Normally foo in from foo import bar is not a definition.
class parso.python.tree.Literal(value, start_pos, prefix='')[source]

Bases: parso.python.tree.PythonLeaf

class parso.python.tree.Number(value, start_pos, prefix='')[source]

Bases: parso.python.tree.Literal

type = 'number'
class parso.python.tree.String(value, start_pos, prefix='')[source]

Bases: parso.python.tree.Literal

type = 'string'
class parso.python.tree.Operator(value, start_pos, prefix='')[source]

Bases: parso.python.tree._LeafWithoutNewlines, parso.python.tree._StringComparisonMixin

type = 'operator'
class parso.python.tree.Keyword(value, start_pos, prefix='')[source]

Bases: parso.python.tree._LeafWithoutNewlines, parso.python.tree._StringComparisonMixin

type = 'keyword'
class parso.python.tree.Scope(children)[source]

Bases: parso.python.tree.PythonBaseNode, parso.python.tree.DocstringMixin

Super class for the parser tree, which represents the state of a python text file. A Scope is either a function, class or lambda.


Returns a generator of funcdef nodes.


Returns a generator of classdef nodes.


Returns a generator of import_name and import_from nodes.


Returns the part that is executed by the function.

class parso.python.tree.Module(children)[source]

Bases: parso.python.tree.Scope

The top scope, which is always a module. Depending on the underlying parser this may be a full module or just a part of a module.

type = 'file_input'

Returns all the Name leafs that exist in this module. This includes both definitions and references of names.

class parso.python.tree.Decorator(children)[source]

Bases: parso.python.tree.PythonBaseNode

type = 'decorator'
class parso.python.tree.ClassOrFunc(children)[source]

Bases: parso.python.tree.Scope


Returns the Name leaf that defines the function or class name.

Return type:list of Decorator
class parso.python.tree.Class(children)[source]

Bases: parso.python.tree.ClassOrFunc

Used to store the parsed contents of a python class.

type = 'classdef'

Returns the arglist node that defines the super classes. It returns None if there are no arguments.

class parso.python.tree.Function(children)[source]

Bases: parso.python.tree.ClassOrFunc

Used to store the parsed contents of a python function.


0. <Keyword: def>
1. <Name>
2. parameter list (including open-paren and close-paren <Operator>s)
3. or 5. <Operator: :>
4. or 6. Node() representing function body
3. -> (if annotation is also present)
4. annotation (if present)
type = 'funcdef'

Returns a list of Param().


Returns a generator of yield_expr.


Returns a generator of return_stmt.


Returns a generator of raise_stmt. Includes raise statements inside try-except blocks

Return bool:Checks if a function is a generator or not.

Returns the test node after -> or None if there is no annotation.

class parso.python.tree.Lambda(children)[source]

Bases: parso.python.tree.Function

Lambdas are basically trimmed functions, so give it the same interface.


 0. <Keyword: lambda>
 *. <Param x> for each argument x
-2. <Operator: :>
-1. Node() representing body
type = 'lambdef'

Raises an AttributeError. Lambdas don’t have a defined name.


Returns None, lambdas don’t have annotations.

class parso.python.tree.Flow(children)[source]

Bases: parso.python.tree.PythonBaseNode

class parso.python.tree.IfStmt(children)[source]

Bases: parso.python.tree.Flow

type = 'if_stmt'

E.g. returns all the test nodes that are named as x, below:

if x:
elif x:

Searches for the branch in which the node is and returns the corresponding test node (see function above). However if the node is in the test node itself and not in the suite return None.


Checks if a node is defined after else.

class parso.python.tree.WhileStmt(children)[source]

Bases: parso.python.tree.Flow

type = 'while_stmt'
class parso.python.tree.ForStmt(children)[source]

Bases: parso.python.tree.Flow

type = 'for_stmt'

Returns the input node y from: for x in y:.

class parso.python.tree.TryStmt(children)[source]

Bases: parso.python.tree.Flow

type = 'try_stmt'

Returns the test nodes found in except_clause nodes. Returns [None] for except clauses without an exception given.

class parso.python.tree.WithStmt(children)[source]

Bases: parso.python.tree.Flow

type = 'with_stmt'

Returns the a list of Name that the with statement defines. The defined names are set after as.

class parso.python.tree.Import(children)[source]

Bases: parso.python.tree.PythonBaseNode


The path is the list of names that leads to the searched name.

Return list of Name:
class parso.python.tree.ImportFrom(children)[source]

Bases: parso.python.tree.Import

type = 'import_from'

Returns the a list of Name that the import defines. The defined names are set after import or in case an alias - as - is present that name is returned.


The level parameter of __import__.


The import paths defined in an import statement. Typically an array like this: [<Name: datetime>, <Name: date>].

Return list of list of Name:
class parso.python.tree.ImportName(children)[source]

Bases: parso.python.tree.Import

For import_name nodes. Covers normal imports without from.

type = 'import_name'

Returns the a list of Name that the import defines. The defined names is always the first name after import or in case an alias - as - is present that name is returned.


The level parameter of __import__.


This checks for the special case of nested imports, without aliases and from statement:

class parso.python.tree.KeywordStatement(children)[source]

Bases: parso.python.tree.PythonBaseNode

For the following statements: assert, del, global, nonlocal, raise, return, yield, return, yield.

pass, continue and break are not in there, because they are just simple keywords and the parser reduces it to a keyword.


Keyword statements start with the keyword and end with _stmt. You can crosscheck this with the Python grammar.

class parso.python.tree.AssertStmt(children)[source]

Bases: parso.python.tree.KeywordStatement

class parso.python.tree.GlobalStmt(children)[source]

Bases: parso.python.tree.KeywordStatement

class parso.python.tree.ReturnStmt(children)[source]

Bases: parso.python.tree.KeywordStatement

class parso.python.tree.YieldExpr(children)[source]

Bases: parso.python.tree.PythonBaseNode

type = 'yield_expr'
class parso.python.tree.ExprStmt(children)[source]

Bases: parso.python.tree.PythonBaseNode, parso.python.tree.DocstringMixin

type = 'expr_stmt'

Returns a list of Name defined before the = sign.


Returns the right-hand-side of the equals.


Returns a generator of +=, =, etc. or None if there is no operation.

class parso.python.tree.Param(children, parent)[source]

Bases: parso.python.tree.PythonBaseNode

It’s a helper class that makes business logic with params much easier. The Python grammar defines no param node. It defines it in a different way that is not really suited to working with parameters.

type = 'param'

Is 0 in case of foo, 1 in case of *foo or 2 in case of **foo.


The default is the test node that appears after the =. Is None in case no default is present.


The default is the test node that appears after :. Is None in case no annotation is present.


The Name leaf of the param.


Property for the positional index of a paramter.


Returns the function/lambda of a parameter.

get_code(include_prefix=True, include_comma=True)[source]

Like all the other get_code functions, but includes the param include_comma.

Parameters:bool (include_comma) – If enabled includes the comma in the string output.
class parso.python.tree.CompFor(children)[source]

Bases: parso.python.tree.PythonBaseNode

type = 'comp_for'

Returns the a list of Name that the comprehension defines.


parso.tree.search_ancestor(node, *node_types)[source]

Recursively looks at the parents of a node and returns the first found node that matches node_types. Returns None if no matching node is found.

  • node – The ancestors of this node will be checked.
  • node_types (tuple of str) – type names that are searched for.