ast
— Árvores de Sintaxe Abstrata¶
Código-fonte: Lib/ast.py
O módulo ast
ajuda os aplicativos Python a processar árvores da gramática de sintaxe abstrata do Python. A sintaxe abstrata em si pode mudar em cada lançamento do Python; este módulo ajuda a descobrir programaticamente como é a gramática atual.
Uma árvore de sintaxe abstrata pode ser gerada passando ast.PyCF_ONLY_AST
como um sinalizador para a função embutida compile()
, ou usando o auxiliar parse()
fornecido neste módulo. O resultado será uma árvore de objetos cujas classes herdam de ast.AST
. Uma árvore de sintaxe abstrata pode ser compilada em um objeto de código Python usando a função embutida compile()
.
Gramática Abstrata¶
A gramática abstrata está atualmente definida da seguinte forma:
-- ASDL's 4 builtin types are:
-- identifier, int, string, constant
module Python
{
mod = Module(stmt* body, type_ignore* type_ignores)
| Interactive(stmt* body)
| Expression(expr body)
| FunctionType(expr* argtypes, expr returns)
stmt = FunctionDef(identifier name, arguments args,
stmt* body, expr* decorator_list, expr? returns,
string? type_comment)
| AsyncFunctionDef(identifier name, arguments args,
stmt* body, expr* decorator_list, expr? returns,
string? type_comment)
| ClassDef(identifier name,
expr* bases,
keyword* keywords,
stmt* body,
expr* decorator_list)
| Return(expr? value)
| Delete(expr* targets)
| Assign(expr* targets, expr value, string? type_comment)
| AugAssign(expr target, operator op, expr value)
-- 'simple' indicates that we annotate simple name without parens
| AnnAssign(expr target, expr annotation, expr? value, int simple)
-- use 'orelse' because else is a keyword in target languages
| For(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
| AsyncFor(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
| While(expr test, stmt* body, stmt* orelse)
| If(expr test, stmt* body, stmt* orelse)
| With(withitem* items, stmt* body, string? type_comment)
| AsyncWith(withitem* items, stmt* body, string? type_comment)
| Match(expr subject, match_case* cases)
| Raise(expr? exc, expr? cause)
| Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
| TryStar(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
| Assert(expr test, expr? msg)
| Import(alias* names)
| ImportFrom(identifier? module, alias* names, int? level)
| Global(identifier* names)
| Nonlocal(identifier* names)
| Expr(expr value)
| Pass | Break | Continue
-- col_offset is the byte offset in the utf8 string the parser uses
attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
-- BoolOp() can use left & right?
expr = BoolOp(boolop op, expr* values)
| NamedExpr(expr target, expr value)
| BinOp(expr left, operator op, expr right)
| UnaryOp(unaryop op, expr operand)
| Lambda(arguments args, expr body)
| IfExp(expr test, expr body, expr orelse)
| Dict(expr* keys, expr* values)
| Set(expr* elts)
| ListComp(expr elt, comprehension* generators)
| SetComp(expr elt, comprehension* generators)
| DictComp(expr key, expr value, comprehension* generators)
| GeneratorExp(expr elt, comprehension* generators)
-- the grammar constrains where yield expressions can occur
| Await(expr value)
| Yield(expr? value)
| YieldFrom(expr value)
-- need sequences for compare to distinguish between
-- x < 4 < 3 and (x < 4) < 3
| Compare(expr left, cmpop* ops, expr* comparators)
| Call(expr func, expr* args, keyword* keywords)
| FormattedValue(expr value, int conversion, expr? format_spec)
| JoinedStr(expr* values)
| Constant(constant value, string? kind)
-- the following expression can appear in assignment context
| Attribute(expr value, identifier attr, expr_context ctx)
| Subscript(expr value, expr slice, expr_context ctx)
| Starred(expr value, expr_context ctx)
| Name(identifier id, expr_context ctx)
| List(expr* elts, expr_context ctx)
| Tuple(expr* elts, expr_context ctx)
-- can appear only in Subscript
| Slice(expr? lower, expr? upper, expr? step)
-- col_offset is the byte offset in the utf8 string the parser uses
attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
expr_context = Load | Store | Del
boolop = And | Or
operator = Add | Sub | Mult | MatMult | Div | Mod | Pow | LShift
| RShift | BitOr | BitXor | BitAnd | FloorDiv
unaryop = Invert | Not | UAdd | USub
cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn
comprehension = (expr target, expr iter, expr* ifs, int is_async)
excepthandler = ExceptHandler(expr? type, identifier? name, stmt* body)
attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
arguments = (arg* posonlyargs, arg* args, arg? vararg, arg* kwonlyargs,
expr* kw_defaults, arg? kwarg, expr* defaults)
arg = (identifier arg, expr? annotation, string? type_comment)
attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
-- keyword arguments supplied to call (NULL identifier for **kwargs)
keyword = (identifier? arg, expr value)
attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
-- import name with optional 'as' alias.
alias = (identifier name, identifier? asname)
attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
withitem = (expr context_expr, expr? optional_vars)
match_case = (pattern pattern, expr? guard, stmt* body)
pattern = MatchValue(expr value)
| MatchSingleton(constant value)
| MatchSequence(pattern* patterns)
| MatchMapping(expr* keys, pattern* patterns, identifier? rest)
| MatchClass(expr cls, pattern* patterns, identifier* kwd_attrs, pattern* kwd_patterns)
| MatchStar(identifier? name)
-- The optional "rest" MatchMapping parameter handles capturing extra mapping keys
| MatchAs(pattern? pattern, identifier? name)
| MatchOr(pattern* patterns)
attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)
type_ignore = TypeIgnore(int lineno, string tag)
}
Classes de nó¶
- class ast.AST¶
This is the base of all AST node classes. The actual node classes are derived from the
Parser/Python.asdl
file, which is reproduced above. They are defined in the_ast
C module and re-exported inast
.Há uma classe definida para cada símbolo do lado esquerdo na gramática abstrata (por exemplo,
ast.stmt
ouast.expr
). Além disso, existe uma classe definida para cada construtor no lado direito; essas classes herdam das classes para as árvores do lado esquerdo. Por exemplo,ast.BinOp
herda deast.expr
. Para regras de produção com alternativas (“somas”), a classe do lado esquerdo é abstrata: apenas instâncias de nós construtores específicos são criadas.- _fields¶
Cada classe concreta possui um atributo
_fields
que fornece os nomes de todos os nós filhos.Cada instância de uma classe concreta tem um atributo para cada nó filho, do tipo definido na gramática. Por exemplo, as instâncias
ast.BinOp
possuem um atributoleft
do tipoast.expr
.Se estes atributos estiverem marcados como opcionais na gramática (usando um ponto de interrogação), o valor pode ser
None
. Se os atributos puderem ter valor zero ou mais (marcados com um asterisco), os valores serão representados como listas do Python. Todos os atributos possíveis devem estar presentes e ter valores válidos ao compilar uma AST comcompile()
.
- lineno¶
- col_offset¶
- end_lineno¶
- end_col_offset¶
Instances of
ast.expr
andast.stmt
subclasses havelineno
,col_offset
,end_lineno
, andend_col_offset
attributes. Thelineno
andend_lineno
are the first and last line numbers of source text span (1-indexed so the first line is line 1) and thecol_offset
andend_col_offset
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.Observe que as posições finais não são exigidas pelo compilador e, portanto, são opcionais. O deslocamento final está após o último símbolo, por exemplo, é possível obter o segmento de origem de um nó de expressão de uma linha usando
source_line[node.col_offset : node.end_col_offset]
.
O construtor de uma classe
ast.T
analisa seus argumentos da seguinte forma:Se houver argumentos posicionais, deve haver tantos quanto houver itens em
T._fields
; eles serão atribuídos como atributos desses nomes.Se houver argumentos nomeados, eles definirão os atributos dos mesmos nomes para os valores fornecidos.
Por exemplo, para criar e popular um nó
ast.UnaryOp
, você poderia usarnode = ast.UnaryOp() node.op = ast.USub() node.operand = ast.Constant() node.operand.value = 5 node.operand.lineno = 0 node.operand.col_offset = 0 node.lineno = 0 node.col_offset = 0
ou a forma mais compacta
node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0), lineno=0, col_offset=0)
Alterado na versão 3.8: A classe ast.Constant
é agora usada para todas as constantes.
Alterado na versão 3.9: Simple indices are represented by their value, extended slices are represented as tuples.
Obsoleto desde a versão 3.8: Old classes ast.Num
, ast.Str
, ast.Bytes
,
ast.NameConstant
and ast.Ellipsis
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.
Obsoleto desde a versão 3.9: Old classes ast.Index
and ast.ExtSlice
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.
Nota
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¶
- class ast.Module(body, type_ignores)¶
A Python module, as with file input. Node type generated by
ast.parse()
in the default"exec"
mode.body is a
list
of the module’s Instruções.type_ignores is a
list
of the module’s type ignore comments; seeast.parse()
for more details.>>> print(ast.dump(ast.parse('x = 1'), indent=4)) Module( body=[ Assign( targets=[ Name(id='x', ctx=Store())], value=Constant(value=1))], type_ignores=[])
- class ast.Expression(body)¶
A single Python expression input. Node type generated by
ast.parse()
when mode is"eval"
.body is a single node, one of the expression types.
>>> print(ast.dump(ast.parse('123', mode='eval'), indent=4)) Expression( body=Constant(value=123))
- class ast.Interactive(body)¶
A single interactive input, like in Modo interativo. Node type generated by
ast.parse()
when mode is"single"
.body is a
list
of statement nodes.>>> 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))])
- class ast.FunctionType(argtypes, returns)¶
A representation of an old-style type comments for functions, as Python versions prior to 3.5 didn’t support PEP 484 annotations. Node type generated by
ast.parse()
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
of expression nodes.returns is a single expression node.
>>> print(ast.dump(ast.parse('(int, str) -> List[int]', mode='func_type'), indent=4)) FunctionType( argtypes=[ Name(id='int', ctx=Load()), Name(id='str', ctx=Load())], returns=Subscript( value=Name(id='List', ctx=Load()), slice=Name(id='int', ctx=Load()), ctx=Load()))
Novo na versão 3.8.
Literais¶
- class ast.Constant(value)¶
A constant value. The
value
attribute of theConstant
literal contains the Python object it represents. The values represented can be simple types such 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))
- class ast.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
.value
is any expression node (such as a literal, a variable, or a function call).conversion
is an integer:-1: no formatting
115:
!s
string formatting114:
!r
repr formatting97:
!a
ascii formatting
format_spec
is aJoinedStr
node representing the formatting of the value, orNone
if no format was specified. Bothconversion
andformat_spec
can be set at the same time.
- class ast.JoinedStr(values)¶
An f-string, comprising a series of
FormattedValue
andConstant
nodes.>>> 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')]))]))
- class ast.List(elts, ctx)¶
- class ast.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()))
- class ast.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)]))
- class ast.Dict(keys, values)¶
A dictionary.
keys
andvalues
hold lists of nodes representing the keys and the values respectively, in matching order (what would be returned when callingdictionary.keys()
anddictionary.values()
).When doing dictionary unpacking using dictionary literals the expression to be expanded goes in the
values
list, with aNone
at the corresponding position 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¶
- class ast.Name(id, ctx)¶
A variable name.
id
holds the name as a string, andctx
is one of the following types.
- class ast.Load¶
- class ast.Store¶
- class ast.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.
>>> 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=[])
- class ast.Starred(value, ctx)¶
A
*var
variable reference.value
holds the variable, typically aName
node. This type must be used when building aCall
node 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=[])
Expressões¶
- class ast.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, 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=[])
- class ast.UnaryOp(op, operand)¶
A unary operation.
op
is the operator, andoperand
any expression node.
- class ast.UAdd¶
- class ast.USub¶
- class ast.Not¶
- class ast.Invert¶
Unary operator tokens.
Not
is thenot
keyword,Invert
is the~
operator.>>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4)) Expression( body=UnaryOp( op=Not(), operand=Name(id='x', ctx=Load())))
- class ast.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())))
- class ast.Add¶
- class ast.Sub¶
- class ast.Mult¶
- class ast.Div¶
- class ast.FloorDiv¶
- class ast.Mod¶
- class ast.Pow¶
- class ast.LShift¶
- class ast.RShift¶
- class ast.BitOr¶
- class ast.BitXor¶
- class ast.BitAnd¶
- class ast.MatMult¶
Binary operator tokens.
- class ast.BoolOp(op, values)¶
A boolean operation, ‘or’ or ‘and’.
op
isOr
orAnd
.values
are the values involved. Consecutive operations with the same operator, such asa or b or c
, are collapsed into one node with several values.This doesn’t include
not
, 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())]))
- class ast.Compare(left, ops, comparators)¶
A comparison of two or more values.
left
is the first value in the comparison,ops
the list of operators, andcomparators
the list of 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)]))
- class ast.Eq¶
- class ast.NotEq¶
- class ast.Lt¶
- class ast.LtE¶
- class ast.Gt¶
- class ast.GtE¶
- class ast.Is¶
- class ast.IsNot¶
- class ast.In¶
- class ast.NotIn¶
Comparison operator tokens.
- class ast.Call(func, args, keywords)¶
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 representing arguments passed by keyword.
When creating a
Call
node,args
andkeywords
are required, but they can be empty lists.>>> 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()))]))
- class ast.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.
- class ast.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 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())))
- class ast.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 how the 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()))
- class ast.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
node 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)))
Subscripting¶
- class ast.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 aTuple
and contain aSlice
.ctx
isLoad
,Store
orDel
according to the action performed with the subscript.>>> print(ast.dump(ast.parse('l[1:2, 3]', mode='eval'), indent=4)) Expression( body=Subscript( value=Name(id='l', ctx=Load()), slice=Tuple( elts=[ Slice( lower=Constant(value=1), upper=Constant(value=2)), Constant(value=3)], ctx=Load()), ctx=Load()))
- class ast.Slice(lower, upper, step)¶
Regular slicing (on the form
lower:upper
orlower:upper:step
). Can occur only inside the slice field ofSubscript
, either directly or as an element ofTuple
.>>> print(ast.dump(ast.parse('l[1:2]', mode='eval'), indent=4)) Expression( body=Subscript( value=Name(id='l', ctx=Load()), slice=Slice( lower=Constant(value=1), upper=Constant(value=2)), ctx=Load()))
Comprehensions¶
- class ast.ListComp(elt, generators)¶
- class ast.SetComp(elt, generators)¶
- class ast.GeneratorExp(elt, generators)¶
- class ast.DictComp(key, value, generators)¶
List and set comprehensions, generator expressions, and dictionary comprehensions.
elt
(orkey
andvalue
) is a single node representing the part that will be evaluated for each item.generators
is a list ofcomprehension
nodes.>>> print(ast.dump(ast.parse('[x for x in numbers]', mode='eval'), indent=4)) Expression( body=ListComp( elt=Name(id='x', ctx=Load()), generators=[ comprehension( target=Name(id='x', ctx=Store()), iter=Name(id='numbers', ctx=Load()), ifs=[], 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', ctx=Load()), value=BinOp( left=Name(id='x', ctx=Load()), op=Pow(), right=Constant(value=2)), generators=[ comprehension( target=Name(id='x', ctx=Store()), iter=Name(id='numbers', ctx=Load()), ifs=[], is_async=0)])) >>> print(ast.dump(ast.parse('{x for x in numbers}', mode='eval'), indent=4)) Expression( body=SetComp( elt=Name(id='x', ctx=Load()), generators=[ comprehension( target=Name(id='x', ctx=Store()), iter=Name(id='numbers', ctx=Load()), ifs=[], is_async=0)]))
- class ast.comprehension(target, iter, ifs, is_async)¶
One
for
clause in a comprehension.target
is the reference to use for each element - typically aName
orTuple
node.iter
is the object to iterate over.ifs
is a list of test expressions: eachfor
clause can have multipleifs
.is_async
indicates a comprehension is asynchronous (using anasync for
instead offor
). The value is an integer (0 or 1).>>> 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', ctx=Load()), args=[ Name(id='c', ctx=Load())], keywords=[]), generators=[ comprehension( target=Name(id='line', ctx=Store()), iter=Name(id='file', ctx=Load()), ifs=[], is_async=0), comprehension( target=Name(id='c', ctx=Store()), iter=Name(id='line', ctx=Load()), ifs=[], 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', ctx=Load()), op=Pow(), right=Constant(value=2)), generators=[ comprehension( target=Name(id='n', ctx=Store()), iter=Name(id='it', ctx=Load()), ifs=[ Compare( left=Name(id='n', ctx=Load()), ops=[ Gt()], comparators=[ Constant(value=5)]), Compare( left=Name(id='n', ctx=Load()), 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', ctx=Load()), generators=[ comprehension( target=Name(id='i', ctx=Store()), iter=Name(id='soc', ctx=Load()), ifs=[], is_async=1)]))
Instruções¶
- class ast.Assign(targets, value, type_comment)¶
An assignment.
targets
is a list of nodes, andvalue
is a single node.Multiple nodes in
targets
represents assigning the same value to each. Unpacking is represented by putting aTuple
orList
withintargets
.- 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 assignment Module( 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)) # Unpacking Module( 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=[])
- class ast.AnnAssign(target, annotation, value, simple)¶
An assignment with a type annotation.
target
is a single node and can be aName
, aAttribute
or aSubscript
.annotation
is the annotation, such as aConstant
orName
node.value
is a single optional node.simple
is a boolean integer set to True for aName
node intarget
that do not appear in between 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 parenthesis Module( 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 annotation Module( 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 annotation Module( 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=[])
- class ast.AugAssign(target, op, value)¶
Augmented assignment, such as
a += 1
. In the following example,target
is aName
node forx
(with theStore
context),op
isAdd
, andvalue
is aConstant
with value for 1.The
target
attribute cannot 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=[])
- class ast.Raise(exc, cause)¶
A
raise
statement.exc
is the exception object to be raised, normally aCall
orName
, orNone
for a standaloneraise
.cause
is the optional part fory
inraise x from y
.>>> 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=[])
- class ast.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=[])
- class ast.Delete(targets)¶
Represents a
del
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=[])
- class ast.Pass¶
A
pass
statement.>>> print(ast.dump(ast.parse('pass'), indent=4)) Module( body=[ Pass()], type_ignores=[])
Other statements which are only applicable inside functions or loops are described in other sections.
Imports¶
- class ast.Import(names)¶
An import statement.
names
is a list ofalias
nodes.>>> print(ast.dump(ast.parse('import x,y,z'), indent=4)) Module( body=[ Import( names=[ alias(name='x'), alias(name='y'), alias(name='z')])], type_ignores=[])
- class ast.ImportFrom(module, names, level)¶
Represents
from x import y
.module
is a raw string of the ‘from’ name, without any leading dots, orNone
for statements such asfrom . import foo
.level
is an integer holding the level of the relative import (0 means absolute import).>>> 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)], type_ignores=[])
- class ast.alias(name, asname)¶
Both parameters are raw strings of the names.
asname
can beNone
if the regular name is to be used.>>> 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)], type_ignores=[])
Control flow¶
Nota
Optional clauses such as else
are stored as an empty list if they’re
not present.
- class ast.If(test, body, orelse)¶
An
if
statement.test
holds a single node, such as aCompare
node.body
andorelse
each hold a list of nodes.elif
clauses don’t have a special representation in the AST, but rather appear as extraIf
nodes within theorelse
section of the previous 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=[])
- class ast.For(target, iter, body, orelse, type_comment)¶
A
for
loop.target
holds the variable(s) the loop assigns to, as a singleName
,Tuple
orList
node.iter
holds the item to be looped over, again as a single node.body
andorelse
contain lists of nodes to execute. Those inorelse
are executed if the loop 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=[])
- class ast.While(test, body, orelse)¶
A
while
loop.test
holds the condition, such as aCompare
node.>> 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=[])
- class ast.Break¶
- class ast.Continue¶
The
break
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=[])
- class ast.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=[])
- class ast.TryStar(body, handlers, orelse, finalbody)¶
try
blocks which are followed byexcept*
clauses. The attributes are the same as forTry
but theExceptHandler
nodes inhandlers
are interpreted asexcept*
blocks rather thenexcept
.>>> 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', ctx=Load()), body=[ Expr( value=Constant(value=Ellipsis))])], orelse=[], finalbody=[])], type_ignores=[])
- class ast.ExceptHandler(type, name, body)¶
A single
except
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
if the clause doesn’t haveas foo
.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=[])
- class ast.With(items, body, type_comment)¶
A
with
block.items
is a list ofwithitem
nodes representing the 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.
- class ast.withitem(context_expr, optional_vars)¶
A single context manager in a
with
block.context_expr
is the context manager, often aCall
node.optional_vars
is aName
,Tuple
orList
for theas foo
part, orNone
if that isn’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=[])
Pattern matching¶
- class ast.Match(subject, cases)¶
A
match
statement.subject
holds the subject of the match (the object that is being matched against the cases) andcases
contains an iterable ofmatch_case
nodes with the different cases.
- class ast.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 theAST
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.>>> print(ast.dump(ast.parse(""" ... match x: ... case [x] if x>0: ... ... ... case tuple(): ... ... ... """), indent=4)) Module( body=[ Match( subject=Name(id='x', ctx=Load()), cases=[ match_case( pattern=MatchSequence( patterns=[ MatchAs(name='x')]), guard=Compare( left=Name(id='x', ctx=Load()), ops=[ Gt()], comparators=[ Constant(value=0)]), body=[ Expr( value=Constant(value=Ellipsis))]), match_case( pattern=MatchClass( cls=Name(id='tuple', ctx=Load()), patterns=[], kwd_attrs=[], kwd_patterns=[]), body=[ Expr( value=Constant(value=Ellipsis))])])], type_ignores=[])
- class ast.MatchValue(value)¶
A match literal or value pattern that compares by equality.
value
is an expression node. Permitted value nodes are restricted as described in the match statement documentation. This pattern succeeds if the match subject is equal to the evaluated value.>>> print(ast.dump(ast.parse(""" ... match x: ... case "Relevant": ... ... ... """), indent=4)) Module( body=[ Match( subject=Name(id='x', ctx=Load()), cases=[ match_case( pattern=MatchValue( value=Constant(value='Relevant')), body=[ Expr( value=Constant(value=Ellipsis))])])], type_ignores=[])
- class ast.MatchSingleton(value)¶
A match literal pattern that compares by identity.
value
is the singleton to be compared against:None
,True
, orFalse
. This pattern succeeds if the match subject is the given constant.>>> print(ast.dump(ast.parse(""" ... match x: ... case None: ... ... ... """), indent=4)) Module( body=[ Match( subject=Name(id='x', ctx=Load()), cases=[ match_case( pattern=MatchSingleton(value=None), body=[ Expr( value=Constant(value=Ellipsis))])])], type_ignores=[])
- class ast.MatchSequence(patterns)¶
A match sequence pattern.
patterns
contains the patterns to be matched against the subject elements if the subject is a sequence. Matches a variable length sequence if one of the subpatterns is aMatchStar
node, otherwise matches a fixed length sequence.>>> print(ast.dump(ast.parse(""" ... match x: ... case [1, 2]: ... ... ... """), indent=4)) Module( body=[ Match( subject=Name(id='x', ctx=Load()), cases=[ match_case( pattern=MatchSequence( patterns=[ MatchValue( value=Constant(value=1)), MatchValue( value=Constant(value=2))]), body=[ Expr( value=Constant(value=Ellipsis))])])], type_ignores=[])
- class ast.MatchStar(name)¶
Matches the rest of the sequence in a variable length match sequence pattern. If
name
is notNone
, a list containing the remaining sequence elements is bound to that name if the overall sequence pattern is successful.>>> print(ast.dump(ast.parse(""" ... match x: ... case [1, 2, *rest]: ... ... ... case [*_]: ... ... ... """), indent=4)) Module( body=[ Match( subject=Name(id='x', ctx=Load()), cases=[ match_case( pattern=MatchSequence( patterns=[ MatchValue( value=Constant(value=1)), MatchValue( value=Constant(value=2)), MatchStar(name='rest')]), body=[ Expr( value=Constant(value=Ellipsis))]), match_case( pattern=MatchSequence( patterns=[ MatchStar()]), body=[ Expr( value=Constant(value=Ellipsis))])])], type_ignores=[])
- class ast.MatchMapping(keys, patterns, rest)¶
A match mapping pattern.
keys
is a sequence of expression nodes.patterns
is a corresponding sequence of pattern nodes.rest
is an optional name that can be specified to capture the remaining mapping elements. Permitted key expressions are restricted as described in the match statement documentation.This pattern succeeds if the subject is a mapping, all evaluated key expressions are present in the mapping, and the value corresponding to each key matches the corresponding subpattern. If
rest
is notNone
, a dict containing the remaining mapping elements is bound to that name if the overall mapping pattern is successful.>>> print(ast.dump(ast.parse(""" ... match x: ... case {1: _, 2: _}: ... ... ... case {**rest}: ... ... ... """), indent=4)) Module( body=[ Match( subject=Name(id='x', ctx=Load()), cases=[ match_case( pattern=MatchMapping( keys=[ Constant(value=1), Constant(value=2)], patterns=[ MatchAs(), MatchAs()]), body=[ Expr( value=Constant(value=Ellipsis))]), match_case( pattern=MatchMapping(keys=[], patterns=[], rest='rest'), body=[ Expr( value=Constant(value=Ellipsis))])])], type_ignores=[])
- class ast.MatchClass(cls, patterns, kwd_attrs, kwd_patterns)¶
A match class pattern.
cls
is an expression giving the nominal class to be matched.patterns
is a sequence of pattern nodes to be matched against the class defined sequence of pattern matching attributes.kwd_attrs
is a sequence of additional attributes to be matched (specified as keyword arguments in the class pattern),kwd_patterns
are the corresponding patterns (specified as keyword values in the class pattern).This pattern succeeds if the subject is an instance of the nominated class, all positional patterns match the corresponding class-defined attributes, and any specified keyword attributes match their corresponding pattern.
Note: classes may define a property that returns self in order to match a pattern node against the instance being matched. Several builtin types are also matched that way, as described in the match statement documentation.
>>> print(ast.dump(ast.parse(""" ... match x: ... case Point2D(0, 0): ... ... ... case Point3D(x=0, y=0, z=0): ... ... ... """), indent=4)) Module( body=[ Match( subject=Name(id='x', ctx=Load()), cases=[ match_case( pattern=MatchClass( cls=Name(id='Point2D', ctx=Load()), patterns=[ MatchValue( value=Constant(value=0)), MatchValue( value=Constant(value=0))], kwd_attrs=[], kwd_patterns=[]), body=[ Expr( value=Constant(value=Ellipsis))]), match_case( pattern=MatchClass( cls=Name(id='Point3D', ctx=Load()), patterns=[], kwd_attrs=[ 'x', 'y', 'z'], kwd_patterns=[ MatchValue( value=Constant(value=0)), MatchValue( value=Constant(value=0)), MatchValue( value=Constant(value=0))]), body=[ Expr( value=Constant(value=Ellipsis))])])], type_ignores=[])
- class ast.MatchAs(pattern, name)¶
A match “as-pattern”, capture pattern or wildcard pattern.
pattern
contains the match pattern that the subject will be matched against. If the pattern isNone
, the node represents a capture pattern (i.e a bare name) and will always succeed.The
name
attribute contains the name that will be bound if the pattern is successful. Ifname
isNone
,pattern
must also beNone
and the node represents the wildcard pattern.>>> print(ast.dump(ast.parse(""" ... match x: ... case [x] as y: ... ... ... case _: ... ... ... """), indent=4)) Module( body=[ Match( subject=Name(id='x', ctx=Load()), cases=[ match_case( pattern=MatchAs( pattern=MatchSequence( patterns=[ MatchAs(name='x')]), name='y'), body=[ Expr( value=Constant(value=Ellipsis))]), match_case( pattern=MatchAs(), body=[ Expr( value=Constant(value=Ellipsis))])])], type_ignores=[])
- class ast.MatchOr(patterns)¶
A match “or-pattern”. An or-pattern matches each of its subpatterns in turn to the subject, until one succeeds. The or-pattern is then deemed to succeed. If none of the subpatterns succeed the or-pattern fails. The
patterns
attribute contains a list of match pattern nodes that will be matched against the subject.>>> print(ast.dump(ast.parse(""" ... match x: ... case [x] | (y): ... ... ... """), indent=4)) Module( body=[ Match( subject=Name(id='x', ctx=Load()), cases=[ match_case( pattern=MatchOr( patterns=[ MatchSequence( patterns=[ MatchAs(name='x')]), MatchAs(name='y')]), body=[ Expr( value=Constant(value=Ellipsis))])])], type_ignores=[])
Function and class definitions¶
- class ast.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 outermost first (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.
- class ast.Lambda(args, body)¶
lambda
is a minimal function definition that can be used inside an expression. 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=[])
- class ast.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. If one isNone
, the corresponding argument is required.defaults
is a list of default values for arguments that can be passed positionally. If there are fewer defaults, they correspond to the last n arguments.
- class ast.arg(arg, annotation, type_comment)¶
A single argument in a list.
arg
is a raw string of the argument name,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=[])
- class ast.Return(value)¶
A
return
statement.>>> print(ast.dump(ast.parse('return 4'), indent=4)) Module( body=[ Return( value=Constant(value=4))], type_ignores=[])
- class ast.Yield(value)¶
- class ast.YieldFrom(value)¶
A
yield
oryield from
expression. Because these are expressions, they must 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=[])
- class ast.Global(names)¶
- class ast.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=[])
- class ast.ClassDef(name, bases, keywords, body, decorator_list)¶
A class definition.
name
is a raw string for the class namebases
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 per PEP-3115.body
is a list of nodes representing the code within the class definition.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¶
- class ast.AsyncFunctionDef(name, args, body, decorator_list, returns, type_comment)¶
An
async def
function definition. Has the same fields asFunctionDef
.
- class ast.Await(value)¶
An
await
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=[])
- class ast.AsyncFor(target, iter, body, orelse, type_comment)¶
- class ast.AsyncWith(items, body, type_comment)¶
async for
loops andasync with
context managers. They have the same fields asFor
andWith
, respectively. Only valid in the body of anAsyncFunctionDef
.
Nota
When a string is parsed by ast.parse()
, operator nodes (subclasses
of ast.operator
, ast.unaryop
, ast.cmpop
,
ast.boolop
and ast.expr_context
) on the returned tree
will be singletons. Changes to one will be reflected in all other
occurrences of the same value (e.g. ast.Add
).
Auxiliares de ast
¶
Além das classes de nós, o módulo ast
define essas funções e classes utilitárias para percorrer árvores de sintaxe abstrata:
- ast.parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None)¶
Analisa a fonte em um nó AST. Equivalente a
compile(source, filename, mode, ast.PyCF_ONLY_AST)
.Se
type_comments=True
é fornecido, o analisador é modificado para verificar e retornar comentários do tipo, conforme especificado por PEP 484 e PEP 526. Isso é equivalente a adicionarast.PyCF_TYPE_COMMENTS
aos sinalizadores passados paracompile()
. Isso relatará erros de sintaxe para comentários do tipo extraviado. Sem esse sinalizador, os comentários do tipo serão ignorados e o campotype_comment
nos nós AST selecionados sempre seráNone
. Além disso, os locais dos comentários# type: ignore
serão retornados como o atributotype_ignores
deModule
(caso contrário, é sempre uma lista vazia).Além disso, se
mode
for'func_type'
, a sintaxe de entrada é modificada para corresponder a “comentários de tipo de assinatura” de PEP 484, por exemplo,(str, int) -> List[str]
.Além disso, definir
feature_version
como uma tupla(maior, menor)
tentará analisar usando a gramática dessa versão do Python. Atualmente,maior
deve ser igual a3
. Por exemplo, definirfeature_version=(3, 4)
permitirá o uso deasync
ewaitit
como nomes de variáveis. A versão mais baixa suportada é(3, 4)
; a mais alta ésys.version_info[0:2]
.If source contains a null character (’0’),
ValueError
is raised.Aviso
Note that successfully parsing source code into an AST object doesn’t guarantee that the source code provided is valid Python code that can be executed as the compilation step can raise further
SyntaxError
exceptions. For instance, the sourcereturn 42
generates a valid AST node for a return statement, but it cannot be compiled alone (it needs to be inside a function node).In particular,
ast.parse()
won’t do any scoping checks, which the compilation step does.Aviso
É possível travar o interpretador Python com uma string suficientemente grande/complexa devido às limitações de profundidade da pilha no compilador de AST do Python.
Alterado na versão 3.8: Adicionado
type_comments
,mode='func_type'
efeature_version
.
- ast.unparse(ast_obj)¶
Unparse an
ast.AST
object and generate a string with code that would produce an equivalentast.AST
object if parsed back withast.parse()
.Aviso
The produced code string will not necessarily be equal to the original code that generated the
ast.AST
object (without any compiler optimizations, such as constant tuples/frozensets).Aviso
Trying to unparse a highly complex expression would result with
RecursionError
.Novo na versão 3.9.
- ast.literal_eval(node_or_string)¶
Evaluate an expression node or a string containing only a Python literal or container display. The string or node provided may only consist of the following Python literal structures: strings, bytes, numbers, tuples, lists, dicts, sets, booleans,
None
andEllipsis
.This can be used for evaluating strings containing Python values without the need to parse the values oneself. It is not capable of evaluating arbitrarily complex expressions, for example involving operators or indexing.
This function had been documented as “safe” in the past without defining what that meant. That was misleading. This is specifically designed not to execute Python code, unlike the more general
eval()
. There is no namespace, no name lookups, or ability to call out. But it is not free from attack: A relatively small input can lead to memory exhaustion or to C stack exhaustion, crashing the process. There is also the possibility for excessive CPU consumption denial of service on some inputs. Calling it on untrusted data is thus not recommended.Aviso
It is possible to crash the Python interpreter due to stack depth limitations in Python’s AST compiler.
It can raise
ValueError
,TypeError
,SyntaxError
,MemoryError
andRecursionError
depending on the malformed input.Alterado na versão 3.2: Agora permite bytes e literais de conjuntos.
Alterado na versão 3.9: Now supports creating empty sets with
'set()'
.Alterado na versão 3.10: For string inputs, leading spaces and tabs are now stripped.
- ast.get_docstring(node, clean=True)¶
Retorna a docstring do node dado (que deve ser um nó
FunctionDef
,AsyncFunctionDef
,ClassDef
ouModule
) ouNone
se não tiver uma docstring. Se clean for verdadeiro, limpa o recuo da docstring cominspect.cleandoc()
.Alterado na versão 3.5: Não há suporte a
AsyncFunctionDef
.
- ast.get_source_segment(source, node, *, padded=False)¶
Obtém o segmento de código-fonte de source que gerou node. Se algumas informações de local (
lineno
,end_lineno
,col_offset
ouend_col_offset
) estiverem faltando, retornaNone
.Se padded for
True
, a primeira linha de uma instrução multilinha será preenchida com espaços para corresponder à sua posição original.Novo na versão 3.8.
- ast.fix_missing_locations(node)¶
Quando você compila uma árvore de nós com
compile()
, o compilador espera atributoslineno
ecol_offset
para cada nó que os suporta. Isso é tedioso para preencher nós gerados, portanto, esse auxiliar adiciona esses atributos recursivamente, onde ainda não estão definidos, definindo-os para os valores do nó pai. Ele funciona recursivamente a partir do node.
- ast.increment_lineno(node, n=1)¶
Incrementa o número da linhas e o número da linha final de cada nó na árvore começando em node em n. Isso é útil para “mover código” para um local diferente em um arquivo.
- ast.copy_location(new_node, old_node)¶
Copia o local de origem (
lineno
,col_offset
,end_lineno
eend_col_offset
) de old_node para new_node se possível e, então, retorna new_node.
- ast.iter_fields(node)¶
Produz uma tupla de
(fieldname, value)
para cada campo emnode._fields
que esteja presente em node.
- ast.iter_child_nodes(node)¶
Produz todos os nós filhos diretos de node, ou seja, todos os campos que são nós e todos os itens de campos que são listas de nós.
- ast.walk(node)¶
Produz recursivamente todos os nós descendentes na árvore começando em node (incluindo o próprio node), em nenhuma ordem especificada. Isso é útil se você quiser apenas modificar nós no lugar e não se importar com o contexto.
- class ast.NodeVisitor¶
Uma classe base de visitante de nó que percorre a árvore de sintaxe abstrata e chama uma função de visitante para cada nó encontrado. Esta função pode retornar um valor que é encaminhado pelo método
visit()
.Esta classe deve ser uma subclasse, com a subclasse adicionando métodos visitantes.
- visit(node)¶
Visita um nó. A implementação padrão chama o método chamado
self.visit_nomedaclasse
sendo nomedaclasse o nome da classe do nó, ougeneric_visit()
se aquele método não existir.
- generic_visit(node)¶
Este visitante chama
visit()
em todos os filhos do nó.Observe que nós filhos de nós que possuem um método de visitante personalizado não serão visitados, a menos que o visitante chame
generic_visit()
ou os visite por conta própria.
Não use o
NodeVisitor
se você quiser aplicar mudanças nos nós durante a travessia. Para isso existe um visitante especial (NodeTransformer
) que permite modificações.Obsoleto desde a versão 3.8: Os métodos
visit_Num()
,visit_Str()
,visit_Bytes()
,visit_NameConstant()
evisit_Ellipsis()
estão agora descontinuados e não serão chamados em futuras versões do Python. Adicione um métodovisit_Constant()
para lidar com nós de constantes.
- class ast.NodeTransformer¶
A subclasse
NodeVisitor
que percorre a árvore de sintaxe abstrata e permite a modificação de nós.O
NodeTransformer
percorrerá a AST e usará o valor de retorno dos métodos do visitante para substituir ou remover o nó antigo. Se o valor de retorno do método visitante forNone
, o nó será removido de seu local, caso contrário, ele será substituído pelo valor de retorno. O valor de retorno pode ser o nó original, caso em que não há substituição.Aqui está um exemplo de transformador que rescreve todas as ocorrências de procuras por nome (
foo
) paradata['foo']
:class RewriteName(NodeTransformer): def visit_Name(self, node): return Subscript( value=Name(id='data', ctx=Load()), slice=Constant(value=node.id), ctx=node.ctx )
Tenha em mente que, se o nó em que você está operando tiver nós filhos, você deve transformar os nós filhos por conta própria ou chamar o método
generic_visit()
para o nó primeiro.Para nós que faziam parte de uma coleção de instruções (que se aplica a todos os nós de instrução), o visitante também pode retornar uma lista de nós em vez de apenas um único nó.
Se
NodeTransformer
introduz novos nós (que não faziam parte da árvore original) sem fornecer informações de localização (comolineno
),fix_missing_locations()
deve ser chamado com o novo subárvore para recalcular as informações de localização:tree = ast.parse('foo', mode='eval') new_tree = fix_missing_locations(RewriteName().visit(tree))
Normalmente você usa o transformador assim:
node = YourTransformer().visit(node)
- ast.dump(node, annotate_fields=True, include_attributes=False, *, indent=None)¶
Retorne um despejo formatado da árvore em node. Isso é útil principalmente para fins de depuração. Se annotate_fields for verdadeiro (por padrão), a sequência retornada mostrará os nomes e os valores para os campos. Se annotate_fields for falso, a sequência de resultados será mais compacta ao omitir nomes de campos não ambíguos. Atributos como números de linha e deslocamentos de coluna não são despejados por padrão. Se isso for desejado, include_attributes pode ser definido como verdadeiro.
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
(the default) 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.Alterado na versão 3.9: Added the indent option.
Compiler Flags¶
The following flags may be passed to compile()
in order to change
effects on the compilation of a program:
- ast.PyCF_ALLOW_TOP_LEVEL_AWAIT¶
Enables support for top-level
await
,async for
,async with
and async comprehensions.Novo na versão 3.8.
- ast.PyCF_ONLY_AST¶
Generates and returns an abstract syntax tree instead of returning a compiled code object.
Uso da linha de comando¶
Novo na versão 3.9.
The ast
module can be executed as a script from the command line.
It is as simple as:
python -m ast [-m <mode>] [-a] [infile]
As seguintes opções são aceitas:
- -h, --help¶
Show the help message and exit.
- -m <mode>¶
- --mode <mode>¶
Specify what kind of code must be compiled, like the mode argument in
parse()
.
- --no-type-comments¶
Don’t parse type comments.
- -a, --include-attributes¶
Include attributes such as line numbers and column offsets.
If infile
is specified its contents are parsed to AST and dumped
to stdout. Otherwise, the content is read from stdin.
Ver também
Green Tree Snakes, um recurso de documentação externo, possui bons detalhes sobre trabalhar com ASTs do Python.
ASTTokens annotates Python ASTs with the positions of tokens and text in the source code that generated them. This is helpful for tools that make source code transformations.
leoAst.py unifies the token-based and parse-tree-based views of python programs by inserting two-way links between tokens and ast nodes.
LibCST parses code as a Concrete Syntax Tree that looks like an ast tree and keeps all formatting details. It’s useful for building automated refactoring (codemod) applications and linters.
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.