Literals¶

classast.Constant(value)¶

A constant value. Thevalue attribute of theConstant literal contains thePython object it represents. The values represented can be simple typessuch as a number, string orNone, but also immutable container types(tuples and frozensets) if all of their elements are constant.

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

classast.FormattedValue(value,conversion,format_spec)¶

Node representing a single formatting field in an f-string. If the stringcontains a single formatting field and nothing else the node can beisolated otherwise it appears inJoinedStr.

• value is any expression node (such as a literal, a variable, or afunction call).

• conversion is an integer:

  • -1: no formatting

  • 115:!s string formatting

  • 114:!r repr formatting

  • 97:!a ascii formatting

• format_spec is aJoinedStr node representing the formattingof the value, orNone if no format was specified. Bothconversion andformat_spec can be set at the same time.

classast.JoinedStr(values)¶

An f-string, comprising a series ofFormattedValue andConstantnodes.

>>>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', ctx=Load()),                conversion=-1),            Constant(value=') is '),            FormattedValue(                value=Call(                    func=Name(id='sin', ctx=Load()),                    args=[                        Name(id='a', ctx=Load())],                    keywords=[]),                conversion=-1,                format_spec=JoinedStr(                    values=[                        Constant(value='.3')]))]))

classast.List(elts,ctx)¶

classast.Tuple(elts,ctx)¶

A list or tuple.elts holds a list of nodes representing the elements.ctx isStore if the container is an assignment target (i.e.(x,y)=something), andLoad otherwise.

>>>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)],        ctx=Load()))>>>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)],        ctx=Load()))

classast.Set(elts)¶

A set.elts holds a list of nodes representing the set’s elements.

>>>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)]))

classast.Dict(keys,values)¶

A dictionary.keys andvalues hold lists of nodes representing thekeys and the values respectively, in matching order (what would be returnedwhen callingdictionary.keys() anddictionary.values()).

When doing dictionary unpacking using dictionary literals the expression to beexpanded goes in thevalues list, with aNone at the correspondingposition inkeys.

>>>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', ctx=Load())]))

Variables¶

classast.Name(id,ctx)¶

A variable name.id holds the name as a string, andctx is one ofthe following types.

classast.Load¶

classast.Store¶

classast.Del¶

Variable references can be used to load the value of a variable, to assigna new value to it, or to delete it. Variable references are given a contextto distinguish these cases.

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

classast.Starred(value,ctx)¶

A*var variable reference.value holds the variable, typically aName node. This type must be used when building aCallnode with*args.

>>>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', ctx=Load()))],    type_ignores=[])

Expressions¶

classast.Expr(value)¶

When an expression, such as a function call, appears as a statement by itselfwith its return value not used or stored, it is wrapped in this container.value holds one of the other nodes in this section, aConstant, aName, aLambda, aYield orYieldFrom node.

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

classast.UnaryOp(op,operand)¶

A unary operation.op is the operator, andoperand any expressionnode.

classast.UAdd¶

classast.USub¶

classast.Not¶

classast.Invert¶

Unary operator tokens.Not is thenot keyword,Invertis the~ operator.

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

classast.BinOp(left,op,right)¶

A binary operation (like addition or division).op is the operator, andleft andright are any expression nodes.

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

classast.Add¶

classast.Sub¶

classast.Mult¶

classast.Div¶

classast.FloorDiv¶

classast.Mod¶

classast.Pow¶

classast.LShift¶

classast.RShift¶

classast.BitOr¶

classast.BitXor¶

classast.BitAnd¶

classast.MatMult¶

Binary operator tokens.

classast.BoolOp(op,values)¶

A boolean operation, ‘or’ or ‘and’.op isOr orAnd.values are the values involved. Consecutive operations with the sameoperator, such asaorborc, are collapsed into one node with severalvalues.

This doesn’t includenot, which is aUnaryOp.

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

classast.And¶

classast.Or¶

Boolean operator tokens.

classast.Compare(left,ops,comparators)¶

A comparison of two or more values.left is the first value in thecomparison,ops the list of operators, andcomparators the listof values after the first element in the comparison.

>>>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', ctx=Load()),            Constant(value=10)]))

classast.Eq¶

classast.NotEq¶

classast.Lt¶

classast.LtE¶

classast.Gt¶

classast.GtE¶

classast.Is¶

classast.IsNot¶

classast.In¶

classast.NotIn¶

Comparison operator tokens.

classast.Call(func,args,keywords,starargs,kwargs)¶

A function call.func is the function, which will often be aName orAttribute object. Of the arguments:

• args holds a list of the arguments passed by position.

• keywords holds a list ofkeyword objects representingarguments passed by keyword.

When creating aCall node,args andkeywords are required, butthey can be empty lists.starargs andkwargs are optional.

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

classast.keyword(arg,value)¶

A keyword argument to a function call or class definition.arg is a rawstring of the parameter name,value is a node to pass in.

classast.IfExp(test,body,orelse)¶

An expression such asaifbelsec. Each field holds a single node, soin the following example, all three areName nodes.

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

classast.Attribute(value,attr,ctx)¶

Attribute access, e.g.d.keys.value is a node, typically aName.attr is a bare string giving the name of the attribute,andctx isLoad,Store orDel according to howthe attribute is acted on.

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

classast.NamedExpr(target,value)¶

A named expression. This AST node is produced by the assignment expressionsoperator (also known as the walrus operator). As opposed to theAssignnode in which the first argument can be multiple nodes, in this case bothtarget andvalue must be single nodes.

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

Statements¶

classast.Assign(targets,value,type_comment)¶

An assignment.targets is a list of nodes, andvalue is a single node.

Multiple nodes intargets represents assigning the same value to each.Unpacking is represented by putting aTuple orListwithintargets.

type_comment¶

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

>>>print(ast.dump(ast.parse('a = b = 1'),indent=4))# Multiple assignmentModule(    body=[        Assign(            targets=[                Name(id='a', ctx=Store()),                Name(id='b', ctx=Store())],            value=Constant(value=1))],    type_ignores=[])>>>print(ast.dump(ast.parse('a,b = c'),indent=4))# UnpackingModule(    body=[        Assign(            targets=[                Tuple(                    elts=[                        Name(id='a', ctx=Store()),                        Name(id='b', ctx=Store())],                    ctx=Store())],            value=Name(id='c', ctx=Load()))],    type_ignores=[])

classast.AnnAssign(target,annotation,value,simple)¶

An assignment with a type annotation.target is a single node and canbe aName, aAttribute or aSubscript.annotation is the annotation, such as aConstant orNamenode.value is a single optional node.simple is a boolean integerset to True for aName node intarget that do not appear inbetween parenthesis and are hence pure names and not expressions.

>>>print(ast.dump(ast.parse('c: int'),indent=4))Module(    body=[        AnnAssign(            target=Name(id='c', ctx=Store()),            annotation=Name(id='int', ctx=Load()),            simple=1)],    type_ignores=[])>>>print(ast.dump(ast.parse('(a): int = 1'),indent=4))# Annotation with parenthesisModule(    body=[        AnnAssign(            target=Name(id='a', ctx=Store()),            annotation=Name(id='int', ctx=Load()),            value=Constant(value=1),            simple=0)],    type_ignores=[])>>>print(ast.dump(ast.parse('a.b: int'),indent=4))# Attribute annotationModule(    body=[        AnnAssign(            target=Attribute(                value=Name(id='a', ctx=Load()),                attr='b',                ctx=Store()),            annotation=Name(id='int', ctx=Load()),            simple=0)],    type_ignores=[])>>>print(ast.dump(ast.parse('a[1]: int'),indent=4))# Subscript annotationModule(    body=[        AnnAssign(            target=Subscript(                value=Name(id='a', ctx=Load()),                slice=Constant(value=1),                ctx=Store()),            annotation=Name(id='int', ctx=Load()),            simple=0)],    type_ignores=[])

classast.AugAssign(target,op,value)¶

Augmented assignment, such asa+=1. In the following example,target is aName node forx (with theStorecontext),op isAdd, andvalue is aConstant withvalue for 1.

Thetarget attribute connot be of classTuple orList,unlike the targets ofAssign.

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

classast.Raise(exc,cause)¶

Araise statement.exc is the exception object to be raised, normally aCall orName, orNone for a standaloneraise.cause is the optional part fory inraisexfromy.

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

classast.Assert(test,msg)¶

An assertion.test holds the condition, such as aCompare node.msg holds the failure message.

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

classast.Delete(targets)¶

Represents adel statement.targets is a list of nodes, such asName,Attribute orSubscript nodes.

>>>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())])],    type_ignores=[])

classast.Pass¶

Apass statement.

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

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

Control flow¶

classast.If(test,body,orelse)¶

Anif statement.test holds a single node, such as aComparenode.body andorelse each hold a list of nodes.

elif clauses don’t have a special representation in the AST, but ratherappear as extraIf nodes within theorelse section of theprevious one.

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

classast.For(target,iter,body,orelse,type_comment)¶

Afor loop.target holds the variable(s) the loop assigns to, as asingleName,Tuple orList node.iter holdsthe item to be looped over, again as a single node.body andorelsecontain lists of nodes to execute. Those inorelse are executed if theloop finishes normally, rather than via abreak statement.

type_comment¶

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

>>>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', ctx=Load()),            body=[                Expr(                    value=Constant(value=Ellipsis))],            orelse=[                Expr(                    value=Constant(value=Ellipsis))])],    type_ignores=[])

classast.While(test,body,orelse)¶

Awhile loop.test holds the condition, such as aComparenode.

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

classast.Break¶

classast.Continue¶

Thebreak andcontinue statements.

>>>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', ctx=Load()),            body=[                If(                    test=Compare(                        left=Name(id='a', ctx=Load()),                        ops=[                            Gt()],                        comparators=[                            Constant(value=5)]),                    body=[                        Break()],                    orelse=[                        Continue()])],            orelse=[])],    type_ignores=[])

classast.Try(body,handlers,orelse,finalbody)¶

try blocks. All attributes are list of nodes to execute, except forhandlers, which is a list ofExceptHandler nodes.

>>>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', ctx=Load()),                    body=[                        Expr(                            value=Constant(value=Ellipsis))]),                ExceptHandler(                    type=Name(id='OtherException', ctx=Load()),                    name='e',                    body=[                        Expr(                            value=Constant(value=Ellipsis))])],            orelse=[                Expr(                    value=Constant(value=Ellipsis))],            finalbody=[                Expr(                    value=Constant(value=Ellipsis))])],    type_ignores=[])

classast.ExceptHandler(type,name,body)¶

A singleexcept clause.type is the exception type it will match,typically aName node (orNone for a catch-allexcept: clause).name is a raw string for the name to hold the exception, orNone ifthe clause doesn’t haveasfoo.body is a list of nodes.

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

classast.With(items,body,type_comment)¶

Awith block.items is a list ofwithitem nodes representingthe context managers, andbody is the indented block inside the context.

type_comment¶

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

classast.withitem(context_expr,optional_vars)¶

A single context manager in awith block.context_expr is the contextmanager, often aCall node.optional_vars is aName,Tuple orList for theasfoo part, orNone if thatisn’t used.

>>>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', ctx=Load()),                    optional_vars=Name(id='b', ctx=Store())),                withitem(                    context_expr=Name(id='c', ctx=Load()),                    optional_vars=Name(id='d', ctx=Store()))],            body=[                Expr(                    value=Call(                        func=Name(id='something', ctx=Load()),                        args=[                            Name(id='b', ctx=Load()),                            Name(id='d', ctx=Load())],                        keywords=[]))])],    type_ignores=[])

Function and class definitions¶

classast.FunctionDef(name,args,body,decorator_list,returns,type_comment)¶

A function definition.

• name is a raw string of the function name.

• args is anarguments node.

• body is the list of nodes inside the function.

• decorator_list is the list of decorators to be applied, stored outermostfirst (i.e. the first in the list will be applied last).

• returns is the return annotation.

type_comment¶

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

classast.Lambda(args,body)¶

lambda is a minimal function definition that can be used inside anexpression. UnlikeFunctionDef,body holds a single node.

>>>print(ast.dump(ast.parse('lambda x,y: ...'),indent=4))Module(    body=[        Expr(            value=Lambda(                args=arguments(                    posonlyargs=[],                    args=[                        arg(arg='x'),                        arg(arg='y')],                    kwonlyargs=[],                    kw_defaults=[],                    defaults=[]),                body=Constant(value=Ellipsis)))],    type_ignores=[])

classast.arguments(posonlyargs,args,vararg,kwonlyargs,kw_defaults,kwarg,defaults)¶

The arguments for a function.

• posonlyargs,args andkwonlyargs are lists ofarg nodes.

• vararg andkwarg are singlearg nodes, referring to the*args,**kwargs parameters.

• kw_defaults is a list of default values for keyword-only arguments. Ifone isNone, the corresponding argument is required.

• defaults is a list of default values for arguments that can be passedpositionally. If there are fewer defaults, they correspond to the last narguments.

classast.arg(arg,annotation,type_comment)¶

A single argument in a list.arg is a raw string of the argumentname,annotation is its annotation, such as aStr orName node.

type_comment¶

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

>>>print(ast.dump(ast.parse("""\...@decorator1...@decorator2...def f(a: 'annotation', b=1, c=2, *d, e, f=3, **g) -> 'return annotation':...    pass..."""),indent=4))Module(    body=[        FunctionDef(            name='f',            args=arguments(                posonlyargs=[],                args=[                    arg(                        arg='a',                        annotation=Constant(value='annotation')),                    arg(arg='b'),                    arg(arg='c')],                vararg=arg(arg='d'),                kwonlyargs=[                    arg(arg='e'),                    arg(arg='f')],                kw_defaults=[                    None,                    Constant(value=3)],                kwarg=arg(arg='g'),                defaults=[                    Constant(value=1),                    Constant(value=2)]),            body=[                Pass()],            decorator_list=[                Name(id='decorator1', ctx=Load()),                Name(id='decorator2', ctx=Load())],            returns=Constant(value='return annotation'))],    type_ignores=[])

classast.Return(value)¶

Areturn statement.

>>>print(ast.dump(ast.parse('return 4'),indent=4))Module(    body=[        Return(            value=Constant(value=4))],    type_ignores=[])

classast.Yield(value)¶

classast.YieldFrom(value)¶

Ayield oryieldfrom expression. Because these are expressions, theymust be wrapped in aExpr node if the value sent back is not used.

>>>print(ast.dump(ast.parse('yield x'),indent=4))Module(    body=[        Expr(            value=Yield(                value=Name(id='x', ctx=Load())))],    type_ignores=[])>>>print(ast.dump(ast.parse('yield from x'),indent=4))Module(    body=[        Expr(            value=YieldFrom(                value=Name(id='x', ctx=Load())))],    type_ignores=[])

classast.Global(names)¶

classast.Nonlocal(names)¶

global andnonlocal statements.names is a list of raw strings.

>>>print(ast.dump(ast.parse('global x,y,z'),indent=4))Module(    body=[        Global(            names=[                'x',                'y',                'z'])],    type_ignores=[])>>>print(ast.dump(ast.parse('nonlocal x,y,z'),indent=4))Module(    body=[        Nonlocal(            names=[                'x',                'y',                'z'])],    type_ignores=[])

classast.ClassDef(name,bases,keywords,starargs,kwargs,body,decorator_list)¶

A class definition.

• name is a raw string for the class name

• bases is a list of nodes for explicitly specified base classes.

• keywords is a list ofkeyword nodes, principally for ‘metaclass’.Other keywords will be passed to the metaclass, as perPEP-3115.

• starargs andkwargs are each a single node, as in a function call.starargs will be expanded to join the list of base classes, and kwargs willbe passed to the metaclass.

• body is a list of nodes representing the code within the classdefinition.

• decorator_list is a list of nodes, as inFunctionDef.

>>>print(ast.dump(ast.parse("""\...@decorator1...@decorator2...class Foo(base1, base2, metaclass=meta):...    pass..."""),indent=4))Module(    body=[        ClassDef(            name='Foo',            bases=[                Name(id='base1', ctx=Load()),                Name(id='base2', ctx=Load())],            keywords=[                keyword(                    arg='metaclass',                    value=Name(id='meta', ctx=Load()))],            body=[                Pass()],            decorator_list=[                Name(id='decorator1', ctx=Load()),                Name(id='decorator2', ctx=Load())])],    type_ignores=[])

Async and await¶

classast.AsyncFunctionDef(name,args,body,decorator_list,returns,type_comment)¶

Anasyncdef function definition. Has the same fields asFunctionDef.

classast.Await(value)¶

Anawait expression.value is what it waits for.Only valid in the body of anAsyncFunctionDef.

>>>print(ast.dump(ast.parse("""\...async def f():...    await other_func()..."""),indent=4))Module(    body=[        AsyncFunctionDef(            name='f',            args=arguments(                posonlyargs=[],                args=[],                kwonlyargs=[],                kw_defaults=[],                defaults=[]),            body=[                Expr(                    value=Await(                        value=Call(                            func=Name(id='other_func', ctx=Load()),                            args=[],                            keywords=[])))],            decorator_list=[])],    type_ignores=[])

classast.AsyncFor(target,iter,body,orelse,type_comment)¶

classast.AsyncWith(items,body,type_comment)¶

asyncfor loops andasyncwith context managers. They have the samefields asFor andWith, respectively. Only valid in thebody of anAsyncFunctionDef.