Spaces:

ITookAPill
/

PyComp

Running on Zero

App Files Files Community

PyComp / python_doc_md /Intermediate /library /ast.md

ITookAPill

PyComp First Commit

9273228 5 months ago

preview code

Raw

History Blame Contribute Delete

75.6 kB

A newer version of the Gradio SDK is available: 6.20.0

Upgrade

`!ast`{.interpreted-text role="mod"} --- Abstract syntax trees

::: {.module synopsis="Abstract Syntax Tree classes and manipulation."} ast :::

::: testsetup import ast :::

Source code: Lib/ast.py{.interpreted-text role="source"}

The !ast{.interpreted-text role="mod"} module helps Python applications to process trees of the Python abstract syntax grammar. The abstract syntax itself might change with each Python release; this module helps to find out programmatically what the current grammar looks like.

An abstract syntax tree can be generated by passing ast.PyCF_ONLY_AST{.interpreted-text role="data"} as a flag to the compile{.interpreted-text role="func"} built-in function, or using the parse{.interpreted-text role="func"} helper provided in this module. The result will be a tree of objects whose classes all inherit from ast.AST{.interpreted-text role="class"}. An abstract syntax tree can be compiled into a Python code object using the built-in compile{.interpreted-text role="func"} function.

Abstract grammar

The abstract grammar is currently defined as follows:

::: {.literalinclude language="asdl"} ../../Parser/Python.asdl :::

Node classes

:::::::::: AST This is the base of all AST node classes. The actual node classes are derived from the Parser/Python.asdl{.interpreted-text role="file"} file, which is reproduced above <abstract-grammar>{.interpreted-text role="ref"}. They are defined in the !_ast{.interpreted-text role="mod"} C module and re-exported in !ast{.interpreted-text role="mod"}.

There is one class defined for each left-hand side symbol in the abstract grammar (for example, ast.stmt{.interpreted-text role="class"} or ast.expr{.interpreted-text role="class"}). In addition, there is one class defined for each constructor on the right-hand side; these classes inherit from the classes for the left-hand side trees. For example, ast.BinOp{.interpreted-text role="class"} inherits from ast.expr{.interpreted-text role="class"}. For production rules with alternatives (aka "sums"), the left-hand side class is abstract: only instances of specific constructor nodes are ever created.

::: index single: ? (question mark); in AST grammar :::

::: index single: * (asterisk); in AST grammar :::

::: attribute [fields]{#fields}

Each concrete class has an attribute !_fields{.interpreted-text role="attr"} which gives the names of all child nodes.

Each instance of a concrete class has one attribute for each child node, of the type as defined in the grammar. For example, ast.BinOp{.interpreted-text role="class"} instances have an attribute left{.interpreted-text role="attr"} of type ast.expr{.interpreted-text role="class"}.

If these attributes are marked as optional in the grammar (using a question mark), the value might be None. If the attributes can have zero-or-more values (marked with an asterisk), the values are represented as Python lists. All possible attributes must be present and have valid values when compiling an AST with compile{.interpreted-text role="func"}. :::

::::: attribute [field_types]{#field_types}

The !_field_types{.interpreted-text role="attr"} attribute on each concrete class is a dictionary mapping field names (as also listed in _fields{.interpreted-text role="attr"}) to their types.

::: doctest >>> ast.TypeVar._field_types {'name': <class 'str'>, 'bound': ast.expr | None, 'default_value': ast.expr | None} :::

::: versionadded 3.13 ::: :::::

::: attribute lineno col_offset end_lineno end_col_offset

Instances of ast.expr{.interpreted-text role="class"} and ast.stmt{.interpreted-text role="class"} subclasses have lineno{.interpreted-text role="attr"}, col_offset{.interpreted-text role="attr"}, end_lineno{.interpreted-text role="attr"}, and end_col_offset{.interpreted-text role="attr"} attributes. The lineno{.interpreted-text role="attr"} and end_lineno{.interpreted-text role="attr"} are the first and last line numbers of source text span (1-indexed so the first line is line 1) and the col_offset{.interpreted-text role="attr"} and end_col_offset{.interpreted-text role="attr"} are the corresponding UTF-8 byte offsets of the first and last tokens that generated the node. The UTF-8 offset is recorded because the parser uses UTF-8 internally.

Note that the end positions are not required by the compiler and are therefore optional. The end offset is after the last symbol, for example one can get the source segment of a one-line expression node using source_line[node.col_offset : node.end_col_offset]. :::

The constructor of a class ast.T{.interpreted-text role="class"} parses its arguments as follows:

If there are positional arguments, there must be as many as there are items in T._fields{.interpreted-text role="attr"}; they will be assigned as attributes of these names.
If there are keyword arguments, they will set the attributes of the same names to the given values.

For example, to create and populate an ast.UnaryOp{.interpreted-text role="class"} node, you could use :

node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),
                   lineno=0, col_offset=0)

If a field that is optional in the grammar is omitted from the constructor, it defaults to None. If a list field is omitted, it defaults to the empty list. If a field of type !ast.expr_context{.interpreted-text role="class"} is omitted, it defaults to Load() <ast.Load>{.interpreted-text role="class"}. If any other field is omitted, a DeprecationWarning{.interpreted-text role="exc"} is raised and the AST node will not have this field. In Python 3.15, this condition will raise an error. ::::::::::

::: versionchanged 3.8

Class ast.Constant{.interpreted-text role="class"} is now used for all constants. :::

::: versionchanged 3.9

Simple indices are represented by their value, extended slices are represented as tuples. :::

::: versionchanged 3.14

The ~object.__repr__{.interpreted-text role="meth"} output of ~ast.AST{.interpreted-text role="class"} nodes includes the values of the node fields. :::

::: deprecated-removed 3.8 3.14

Previous versions of Python provided the AST classes !ast.Num{.interpreted-text role="class"}, !ast.Str{.interpreted-text role="class"}, !ast.Bytes{.interpreted-text role="class"}, !ast.NameConstant{.interpreted-text role="class"} and !ast.Ellipsis{.interpreted-text role="class"}, which were deprecated in Python 3.8. These classes were removed in Python 3.14, and their functionality has been replaced with ast.Constant{.interpreted-text role="class"}. :::

::: deprecated 3.9

Old classes !ast.Index{.interpreted-text role="class"} and !ast.ExtSlice{.interpreted-text role="class"} are still available, but they will be removed in future Python releases. In the meantime, instantiating them will return an instance of a different class. :::

::: deprecated-removed 3.13 3.15

Previous versions of Python allowed the creation of AST nodes that were missing required fields. Similarly, AST node constructors allowed arbitrary keyword arguments that were set as attributes of the AST node, even if they did not match any of the fields of the AST node. This behavior is deprecated and will be removed in Python 3.15. :::

:::: note ::: title Note :::

The descriptions of the specific node classes displayed here were initially adapted from the fantastic Green Tree Snakes project and all its contributors. ::::

Root nodes {#ast-root-nodes}

:::: {.Module(body, .type_ignores)} A Python module, as with file input <file-input>{.interpreted-text role="ref"}. Node type generated by ast.parse{.interpreted-text role="func"} in the default "exec" mode.

body is a list{.interpreted-text role="class"} of the module's ast-statements{.interpreted-text role="ref"}.

type_ignores is a list{.interpreted-text role="class"} of the module's type ignore comments; see ast.parse{.interpreted-text role="func"} for more details.

::: doctest >>> print(ast.dump(ast.parse('x = 1'), indent=4)) Module( body=[ Assign( targets=[ Name(id='x', ctx=Store())], value=Constant(value=1))]) ::: ::::

:::: Expression(body) A single Python expression input <expression-input>{.interpreted-text role="ref"}. Node type generated by ast.parse{.interpreted-text role="func"} when mode is "eval".

body is a single node, one of the expression types <ast-expressions>{.interpreted-text role="ref"}.

::: doctest >>> print(ast.dump(ast.parse('123', mode='eval'), indent=4)) Expression( body=Constant(value=123)) ::: ::::

:::: Interactive(body) A single interactive input <interactive>{.interpreted-text role="ref"}, like in tut-interac{.interpreted-text role="ref"}. Node type generated by ast.parse{.interpreted-text role="func"} when mode is "single".

body is a list{.interpreted-text role="class"} of statement nodes <ast-statements>{.interpreted-text role="ref"}.

::: doctest >>> print(ast.dump(ast.parse('x = 1; y = 2', mode='single'), indent=4)) Interactive( body=[ Assign( targets=[ Name(id='x', ctx=Store())], value=Constant(value=1)), Assign( targets=[ Name(id='y', ctx=Store())], value=Constant(value=2))]) ::: ::::

::::: {.FunctionType(argtypes, .returns)} A representation of an old-style type comments for functions, as Python versions prior to 3.5 didn't support 484{.interpreted-text role="pep"} annotations. Node type generated by ast.parse{.interpreted-text role="func"} when mode is "func_type".

Such type comments would look like this:

def sum_two_number(a, b):
    # type: (int, int) -> int
    return a + b

argtypes is a list{.interpreted-text role="class"} of expression nodes <ast-expressions>{.interpreted-text role="ref"}.

returns is a single expression node <ast-expressions>{.interpreted-text role="ref"}.

::: doctest >>> print(ast.dump(ast.parse('(int, str) -> List[int]', mode='func_type'), indent=4)) FunctionType( argtypes=[ Name(id='int'), Name(id='str')], returns=Subscript( value=Name(id='List'), slice=Name(id='int'))) :::

::: versionadded 3.8 ::: :::::

Literals

:::: Constant(value) A constant value. The value attribute of the Constant literal contains the Python object it represents. The values represented can be instances of str{.interpreted-text role="class"}, bytes{.interpreted-text role="class"}, int{.interpreted-text role="class"}, float{.interpreted-text role="class"}, complex{.interpreted-text role="class"}, and bool{.interpreted-text role="class"}, and the constants None{.interpreted-text role="data"} and Ellipsis{.interpreted-text role="data"}.

::: doctest >>> print(ast.dump(ast.parse('123', mode='eval'), indent=4)) Expression( body=Constant(value=123)) ::: ::::

::: {.FormattedValue(value, .conversion, .format_spec)} Node representing a single formatting field in an f-string. If the string contains a single formatting field and nothing else the node can be isolated otherwise it appears in JoinedStr{.interpreted-text role="class"}.

value is any expression node (such as a literal, a variable, or a function call).
conversion is an integer:
- -1: no formatting
- 97 (ord('a')): !a ASCII <ascii>{.interpreted-text role="func"} formatting
- 114 (ord('r')): !r repr{.interpreted-text role="func"} formatting
- 115 (ord('s')): !s string <str>{.interpreted-text role="func"} formatting
format_spec is a JoinedStr{.interpreted-text role="class"} node representing the formatting of the value, or None if no format was specified. Both conversion and format_spec can be set at the same time. :::

:::: JoinedStr(values) An f-string, comprising a series of FormattedValue{.interpreted-text role="class"} and Constant{.interpreted-text role="class"} nodes.

::: doctest >>> print(ast.dump(ast.parse('f"sin({a}) is {sin(a):.3}"', mode='eval'), indent=4)) Expression( body=JoinedStr( values=[ Constant(value='sin('), FormattedValue( value=Name(id='a'), conversion=-1), Constant(value=') is '), FormattedValue( value=Call( func=Name(id='sin'), args=[ Name(id='a')]), conversion=-1, format_spec=JoinedStr( values=[ Constant(value='.3')]))])) ::: ::::

::::: {.TemplateStr(values, ./)} ::: versionadded 3.14 :::

Node representing a template string literal, comprising a series of Interpolation{.interpreted-text role="class"} and Constant{.interpreted-text role="class"} nodes. These nodes may be any order, and do not need to be interleaved.

::: doctest >>> expr = ast.parse('t"{name} finished {place:ordinal}"', mode='eval') >>> print(ast.dump(expr, indent=4)) Expression( body=TemplateStr( values=[ Interpolation( value=Name(id='name'), str='name', conversion=-1), Constant(value=' finished '), Interpolation( value=Name(id='place'), str='place', conversion=-1, format_spec=JoinedStr( values=[ Constant(value='ordinal')]))])) ::: :::::

:::: {.Interpolation(value, .str, .conversion, .format_spec=None)} ::: versionadded 3.14 :::

Node representing a single interpolation field in a template string literal.

value is any expression node (such as a literal, a variable, or a function call). This has the same meaning as FormattedValue.value.
str is a constant containing the text of the interpolation expression.

If str is set to None, then value is used to generate code when calling ast.unparse{.interpreted-text role="func"}. This no longer guarantees that the generated code is identical to the original and is intended for code generation.
conversion is an integer:
- -1: no conversion
- 97 (ord('a')): !a ASCII <ascii>{.interpreted-text role="func"} conversion
- 114 (ord('r')): !r repr{.interpreted-text role="func"} conversion
- 115 (ord('s')): !s string <str>{.interpreted-text role="func"} conversion
This has the same meaning as FormattedValue.conversion.
format_spec is a JoinedStr{.interpreted-text role="class"} node representing the formatting of the value, or None if no format was specified. Both conversion and format_spec can be set at the same time. This has the same meaning as FormattedValue.format_spec. ::::

:::: {.List(elts, .ctx) .Tuple(elts, .ctx)} A list or tuple. elts holds a list of nodes representing the elements. ctx is Store{.interpreted-text role="class"} if the container is an assignment target (i.e. (x,y)=something), and Load{.interpreted-text role="class"} otherwise.

::: doctest >>> print(ast.dump(ast.parse('[1, 2, 3]', mode='eval'), indent=4)) Expression( body=List( elts=[ Constant(value=1), Constant(value=2), Constant(value=3)])) >>> print(ast.dump(ast.parse('(1, 2, 3)', mode='eval'), indent=4)) Expression( body=Tuple( elts=[ Constant(value=1), Constant(value=2), Constant(value=3)])) ::: ::::

:::: Set(elts) A set. elts holds a list of nodes representing the set's elements.

::: doctest >>> print(ast.dump(ast.parse('{1, 2, 3}', mode='eval'), indent=4)) Expression( body=Set( elts=[ Constant(value=1), Constant(value=2), Constant(value=3)])) ::: ::::

:::: {.Dict(keys, .values)} A dictionary. keys and values hold lists of nodes representing the keys and the values respectively, in matching order (what would be returned when calling dictionary.keys() and dictionary.values()).

When doing dictionary unpacking using dictionary literals the expression to be expanded goes in the values list, with a None at the corresponding position in keys.

::: doctest >>> print(ast.dump(ast.parse('{"a":1, **d}', mode='eval'), indent=4)) Expression( body=Dict( keys=[ Constant(value='a'), None], values=[ Constant(value=1), Name(id='d')])) ::: ::::

Variables

::: {.Name(id, .ctx)} A variable name. id holds the name as a string, and ctx is one of the following types. :::

:::: {.Load() .Store() .Del()} Variable references can be used to load the value of a variable, to assign a new value to it, or to delete it. Variable references are given a context to distinguish these cases.

::: doctest >>> print(ast.dump(ast.parse('a'), indent=4)) Module( body=[ Expr( value=Name(id='a'))])

>>> print(ast.dump(ast.parse('a = 1'), indent=4)) Module( body=[ Assign( targets=[ Name(id='a', ctx=Store())], value=Constant(value=1))])

>>> print(ast.dump(ast.parse('del a'), indent=4)) Module( body=[ Delete( targets=[ Name(id='a', ctx=Del())])]) ::: ::::

:::: {.Starred(value, .ctx)} A *var variable reference. value holds the variable, typically a Name{.interpreted-text role="class"} node. This type must be used when building a Call{.interpreted-text role="class"} node with *args.

::: doctest >>> print(ast.dump(ast.parse('a, *b = it'), indent=4)) Module( body=[ Assign( targets=[ Tuple( elts=[ Name(id='a', ctx=Store()), Starred( value=Name(id='b', ctx=Store()), ctx=Store())], ctx=Store())], value=Name(id='it'))]) ::: ::::

Expressions {#ast-expressions}

:::: Expr(value) When an expression, such as a function call, appears as a statement by itself with its return value not used or stored, it is wrapped in this container. value holds one of the other nodes in this section, a Constant{.interpreted-text role="class"}, a Name{.interpreted-text role="class"}, a Lambda{.interpreted-text role="class"}, a Yield{.interpreted-text role="class"} or YieldFrom{.interpreted-text role="class"} node.

::: doctest >>> print(ast.dump(ast.parse('-a'), indent=4)) Module( body=[ Expr( value=UnaryOp( op=USub(), operand=Name(id='a')))]) ::: ::::

::: {.UnaryOp(op, .operand)} A unary operation. op is the operator, and operand any expression node. :::

:::: {.UAdd .USub .Not .Invert} Unary operator tokens. Not{.interpreted-text role="class"} is the not keyword, Invert{.interpreted-text role="class"} is the ~ operator.

::: doctest >>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4)) Expression( body=UnaryOp( op=Not(), operand=Name(id='x'))) ::: ::::

:::: {.BinOp(left, .op, .right)} A binary operation (like addition or division). op is the operator, and left and right are any expression nodes.

::: doctest >>> print(ast.dump(ast.parse('x + y', mode='eval'), indent=4)) Expression( body=BinOp( left=Name(id='x'), op=Add(), right=Name(id='y'))) ::: ::::

::: {.Add .Sub .Mult .Div .FloorDiv .Mod .Pow .LShift .RShift .BitOr .BitXor .BitAnd .MatMult} Binary operator tokens. :::

:::: {.BoolOp(op, .values)} A boolean operation, 'or' or 'and'. op is Or{.interpreted-text role="class"} or And{.interpreted-text role="class"}. values are the values involved. Consecutive operations with the same operator, such as a or b or c, are collapsed into one node with several values.

This doesn't include not, which is a UnaryOp{.interpreted-text role="class"}.

::: doctest >>> print(ast.dump(ast.parse('x or y', mode='eval'), indent=4)) Expression( body=BoolOp( op=Or(), values=[ Name(id='x'), Name(id='y')])) ::: ::::

::: {.And .Or} Boolean operator tokens. :::

:::: {.Compare(left, .ops, .comparators)} A comparison of two or more values. left is the first value in the comparison, ops the list of operators, and comparators the list of values after the first element in the comparison.

::: doctest >>> print(ast.dump(ast.parse('1 <= a < 10', mode='eval'), indent=4)) Expression( body=Compare( left=Constant(value=1), ops=[ LtE(), Lt()], comparators=[ Name(id='a'), Constant(value=10)])) ::: ::::

::: {.Eq .NotEq .Lt .LtE .Gt .GtE .Is .IsNot .In .NotIn} Comparison operator tokens. :::

:::: {.Call(func, .args, .keywords)} A function call. func is the function, which will often be a Name{.interpreted-text role="class"} or Attribute{.interpreted-text role="class"} object. Of the arguments:

args holds a list of the arguments passed by position.
keywords holds a list of .keyword{.interpreted-text role="class"} objects representing arguments passed by keyword.

The args and keywords arguments are optional and default to empty lists.

::: doctest >>> print(ast.dump(ast.parse('func(a, b=c, d,*e)', mode='eval'), indent=4)) Expression( body=Call( func=Name(id='func'), args=[ Name(id='a'), Starred( value=Name(id='d'))], keywords=[ keyword( arg='b', value=Name(id='c')), keyword( value=Name(id='e'))])) ::: ::::

::: {.keyword(arg, .value)} A keyword argument to a function call or class definition. arg is a raw string of the parameter name, value is a node to pass in. :::

:::: {.IfExp(test, .body, .orelse)} An expression such as a if b else c. Each field holds a single node, so in the following example, all three are Name{.interpreted-text role="class"} nodes.

::: doctest >>> print(ast.dump(ast.parse('a if b else c', mode='eval'), indent=4)) Expression( body=IfExp( test=Name(id='b'), body=Name(id='a'), orelse=Name(id='c'))) ::: ::::

:::: {.Attribute(value, .attr, .ctx)} Attribute access, e.g. d.keys. value is a node, typically a Name{.interpreted-text role="class"}. attr is a bare string giving the name of the attribute, and ctx is Load{.interpreted-text role="class"}, Store{.interpreted-text role="class"} or Del{.interpreted-text role="class"} according to how the attribute is acted on.

::: doctest >>> print(ast.dump(ast.parse('snake.colour', mode='eval'), indent=4)) Expression( body=Attribute( value=Name(id='snake'), attr='colour')) ::: ::::

::::: {.NamedExpr(target, .value)} A named expression. This AST node is produced by the assignment expressions operator (also known as the walrus operator). As opposed to the Assign{.interpreted-text role="class"} node in which the first argument can be multiple nodes, in this case both target and value must be single nodes.

::: doctest >>> print(ast.dump(ast.parse('(x := 4)', mode='eval'), indent=4)) Expression( body=NamedExpr( target=Name(id='x', ctx=Store()), value=Constant(value=4))) :::

::: versionadded 3.8 ::: :::::

Subscripting

:::: {.Subscript(value, .slice, .ctx)} A subscript, such as l[1]. value is the subscripted object (usually sequence or mapping). slice is an index, slice or key. It can be a Tuple{.interpreted-text role="class"} and contain a Slice{.interpreted-text role="class"}. ctx is Load{.interpreted-text role="class"}, Store{.interpreted-text role="class"} or Del{.interpreted-text role="class"} according to the action performed with the subscript.

::: doctest >>> print(ast.dump(ast.parse('l[1:2, 3]', mode='eval'), indent=4)) Expression( body=Subscript( value=Name(id='l'), slice=Tuple( elts=[ Slice( lower=Constant(value=1), upper=Constant(value=2)), Constant(value=3)]))) ::: ::::

:::: {.Slice(lower, .upper, .step)} Regular slicing (on the form lower:upper or lower:upper:step). Can occur only inside the slice field of Subscript{.interpreted-text role="class"}, either directly or as an element of Tuple{.interpreted-text role="class"}.

::: doctest >>> print(ast.dump(ast.parse('l[1:2]', mode='eval'), indent=4)) Expression( body=Subscript( value=Name(id='l'), slice=Slice( lower=Constant(value=1), upper=Constant(value=2)))) ::: ::::

Comprehensions

:::: {.ListComp(elt, .generators) .SetComp(elt, .generators) .GeneratorExp(elt, .generators) .DictComp(key, .value, .generators)} List and set comprehensions, generator expressions, and dictionary comprehensions. elt (or key and value) is a single node representing the part that will be evaluated for each item.

generators is a list of comprehension{.interpreted-text role="class"} nodes.

::: doctest >>> print(ast.dump( ... ast.parse('[x for x in numbers]', mode='eval'), ... indent=4, ... )) Expression( body=ListComp( elt=Name(id='x'), generators=[ comprehension( target=Name(id='x', ctx=Store()), iter=Name(id='numbers'), is_async=0)])) >>> print(ast.dump( ... ast.parse('{x: x**2 for x in numbers}', mode='eval'), ... indent=4, ... )) Expression( body=DictComp( key=Name(id='x'), value=BinOp( left=Name(id='x'), op=Pow(), right=Constant(value=2)), generators=[ comprehension( target=Name(id='x', ctx=Store()), iter=Name(id='numbers'), is_async=0)])) >>> print(ast.dump( ... ast.parse('{x for x in numbers}', mode='eval'), ... indent=4, ... )) Expression( body=SetComp( elt=Name(id='x'), generators=[ comprehension( target=Name(id='x', ctx=Store()), iter=Name(id='numbers'), is_async=0)])) ::: ::::

:::: {.comprehension(target, .iter, .ifs, .is_async)} One for clause in a comprehension. target is the reference to use for each element - typically a Name{.interpreted-text role="class"} or Tuple{.interpreted-text role="class"} node. iter is the object to iterate over. ifs is a list of test expressions: each for clause can have multiple ifs.

is_async indicates a comprehension is asynchronous (using an async for instead of for). The value is an integer (0 or 1).

::: doctest >>> print(ast.dump(ast.parse('[ord(c) for line in file for c in line]', mode='eval'), ... indent=4)) # Multiple comprehensions in one. Expression( body=ListComp( elt=Call( func=Name(id='ord'), args=[ Name(id='c')]), generators=[ comprehension( target=Name(id='line', ctx=Store()), iter=Name(id='file'), is_async=0), comprehension( target=Name(id='c', ctx=Store()), iter=Name(id='line'), is_async=0)]))

>>> print(ast.dump(ast.parse('(n**2 for n in it if n>5 if n<10)', mode='eval'), ... indent=4)) # generator comprehension Expression( body=GeneratorExp( elt=BinOp( left=Name(id='n'), op=Pow(), right=Constant(value=2)), generators=[ comprehension( target=Name(id='n', ctx=Store()), iter=Name(id='it'), ifs=[ Compare( left=Name(id='n'), ops=[ Gt()], comparators=[ Constant(value=5)]), Compare( left=Name(id='n'), ops=[ Lt()], comparators=[ Constant(value=10)])], is_async=0)]))

>>> print(ast.dump(ast.parse('[i async for i in soc]', mode='eval'), ... indent=4)) # Async comprehension Expression( body=ListComp( elt=Name(id='i'), generators=[ comprehension( target=Name(id='i', ctx=Store()), iter=Name(id='soc'), is_async=1)])) ::: ::::

Statements {#ast-statements}

::::: {.Assign(targets, .value, .type_comment)} An assignment. targets is a list of nodes, and value is a single node.

Multiple nodes in targets represents assigning the same value to each. Unpacking is represented by putting a Tuple{.interpreted-text role="class"} or List{.interpreted-text role="class"} within targets.

::: attribute type_comment

type_comment is an optional string with the type annotation as a comment. :::

::: doctest >>> print(ast.dump(ast.parse('a = b = 1'), indent=4)) # Multiple assignment Module( body=[ Assign( targets=[ Name(id='a', ctx=Store()), Name(id='b', ctx=Store())], value=Constant(value=1))])

>>> print(ast.dump(ast.parse('a,b = c'), indent=4)) # Unpacking Module( body=[ Assign( targets=[ Tuple( elts=[ Name(id='a', ctx=Store()), Name(id='b', ctx=Store())], ctx=Store())], value=Name(id='c'))]) ::: :::::

:::: {.AnnAssign(target, .annotation, .value, .simple)} An assignment with a type annotation. target is a single node and can be a Name{.interpreted-text role="class"}, an Attribute{.interpreted-text role="class"} or a Subscript{.interpreted-text role="class"}. annotation is the annotation, such as a Constant{.interpreted-text role="class"} or Name{.interpreted-text role="class"} node. value is a single optional node.

simple is always either 0 (indicating a "complex" target) or 1 (indicating a "simple" target). A "simple" target consists solely of a Name{.interpreted-text role="class"} node that does not appear between parentheses; all other targets are considered complex. Only simple targets appear in the ~object.__annotations__{.interpreted-text role="attr"} dictionary of modules and classes.

::: doctest >>> print(ast.dump(ast.parse('c: int'), indent=4)) Module( body=[ AnnAssign( target=Name(id='c', ctx=Store()), annotation=Name(id='int'), simple=1)])

>>> print(ast.dump(ast.parse('(a): int = 1'), indent=4)) # Annotation with parenthesis Module( body=[ AnnAssign( target=Name(id='a', ctx=Store()), annotation=Name(id='int'), value=Constant(value=1), simple=0)])

>>> print(ast.dump(ast.parse('a.b: int'), indent=4)) # Attribute annotation Module( body=[ AnnAssign( target=Attribute( value=Name(id='a'), attr='b', ctx=Store()), annotation=Name(id='int'), simple=0)])

>>> print(ast.dump(ast.parse('a[1]: int'), indent=4)) # Subscript annotation Module( body=[ AnnAssign( target=Subscript( value=Name(id='a'), slice=Constant(value=1), ctx=Store()), annotation=Name(id='int'), simple=0)]) ::: ::::

:::: {.AugAssign(target, .op, .value)} Augmented assignment, such as a += 1. In the following example, target is a Name{.interpreted-text role="class"} node for x (with the Store{.interpreted-text role="class"} context), op is Add{.interpreted-text role="class"}, and value is a Constant{.interpreted-text role="class"} with value for 1.

The target attribute cannot be of class Tuple{.interpreted-text role="class"} or List{.interpreted-text role="class"}, unlike the targets of Assign{.interpreted-text role="class"}.

::: doctest >>> print(ast.dump(ast.parse('x += 2'), indent=4)) Module( body=[ AugAssign( target=Name(id='x', ctx=Store()), op=Add(), value=Constant(value=2))]) ::: ::::

:::: {.Raise(exc, .cause)} A raise statement. exc is the exception object to be raised, normally a Call{.interpreted-text role="class"} or Name{.interpreted-text role="class"}, or None for a standalone raise. cause is the optional part for y in raise x from y.

::: doctest >>> print(ast.dump(ast.parse('raise x from y'), indent=4)) Module( body=[ Raise( exc=Name(id='x'), cause=Name(id='y'))]) ::: ::::

:::: {.Assert(test, .msg)} An assertion. test holds the condition, such as a Compare{.interpreted-text role="class"} node. msg holds the failure message.

::: doctest >>> print(ast.dump(ast.parse('assert x,y'), indent=4)) Module( body=[ Assert( test=Name(id='x'), msg=Name(id='y'))]) ::: ::::

:::: Delete(targets) Represents a del statement. targets is a list of nodes, such as Name{.interpreted-text role="class"}, Attribute{.interpreted-text role="class"} or Subscript{.interpreted-text role="class"} nodes.

::: doctest >>> print(ast.dump(ast.parse('del x,y,z'), indent=4)) Module( body=[ Delete( targets=[ Name(id='x', ctx=Del()), Name(id='y', ctx=Del()), Name(id='z', ctx=Del())])]) ::: ::::

:::: Pass() A pass statement.

::: doctest >>> print(ast.dump(ast.parse('pass'), indent=4)) Module( body=[ Pass()]) ::: ::::

::::: {.TypeAlias(name, .type_params, .value)} A type alias <type-aliases>{.interpreted-text role="ref"} created through the type{.interpreted-text role="keyword"} statement. name is the name of the alias, type_params is a list of type parameters <ast-type-params>{.interpreted-text role="ref"}, and value is the value of the type alias.

::: doctest >>> print(ast.dump(ast.parse('type Alias = int'), indent=4)) Module( body=[ TypeAlias( name=Name(id='Alias', ctx=Store()), value=Name(id='int'))]) :::

::: versionadded 3.12 ::: :::::

Other statements which are only applicable inside functions or loops are described in other sections.

Imports

:::: Import(names) An import statement. names is a list of alias{.interpreted-text role="class"} nodes.

::: doctest >>> print(ast.dump(ast.parse('import x,y,z'), indent=4)) Module( body=[ Import( names=[ alias(name='x'), alias(name='y'), alias(name='z')], is_lazy=0)]) ::: ::::

:::: {.ImportFrom(module, .names, .level)} Represents from x import y. module is a raw string of the 'from' name, without any leading dots, or None for statements such as from . import foo. level is an integer holding the level of the relative import (0 means absolute import).

::: doctest >>> print(ast.dump(ast.parse('from y import x,y,z'), indent=4)) Module( body=[ ImportFrom( module='y', names=[ alias(name='x'), alias(name='y'), alias(name='z')], level=0, is_lazy=0)]) ::: ::::

:::: {.alias(name, .asname)} Both parameters are raw strings of the names. asname can be None if the regular name is to be used.

::: doctest >>> print(ast.dump(ast.parse('from ..foo.bar import a as b, c'), indent=4)) Module( body=[ ImportFrom( module='foo.bar', names=[ alias(name='a', asname='b'), alias(name='c')], level=2, is_lazy=0)]) ::: ::::

Control flow

:::: note ::: title Note :::

Optional clauses such as else are stored as an empty list if they're not present. ::::

:::: {.If(test, .body, .orelse)} An if statement. test holds a single node, such as a Compare{.interpreted-text role="class"} node. body and orelse each hold a list of nodes.

elif clauses don't have a special representation in the AST, but rather appear as extra If{.interpreted-text role="class"} nodes within the orelse section of the previous one.

::: doctest >>> print(ast.dump(ast.parse(""" ... if x: ... ... ... elif y: ... ... ... else: ... ... ... """), indent=4)) Module( body=[ If( test=Name(id='x'), body=[ Expr( value=Constant(value=Ellipsis))], orelse=[ If( test=Name(id='y'), body=[ Expr( value=Constant(value=Ellipsis))], orelse=[ Expr( value=Constant(value=Ellipsis))])])]) ::: ::::

::::: {.For(target, .iter, .body, .orelse, .type_comment)} A for loop. target holds the variable(s) the loop assigns to, as a single Name{.interpreted-text role="class"}, Tuple{.interpreted-text role="class"}, List{.interpreted-text role="class"}, Attribute{.interpreted-text role="class"} or Subscript{.interpreted-text role="class"} node. iter holds the item to be looped over, again as a single node. body and orelse contain lists of nodes to execute. Those in orelse are executed if the loop finishes normally, rather than via a break statement.

::: attribute type_comment

type_comment is an optional string with the type annotation as a comment. :::

::: doctest >>> print(ast.dump(ast.parse(""" ... for x in y: ... ... ... else: ... ... ... """), indent=4)) Module( body=[ For( target=Name(id='x', ctx=Store()), iter=Name(id='y'), body=[ Expr( value=Constant(value=Ellipsis))], orelse=[ Expr( value=Constant(value=Ellipsis))])]) ::: :::::

:::: {.While(test, .body, .orelse)} A while loop. test holds the condition, such as a Compare{.interpreted-text role="class"} node.

::: doctest >>> print(ast.dump(ast.parse(""" ... while x: ... ... ... else: ... ... ... """), indent=4)) Module( body=[ While( test=Name(id='x'), body=[ Expr( value=Constant(value=Ellipsis))], orelse=[ Expr( value=Constant(value=Ellipsis))])]) ::: ::::

:::: {.Break .Continue} The break and continue statements.

::: doctest >>> print(ast.dump(ast.parse("""... for a in b: ... if a > 5: ... break ... else: ... continue ... ... """), indent=4)) Module( body=[ For( target=Name(id='a', ctx=Store()), iter=Name(id='b'), body=[ If( test=Compare( left=Name(id='a'), ops=[ Gt()], comparators=[ Constant(value=5)]), body=[ Break()], orelse=[ Continue()])])]) ::: ::::

:::: {.Try(body, .handlers, .orelse, .finalbody)} try blocks. All attributes are list of nodes to execute, except for handlers, which is a list of ExceptHandler{.interpreted-text role="class"} nodes.

::: doctest >>> print(ast.dump(ast.parse(""" ... try: ... ... ... except Exception: ... ... ... except OtherException as e: ... ... ... else: ... ... ... finally: ... ... ... """), indent=4)) Module( body=[ Try( body=[ Expr( value=Constant(value=Ellipsis))], handlers=[ ExceptHandler( type=Name(id='Exception'), body=[ Expr( value=Constant(value=Ellipsis))]), ExceptHandler( type=Name(id='OtherException'), name='e', body=[ Expr( value=Constant(value=Ellipsis))])], orelse=[ Expr( value=Constant(value=Ellipsis))], finalbody=[ Expr( value=Constant(value=Ellipsis))])]) ::: ::::

::::: {.TryStar(body, .handlers, .orelse, .finalbody)} try blocks which are followed by except* clauses. The attributes are the same as for Try{.interpreted-text role="class"} but the ExceptHandler{.interpreted-text role="class"} nodes in handlers are interpreted as except* blocks rather then except.

::: doctest >>> print(ast.dump(ast.parse(""" ... try: ... ... ... except* Exception: ... ... ... """), indent=4)) Module( body=[ TryStar( body=[ Expr( value=Constant(value=Ellipsis))], handlers=[ ExceptHandler( type=Name(id='Exception'), body=[ Expr( value=Constant(value=Ellipsis))])])]) :::

::: versionadded 3.11 ::: :::::

:::: {.ExceptHandler(type, .name, .body)} A single except clause. type is the exception type it will match, typically a Name{.interpreted-text role="class"} node (or None for a catch-all except: clause). name is a raw string for the name to hold the exception, or None if the clause doesn't have as foo. body is a list of nodes.

::: doctest >>> print(ast.dump(ast.parse("""... try: ... a + 1 ... except TypeError: ... pass ... """), indent=4)) Module( body=[ Try( body=[ Expr( value=BinOp( left=Name(id='a'), op=Add(), right=Constant(value=1)))], handlers=[ ExceptHandler( type=Name(id='TypeError'), body=[ Pass()])])]) ::: ::::

:::: {.With(items, .body, .type_comment)} A with block. items is a list of withitem{.interpreted-text role="class"} nodes representing the context managers, and body is the indented block inside the context.

::: attribute type_comment

type_comment is an optional string with the type annotation as a comment. ::: ::::

:::: {.withitem(context_expr, .optional_vars)} A single context manager in a with block. context_expr is the context manager, often a Call{.interpreted-text role="class"} node. optional_vars is a Name{.interpreted-text role="class"}, Tuple{.interpreted-text role="class"} or List{.interpreted-text role="class"} for the as foo part, or None if that isn't used.

::: doctest >>> print(ast.dump(ast.parse("""... with a as b, c as d: ... something(b, d) ... """), indent=4)) Module( body=[ With( items=[ withitem( context_expr=Name(id='a'), optional_vars=Name(id='b', ctx=Store())), withitem( context_expr=Name(id='c'), optional_vars=Name(id='d', ctx=Store()))], body=[ Expr( value=Call( func=Name(id='something'), args=[ Name(id='b'), Name(id='d')]))])]) ::: ::::

Pattern matching

:::: {.Match(subject, .cases)} A match statement. subject holds the subject of the match (the object that is being matched against the cases) and cases contains an iterable of match_case{.interpreted-text role="class"} nodes with the different cases.

::: versionadded 3.10 ::: ::::

::::: {.match_case(pattern, .guard, .body)} A single case pattern in a match statement. pattern contains the match pattern that the subject will be matched against. Note that the AST{.interpreted-text role="class"} nodes produced for patterns differ from those produced for expressions, even when they share the same syntax.

The guard attribute contains an expression that will be evaluated if the pattern matches the subject.

body contains a list of nodes to execute if the pattern matches and the result of evaluating the guard expression is true.

::: doctest >>> print(ast.dump(ast.parse(""" ... match x: ... case [x] if x>0: ... ... ... case tuple(): ... ... ... """), indent=4)) Module( body=[ Match( subject=Name(id='x'), cases=[ match_case( pattern=MatchSequence( patterns=[ MatchAs(name='x')]), guard=Compare( left=Name(id='x'), ops=[ Gt()], comparators=[ Constant(value=0)]), body=[ Expr( value=Constant(value=Ellipsis))]), match_case( pattern=MatchClass( cls=Name(id='tuple')), body=[ Expr( value=Constant(value=Ellipsis))])])]) :::