# `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)

              | Raise(expr? exc, expr? cause)
              | Try(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)

        withitem = (expr context_expr, expr? optional_vars)

        type_ignore = TypeIgnore(int lineno, string tag)
    }

## Classes de nó

class `ast.``AST`

  Esta é a base de todas as classes de nós AST. As classes de nós reais são derivadas do arquivo `Parser/Python.asdl`, o qual é reproduzido abaixo. Elas são definidas no módulo C `_ast` e reexportadas em `ast`.

  Há uma classe definida para cada símbolo do lado esquerdo na gramática abstrata (por exemplo, `ast.stmt` ou `ast.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 de `ast.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 atributo `left` do tipo `ast.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 com `compile()`.

  `lineno`
  `col_offset`
  `end_lineno`
  `end_col_offset`

    Instances of `ast.expr` and `ast.stmt` subclasses have `lineno`, `col_offset`, `end_lineno`, and `end_col_offset` attributes. The `lineno` and `end_lineno` are the first and last line numbers of the source text span (1-indexed so the first line is line 1), and the `col_offset` and `end_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 usar

      node = 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.

### Literais

class `ast.``Constant`(value)

  A constant value. The `value` attribute of the `Constant` literal contains the Python object it represents. The values represented can be simple types such as a number, string or `None`, 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 formatting

    - 114: `!r` repr formatting

    - 97: `!a` ascii formatting

  - `format_spec` is a `JoinedStr` 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.

class `ast.``JoinedStr`(values)

  An f-string, comprising a series of `FormattedValue` and `Constant` 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` is `Store` if the container is an assignment target (i.e. `(x,y)=something`), and `Load` 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` 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`.

      >>> 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, and `ctx` 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 a `Name` node. This type must be used when building a `Call` 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, a `Constant`, a `Name`, a `Lambda`, a `Yield` or `YieldFrom` 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, and `operand` any expression node.

class `ast.``UAdd`
class `ast.``USub`
class `ast.``Not`
class `ast.``Invert`

  Unary operator tokens. `Not` is the `not` 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, and `left` and `right` 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` is `Or` or `And`. `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`.

      >>> 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.``And`
class `ast.``Or`

  Boolean operator tokens.

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, and `comparators` 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, starargs, kwargs)

  A function call. `func` is the function, which will often be a `Name` or `Attribute` object. Of the arguments:

  - `args` holds a list of the arguments passed by position.

  - `keywords` holds a list of `keyword` objects representing arguments passed by keyword.

  When creating a `Call` node, `args` and `keywords` are required, but they can be empty lists. `starargs` and `kwargs` 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()))]))

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 are `Name` 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 a `Name`. `attr` is a bare string giving the name of the attribute, and `ctx` is `Load`, `Store` or `Del` 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 both `target` and `value` 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 a `Tuple` and contain a `Slice`. `ctx` is `Load`, `Store` or `Del` 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` or `lower:upper:step`). Can occur only inside the slice field of `Subscript`, either directly or as an element of `Tuple`.

      >>> 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` (or `key` and `value`) is a single node representing the part that will be evaluated for each item.

  `generators` is a list of `comprehension` 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 a `Name` or `Tuple` 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).

      >>> 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, and `value` is a single node.

  Multiple nodes in `targets` represents assigning the same value to each. Unpacking is represented by putting a `Tuple` or `List` within `targets`.

  `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 a `Name`, a `Attribute` or a `Subscript`. `annotation` is the annotation, such as a `Constant` or `Name` node. `value` is a single optional node. `simple` is a boolean integer set to True for a `Name` node in `target` 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 a `Name` node for `x` (with the `Store` context), `op` is `Add`, and `value` is a `Constant` with value for 1.

  The `target` attribute connot be of class `Tuple` or `List`, unlike the targets of `Assign`.

      >>> 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 a `Call` or `Name`, or `None` for a standalone `raise`. `cause` is the optional part for `y` in `raise 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 a `Compare` 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 as `Name`, `Attribute` or `Subscript` 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 of `alias` 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, or `None` for statements such as `from . 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 be `None` 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 a `Compare` 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` nodes within the `orelse` 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 single `Name`, `Tuple` or `List` 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.

  `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 a `Compare` 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` and `continue` 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 for `handlers`, which is a list of `ExceptHandler` 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.``ExceptHandler`(type, name, body)

  A single `except` clause. `type` is the exception type it will match, typically a `Name` 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.

      >>> 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 of `withitem` nodes representing the context managers, and `body` 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 a `Call` node. `optional_vars` is a `Name`, `Tuple` or `List` for the `as foo` part, or `None` 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=[])

### 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 an `arguments` 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. Unlike `FunctionDef`, `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` and `kwonlyargs` are lists of `arg` nodes.

  - `vararg` and `kwarg` are single `arg` nodes, referring to the `*args, **kwargs` parameters.

  - `kw_defaults` is a list of default values for keyword-only arguments. If one is `None`, 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 a `Str` or `Name` 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` or `yield from` expression. Because these are expressions, they must be wrapped in a `Expr` 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` and `nonlocal` 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, 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 of `keyword` nodes, principally for ‘metaclass’. Other keywords will be passed to the metaclass, as per PEP-3115.

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

  - `body` is a list of nodes representing the code within the class definition.

  - `decorator_list` is a list of nodes, as in `FunctionDef`.

      >>> 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 as `FunctionDef`.

class `ast.``Await`(value)

  An `await` expression. `value` is what it waits for. Only valid in the body of an `AsyncFunctionDef`.

    >>> 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 and `async with` context managers. They have the same fields as `For` and `With`, respectively. Only valid in the body of an `AsyncFunctionDef`.

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 adicionar `ast.PyCF_TYPE_COMMENTS` aos sinalizadores passados para `compile() `. Isso relatará erros de sintaxe para comentários do tipo extraviado. Sem esse sinalizador, os comentários do tipo serão ignorados e o campo ``type_comment`()` nos nós AST selecionados sempre será `None`. Além disso, os locais dos comentários `# type: ignore` serão retornados como o atributo `type_ignores` de `Module` (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 a `3`. Por exemplo, definir `feature_version=(3, 4)` permitirá o uso de `async` e `waitit` 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 source `return 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'` e `feature_version`.

`ast.``unparse`(ast_obj)

  Unparse an `ast.AST` object and generate a string with code that would produce an equivalent `ast.AST` object if parsed back with `ast.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)

  Avalia com segurança um nó de expressão ou uma string contendo um literal Python ou exibição de contêiner. A string ou o nó fornecido pode consistir apenas nas seguintes estruturas literais de Python: strings, bytes, números, tuplas, listas, dicts, conjuntos, booleanos e `None`.

  Isso pode ser usado para avaliar com segurança strings contendo valores Python de fontes não confiáveis sem a necessidade de analisar os valores por si próprio. Não é capaz de avaliar expressões arbitrariamente complexas, por exemplo, envolvendo operadores ou indexação.

  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.2: Agora permite bytes e literais de conjuntos.

  Alterado na versão 3.9: Now supports creating empty sets with `'set()'`.

`ast.``get_docstring`(node, clean=True)

  Retorna a docstring do node dado (que deve ser um nó `FunctionDef`, `AsyncFunctionDef`, `ClassDef` ou `Module`) ou `None` se não tiver uma docstring. Se clean for verdadeiro, limpa o recuo da docstring com `inspect.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` ou `end_col_offset`) estiverem faltando, retorna `None`.

  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 atributos `lineno` e `col_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` e `end_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 em `node._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ó, ou `generic_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()` e `visit_Ellipsis()` estão agora descontinuados e não serão chamados em futuras versões do Python. Adicione um método `visit_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 for `None`, 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`) para `data['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 (como `lineno`), `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.

`ast.``PyCF_TYPE_COMMENTS`

  Enables support for PEP 484 and PEP 526 style type comments (`# type: <type>`, `# type: ignore <stuff>`).

  Novo na versão 3.8.

## 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.

`-i``<indent>`
`--indent``<indent>`

  Indentation of nodes in AST (number of spaces).

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.