PARSO(1)

parso

PARSO(1)

NAME

parso - parso Documentation

Release v0.8.5. (Installation <>)

Parso is a Python parser that supports error recovery and round-trip parsing for different Python versions (in multiple Python versions). Parso is also able to list multiple syntax errors in your python file.

Parso has been battle-tested by jedi https://github.com/davidhalter/jedi. It was pulled out of jedi to be useful for other projects as well.

Parso consists of a small API to parse Python and analyse the syntax tree.

A simple example:

>>> import parso
>>> module = parso.parse('hello + 1', version="3.9")
>>> expr = module.children[0]
>>> expr
PythonNode(arith_expr, [<Name: hello@1,0>, <Operator: +>, <Number: 1>])
>>> print(expr.get_code())
hello + 1
>>> name = expr.children[0]
>>> name
<Name: hello@1,0>
>>> name.end_pos
(1, 5)
>>> expr.end_pos
(1, 9)

To list multiple issues:

>>> grammar = parso.load_grammar()
>>> module = grammar.parse('foo +\nbar\ncontinue')
>>> error1, error2 = grammar.iter_errors(module)
>>> error1.message
'SyntaxError: invalid syntax'
>>> error2.message
"SyntaxError: 'continue' not properly in loop"

DOCS

Installation and Configuration

The preferred way (pip)

On any system you can install parso directly from the Python package index using pip:

sudo pip install parso

From git

If you want to install the current development version (master branch):

sudo pip install -e git+https://github.com/davidhalter/parso.git#egg=parso

Manual installation from a downloaded package (not recommended)

If you prefer not to use an automated package installer, you can download https://github.com/davidhalter/parso/archive/master.zip a current copy of parso and install it manually.

To install it, navigate to the directory containing setup.py on your console and type:

sudo python setup.py install

Usage

parso works around grammars. You can simply create Python grammars by calling parso.load_grammar(). Grammars (with a custom tokenizer and custom parser trees) can also be created by directly instantiating parso.Grammar(). More information about the resulting objects can be found in the parser tree documentation <#parser-tree>.

The simplest way of using parso is without even loading a grammar (parso.parse()):

>>> import parso
>>> parso.parse('foo + bar')
<Module: @1-1>

Loading a Grammar

Typically if you want to work with one specific Python version, use:

parso.load_grammar(*, version: str <https://docs.python.org/3/library/stdtypes.html#str> = None, path: str <https://docs.python.org/3/library/stdtypes.html#str> = None): Loads a parso.Grammar. The default version is the current Python version.

Parameters

version (str https://docs.python.org/3/library/stdtypes.html#str) -- A python version string, e.g. version='3.8'.
path (str https://docs.python.org/3/library/stdtypes.html#str) -- A path to a grammar file

Grammar methods

You will get back a grammar object that you can use to parse code and find issues in it:

class parso.Grammar(text: str, *, tokenizer, parser=<class 'parso.parser.BaseParser'>, diff_parser=None): parso.load_grammar() returns instances of this class.
Creating custom none-python grammars by calling this is not supported, yet.

Parameters: text -- A BNF representation of your grammar.

parse(code: str <https://docs.python.org/3/library/stdtypes.html#str> | bytes <https://docs.python.org/3/library/stdtypes.html#bytes> = None, *, error_recovery=True, path: PathLike <https://docs.python.org/3/library/os.html#os.PathLike> | str <https://docs.python.org/3/library/stdtypes.html#str> = None, start_symbol: str <https://docs.python.org/3/library/stdtypes.html#str> = None, cache=False, diff_cache=False, cache_path: PathLike <https://docs.python.org/3/library/os.html#os.PathLike> | str <https://docs.python.org/3/library/stdtypes.html#str> = None, file_io: FileIO = None) -> _NodeT: If you want to parse a Python file you want to start here, most likely.
If you need finer grained control over the parsed instance, there will be other ways to access it.

Parameters

code (str https://docs.python.org/3/library/stdtypes.html#str) -- A unicode or bytes string. When it's not possible to decode bytes to a string, returns a UnicodeDecodeError https://docs.python.org/3/library/exceptions.html#UnicodeDecodeError.
error_recovery (bool https://docs.python.org/3/library/functions.html#bool) -- If enabled, any code will be returned. If it is invalid, it will be returned as an error node. If disabled, you will get a ParseError when encountering syntax errors in your code.
start_symbol (str https://docs.python.org/3/library/stdtypes.html#str) -- The grammar rule (nonterminal) that you want to parse. Only allowed to be used when error_recovery is False.
path (str https://docs.python.org/3/library/stdtypes.html#str) -- The path to the file you want to open. Only needed for caching.
cache (bool https://docs.python.org/3/library/functions.html#bool) -- Keeps a copy of the parser tree in RAM and on disk if a path is given. Returns the cached trees if the corresponding files on disk have not changed. Note that this stores pickle files on your file system (e.g. for Linux in ~/.cache/parso/).
diff_cache (bool https://docs.python.org/3/library/functions.html#bool) -- Diffs the cached python module against the new code and tries to parse only the parts that have changed. Returns the same (changed) module that is found in cache. Using this option requires you to not do anything anymore with the cached modules under that path, because the contents of it might change. This option is still somewhat experimental. If you want stability, please don't use it.
cache_path (bool https://docs.python.org/3/library/functions.html#bool) -- If given saves the parso cache in this directory. If not given, defaults to the default cache places on each platform.

Returns: A subclass of parso.tree.NodeOrLeaf <#parso.tree.NodeOrLeaf>. Typically a parso.python.tree.Module <#parso.python.tree.Module>.

iter_errors(node): Given a parso.tree.NodeOrLeaf <#parso.tree.NodeOrLeaf> returns a generator of parso.normalizer.Issue objects. For Python this is a list of syntax/indentation errors.

refactor(base_node, node_to_str_map)

Error Retrieval

parso is able to find multiple errors in your source code. Iterating through those errors yields the following instances:

class parso.normalizer.Issue(node, code, message)

code: An integer code that stands for the type of error.

message: A message (string) for the issue.

start_pos: The start position position of the error as a tuple (line, column). As always in parso the first line is 1 and the first column 0.

Utility

parso also offers some utility functions that can be really useful:

parso.parse(code=None, **kwargs): A utility function to avoid loading grammars. Params are documented in parso.Grammar.parse().

Parameters: version (str https://docs.python.org/3/library/stdtypes.html#str) -- The version used by parso.load_grammar().

parso.split_lines(string: str <https://docs.python.org/3/library/stdtypes.html#str>, keepends: bool <https://docs.python.org/3/library/functions.html#bool> = False) -> Sequence <https://docs.python.org/3/library/typing.html#typing.Sequence>[str <https://docs.python.org/3/library/stdtypes.html#str>]: Intended for Python code. In contrast to Python's str.splitlines() https://docs.python.org/3/library/stdtypes.html#str.splitlines, looks at form feeds and other special characters as normal text. Just splits \n and \r\n. Also different: Returns [""] for an empty string input.
In Python 2.7 form feeds are used as normal characters when using str.splitlines. However in Python 3 somewhere there was a decision to split also on form feeds.

parso.python_bytes_to_unicode(source: str <https://docs.python.org/3/library/stdtypes.html#str> | bytes <https://docs.python.org/3/library/stdtypes.html#bytes>, encoding: str <https://docs.python.org/3/library/stdtypes.html#str> = 'utf-8', errors: str <https://docs.python.org/3/library/stdtypes.html#str> = 'strict') -> str <https://docs.python.org/3/library/stdtypes.html#str>: Checks for unicode BOMs and PEP 263 encoding declarations. Then returns a unicode object like in bytes.decode() https://docs.python.org/3/library/stdtypes.html#bytes.decode.

Parameters

encoding -- See bytes.decode() https://docs.python.org/3/library/stdtypes.html#bytes.decode documentation.
errors -- See bytes.decode() https://docs.python.org/3/library/stdtypes.html#bytes.decode documentation. errors can be 'strict', 'replace' or 'ignore'.

Used By

jedi https://github.com/davidhalter/jedi (which is used by IPython and a lot of editor plugins).
mutmut https://github.com/boxed/mutmut (mutation tester)

Parser Tree

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

Note:

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: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: NodeOrLeaf
The super class for all nodes. A node has children, a type and possibly a parent node.

children: A list of NodeOrLeaf child nodes.

property start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]: Returns the starting position of the prefix as a tuple, e.g. (3, 4).

Return tuple of int: (line, column)

get_start_pos_of_prefix(): 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)

property end_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]: Returns the end position of the prefix as a tuple, e.g. (3, 4).

Return tuple of int: (line, column)

get_code(include_prefix=True): Returns the code that was the input for the parser for this node.

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

get_leaf_for_position(position, include_prefixes=False): Get the parso.tree.Leaf at position

Parameters

position (tuple https://docs.python.org/3/library/stdtypes.html#tuple) -- A position tuple, row, column. Rows start from 1
include_prefixes (bool https://docs.python.org/3/library/functions.html#bool) -- If False, None will be returned if position falls on whitespace or comments before a leaf

Returns: parso.tree.Leaf at position, or None

get_first_leaf(): Returns the first leaf of a node or itself if this is a leaf.

get_last_leaf(): Returns the last leaf of a node or itself if this is a leaf.

class parso.tree.Leaf(value: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: NodeOrLeaf
Leafs are basically tokens with a better API. Leafs exactly know where they were defined and what text preceeds them.

value: str() The value of the current token.

prefix: str <https://docs.python.org/3/library/stdtypes.html#str>: str() Typically a mixture of whitespace and comments. Stuff that is syntactically irrelevant for the syntax tree.

property start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]: Returns the starting position of the prefix as a tuple, e.g. (3, 4).

Return tuple of int: (line, column)

get_start_pos_of_prefix(): 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)

get_first_leaf(): Returns the first leaf of a node or itself if this is a leaf.

get_last_leaf(): Returns the last leaf of a node or itself if this is a leaf.

get_code(include_prefix=True): Returns the code that was the input for the parser for this node.

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

property end_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]: Returns the end position of the prefix as a tuple, e.g. (3, 4).

Return tuple of int: (line, column)

All nodes and leaves have these methods/properties:

class parso.tree.NodeOrLeaf: Bases: object https://docs.python.org/3/library/functions.html#object
The base class for nodes and leaves.

type: str <https://docs.python.org/3/library/stdtypes.html#str>: The type is a string that typically matches the types of the grammar file.

parent: BaseNode <#parso.tree.BaseNode> | None <https://docs.python.org/3/library/constants.html#None>: The parent BaseNode of this node or leaf. None if this is the root node.

get_root_node(): Returns the root node of a parser tree. The returned node doesn't have a parent node like all the other nodes/leaves.

get_next_sibling(): 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

get_previous_sibling(): 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.

get_previous_leaf(): Returns the previous leaf in the parser tree. Returns None if this is the first element in the parser tree.

get_next_leaf(): Returns the next leaf in the parser tree. Returns None if this is the last element in the parser tree.

abstract property start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]: Returns the starting position of the prefix as a tuple, e.g. (3, 4).

Return tuple of int: (line, column)

abstract property end_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>]: Returns the end position of the prefix as a tuple, e.g. (3, 4).

Return tuple of int: (line, column)

abstractmethod get_start_pos_of_prefix(): 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)

abstractmethod get_first_leaf(): Returns the first leaf of a node or itself if this is a leaf.

abstractmethod get_last_leaf(): Returns the last leaf of a node or itself if this is a leaf.

abstractmethod get_code(include_prefix=True): Returns the code that was the input for the parser for this node.

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

search_ancestor(*node_types: str <https://docs.python.org/3/library/stdtypes.html#str>) -> BaseNode <#parso.tree.BaseNode> | None <https://docs.python.org/3/library/constants.html#None>: Recursively looks at the parents of this node or leaf and returns the first found node that matches node_types. Returns None if no matching node is found.

Parameters: node_types -- type names that are searched for.

dump(*, indent: int <https://docs.python.org/3/library/functions.html#int> | str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = 4) -> str <https://docs.python.org/3/library/stdtypes.html#str>: Returns a formatted dump of the parser tree rooted at this node or leaf. This is mainly useful for debugging purposes.
The indent parameter is interpreted in a similar way as ast.dump() https://docs.python.org/3/library/ast.html#ast.dump. If indent is a non-negative integer or string, then the tree will be pretty-printed with that indent level. An indent level of 0, negative, or "" will only insert newlines. None selects the single line representation. Using a positive integer indent indents that many spaces per level. If indent is a string (such as "\t"), that string is used to indent each level.

Parameters: indent -- Indentation style as described above. The default indentation is 4 spaces, which yields a pretty-printed dump.

>>> import parso
>>> print(parso.parse("lambda x, y: x + y").dump())
Module([
    Lambda([
        Keyword('lambda', (1, 0)),
        Param([
            Name('x', (1, 7), prefix=' '),
            Operator(',', (1, 8)),
        ]),
        Param([
            Name('y', (1, 10), prefix=' '),
        ]),
        Operator(':', (1, 11)),
        PythonNode('arith_expr', [
            Name('x', (1, 13), prefix=' '),
            Operator('+', (1, 15), prefix=' '),
            Name('y', (1, 17), prefix=' '),
        ]),
    ]),
    EndMarker('', (1, 18)),
])

Python Parser Tree

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

All of the nodes can be traced back to the Python grammar file https://docs.python.org/3/reference/grammar.html. 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: Bases: object https://docs.python.org/3/library/functions.html#object

get_doc_node(): Returns the string leaf of a docstring. e.g. r'''foo'''.

class parso.python.tree.PythonMixin: Bases: object https://docs.python.org/3/library/functions.html#object
Some Python specific utilities.

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

class parso.python.tree.PythonLeaf(value: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: PythonMixin, Leaf

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

class parso.python.tree.PythonBaseNode(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: PythonMixin, BaseNode

class parso.python.tree.PythonNode(type, children): Bases: PythonMixin, Node

class parso.python.tree.PythonErrorNode(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: PythonMixin, ErrorNode

class parso.python.tree.PythonErrorLeaf(token_type, value, start_pos, prefix=''): Bases: ErrorLeaf, PythonLeaf

class parso.python.tree.EndMarker(value: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: _LeafWithoutNewlines

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'endmarker': The type is a string that typically matches the types of the grammar file.

class parso.python.tree.Newline(value: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: PythonLeaf
Contains NEWLINE and ENDMARKER tokens.

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'newline': The type is a string that typically matches the types of the grammar file.

class parso.python.tree.Name(value: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: _LeafWithoutNewlines
A string. Sometimes it is important to know if the string belongs to a name or not.

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'name': The type is a string that typically matches the types of the grammar file.

is_definition(include_setitem=False): Returns True if the name is being defined.

get_definition(import_name_always=False, include_setitem=False): Returns None if there's no definition for a name.

Parameters: import_name_always -- 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: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: PythonLeaf

class parso.python.tree.Number(value: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: Literal

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'number': The type is a string that typically matches the types of the grammar file.

class parso.python.tree.String(value: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: Literal

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'string': The type is a string that typically matches the types of the grammar file.

property string_prefix

class parso.python.tree.FStringString(value: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: PythonLeaf
f-strings contain f-string expressions and normal python strings. These are the string parts of f-strings.

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'fstring_string': The type is a string that typically matches the types of the grammar file.

class parso.python.tree.FStringStart(value: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: PythonLeaf
f-strings contain f-string expressions and normal python strings. These are the string parts of f-strings.

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'fstring_start': The type is a string that typically matches the types of the grammar file.

class parso.python.tree.FStringEnd(value: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: PythonLeaf
f-strings contain f-string expressions and normal python strings. These are the string parts of f-strings.

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'fstring_end': The type is a string that typically matches the types of the grammar file.

class parso.python.tree.Operator(value: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: _LeafWithoutNewlines, _StringComparisonMixin

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'operator': The type is a string that typically matches the types of the grammar file.

class parso.python.tree.Keyword(value: str <https://docs.python.org/3/library/stdtypes.html#str>, start_pos: Tuple <https://docs.python.org/3/library/typing.html#typing.Tuple>[int <https://docs.python.org/3/library/functions.html#int>, int <https://docs.python.org/3/library/functions.html#int>], prefix: str <https://docs.python.org/3/library/stdtypes.html#str> = ''): Bases: _LeafWithoutNewlines, _StringComparisonMixin

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'keyword': The type is a string that typically matches the types of the grammar file.

class parso.python.tree.Scope(children): Bases: PythonBaseNode, 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.

iter_funcdefs(): Returns a generator of funcdef nodes.

iter_classdefs(): Returns a generator of classdef nodes.

iter_imports(): Returns a generator of import_name and import_from nodes.

get_suite(): Returns the part that is executed by the function.

class parso.python.tree.Module(children): Bases: 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: str <https://docs.python.org/3/library/stdtypes.html#str> = 'file_input': The type is a string that typically matches the types of the grammar file.

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

class parso.python.tree.Decorator(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: PythonBaseNode

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'decorator': The type is a string that typically matches the types of the grammar file.

class parso.python.tree.ClassOrFunc(children): Bases: Scope

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

get_decorators()

Return type: list of Decorator

class parso.python.tree.Class(children): Bases: ClassOrFunc
Used to store the parsed contents of a python class.

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'classdef': The type is a string that typically matches the types of the grammar file.

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

class parso.python.tree.Function(children)

Bases: ClassOrFunc

Used to store the parsed contents of a python function.

Children:

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: str <https://docs.python.org/3/library/stdtypes.html#str> = 'funcdef': The type is a string that typically matches the types of the grammar file.

get_params(): Returns a list of Param().

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

iter_yield_exprs(): Returns a generator of yield_expr.

iter_return_stmts(): Returns a generator of return_stmt.

iter_raise_stmts(): Returns a generator of raise_stmt. Includes raise statements inside try-except blocks

is_generator()

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

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

class parso.python.tree.Lambda(children)

Bases: Function

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

Children:

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

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'lambdef': The type is a string that typically matches the types of the grammar file.

property name: Raises an AttributeError. Lambdas don't have a defined name.

property annotation: Returns None, lambdas don't have annotations.

class parso.python.tree.Flow(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: PythonBaseNode

class parso.python.tree.IfStmt(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: Flow

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'if_stmt': The type is a string that typically matches the types of the grammar file.

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

if x:: pass
elif x:: pass

get_corresponding_test_node(node): 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.

is_node_after_else(node): Checks if a node is defined after else.

class parso.python.tree.WhileStmt(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: Flow

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'while_stmt': The type is a string that typically matches the types of the grammar file.

class parso.python.tree.ForStmt(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: Flow

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'for_stmt': The type is a string that typically matches the types of the grammar file.

get_testlist(): Returns the input node y from: for x in y:.

get_defined_names(include_setitem=False)

class parso.python.tree.TryStmt(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: Flow

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'try_stmt': The type is a string that typically matches the types of the grammar file.

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

class parso.python.tree.WithStmt(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: Flow

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'with_stmt': The type is a string that typically matches the types of the grammar file.

get_defined_names(include_setitem=False): Returns the a list of Name that the with statement defines. The defined names are set after as.

get_test_node_from_name(name)

class parso.python.tree.Import(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: PythonBaseNode

get_path_for_name(name): The path is the list of names that leads to the searched name.

Return list of Name

is_nested()

is_star_import()

class parso.python.tree.ImportFrom(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: Import

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'import_from': The type is a string that typically matches the types of the grammar file.

get_defined_names(include_setitem=False): 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.

get_from_names()

property level: The level parameter of __import__.

get_paths(): 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: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: Import
For import_name nodes. Covers normal imports without from.

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'import_name': The type is a string that typically matches the types of the grammar file.

get_defined_names(include_setitem=False): 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.

property level: The level parameter of __import__.

get_paths()

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

import foo.bar

class parso.python.tree.KeywordStatement(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>])

Bases: PythonBaseNode

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

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

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

property keyword

get_defined_names(include_setitem=False)

class parso.python.tree.AssertStmt(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: KeywordStatement

property assertion

class parso.python.tree.GlobalStmt(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: KeywordStatement

get_global_names()

class parso.python.tree.ReturnStmt(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: KeywordStatement

class parso.python.tree.YieldExpr(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: PythonBaseNode

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'yield_expr': The type is a string that typically matches the types of the grammar file.

class parso.python.tree.ExprStmt(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: PythonBaseNode, DocstringMixin

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'expr_stmt': The type is a string that typically matches the types of the grammar file.

get_defined_names(include_setitem=False): Returns a list of Name defined before the = sign.

get_rhs(): Returns the right-hand-side of the equals.

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

class parso.python.tree.NamedExpr(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: PythonBaseNode

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'namedexpr_test': The type is a string that typically matches the types of the grammar file.

get_defined_names(include_setitem=False)

class parso.python.tree.Param(children, parent=None): Bases: 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: str <https://docs.python.org/3/library/stdtypes.html#str> = 'param': The type is a string that typically matches the types of the grammar file.

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

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

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

property name: The Name leaf of the param.

get_defined_names(include_setitem=False)

property position_index: Property for the positional index of a paramter.

get_parent_function(): Returns the function/lambda of a parameter.

get_code(include_prefix=True, include_comma=True): 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.SyncCompFor(children: List <https://docs.python.org/3/library/typing.html#typing.List>[NodeOrLeaf <#parso.tree.NodeOrLeaf>]): Bases: PythonBaseNode

type: str <https://docs.python.org/3/library/stdtypes.html#str> = 'sync_comp_for': The type is a string that typically matches the types of the grammar file.

get_defined_names(include_setitem=False): Returns the a list of Name that the comprehension defines.

parso.python.tree.CompFor: alias of SyncCompFor

class parso.python.tree.UsedNamesMapping(dct): Bases: Mapping https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping
This class exists for the sole purpose of creating an immutable dict.

Utility

parso.tree.search_ancestor(node: NodeOrLeaf <#parso.tree.NodeOrLeaf>, *node_types: str <https://docs.python.org/3/library/stdtypes.html#str>) -> BaseNode <#parso.tree.BaseNode> | None <https://docs.python.org/3/library/constants.html#None>: 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.
This function is deprecated, use NodeOrLeaf.search_ancestor() instead.

Parameters

node -- The ancestors of this node will be checked.
node_types -- type names that are searched for.

Development

If you want to contribute anything to parso, just open an issue or pull request to discuss it. We welcome changes! Please check the CONTRIBUTING.md file in the repository, first.

Deprecations Process

The deprecation process is as follows:

1.: A deprecation is announced in the next major/minor release.
2.: We wait either at least a year & at least two minor releases until we remove the deprecated functionality.