# `ast` — Arbres Syntaxiques Abstraits

Code source : Lib/ast.py

Le module `ast` permet aux applications Python de traiter la grammaire abstraite de l'arbre syntaxique Python. La grammaire abstraite Python elle-même est susceptible d'être modifiée à chaque nouvelle version de Python; ce module permet de trouver à quoi la grammaire actuelle ressemble.

Un arbre syntaxique abstrait peut être généré en passant l'option `ast.PyCF_ONLY_AST` à la fonction native `compile()`, ou en utilisant la fonction de facilité `parse()` fournie par le module. Le résultat est un arbre composé d'objets dont les classes héritent toutes de `ast.AST`. Un arbre syntaxique abstrait peut être compilé en code objet Python en utilisant la fonction native `compile()`.

## Grammaire abstraite

La grammaire abstraite est actuellement définie comme suit :

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

## Les classes nœud

class `ast.``AST`

  C'est la classe de base de toute classe nœud de l'AST. Les classes nœud courantes sont dérivées du fichier `Parser/Python.asdl`, qui est reproduit ci-dessous. Ils sont définis dans le module C `_ast` et ré-exportés dans le module `ast`.

  Il y a une classe définie pour chacun des symboles présents à gauche dans la grammaire abstraite (par exemple, `ast.stmt` ou `ast.expr`). En plus de cela, il y a une classe définie pour chacun des constructeurs présentés à droite; ces classes héritent des classes situées à gauche dans l'arbre. Par exemple, la classe `ast.BinOp` hérite de la classe `ast.expr`. Pour les règles de réécriture avec alternatives (comme sums), la partie gauche est abstraite : seules les instances des constructeurs spécifiques aux nœuds sont créés.

  `_fields`

    Chaque classe concrète possède un attribut `_fields` donnant les noms de tous les nœuds enfants.

    Chaque instance d'une classe concrète possède un attribut pour chaque nœud enfant, du type défini par la grammaire. Par exemple, les instances `ast.BinOp` possèdent un attribut `left` de type `ast.expr`.

    Si ces attributs sont marqués comme optionnels dans la grammaire (en utilisant un point d'interrogation `?`), la valeur peut être `None`. Si les attributs peuvent avoir zéro ou plus valeurs (marqués avec un astérisque `*`), les valeurs sont représentées par des listes Python. Tous les attributs possibles doivent être présents et avoir une valeur valide pour compiler un AST avec `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.

    Les décalages end… ne sont pas obligatoires ni nécessaires au compilateur. end_col_offset pointe après le dernier lexème. On peut donc obtenir la partie du code source ayant donné lieu à une expression avec `ligne_source[nœud.col_offset : nœud.end_col_offset]`.

  Le constructeur d'une classe `ast.T` analyse ses arguments comme suit :

  - S'il y a des arguments positionnels, il doit y avoir autant de termes dans `T._fields`; ils sont assignés comme attributs portant ces noms.

  - S'il y a des arguments nommés, ils définissent les attributs de mêmes noms avec les valeurs données.

  Par exemple, pour créer et peupler un nœud `ast.UnaryOp`, on peut utiliser

      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, plus compact

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

Modifié dans la version 3.8: toutes les constantes sont désormais représentées par des instances de `ast.Constant`.

Modifié dans la version 3.9: Simple indices are represented by their value, extended slices are represented as tuples.

Obsolète depuis la version 3.8: les classes `ast.Num`, `ast.Str`, `ast.Bytes`, `ast.NameConstant` et `ast.Ellipsis` sont toujours présentes, mais seront supprimées dans une version future. Pour l'instant, leurs constructeurs renvoient des instances de classes différentes.

Obsolète depuis la version 3.9: les classes `ast.Index` et `ast.ExtSlice` seront retirées à l'avenir. Pour l'instant, elles sont toujours disponibles mais leurs constructeurs renvoient des instances de classes différentes.

Note

Les descriptions individuelles des classes de nœuds dans la prochaine section sont au départ adaptées du merveilleux projet Green Tree Snakes, porté par de nombreux contributeurs.

### Littéraux

class `ast.``Constant`(value)

  Valeur constante, contenue dans le champ value. Les valeurs possibles sont celles de types simples comme les nombres, les chaînes de caractères, ou encore `None`, mais aussi certains conteneurs immuables (n-uplets et ensembles figés) lorsque tous leurs éléments sont constants.

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

class `ast.``FormattedValue`(value, conversion, format_spec)

  Champ de formatage dans une chaîne littérale formatée (f-string). Ce nœud peut être isolé si la chaîne contient un unique champ et rien d'autre. Sinon, il apparaît dans `JoinedStr`.

  - value est un nœud d'expression quelconque (comme un littéral, une variable, ou encore un appel de fonction).

  - conversion est un entier parmi les valeurs suivantes :

    - -1, aucun formatage ;

    - 115, pour le formatage par `str()` correspondant à `!s` ;

    - 114, pour le formatage par `repr()` correspondant à `!r` ;

    - 97, pour le formatage par `ascii()` correspondant à `!a`.

  - format_spec est un nœud `JoinedStr` qui précise la manière de formater la valeur. Si aucun formatage particulier n'a été donné, format_spec vaut `None`. conversion et format_spec peuvent tout à fait coexister.

class `ast.``JoinedStr`(values)

  Chaîne littérale formatée (f-string), qui contient une liste de nœuds `FormattedValue` et `Constant`.

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

  Liste ou n-uplet, dont les éléments sont rassemblés dans la liste elts. ctx est une instance de `Store` si la liste ou le n-uplet est la cible d'une affectation (par exemple `(x, y) = quelque_chose`). Sinon, c'est une instance de `Load`.

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

  Ensemble. elts est la liste de ses éléments.

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

  Dictionnaire. Les listes keys et values contiennent respectivement les clés et les valeurs. Leurs ordres se correspondent, c'est-à-dire que la valeur associée à l'élément d'indice i dans keys est à chercher à l'indice i de values. keys et values sont donc des équivalents à `dictionnaire.keys()` et `dictionnaire.values()`.

  Si un dictionnaire littéral contient une expression doublement étoilée à déballer, elle est intégrée dans values, et `None` est mis à la place correspondante dans 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)

  Variable, dont le nom est id (une chaîne de caractères). ctx est de l'un des trois types :

class `ast.``Load`
class `ast.``Store`
class `ast.``Del`

  Ces types de contexte distinguent les variables selon qu'elles sont utilisées pour lire la valeur, mettre la variable à une nouvelle valeur, ou supprimer la variable.

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

  Élément étoilé. value est le nœud auquel s'applique l'étoile. Le plus souvent, value est une instance de `Name`. Ce type est notamment nécessaire pour les appels de fonction avec déballage d'arguments (par exemple `fonction(*args)` ; voir aussi `Call`).

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

### Expressions

class `ast.``Expr`(value)

  Lorsque une expression, comme l'appel d'une fonction, apparaît comme une instruction à elle seule, sans que la valeur ne soit utilisée ou sauvegardée, l'expression est insérée dans ce conteneur. Le type de value peut être l'un des autres nœuds décrits dans cette section, ou bien parmi `Constant`, `Name`, `Lambda`, `Yield` et `YieldFrom`.

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

  Unité lexicale désignant une opération unaire. L'opérateur est op, l'opérande operand est un nœud d'expression quelconque.

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

  Unités lexicales désignant des opérations unaires. `Not` correspond au mot-clé `not`, `Invert` à l'opérateur `~`.

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

  Opération binaire (comme l'addition ou la division). L'opérateur est op, les opérandes left et right sont des nœuds d'expression quelconques.

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

  Unités lexicales pour les opérations binaires.

class `ast.``BoolOp`(op, values)

  Opération booléenne, c'est-à-dire `and` ou `or`, entre op et les éléments de values. Les deux opérateurs sont distingués par le type de op, à savoir `And` ou `Or`. Les applications successives du même opérateur (comme `a or b or c`) sont regroupées dans un nœud unique avec plusieurs éléments dans la liste values.

  L'opérateur `not` n'est pas implémenté ici, mais bien dans `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`

  Unités lexicales pour les opérations booléennes.

class `ast.``Compare`(left, ops, comparators)

  Comparaison de deux valeurs ou plus. left est le premier élément de la comparaison, ops la liste des opérateurs, et comparators la liste des éléments restants de la comparaison.

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

  Unités lexicales pour les comparaisons.

class `ast.``Call`(func, args, keywords, starargs, kwargs)

  Appel d'une fonction. Le nœud func, représentant la fonction appelée, est habituellement de type `Name` ou `Attribute`. Les arguments sont contenus dans :

  - args, la liste des arguments passés sans les nommer (arguments positionnels) ;

  - keywords, la liste des arguments nommés sous forme de nœuds `keyword`.

  Les arguments args et keywords du constructeur de `Call` sont obligatoires (mais peuvent être des listes vides). starargs (arguments étoilés) et kwargs (arguments nommés) sont facultatifs.

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

  Expression ternaire (`a if b else c`). Chaque champ contient un unique nœud. Dans l'exemple suivant, les trois sont de la classe `Name`.

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

  Accès à un attribut (comme `d.keys`). value est un nœud, souvent de la classe `Name`. attr est le nom de l'attribut, sous forme de chaîne de caractères. ctx est de classe `Load`, `Store` ou `Del` selon le type de l'action effectuée sur l'attribut.

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

  > Expression d'affectation. Ces nœuds proviennent de l'opérateur « morse » `:=`. Contrairement à `Assign`, dont le premier argument est une liste qui peut contenir plusieurs cibles, les arguments target et value sont ici des nœuds simples.

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

#### Indiçage

class `ast.``Subscript`(value, slice, ctx)

  Accès à un indice, par exemple `liste[1]`. value est l'objet où l'indice est pris, donc la plupart du temps une séquence ou une table associative. slice est soit un indice, soit une tranche, soit une clé. Les instances de `Tuple` pour slice peuvent contenir des objets `Slice`. ctx est de type `Load`, `Store` ou `Del` selon l'action appliquée à l'indice.

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

  Tranches normales (de la forme `début:fin` ou `début:fin:pas`). Les instances de cette classe ne peuvent apparaître que dans le champ slice d'un `Subscript`, que ce soit directement ou en tant qu'élément d'un `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()))

#### Compréhensions

class `ast.``ListComp`(elt, generators)
class `ast.``SetComp`(elt, generators)
class `ast.``GeneratorExp`(elt, generators)
class `ast.``DictComp`(key, value, generators)

  Liste, ensemble ou dictionnaire en compréhension, ou expression génératrice. elt est l'expression avant le premier `for`, évaluée à chaque itération. Il est remplacé par key (expression pour la clé) et value (expression pour la valeur) dans le cas des dictionnaires.

  generators est une liste de nœuds `comprehension`.

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

  Une clause `for` à l'intérieur d'une compréhension. iter est l'objet à parcourir, target est la cible de l'affectation qui se produit à chaque itération (la plupart du temps un nœud `Name` ou `Tuple`). ifs contient les tests qui décident si l'élément doit être inséré. C'est une liste, car chaque `for` peut être suivi de plusieurs `if`.

  is_async est une valeur booléenne sous forme d'entier, 0 ou 1, qui indique si la compréhension est asynchrone, c'est-à-dire qu'elle a été écrite avec `async for` au lieu de `for`.

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

### Instructions

class `ast.``Assign`(targets, value, type_comment)

  Affectation. targets est une liste de nœuds, value est simplement un nœud.

  S'il y a plusieurs nœuds dans targets, ils sont tous pris comme des cibles auxquelles est affectée la même expression. Le déballage de séquences est représenté par des nœuds `Tuple` ou `List` comme éléments de targets.

  `type_comment`

    Le champ facultatif type_comment contient une annotation de type fournie par un commentaire, et ce sous la forme d'une chaîne de caractères.

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

  Affectation accompagnée d'une annotation de type. La cible target est un nœud de type `Name`, `Attribute` ou `Subscript`. annotation est le contenu de l'annotation, par exemple un nœud `Constant` ou `Name`. Le champ value est facultatif et peut contenir un nœud, la valeur affectée à la cible. simple est une valeur booléenne sous forme d'entier, 0 ou 1, qui vaut 1 si et seulement si target est de type `Name` et provient d'un nom sans parenthèses, donc un nom simple plutôt qu'une expression.

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

  Affectation incrémentale, par exemple `a += 1`. Dans l'exemple qui suit, target est un nœud de type `Name` avec le nom `'x'` (de contexte `Store`), op est une instance de `Add`, et value est un nœud `Constant` contenant la valeur 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)

  Instruction `raise`. exc est l'exception à lever, la plupart du temps un nœud de type `Call` ou `Name`. Ce champ vaut `None` dans le cas d'un `raise` sans rien d'autre. Le champ facultatif cause correspond à la partie après le `from` dans `raise ... from ...`.

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

  Assertion. test est la condition, par exemple un nœud `Compare`. msg est le message d'erreur affiché si le test s'évalue comme faux.

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

  Instruction `del`. Les éléments à supprimer sont rassemblés dans la liste target. Ce sont généralement des nœuds de type `Name`, `Attribute` ou `Subscript`.

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

  Instruction `pass`.

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

Il existe d'autres instructions, qui ne peuvent apparaître que dans certains contextes spécifiques comme l'intérieur d'une fonction ou d'une boucle. Elles sont décrites dans d'autres sections de ce document.

#### Importations

class `ast.``Import`(names)

  Instruction `import`. names prend la forme d'une liste de nœuds `alias`.

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

  Instruction `from ... import ...`. La partie après `from` est mise dans module comme une simple chaîne de caractères. Dans le cas des importations relatives, comme `from ..module import quelque_chose`, module ne contient pas les points au début. Dans les instructions de la forme `from . import toto`, module vaut `None`. level est le niveau d'importation relative sous forme d'entier (0 pour les importations absolues).

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

  Correspond à `... as ...` dans une importation. name et asname sont de simples chaînes de caractères, qui correspondent aux deux parties de `... as ...`. Dans les instructions sans `as` (où le module n'est pas renommé), asname vaut `None`.

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

### Contrôle de l'exécution

Note

Si une clause facultative comme `else` est absente, le champ correspondant dans l'arbre est une liste vide.

class `ast.``If`(test, body, orelse)

  Instruction `if`. La condition, test, est un nœud, par exemple une instance de `Compare`. body est la liste des instructions du bloc. orelse contient les instructions dans le `else` (liste vide s'il n'y a pas de `else`).

  Les clauses `elif` ne possèdent pas de représentation particulière. Elles sont simplement mises dans le orelse du `if` ou `elif` précédent, comme nœuds de type `If`.

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

  Boucle `for`. Elle porte sur l'itérable donné par le nœud iter. La cible des affectations successives est target, qui est un nœud de type `Name`, `Tuple` ou `List`. Les instructions du bloc `for` forment la liste body. Celles de la liste orelse proviennent d'une éventuelle clause `else` et sont exécutées si la boucle se termine par épuisement de l'itérable, et non pas par un `break`.

  `type_comment`

    Le champ facultatif type_comment contient une annotation de type fournie par un commentaire, et ce sous la forme d'une chaîne de caractères.

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

  Boucle `while`. test est la condition évaluée à chaque itération, par exemple un nœud `Compare`. body contient les instructions du bloc, et orelse celles d'un éventuel bloc `else`, exécuté lorsque la boucle termine parce que la condition devient fausse et non pas à cause d'une instruction `break`.

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

  Instructions `break` et `continue`.

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

  Bloc `try`. Les nœuds de la liste body sont les instructions à exécuter sous contrôle des exceptions. La liste handlers contient des nœuds `ExceptHandler`, un par `except`. Les listes orelse et finalbody contiennent respectivement les instructions se trouvant dans d'éventuels blocs `else` et `finally`.

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

  Une clause `except`. Elle intercepte les exceptions de types donnés par type, qui est le plus souvent un nœud `Name` ou bien `None` (cette dernière valeur pour les clauses fourre-tout `except:`). Le nom éventuel de la variable à laquelle affecter l'exception est dans la chaîne de caractères name (`None` s'il n'y a pas de `as`). Les instructions sous le `except` sont dans la liste body.

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

  Bloc `with`. Les gestionnaires de contexte sont stockés dans items comme instances de `withitem`. Les instructions sous le `with` forment la liste body.

  `type_comment`

    Le champ facultatif type_comment contient une annotation de type fournie par un commentaire, et ce sous la forme d'une chaîne de caractères.

class `ast.``withitem`(context_expr, optional_vars)

  Gestionnaire de contexte dans un bloc `with`. Le gestionnaire est donné par le nœud context_expr, souvent une instance de `Call`. S'il y a affectation avec `as`, optional_vars contient sa cible, qui est un nœud de type `Name`, `Tuple` ou `List`. Sinon, optional_vars vaut `None`.

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

### Définition de fonctions et de classes

class `ast.``FunctionDef`(name, args, body, decorator_list, returns, type_comment)

  Définition d'une fonction.

  - name donne le nom de la fonction sous forme d'une chaîne de caractères.

  - `args` is an `arguments` node.

  - body est la liste des instructions dans le corps de la fonction.

  - decorators_list est une liste de décorateurs appliqués à la fonction. Ils sont rangés dans leur ordre d'apparition, c'est-à-dire que le premier de la liste est appliqué en dernier.

  - returns est l'annotation de renvoi éventuelle.

  `type_comment`

    Le champ facultatif type_comment contient une annotation de type fournie par un commentaire, et ce sous la forme d'une chaîne de caractères.

class `ast.``Lambda`(args, body)

  Fonction anonyme. Elle est créée avec le mot-clé `lambda`, limitée à renvoyer une simple expression, et peut être intégrée à une expression plus large. Contrairement à `FunctionDef`, body est ici un nœud unique. args est une instance de `arguments` qui contient les arguments de la signature.

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

  Arguments d'une fonction.

  - posonlyargs, args et kwonlyargs sont des listes de nœuds `arg` qui correspondent respectivement aux arguments obligatoirement positionnels, positionnels ou nommés et obligatoirement nommés.

  - varargs et kwargs sont des nœuds `arg` qui apparaissent avec la capture des arguments restants, positionnels (`*arguments_positionnels`) et nommés (`**arguments_nommés`).

  - kw_defaults est la liste des valeurs par défaut pour les arguments obligatoirement nommés. Si l'un des éléments n'est pas un nœud mais `None`, il n'y a pas de valeur par défaut et l'argument correspondant doit être passé obligatoirement à la fonction.

  - defaults est, quant à elle, la liste des valeurs par défauts pour les arguments qui peuvent être passés de manière positionnelle (obligatoirement ou non). S'il y a moins d'éléments dans la liste que d'arguments positionnels, ces éléments donnent les valeurs par défaut des n derniers arguments positionnels (avec n la longueur de defaults).

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`

    Le champ facultatif type_comment est, sous forme de chaîne, une annotation de type fournie par un commentaire.

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

  Instruction `return`, qui renvoie value.

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

  Expression `yield` ou `yield from`. Ce sont bien des expressions, non pas des instructions. Il faut donc les placer dans un nœud `Expr` si la valeur qu'elles renvoient n'est pas utilisée dans une expression plus large.

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

  Instruction `global` ou `nonlocal`. Elle s'applique aux noms de variables donnés dans names, une liste de chaînes de caractères.

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

  Définition d'une classe.

  - name est le nom de la classe sous forme de chaîne de caractères ;

  - bases est la liste des classes mères données explicitement ;

  - `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 est la liste des instructions contenues dans la définition de classe ;

  - decorators_list est une liste de nœuds, comme pour `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` et `await`

class `ast.``AsyncFunctionDef`(name, args, body, decorator_list, returns, type_comment)

  Fonction déclarée avec `async def`. Les champs sont les mêmes que dans `FunctionDef`.

class `ast.``Await`(value)

  Expression `await`, qui attend value. Ces nœuds ne peuvent apparaître qu'à l'intérieur de `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)

  Instruction `async for` ou `async with`. Les champs sont les mêmes que ceux de `For` et `With`. Ces nœuds ne peuvent apparaître qu'à l'intérieur de `AsyncFunctionDef`.

Note

Lorsqu'une chaîne contenant du code est transformée en arbre syntaxique par `ast.parse()`, les nœuds représentants les opérateurs (classes filles de `ast.operator`, `ast.unaryop`, `ast.cmpop`, `ast.boolop` et `ast.expr_context`) sont des singletons à l'intérieur de l'arbre renvoyé. Si l'un, par exemple une instance de `ast.Add`, est muté, la modification sera visible sur toutes les autres apparitions de l'opérateur.

## Outils du module `ast`

À part la classe nœud, le module `ast` définit ces fonctions et classes utilitaires pour traverser les arbres syntaxiques abstraits :

`ast.``parse`(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None)

  Analyse le code source en un nœud AST. Équivalent à `compile(source, filename, mode, ast.PyCF_ONLY_AST)`.

  Si type_comments est mis à `True`, l'analyseur syntaxique reconnaît les commentaires de type et les ajoute à l'arbre, comme décrit dans la PEP 484 et la PEP 526. Ceci revient à ajouter `ast.PyCF_TYPE_COMMENTS` à l'argument flags de `compile()`. Une erreur de syntaxe est levée si un commentaire de type est placé au mauvais endroit. Les commentaires `# type: ignore` sont également détectés et leurs positions dans la source sont placées dans l'attribut type_ignores du nœud `Module`. Sans cette option, les commentaires de type sont ignorés tout comme les commentaires ordinaires, et l'attribut type_comment des nœuds dont le type possède ce champ sera toujours mis à `None`.

  In addition, if `mode` is `'func_type'`, the input syntax is modified to correspond to PEP 484 "signature type comments", e.g. `(str, int) -> List[str]`.

  Si feature_version est défini à une version de Python, sous la forme d'un couple `(version_majeure, version_mineure)`, l'analyseur tentera de lire la source en se conformant à la syntaxe de cette version. Ainsi, avec `feature_version=(3, 4)`, les noms `async` et `await` peuvent nommer des variables. La version la plus ancienne prise en charge est actuellement `(3, 4)` ; la plus récente est `sys.version_info[0:2]`.

  If source contains a null character ('0'), `ValueError` is raised.

  > Avertissement

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

  Avertissement

  Il est possible de faire planter l'interpréteur Python avec des chaînes suffisamment grandes ou complexes lors de la compilation d'un objet AST dû à la limitation de la profondeur de la pile d'appels.

  Modifié dans la version 3.8: ajout des paramètres type_comments et feature_version ainsi que de la valeur `'func_type'` pour mode.

`ast.``unparse`(ast_obj)

  À partir d'un arbre syntaxique `ast.AST`, reconstruit un code sous forme de chaîne de caractères. S'il est passé à `ast.parse()`, le résultat produit un arbre `ast.AST` équivalent à l'original.

  Avertissement

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

  Avertissement

  Une `RecursionError` est levée si l'expression comporte de très nombreux niveaux d'imbrication.

  Nouveau dans la version 3.9.

`ast.``literal_eval`(node_or_string)

  Évalue de manière sûre un nœud expression ou une chaîne de caractères contenant une expression littérale Python ou un conteneur. La chaîne de caractères ou le nœud fourni peut seulement faire partie des littéraux Python suivants : chaînes de caractères, bytes, nombres, n-uplets, listes, dictionnaires, ensembles, booléens, et `None`.

  Cela peut être utilisé pour évaluer de manière sûre la chaîne de caractères contenant des valeurs Python de sources non fiable sans avoir besoin d'analyser les valeurs elles-mêmes. Cette fonction n'est pas capable d'évaluer des expressions complexes arbitraires, par exemple impliquant des opérateurs ou de l'indexation.

  Avertissement

  Il est possible de faire planter l'interpréteur Python avec des chaînes suffisamment grandes ou complexes lors de la compilation d'un objet AST dû à la limitation de la profondeur de la pile d'appels.

  Modifié dans la version 3.2: Accepte maintenant les littéraux suivants bytes et sets.

  Modifié dans la version 3.9: accepte `set()` pour les ensembles vides.

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

  Renvoie la docstring du node donné (qui doit être un nœud de type `FunctionDef`, `AsyncFunctionDef`, `ClassDef`, or `Module`), ou `None` s'il n'a pas de docstring. Si clean est vrai, cette fonction nettoie l'indentation de la docstring avec `inspect.cleandoc()`.

  Modifié dans la version 3.5: `AsyncFunctionDef` est maintenant gérée

`ast.``get_source_segment`(source, node, *, padded=False)

  Donne la partie de source (le code source) qui a donné lieu à node. Si l'un des attributs de localisation du nœud (`lineno`, `end_lineno`, `col_offset` et `end_col_offset`) n'est pas rempli, cette fonction renvoie `None`.

  If padded is `True`, the first line of a multi-line statement will be padded with spaces to match its original position.

  Nouveau dans la version 3.8.

`ast.``fix_missing_locations`(node)

  Lorsque l'on compile un arbre avec `compile()`, le compilateur attend les attributs `lineno` et `col_offset` pour tous les nœuds qui les supportent. Il est fastidieux de les remplir pour les nœuds générés, cette fonction utilitaire ajoute ces attributs de manière récursive là où ils ne sont pas déjà définis, en les définissant comme les valeurs du nœud parent. Elle fonctionne récursivement en démarrant de node.

`ast.``increment_lineno`(node, n=1)

  Incrémente de n les numéros des lignes de début et ligne de fin de chaque nœud dans l'arbre, en commençant par le nœud node. C'est utile pour « déplacer du code » à un endroit différent dans un fichier.

`ast.``copy_location`(new_node, old_node)

  Copie la position dans la source (attributs `lineno`, `col_offset`, `end_lineno` et `end_col_offset`) de l'ancien nœud old_node vers le nouveau nœud new_node, si possible, et renvoie new_node.

`ast.``iter_fields`(node)

  Produit un n-uplet de `(fieldname, value)` pour chaque champ de `node._fields` qui est présent dans node.

`ast.``iter_child_nodes`(node)

  Produit tous les nœuds enfants directs de node, c'est à dire, tous les champs qui sont des nœuds et tous les éléments des champs qui sont des listes de nœuds.

`ast.``walk`(node)

  Produit récursivement tous les nœuds enfants dans l'arbre en commençant par node (node lui-même est inclus), sans ordre spécifique. C'est utile lorsque l'on souhaite modifier les nœuds sur place sans prêter attention au contexte.

class `ast.``NodeVisitor`

  Classe de base pour un visiteur de nœud, qui parcourt l'arbre syntaxique abstrait et appelle une fonction de visite pour chacun des nœuds trouvés. Cette fonction peut renvoyer une valeur qui est transmise par la méthode `visit()`.

  Cette classe est faite pour être dérivée, en ajoutant des méthodes de visite à la sous-classe.

  `visit`(node)

    Visite un nœud. L'implémentation par défaut appelle la méthode `self.visit_classname` où classname représente le nom de la classe du nœud, ou `generic_visit()` si cette méthode n'existe pas.

  `generic_visit`(node)

    Le visiteur appelle la méthode `visit()` de tous les enfants du nœud.

    Notons que les nœuds enfants qui possèdent une méthode de visite spéciale ne seront pas visités à moins que le visiteur n'appelle la méthode `generic_visit()` ou ne les visite lui-même.

  N'utilisez pas `NodeVisitor` si vous souhaitez appliquer des changements sur les nœuds lors du parcours. Pour cela, un visiteur spécial existe (`NodeTransformer`) qui permet les modifications.

  Obsolète depuis la version 3.8: les méthodes `visit_Num()`, `visit_Str()`, `visit_Bytes()`, `visit_NameConstant()` et `visit_Ellipsis()` sont devenues obsolètes et cesseront d'être appelées dans une version ultérieure de Python. Écrivez une méthode `visit_Constant()` pour traiter tous les nœuds qui représentent des valeurs constantes.

class `ast.``NodeTransformer`

  Une sous-classe `NodeVisitor` qui traverse l'arbre syntaxique abstrait et permet les modifications des nœuds.

  Le `NodeTransformer` traverse l'AST et utilise la valeur renvoyée par les méthodes du visiteur pour remplacer ou supprimer l'ancien nœud. Si la valeur renvoyée par la méthode du visiteur est `None`, le nœud est supprimé de sa position, sinon il est remplacé par la valeur de retour. La valeur de retour peut être le nœud original et dans ce cas, il n'y a pas de remplacement.

  Voici un exemple du transformer qui réécrit les occurrences du dictionnaire (`foo`) en `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
              )

  Gardez en tête que si un nœud sur lequel vous travaillez a des nœuds enfants, vous devez transformer également ces nœuds enfant vous-même ou appeler d'abord la méthode `generic_visit()` sur le nœud.

  Pour les nœuds qui font partie d'une collection d'instructions (cela s'applique à tous les nœuds instruction), le visiteur peut aussi renvoyer la liste des nœuds plutôt qu'un seul nœud.

  Si `NodeTransformer` ajoute de nouveaux nœuds à l'original sans leur donner les attributs de position dans la source (`lineno` et consorts), il faut passer le nouvel arbre (ou la nouvelle partie de l'arbre) à `fix_missing_locations()` pour calculer les positions manquantes :

      tree = ast.parse('foo', mode='eval')
      new_tree = fix_missing_locations(RewriteName().visit(tree))

  Utilisation typique du transformer :

      node = YourTransformer().visit(node)

`ast.``dump`(node, annotate_fields=True, include_attributes=False, *, indent=None)

  Renvoie une représentation sous forme de chaîne de caractères de l'arbre contenu dans node. Ceci est principalement utile à des fins de débogage. Par défaut, les champs sont passés comme paramètres nommés aux constructeurs des classes d'arbre syntaxiques. Cependant, si annotate_fields est mis à `False`, les valeurs sont passées, lorsque cela est possible, comme arguments positionnels, rendant la représentation plus compacte. Les attributs comme les numéros de lignes et positions sur les lignes sont masqués par défaut, mais on peut les inclure en mettant include_attributes à `True`.

  La représentation peut comprendre une indentation afin d'être plus lisible. Si indent est une chaîne de caractères (par exemple une tabulation `"\t"`), elle est insérée au début des lignes en la répétant autant de fois que le niveau d'indentation. Un entier positif équivaut à un certain nombre d'espaces. Un entier strictement négatif produit un effet identique à 0 ou la chaîne vide, c'est-à-dire des retours à la ligne sans indentation. Avec la valeur par défaut de `None`, la sortie tient sur une seule ligne.

  Modifié dans la version 3.9: ajout du paramètre indent.

## Options du compilateur

Les options suivantes sont prises en charge par la fonction `compile()`. Elles permettent de modifier le comportement de la compilation.

`ast.``PyCF_ALLOW_TOP_LEVEL_AWAIT`

  Active la reconnaissance de `await`, `async for`, `async with` et des compréhensions asynchrones au niveau le plus haut.

  Nouveau dans la version 3.8.

`ast.``PyCF_ONLY_AST`

  Génère et renvoie un arbre syntaxique au lieu d'un objet de code compilé.

`ast.``PyCF_TYPE_COMMENTS`

  Ajoute la prise en charge des commentaires de types tels que définis dans la PEP 484 et la PEP 526 (`# type: un_type` et `# type: ignore`).

  Nouveau dans la version 3.8.

## Utilisation en ligne de commande.

Nouveau dans la version 3.9.

Le module `ast` peut être exécuté en tant que script en ligne de commande. C'est aussi simple que ceci :

    python -m ast [-m <mode>] [-a] [infile]

Les options suivantes sont acceptées :

`-h````,` `--help```

  Affiche un message d'aide et quitte.

`-m``<mode>`
`--mode``<mode>`

  Précise le type de code à compiler, comme l'argument mode de la fonction `parse()`.

`--no-type-comments```

  Désactive la reconnaissance des commentaires de type.

`-a````,` `--include-attributes```

  Affiche les attributs comme les numéros de lignes et les décalages par rapport aux débuts des lignes.

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

  Nombre d'espaces pour chaque niveau d'indentation dans la sortie.

L'entrée est lue dans le fichier `infile`, s'il est donné, ou l'entrée standard sinon. Le code source est transformé en un arbre syntaxique, qui est affiché sur la sortie standard.

Voir aussi

Green Tree Snakes, une ressource documentaire externe, qui possède plus de détails pour travailler avec des ASTs Python.

ASTTokens annote les arbres syntaxiques Python avec les positions des lexèmes et les extraits de code source à partir desquels ils sont produits. Ceci est utile pour les outils qui transforment du code source.

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 produit à partir du code source des arbres syntaxiques concrets, qui ressemblent à leurs homologues abstraits et conservent tous les détails du formatage. Cette bibliothèque est utile aux outils de réusinage et d'analyse de code.

Parso est un analyseur syntaxique de code Python qui gère la récupération d'erreurs et la génération de code (de l'arbre syntaxique vers le code source), le tout pour les grammaires de différentes versions de Python et en utilisant différentes versions. Il sait également donner plusieurs erreurs de syntaxe en une seule fois.