# `ast` --- Abstract syntax trees

Code source : Lib/ast.py

Le module `ast` permet aux applications Python de traiter les arbres syntaxiques, dérivés directement de la grammaire abstraite du langage. On peut notamment déterminer dans un programme la forme de chaque élément de grammaire, qui est susceptible d'être modifiée par les nouvelles versions de Python.

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

## Abstract grammar

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, type_param* type_params)
              | AsyncFunctionDef(identifier name, arguments args,
                                 stmt* body, expr* decorator_list, expr? returns,
                                 string? type_comment, type_param* type_params)

              | ClassDef(identifier name,
                 expr* bases,
                 keyword* keywords,
                 stmt* body,
                 expr* decorator_list,
                 type_param* type_params)
              | Return(expr? value)

              | Delete(expr* targets)
              | Assign(expr* targets, expr value, string? type_comment)
              | TypeAlias(expr name, type_param* type_params, expr value)
              | AugAssign(expr target, operator op, expr value)
              -- 'simple' indicates that we annotate simple name without parens
              | AnnAssign(expr target, expr annotation, expr? value, int simple)

              -- use 'orelse' because else is a keyword in target languages
              | For(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
              | AsyncFor(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
              | While(expr test, stmt* body, stmt* orelse)
              | If(expr test, stmt* body, stmt* orelse)
              | With(withitem* items, stmt* body, string? type_comment)
              | AsyncWith(withitem* items, stmt* body, string? type_comment)

              | Match(expr subject, match_case* cases)

              | Raise(expr? exc, expr? cause)
              | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
              | TryStar(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
              | Assert(expr test, expr? msg)

              | Import(alias* names)
              | ImportFrom(identifier? module, alias* names, int? level)

              | Global(identifier* names)
              | Nonlocal(identifier* names)
              | Expr(expr value)
              | Pass | Break | Continue

              -- col_offset is the byte offset in the utf8 string the parser uses
              attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

              -- BoolOp() can use left & right?
        expr = BoolOp(boolop op, expr* values)
             | NamedExpr(expr target, expr value)
             | BinOp(expr left, operator op, expr right)
             | UnaryOp(unaryop op, expr operand)
             | Lambda(arguments args, expr body)
             | IfExp(expr test, expr body, expr orelse)
             | Dict(expr?* keys, expr* values)
             | Set(expr* elts)
             | ListComp(expr elt, comprehension* generators)
             | SetComp(expr elt, comprehension* generators)
             | DictComp(expr key, expr value, comprehension* generators)
             | GeneratorExp(expr elt, comprehension* generators)
             -- the grammar constrains where yield expressions can occur
             | Await(expr value)
             | Yield(expr? value)
             | YieldFrom(expr value)
             -- need sequences for compare to distinguish between
             -- x < 4 < 3 and (x < 4) < 3
             | Compare(expr left, cmpop* ops, expr* comparators)
             | Call(expr func, expr* args, keyword* keywords)
             | FormattedValue(expr value, int conversion, expr? format_spec)
             | Interpolation(expr value, constant str, int conversion, expr? format_spec)
             | JoinedStr(expr* values)
             | TemplateStr(expr* values)
             | Constant(constant value, string? kind)

             -- the following expression can appear in assignment context
             | Attribute(expr value, identifier attr, expr_context ctx)
             | Subscript(expr value, expr slice, expr_context ctx)
             | Starred(expr value, expr_context ctx)
             | Name(identifier id, expr_context ctx)
             | List(expr* elts, expr_context ctx)
             | Tuple(expr* elts, expr_context ctx)

             -- can appear only in Subscript
             | Slice(expr? lower, expr? upper, expr? step)

              -- col_offset is the byte offset in the utf8 string the parser uses
              attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

        expr_context = Load | Store | Del

        boolop = And | Or

        operator = Add | Sub | Mult | MatMult | Div | Mod | Pow | LShift
                     | RShift | BitOr | BitXor | BitAnd | FloorDiv

        unaryop = Invert | Not | UAdd | USub

        cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn

        comprehension = (expr target, expr iter, expr* ifs, int is_async)

        excepthandler = ExceptHandler(expr? type, identifier? name, stmt* body)
                        attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

        arguments = (arg* posonlyargs, arg* args, arg? vararg, arg* kwonlyargs,
                     expr?* kw_defaults, arg? kwarg, expr* defaults)

        arg = (identifier arg, expr? annotation, string? type_comment)
               attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

        -- keyword arguments supplied to call (NULL identifier for **kwargs)
        keyword = (identifier? arg, expr value)
                   attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

        -- import name with optional 'as' alias.
        alias = (identifier name, identifier? asname)
                 attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

        withitem = (expr context_expr, expr? optional_vars)

        match_case = (pattern pattern, expr? guard, stmt* body)

        pattern = MatchValue(expr value)
                | MatchSingleton(constant value)
                | MatchSequence(pattern* patterns)
                | MatchMapping(expr* keys, pattern* patterns, identifier? rest)
                | MatchClass(expr cls, pattern* patterns, identifier* kwd_attrs, pattern* kwd_patterns)

                | MatchStar(identifier? name)
                -- The optional "rest" MatchMapping parameter handles capturing extra mapping keys

                | MatchAs(pattern? pattern, identifier? name)
                | MatchOr(pattern* patterns)

                 attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)

        type_ignore = TypeIgnore(int lineno, string tag)

        type_param = TypeVar(identifier name, expr? bound, expr? default_value)
                   | ParamSpec(identifier name, expr? default_value)
                   | TypeVarTuple(identifier name, expr? default_value)
                   attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)
    }

## Classes de nœuds

class ast.AST

  This is the base of all AST node classes. The actual node classes are derived from the `Parser/Python.asdl` file, which is reproduced above. They are defined in the `_ast` C module and re-exported in `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, une classe est définie pour chacun des constructeurs présentés à droite ; ces classes héritent des classes situées à leur 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 (les « sommes »), la classe de la partie gauche est abstraite : seules les classes de nœuds à droite sont instanciées.

  _fields

    Each concrete class has an attribute `_fields` which gives the names of all child nodes.

    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 un attribut est marqué comme optionnel dans la grammaire (avec un point d'interrogation `?`), sa valeur peut être `None`. S'il peut avoir zéro, une ou plusieurs valeurs (ce qui est marqué par un astérisque `*`), elles sont regroupées dans une liste Python. Tous les attributs possibles doivent être présents et avoir une valeur valide pour compiler un arbre syntaxique avec `compile()`.

  _field_types

    The `_field_types` attribute on each concrete class is a dictionary mapping field names (as also listed in `_fields`) to their types.

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

    Ajouté dans la version 3.13.

  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 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 nommée `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(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),
                         lineno=0, col_offset=0)

  If a field that is optional in the grammar is omitted from the constructor, it defaults to `None`. If a list field is omitted, it defaults to the empty list. If a field of type `ast.expr_context` is omitted, it defaults to `Load()`. If any other field is omitted, a `DeprecationWarning` is raised and the AST node will not have this field. In Python 3.15, this condition will raise an error.

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.

Modifié dans la version 3.14: The `__repr__()` output of `AST` nodes includes the values of the node fields.

Deprecated since version 3.8, removed in version 3.14: Previous versions of Python provided the AST classes `ast.Num`, `ast.Str`, `ast.Bytes`, `ast.NameConstant` and `ast.Ellipsis`, which were deprecated in Python 3.8. These classes were removed in Python 3.14, and their functionality has been replaced with `ast.Constant`.

Obsolète depuis la version 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.

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

Note

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.

### Root nodes

class ast.Module(body, type_ignores)

  A Python module, as with file input. Node type generated by `ast.parse()` in the default `"exec"` mode.

  `body` is a `list` of the module's Instructions.

  `type_ignores` is a `list` of the module's type ignore comments; see `ast.parse()` for more details.

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

class ast.Expression(body)

  A single Python expression input. Node type generated by `ast.parse()` when mode is `"eval"`.

  `body` is a single node, one of the expression types.

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

class ast.Interactive(body)

  A single interactive input, like in Mode interactif. Node type generated by `ast.parse()` when mode is `"single"`.

  `body` is a `list` of statement nodes.

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

class ast.FunctionType(argtypes, returns)

  A representation of an old-style type comments for functions, as Python versions prior to 3.5 didn't support PEP 484 annotations. Node type generated by `ast.parse()` when mode is `"func_type"`.

  Such type comments would look like this:

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

  `argtypes` is a `list` of expression nodes.

  `returns` is a single expression node.

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

  Ajouté dans la version 3.8.

### Littéraux

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 instances of `str`, `bytes`, `int`, `float`, `complex`, and `bool`, and the constants `None` and `Ellipsis`.

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

    - 97 (`ord('a')`): `!a` `ASCII` formatting

    - 114 (`ord('r')`): `!r` `repr()` formatting

    - 115 (`ord('s')`): `!s` `string` formatting

  - 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())]),
                      conversion=-1,
                      format_spec=JoinedStr(
                          values=[
                              Constant(value='.3')]))]))

class ast.TemplateStr(values, /)

  Ajouté dans la version 3.14.

  Node representing a template string literal, comprising a series of `Interpolation` and `Constant` nodes. These nodes may be any order, and do not need to be interleaved.

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

class ast.Interpolation(value, str, conversion, format_spec=None)

  Ajouté dans la version 3.14.

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

  - `value` is any expression node (such as a literal, a variable, or a function call). This has the same meaning as `FormattedValue.value`.

  - `str` is a constant containing the text of the interpolation expression.

    If `str` is set to `None`, then `value` is used to generate code when calling `ast.unparse()`. This no longer guarantees that the generated code is identical to the original and is intended for code generation.

  - conversion est un entier parmi les valeurs suivantes :

    - -1: no conversion

    - 97 (`ord('a')`): `!a` `ASCII` conversion

    - 114 (`ord('r')`): `!r` `repr()` conversion

    - 115 (`ord('s')`): `!s` `string` conversion

    This has the same meaning as `FormattedValue.conversion`.

  - `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. This has the same meaning as `FormattedValue.format_spec`.

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

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

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

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

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

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)

  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` holds a list of `keyword` objects representing arguments passed by keyword.

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

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

class ast.keyword(arg, value)

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

class ast.IfExp(test, body, orelse)

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

  Ajouté dans la version 3.8.

#### 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()),
                      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()),
                      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()),
                      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())]),
              generators=[
                  comprehension(
                      target=Name(id='line', ctx=Store()),
                      iter=Name(id='file', ctx=Load()),
                      is_async=0),
                  comprehension(
                      target=Name(id='c', ctx=Store()),
                      iter=Name(id='line', ctx=Load()),
                      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()),
                      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))])

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

class ast.AnnAssign(target, annotation, value, simple)

  An assignment with a type annotation. `target` is a single node and can be a `Name`, an `Attribute` or a `Subscript`. `annotation` is the annotation, such as a `Constant` or `Name` node. `value` is a single optional node.

  `simple` is always either 0 (indicating a "complex" target) or 1 (indicating a "simple" target). A "simple" target consists solely of a `Name` node that does not appear between parentheses; all other targets are considered complex. Only simple targets appear in the `__annotations__` dictionary of modules and classes.

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

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

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

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

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

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

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

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

class ast.Pass

  Instruction `pass`.

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

class ast.TypeAlias(name, type_params, value)

  A type alias created through the `type` statement. `name` is the name of the alias, `type_params` is a list of type parameters, and `value` is the value of the type alias.

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

  Ajouté dans la version 3.12.

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

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

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

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

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`, `List`, `Attribute` or `Subscript` 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

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

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

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

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

class ast.TryStar(body, handlers, orelse, finalbody)

  `try` blocks which are followed by `except*` clauses. The attributes are the same as for `Try` but the `ExceptHandler` nodes in `handlers` are interpreted as `except*` blocks rather then `except`.

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

  Ajouté dans la version 3.11.

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

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

### Pattern matching

class ast.Match(subject, cases)

  A `match` statement. `subject` holds the subject of the match (the object that is being matched against the cases) and `cases` contains an iterable of `match_case` nodes with the different cases.

  Ajouté dans la version 3.10.

class ast.match_case(pattern, guard, body)

  A single case pattern in a `match` statement. `pattern` contains the match pattern that the subject will be matched against. Note that the `AST` nodes produced for patterns differ from those produced for expressions, even when they share the same syntax.

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

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

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

  Ajouté dans la version 3.10.

class ast.MatchValue(value)

  A match literal or value pattern that compares by equality. `value` is an expression node. Permitted value nodes are restricted as described in the match statement documentation. This pattern succeeds if the match subject is equal to the evaluated value.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case "Relevant":
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchValue(
                              value=Constant(value='Relevant')),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

  Ajouté dans la version 3.10.

class ast.MatchSingleton(value)

  A match literal pattern that compares by identity. `value` is the singleton to be compared against: `None`, `True`, or `False`. This pattern succeeds if the match subject is the given constant.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case None:
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchSingleton(value=None),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

  Ajouté dans la version 3.10.

class ast.MatchSequence(patterns)

  A match sequence pattern. `patterns` contains the patterns to be matched against the subject elements if the subject is a sequence. Matches a variable length sequence if one of the subpatterns is a `MatchStar` node, otherwise matches a fixed length sequence.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case [1, 2]:
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchSequence(
                              patterns=[
                                  MatchValue(
                                      value=Constant(value=1)),
                                  MatchValue(
                                      value=Constant(value=2))]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

  Ajouté dans la version 3.10.

class ast.MatchStar(name)

  Matches the rest of the sequence in a variable length match sequence pattern. If `name` is not `None`, a list containing the remaining sequence elements is bound to that name if the overall sequence pattern is successful.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case [1, 2, *rest]:
      ...         ...
      ...     case [*_]:
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchSequence(
                              patterns=[
                                  MatchValue(
                                      value=Constant(value=1)),
                                  MatchValue(
                                      value=Constant(value=2)),
                                  MatchStar(name='rest')]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))]),
                      match_case(
                          pattern=MatchSequence(
                              patterns=[
                                  MatchStar()]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

  Ajouté dans la version 3.10.

class ast.MatchMapping(keys, patterns, rest)

  A match mapping pattern. `keys` is a sequence of expression nodes. `patterns` is a corresponding sequence of pattern nodes. `rest` is an optional name that can be specified to capture the remaining mapping elements. Permitted key expressions are restricted as described in the match statement documentation.

  This pattern succeeds if the subject is a mapping, all evaluated key expressions are present in the mapping, and the value corresponding to each key matches the corresponding subpattern. If `rest` is not `None`, a dict containing the remaining mapping elements is bound to that name if the overall mapping pattern is successful.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case {1: _, 2: _}:
      ...         ...
      ...     case {**rest}:
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchMapping(
                              keys=[
                                  Constant(value=1),
                                  Constant(value=2)],
                              patterns=[
                                  MatchAs(),
                                  MatchAs()]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))]),
                      match_case(
                          pattern=MatchMapping(rest='rest'),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

  Ajouté dans la version 3.10.

class ast.MatchClass(cls, patterns, kwd_attrs, kwd_patterns)

  A match class pattern. `cls` is an expression giving the nominal class to be matched. `patterns` is a sequence of pattern nodes to be matched against the class defined sequence of pattern matching attributes. `kwd_attrs` is a sequence of additional attributes to be matched (specified as keyword arguments in the class pattern), `kwd_patterns` are the corresponding patterns (specified as keyword values in the class pattern).

  This pattern succeeds if the subject is an instance of the nominated class, all positional patterns match the corresponding class-defined attributes, and any specified keyword attributes match their corresponding pattern.

  Note: classes may define a property that returns self in order to match a pattern node against the instance being matched. Several builtin types are also matched that way, as described in the match statement documentation.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case Point2D(0, 0):
      ...         ...
      ...     case Point3D(x=0, y=0, z=0):
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchClass(
                              cls=Name(id='Point2D', ctx=Load()),
                              patterns=[
                                  MatchValue(
                                      value=Constant(value=0)),
                                  MatchValue(
                                      value=Constant(value=0))]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))]),
                      match_case(
                          pattern=MatchClass(
                              cls=Name(id='Point3D', ctx=Load()),
                              kwd_attrs=[
                                  'x',
                                  'y',
                                  'z'],
                              kwd_patterns=[
                                  MatchValue(
                                      value=Constant(value=0)),
                                  MatchValue(
                                      value=Constant(value=0)),
                                  MatchValue(
                                      value=Constant(value=0))]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

  Ajouté dans la version 3.10.

class ast.MatchAs(pattern, name)

  A match "as-pattern", capture pattern or wildcard pattern. `pattern` contains the match pattern that the subject will be matched against. If the pattern is `None`, the node represents a capture pattern (i.e a bare name) and will always succeed.

  The `name` attribute contains the name that will be bound if the pattern is successful. If `name` is `None`, `pattern` must also be `None` and the node represents the wildcard pattern.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case [x] as y:
      ...         ...
      ...     case _:
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchAs(
                              pattern=MatchSequence(
                                  patterns=[
                                      MatchAs(name='x')]),
                              name='y'),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))]),
                      match_case(
                          pattern=MatchAs(),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

  Ajouté dans la version 3.10.

class ast.MatchOr(patterns)

  A match "or-pattern". An or-pattern matches each of its subpatterns in turn to the subject, until one succeeds. The or-pattern is then deemed to succeed. If none of the subpatterns succeed the or-pattern fails. The `patterns` attribute contains a list of match pattern nodes that will be matched against the subject.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case [x] | (y):
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchOr(
                              patterns=[
                                  MatchSequence(
                                      patterns=[
                                          MatchAs(name='x')]),
                                  MatchAs(name='y')]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

  Ajouté dans la version 3.10.

### Type annotations

class ast.TypeIgnore(lineno, tag)

  A `# type: ignore` comment located at lineno. tag is the optional tag specified by the form `# type: ignore <tag>`.

      >>> print(ast.dump(ast.parse('x = 1 # type: ignore', type_comments=True), indent=4))
      Module(
          body=[
              Assign(
                  targets=[
                      Name(id='x', ctx=Store())],
                  value=Constant(value=1))],
          type_ignores=[
              TypeIgnore(lineno=1, tag='')])
      >>> print(ast.dump(ast.parse('x: bool = 1 # type: ignore[assignment]', type_comments=True), indent=4))
      Module(
          body=[
              AnnAssign(
                  target=Name(id='x', ctx=Store()),
                  annotation=Name(id='bool', ctx=Load()),
                  value=Constant(value=1),
                  simple=1)],
          type_ignores=[
              TypeIgnore(lineno=1, tag='[assignment]')])

  Note

  `TypeIgnore` nodes are not generated when the type_comments parameter is set to `False` (default). See `ast.parse()` for more details.

  Ajouté dans la version 3.8.

### Type parameters

Type parameters can exist on classes, functions, and type aliases.

class ast.TypeVar(name, bound, default_value)

  A `typing.TypeVar`. `name` is the name of the type variable. `bound` is the bound or constraints, if any. If `bound` is a `Tuple`, it represents constraints; otherwise it represents the bound. `default_value` is the default value; if the `TypeVar` has no default, this attribute will be set to `None`.

      >>> print(ast.dump(ast.parse("type Alias[T: int = bool] = list[T]"), indent=4))
      Module(
          body=[
              TypeAlias(
                  name=Name(id='Alias', ctx=Store()),
                  type_params=[
                      TypeVar(
                          name='T',
                          bound=Name(id='int', ctx=Load()),
                          default_value=Name(id='bool', ctx=Load()))],
                  value=Subscript(
                      value=Name(id='list', ctx=Load()),
                      slice=Name(id='T', ctx=Load()),
                      ctx=Load()))])

  Ajouté dans la version 3.12.

  Modifié dans la version 3.13: Added the default_value parameter.

class ast.ParamSpec(name, default_value)

  A `typing.ParamSpec`. `name` is the name of the parameter specification. `default_value` is the default value; if the `ParamSpec` has no default, this attribute will be set to `None`.

      >>> print(ast.dump(ast.parse("type Alias[**P = [int, str]] = Callable[P, int]"), indent=4))
      Module(
          body=[
              TypeAlias(
                  name=Name(id='Alias', ctx=Store()),
                  type_params=[
                      ParamSpec(
                          name='P',
                          default_value=List(
                              elts=[
                                  Name(id='int', ctx=Load()),
                                  Name(id='str', ctx=Load())],
                              ctx=Load()))],
                  value=Subscript(
                      value=Name(id='Callable', ctx=Load()),
                      slice=Tuple(
                          elts=[
                              Name(id='P', ctx=Load()),
                              Name(id='int', ctx=Load())],
                          ctx=Load()),
                      ctx=Load()))])

  Ajouté dans la version 3.12.

  Modifié dans la version 3.13: Added the default_value parameter.

class ast.TypeVarTuple(name, default_value)

  A `typing.TypeVarTuple`. `name` is the name of the type variable tuple. `default_value` is the default value; if the `TypeVarTuple` has no default, this attribute will be set to `None`.

      >>> print(ast.dump(ast.parse("type Alias[*Ts = ()] = tuple[*Ts]"), indent=4))
      Module(
          body=[
              TypeAlias(
                  name=Name(id='Alias', ctx=Store()),
                  type_params=[
                      TypeVarTuple(
                          name='Ts',
                          default_value=Tuple(ctx=Load()))],
                  value=Subscript(
                      value=Name(id='tuple', ctx=Load()),
                      slice=Tuple(
                          elts=[
                              Starred(
                                  value=Name(id='Ts', ctx=Load()),
                                  ctx=Load())],
                          ctx=Load()),
                      ctx=Load()))])

  Ajouté dans la version 3.12.

  Modifié dans la version 3.13: Added the default_value parameter.

### Définition de fonctions et de classes

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

  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_params` is a list of type parameters.

  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.

  Modifié dans la version 3.12: Added `type_params`.

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(
                          args=[
                              arg(arg='x'),
                              arg(arg='y')]),
                      body=Constant(value=Ellipsis)))])

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 `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(
                      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'))])

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

class ast.Yield(value)
class ast.YieldFrom(value)

  A `yield` or `yield from` expression. Because these are expressions, they must be wrapped in an `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())))])

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

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

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

class ast.ClassDef(name, bases, keywords, body, decorator_list, type_params)

  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.

  - body est la liste des instructions contenues dans la définition de classe ;

  - decorators_list est une liste de nœuds, comme pour `FunctionDef`.

  - `type_params` is a list of type parameters.

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

  Modifié dans la version 3.12: Added `type_params`.

### `async` et `await`

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

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

  Modifié dans la version 3.12: Added `type_params`.

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(),
                body=[
                    Expr(
                        value=Await(
                            value=Call(
                                func=Name(id='other_func', ctx=Load()))))])])

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

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 (for example, `ast.Add`).

## `ast` helpers

À part les classes de nœuds, le module `ast` définit plusieurs fonctions et classes utilitaires pour traverser les arbres syntaxiques abstraits :

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

  Parse the source into an AST node. Equivalent to `compile(source, filename, mode, flags=FLAGS_VALUE, optimize=optimize)`, where `FLAGS_VALUE` is `ast.PyCF_ONLY_AST` if `optimize <= 0` and `ast.PyCF_OPTIMIZED_AST` otherwise.

  If `type_comments=True` is given, the parser is modified to check and return type comments as specified by PEP 484 and PEP 526. This is equivalent to adding `ast.PyCF_TYPE_COMMENTS` to the flags passed to `compile()`. This will report syntax errors for misplaced type comments. Without this flag, type comments will be ignored, and the `type_comment` field on selected AST nodes will always be `None`. In addition, the locations of `# type: ignore` comments will be returned as the `type_ignores` attribute of `Module` (otherwise it is always an empty list).

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

  Setting `feature_version` to a tuple `(major, minor)` will result in a "best-effort" attempt to parse using that Python version's grammar. For example, setting `feature_version=(3, 9)` will attempt to disallow parsing of `match` statements. Currently `major` must equal to `3`. The lowest supported version is `(3, 7)` (and this may increase in future Python versions); the highest is `sys.version_info[0:2]`. "Best-effort" attempt means there is no guarantee that the parse (or success of the parse) is the same as when run on the Python version corresponding to `feature_version`.

  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 arbre syntaxique en raison de 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.

  Modifié dans la version 3.13: The minimum supported version for `feature_version` is now `(3, 7)`. The `optimize` argument was added.

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.

  Ajouté dans la version 3.9.

ast.literal_eval(node_or_string)

  Evaluate an expression node or a string containing only a Python literal or container display. The string or node provided may only consist of the following Python literal structures: strings, bytes, numbers, tuples, lists, dicts, sets, booleans, `None` and `Ellipsis`.

  This can be used for evaluating strings containing Python values without the need to parse the values oneself. It is not capable of evaluating arbitrarily complex expressions, for example involving operators or indexing.

  This function had been documented as "safe" in the past without defining what that meant. That was misleading. This is specifically designed not to execute Python code, unlike the more general `eval()`. There is no namespace, no name lookups, or ability to call out. But it is not free from attack: A relatively small input can lead to memory exhaustion or to C stack exhaustion, crashing the process. There is also the possibility for excessive CPU consumption denial of service on some inputs. Calling it on untrusted data is thus not recommended.

  Avertissement

  It is possible to crash the Python interpreter due to stack depth limitations in Python's AST compiler.

  It can raise `ValueError`, `TypeError`, `SyntaxError`, `MemoryError` and `RecursionError` depending on the malformed input.

  Modifié dans la version 3.2: accepte maintenant les octets et ensembles littéraux.

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

  Modifié dans la version 3.10: For string inputs, leading spaces and tabs are now stripped.

ast.get_docstring(node, clean=True)

  Renvoie la docstring du nœud node (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)

  Get source code segment of the source that generated node. If some location information (`lineno`, `end_lineno`, `col_offset`, or `end_col_offset`) is missing, return `None`.

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

  Ajouté dans la version 3.8.

ast.fix_missing_locations(node)

  When you compile a node tree with `compile()`, the compiler expects `lineno` and `col_offset` attributes for every node that supports them. This is rather tedious to fill in for generated nodes, so this helper adds these attributes recursively where not already set, by setting them to the values of the parent node. It works recursively starting at 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)

  Copy source location (`lineno`, `col_offset`, `end_lineno`, and `end_col_offset`) from old_node to new_node if possible, and return new_node.

ast.iter_fields(node)

  Produit un n-uplet de couples `(nom_du_champ, valeur)` 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_classe` où classe 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 sont pas visités à moins que le visiteur n'appelle la méthode `generic_visit()` ou ne les visite lui-même.

  visit_Constant(node)

    Handles all constant nodes.

  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.

  Deprecated since version 3.8, removed in version 3.14: Methods `visit_Num()`, `visit_Str()`, `visit_Bytes()`, `visit_NameConstant()` and `visit_Ellipsis()` will not be called in Python 3.14+. Add the `visit_Constant()` method instead to handle all constant nodes.

class ast.NodeTransformer

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

  Le `NodeTransformer` traverse l'arbre syntaxique 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 cette valeur. Elle peut être le nœud original, auquel cas il n'y a pas de remplacement.

  Voici un exemple de transformation qui réécrit tous les accès à la valeur d'une variable `toto` en `data['toto']` :

      class RewriteName(NodeTransformer):

          def visit_Name(self, node):
              return Subscript(
                  value=Name(id='data', ctx=Load()),
                  slice=Constant(value=node.id),
                  ctx=node.ctx
              )

  Keep in mind that if the node you're operating on has child nodes you must either transform the child nodes yourself or call the `generic_visit()` method for the node first.

  Pour les nœuds qui font partie d'un groupe (notamment toutes les instructions), le visiteur peut aussi renvoyer une liste des nœuds plutôt qu'un seul nœud.

  If `NodeTransformer` introduces new nodes (that weren't part of original tree) without giving them location information (such as `lineno`), `fix_missing_locations()` should be called with the new sub-tree to recalculate the location information:

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

  Utilisation typique des transformations :

      node = YourTransformer().visit(node)

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

  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.

  If show_empty is false (the default), optional empty lists will be omitted from the output. Optional `None` values are always omitted.

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

  Modifié dans la version 3.13: Added the show_empty option.

      >>> print(ast.dump(ast.parse("""\
      ... async def f():
      ...     await other_func()
      ... """), indent=4, show_empty=True))
      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_params=[])],
          type_ignores=[])

## Compiler flags

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.

  Ajouté 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_OPTIMIZED_AST

  The returned AST is optimized according to the optimize argument in `compile()` or `ast.parse()`.

  Ajouté dans la version 3.13.

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

  Ajouté dans la version 3.8.

ast.compare(a, b, /, *, compare_attributes=False)

  Recursively compares two ASTs.

  compare_attributes affects whether AST attributes are considered in the comparison. If compare_attributes is `False` (default), then attributes are ignored. Otherwise they must all be equal. This option is useful to check whether the ASTs are structurally equal but differ in whitespace or similar details. Attributes include line numbers and column offsets.

  Ajouté dans la version 3.14.

## Command-line usage

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

--feature-version <version>

  Python version in the format 3.x (for example, 3.10). Defaults to the current version of the interpreter.

  Ajouté dans la version 3.14.

-O <level>
--optimize <level>

  Optimization level for parser. Defaults to no optimization.

  Ajouté dans la version 3.14.

--show-empty

  Show empty lists and fields that are `None`. Defaults to not showing empty objects.

  Ajouté dans la version 3.14.

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