# 32.2. `ast` — Arbres Syntaxiques Abstraits

Code source : Lib/ast.py

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

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

## 32.2.1. Les classes nœud

class `ast.``AST`

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

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

  `_fields`

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

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

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

  `lineno`
  `col_offset`

    Les instances des sous-classes `ast.expr` et `ast.stmt` possèdent les attributs `lineno` et `col_offset`. L’attribut `lineno` est le numéro de ligne dans le code source (indexé à partir de 1 tel que la première ligne est la ligne 1) et l’attribut `col_offset` qui représente le décalage UTF-8 en byte du premier jeton qui a généré le nœud. Le décalage UTF-8 est enregistré parce que l’analyseur syntaxique utilise l’UTF-8 en interne.

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

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

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

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

      node = ast.UnaryOp()
      node.op = ast.USub()
      node.operand = ast.Num()
      node.operand.n = 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.Num(5, lineno=0, col_offset=0),
                         lineno=0, col_offset=0)

## 32.2.2. Grammaire abstraite

La grammaire abstraite est actuellement définie comme suit :

    -- ASDL's 7 builtin types are:
    -- identifier, int, string, bytes, object, singleton, constant
    --
    -- singleton: None, True or False
    -- constant can be None, whereas None means "no value" for object.

    module Python
    {
        mod = Module(stmt* body)
            | Interactive(stmt* body)
            | Expression(expr body)

            -- not really an actual node but useful in Jython's typesystem.
            | Suite(stmt* body)

        stmt = FunctionDef(identifier name, arguments args,
                           stmt* body, expr* decorator_list, expr? returns)
              | AsyncFunctionDef(identifier name, arguments args,
                                 stmt* body, expr* decorator_list, expr? returns)

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

              | Delete(expr* targets)
              | Assign(expr* targets, 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)
              | AsyncFor(expr target, expr iter, stmt* body, stmt* orelse)
              | While(expr test, stmt* body, stmt* orelse)
              | If(expr test, stmt* body, stmt* orelse)
              | With(withitem* items, stmt* body)
              | AsyncWith(withitem* items, stmt* body)

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

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

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

              -- XXX Jython will be different
              -- col_offset is the byte offset in the utf8 string the parser uses
              attributes (int lineno, int col_offset)

              -- BoolOp() can use left & right?
        expr = BoolOp(boolop op, expr* values)
             | 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)
             | Num(object n) -- a number as a PyObject.
             | Str(string s) -- need to specify raw, unicode, etc?
             | FormattedValue(expr value, int? conversion, expr? format_spec)
             | JoinedStr(expr* values)
             | Bytes(bytes s)
             | NameConstant(singleton value)
             | Ellipsis
             | Constant(constant value)

             -- the following expression can appear in assignment context
             | Attribute(expr value, identifier attr, expr_context ctx)
             | Subscript(expr value, slice 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)

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

        expr_context = Load | Store | Del | AugLoad | AugStore | Param

        slice = Slice(expr? lower, expr? upper, expr? step)
              | ExtSlice(slice* dims)
              | Index(expr value)

        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)

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

        arg = (identifier arg, expr? annotation)
               attributes (int lineno, int col_offset)

        -- keyword arguments supplied to call (NULL identifier for **kwargs)
        keyword = (identifier? arg, expr value)

        -- import name with optional 'as' alias.
        alias = (identifier name, identifier? asname)

        withitem = (expr context_expr, expr? optional_vars)
    }

## 32.2.3. Outils du module `ast`

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

`ast.``parse`(source, filename='<unknown>', mode='exec')

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

  Avertissement

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

`ast.``literal_eval`(node_or_string)

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

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

  Avertissement

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

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

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

  Return the docstring of the given node (which must be a `FunctionDef`, `ClassDef` or `Module` node), or `None` if it has no docstring. If clean is true, clean up the docstring’s indentation with `inspect.cleandoc()`.

`ast.``fix_missing_locations`(node)

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

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

  Incrémente de n le numéro de ligne de chaque nœud dans l’arbre en commençant par le nœud node. C’est utile pour « déplacer du code » à un endroit différent dans un fichier.

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

  Copie le code source (`lineno` et `col_offset`) de l’ancien nœud old_node vers le nouveau nœud new_node si possible, et renvoie new_node.

`ast.``iter_fields`(node)

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

`ast.``iter_child_nodes`(node)

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

`ast.``walk`(node)

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

class `ast.``NodeVisitor`

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

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

  `visit`(node)

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

  `generic_visit`(node)

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

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

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

class `ast.``NodeTransformer`

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

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

  Voici un exemple du transformer qui réécrit les occurrences du dictionnaire (`foo`) en `data['foo']` :

      class RewriteName(NodeTransformer):

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

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

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

  Utilisation typique du transformer :

      node = YourTransformer().visit(node)

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

  Renvoie un dump formaté de l’arbre dans node. C’est principalement utile à des fins de débogage. La chaîne de caractères renvoyée présente les noms et valeurs des champs. Cela rend le code impossible à évaluer, si l’on souhaite évaluer ce code, l’option annotate_fields doit être définie comme `False`. Les attributs comme les numéros de ligne et les décalages de colonne ne sont pas récupérés par défaut. Si l’on souhaite les récupérer, l’option include_attributes peut être définie comme `True`.

Voir aussi

Green Tree Snakes, an external documentation resource, has good details on working with Python ASTs.