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


Grammaire abstraite
===================

La grammaire abstraite est actuellement définie comme suit :

   -- ASDL's 4 builtin types are:
   -- identifier, int, string, constant

   module Python
   {
       mod = Module(stmt* body, type_ignore* type_ignores)
           | Interactive(stmt* body)
           | Expression(expr body)
           | FunctionType(expr* argtypes, expr returns)

       stmt = FunctionDef(identifier name, arguments args,
                          stmt* body, expr* decorator_list, expr? returns,
                          string? type_comment, 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)
            | JoinedStr(expr* values)
            | Constant(constant value, string? kind)

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

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

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

       expr_context = Load | Store | Del

       boolop = And | Or

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

       unaryop = Invert | Not | UAdd | USub

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

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

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

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

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

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

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

       withitem = (expr context_expr, expr? optional_vars)

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

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

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

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

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

       type_ignore = TypeIgnore(int lineno, string tag)

       type_param = TypeVar(identifier name, expr? bound)
                  | ParamSpec(identifier name)
                  | TypeVarTuple(identifier name)
                  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

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

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

      Si 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()".

   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()
      node.op = ast.USub()
      node.operand = ast.Constant()
      node.operand.value = 5
      node.operand.lineno = 0
      node.operand.col_offset = 0
      node.lineno = 0
      node.col_offset = 0

   ou, plus compact

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

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

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

Obsolète depuis la version 3.8: Old classes "ast.Num", "ast.Str",
"ast.Bytes", "ast.NameConstant" and "ast.Ellipsis" are still
available, but they will be removed in future Python releases.  In the
meantime, instantiating them will return an instance of a different
class.

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.

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

class ast.Expression(body)

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

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

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

class ast.Interactive(body)

   A single interactive input, like in 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)

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

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

class ast.FormattedValue(value, conversion, format_spec)

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

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

   * *conversion* est un entier parmi les valeurs suivantes :

     * -1, aucun formatage ;

     * 115, pour le formatage par "str()" correspondant à "!s" ;

     * 114, pour le formatage par "repr()" correspondant à "!r" ;

     * 97, pour le formatage par "ascii()" correspondant à "!a".

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

class ast.JoinedStr(values)

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

      >>> print(ast.dump(ast.parse('f"sin({a}) is {sin(a):.3}"', mode='eval'), indent=4))
      Expression(
          body=JoinedStr(
              values=[
                  Constant(value='sin('),
                  FormattedValue(
                      value=Name(id='a', ctx=Load()),
                      conversion=-1),
                  Constant(value=') is '),
                  FormattedValue(
                      value=Call(
                          func=Name(id='sin', ctx=Load()),
                          args=[
                              Name(id='a', ctx=Load())],
                          keywords=[]),
                      conversion=-1,
                      format_spec=JoinedStr(
                          values=[
                              Constant(value='.3')]))]))

class ast.List(elts, ctx)
class ast.Tuple(elts, ctx)

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

      >>> print(ast.dump(ast.parse('[1, 2, 3]', mode='eval'), indent=4))
      Expression(
          body=List(
              elts=[
                  Constant(value=1),
                  Constant(value=2),
                  Constant(value=3)],
              ctx=Load()))
      >>> print(ast.dump(ast.parse('(1, 2, 3)', mode='eval'), indent=4))
      Expression(
          body=Tuple(
              elts=[
                  Constant(value=1),
                  Constant(value=2),
                  Constant(value=3)],
              ctx=Load()))

class ast.Set(elts)

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

      >>> print(ast.dump(ast.parse('{1, 2, 3}', mode='eval'), indent=4))
      Expression(
          body=Set(
              elts=[
                  Constant(value=1),
                  Constant(value=2),
                  Constant(value=3)]))

class ast.Dict(keys, values)

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

   Si un dictionnaire littéral contient une expression doublement
   étoilée à déballer, elle est intégrée dans *values*, et "None" est
   mis à la place correspondante dans *keys*.

      >>> print(ast.dump(ast.parse('{"a":1, **d}', mode='eval'), indent=4))
      Expression(
          body=Dict(
              keys=[
                  Constant(value='a'),
                  None],
              values=[
                  Constant(value=1),
                  Name(id='d', ctx=Load())]))


Variables
---------

class ast.Name(id, ctx)

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

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

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

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

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

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

class ast.Starred(value, ctx)

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

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


Expressions
-----------

class ast.Expr(value)

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

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

class ast.UnaryOp(op, operand)

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

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

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

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

class ast.BinOp(left, op, right)

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

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

class ast.Add
class ast.Sub
class ast.Mult
class ast.Div
class ast.FloorDiv
class ast.Mod
class ast.Pow
class ast.LShift
class ast.RShift
class ast.BitOr
class ast.BitXor
class ast.BitAnd
class ast.MatMult

   Unités lexicales pour les opérations binaires.

class ast.BoolOp(op, values)

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

   L'opérateur "not" n'est pas implémenté ici, mais bien dans
   "UnaryOp".

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

class ast.And
class ast.Or

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

class ast.Compare(left, ops, comparators)

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

      >>> print(ast.dump(ast.parse('1 <= a < 10', mode='eval'), indent=4))
      Expression(
          body=Compare(
              left=Constant(value=1),
              ops=[
                  LtE(),
                  Lt()],
              comparators=[
                  Name(id='a', ctx=Load()),
                  Constant(value=10)]))

class ast.Eq
class ast.NotEq
class ast.Lt
class ast.LtE
class ast.Gt
class ast.GtE
class ast.Is
class ast.IsNot
class ast.In
class ast.NotIn

   Unités lexicales pour les comparaisons.

class ast.Call(func, args, keywords)

   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.

   When creating a "Call" node, "args" and "keywords" are required,
   but they can be empty lists.

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

class ast.keyword(arg, value)

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

class ast.IfExp(test, body, orelse)

   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()),
                      ifs=[],
                      is_async=0)]))
      >>> print(ast.dump(ast.parse('{x: x**2 for x in numbers}', mode='eval'), indent=4))
      Expression(
          body=DictComp(
              key=Name(id='x', ctx=Load()),
              value=BinOp(
                  left=Name(id='x', ctx=Load()),
                  op=Pow(),
                  right=Constant(value=2)),
              generators=[
                  comprehension(
                      target=Name(id='x', ctx=Store()),
                      iter=Name(id='numbers', ctx=Load()),
                      ifs=[],
                      is_async=0)]))
      >>> print(ast.dump(ast.parse('{x for x in numbers}', mode='eval'), indent=4))
      Expression(
          body=SetComp(
              elt=Name(id='x', ctx=Load()),
              generators=[
                  comprehension(
                      target=Name(id='x', ctx=Store()),
                      iter=Name(id='numbers', ctx=Load()),
                      ifs=[],
                      is_async=0)]))

class ast.comprehension(target, iter, ifs, is_async)

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

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

      >>> print(ast.dump(ast.parse('[ord(c) for line in file for c in line]', mode='eval'),
      ...                indent=4)) # Multiple comprehensions in one.
      Expression(
          body=ListComp(
              elt=Call(
                  func=Name(id='ord', ctx=Load()),
                  args=[
                      Name(id='c', ctx=Load())],
                  keywords=[]),
              generators=[
                  comprehension(
                      target=Name(id='line', ctx=Store()),
                      iter=Name(id='file', ctx=Load()),
                      ifs=[],
                      is_async=0),
                  comprehension(
                      target=Name(id='c', ctx=Store()),
                      iter=Name(id='line', ctx=Load()),
                      ifs=[],
                      is_async=0)]))

      >>> print(ast.dump(ast.parse('(n**2 for n in it if n>5 if n<10)', mode='eval'),
      ...                indent=4)) # generator comprehension
      Expression(
          body=GeneratorExp(
              elt=BinOp(
                  left=Name(id='n', ctx=Load()),
                  op=Pow(),
                  right=Constant(value=2)),
              generators=[
                  comprehension(
                      target=Name(id='n', ctx=Store()),
                      iter=Name(id='it', ctx=Load()),
                      ifs=[
                          Compare(
                              left=Name(id='n', ctx=Load()),
                              ops=[
                                  Gt()],
                              comparators=[
                                  Constant(value=5)]),
                          Compare(
                              left=Name(id='n', ctx=Load()),
                              ops=[
                                  Lt()],
                              comparators=[
                                  Constant(value=10)])],
                      is_async=0)]))

      >>> print(ast.dump(ast.parse('[i async for i in soc]', mode='eval'),
      ...                indent=4)) # Async comprehension
      Expression(
          body=ListComp(
              elt=Name(id='i', ctx=Load()),
              generators=[
                  comprehension(
                      target=Name(id='i', ctx=Store()),
                      iter=Name(id='soc', ctx=Load()),
                      ifs=[],
                      is_async=1)]))


Instructions
------------

class ast.Assign(targets, value, type_comment)

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

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

   type_comment

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

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

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

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

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

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

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

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

class ast.AugAssign(target, op, value)

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

   The "target" attribute 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))],
          type_ignores=[])

class ast.Raise(exc, cause)

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

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

class ast.Assert(test, msg)

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

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

class ast.Delete(targets)

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

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

class ast.Pass

   Instruction "pass".

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

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()),
                  type_params=[],
                  value=Name(id='int', ctx=Load()))],
          type_ignores=[])

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

class ast.ImportFrom(module, names, level)

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

      >>> print(ast.dump(ast.parse('from y import x,y,z'), indent=4))
      Module(
          body=[
              ImportFrom(
                  module='y',
                  names=[
                      alias(name='x'),
                      alias(name='y'),
                      alias(name='z')],
                  level=0)],
          type_ignores=[])

class ast.alias(name, asname)

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

      >>> print(ast.dump(ast.parse('from ..foo.bar import a as b, c'), indent=4))
      Module(
          body=[
              ImportFrom(
                  module='foo.bar',
                  names=[
                      alias(name='a', asname='b'),
                      alias(name='c')],
                  level=2)],
          type_ignores=[])


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

Note:

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

class ast.If(test, body, orelse)

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

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

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

class ast.For(target, iter, body, orelse, type_comment)

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

class ast.While(test, body, orelse)

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

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

class ast.Break
class ast.Continue

   Instructions "break" et "continue".

      >>> print(ast.dump(ast.parse("""\
      ... for a in b:
      ...     if a > 5:
      ...         break
      ...     else:
      ...         continue
      ...
      ... """), indent=4))
      Module(
          body=[
              For(
                  target=Name(id='a', ctx=Store()),
                  iter=Name(id='b', ctx=Load()),
                  body=[
                      If(
                          test=Compare(
                              left=Name(id='a', ctx=Load()),
                              ops=[
                                  Gt()],
                              comparators=[
                                  Constant(value=5)]),
                          body=[
                              Break()],
                          orelse=[
                              Continue()])],
                  orelse=[])],
          type_ignores=[])

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

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

      >>> print(ast.dump(ast.parse("""
      ... try:
      ...    ...
      ... except Exception:
      ...    ...
      ... except OtherException as e:
      ...    ...
      ... else:
      ...    ...
      ... finally:
      ...    ...
      ... """), indent=4))
      Module(
          body=[
              Try(
                  body=[
                      Expr(
                          value=Constant(value=Ellipsis))],
                  handlers=[
                      ExceptHandler(
                          type=Name(id='Exception', ctx=Load()),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))]),
                      ExceptHandler(
                          type=Name(id='OtherException', ctx=Load()),
                          name='e',
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])],
                  orelse=[
                      Expr(
                          value=Constant(value=Ellipsis))],
                  finalbody=[
                      Expr(
                          value=Constant(value=Ellipsis))])],
          type_ignores=[])

class ast.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))])],
                  orelse=[],
                  finalbody=[])],
          type_ignores=[])

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

class ast.With(items, body, type_comment)

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

   type_comment

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

class ast.withitem(context_expr, optional_vars)

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

      >>> print(ast.dump(ast.parse("""\
      ... with a as b, c as d:
      ...    something(b, d)
      ... """), indent=4))
      Module(
          body=[
              With(
                  items=[
                      withitem(
                          context_expr=Name(id='a', ctx=Load()),
                          optional_vars=Name(id='b', ctx=Store())),
                      withitem(
                          context_expr=Name(id='c', ctx=Load()),
                          optional_vars=Name(id='d', ctx=Store()))],
                  body=[
                      Expr(
                          value=Call(
                              func=Name(id='something', ctx=Load()),
                              args=[
                                  Name(id='b', ctx=Load()),
                                  Name(id='d', ctx=Load())],
                              keywords=[]))])],
          type_ignores=[])


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()),
                              patterns=[],
                              kwd_attrs=[],
                              kwd_patterns=[]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])],
          type_ignores=[])

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

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

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

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

   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(keys=[], patterns=[], rest='rest'),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])],
          type_ignores=[])

   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))],
                              kwd_attrs=[],
                              kwd_patterns=[]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))]),
                      match_case(
                          pattern=MatchClass(
                              cls=Name(id='Point3D', ctx=Load()),
                              patterns=[],
                              kwd_attrs=[
                                  'x',
                                  'y',
                                  'z'],
                              kwd_patterns=[
                                  MatchValue(
                                      value=Constant(value=0)),
                                  MatchValue(
                                      value=Constant(value=0)),
                                  MatchValue(
                                      value=Constant(value=0))]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])],
          type_ignores=[])

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

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

   Ajouté dans la version 3.10.


Type parameters
---------------

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

class ast.TypeVar(name, bound)

   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.

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

   Ajouté dans la version 3.12.

class ast.ParamSpec(name)

   A "typing.ParamSpec". "name" is the name of the parameter
   specification.

      >>> print(ast.dump(ast.parse("type Alias[**P] = Callable[P, int]"), indent=4))
      Module(
          body=[
              TypeAlias(
                  name=Name(id='Alias', ctx=Store()),
                  type_params=[
                      ParamSpec(name='P')],
                  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()))],
          type_ignores=[])

   Ajouté dans la version 3.12.

class ast.TypeVarTuple(name)

   A "typing.TypeVarTuple". "name" is the name of the type variable
   tuple.

      >>> 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')],
                  value=Subscript(
                      value=Name(id='tuple', ctx=Load()),
                      slice=Tuple(
                          elts=[
                              Starred(
                                  value=Name(id='Ts', ctx=Load()),
                                  ctx=Load())],
                          ctx=Load()),
                      ctx=Load()))],
          type_ignores=[])

   Ajouté dans la version 3.12.


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

class ast.arguments(posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults)

   Arguments d'une fonction.

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

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

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

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

class ast.arg(arg, annotation, type_comment)

   A single argument in a list. "arg" is a raw string of the argument
   name; "annotation" is its annotation, such as a "Name" node.

   type_comment

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

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

class ast.Return(value)

   Instruction "return", qui renvoie *value*.

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

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

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

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

class ast.Global(names)
class ast.Nonlocal(names)

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

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

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

class ast.ClassDef(name, bases, keywords, 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())],
                  type_params=[])],
          type_ignores=[])

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

class ast.AsyncFor(target, iter, body, orelse, type_comment)
class ast.AsyncWith(items, body, type_comment)

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

Note:

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


Outils du module "ast"
======================

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

   Analyse le code source et renvoie un arbre syntaxique. Équivalent à
   "compile(source, filename, mode, ast.PyCF_ONLY_AST)".

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

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

   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, 4)" (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*.

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.

   Obsolète depuis la version 3.8: Methods "visit_Num()",
   "visit_Str()", "visit_Bytes()", "visit_NameConstant()" and
   "visit_Ellipsis()" are deprecated now and will not be called in
   future Python versions.  Add the "visit_Constant()" method 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)

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

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

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


Options du compilateur
======================

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

ast.PyCF_ALLOW_TOP_LEVEL_AWAIT

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

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


Utilisation en ligne de commande
================================

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.

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.
