32.2. "ast" — Arbres Syntaxiques Abstraits
******************************************

Nouveau dans la version 2.5: The low-level "_ast" module containing
only the node classes.

Nouveau dans la version 2.6: The high-level "ast" module containing
all helpers.

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

   Nouveau dans la version 2.6: The constructor as explained above was
   added.  In Python 2.5 nodes had to be created by calling the class
   constructor without arguments and setting the attributes
   afterwards.


32.2.2. Grammaire abstraite
===========================

The module defines a string constant "__version__" which is the
decimal Subversion revision number of the file shown below.

La grammaire abstraite est actuellement définie comme suit :

   -- ASDL's five builtin types are identifier, int, string, object, bool

   module Python version "$Revision$"
   {
   	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)
   	      | ClassDef(identifier name, expr* bases, stmt* body, expr* decorator_list)
   	      | Return(expr? value)

   	      | Delete(expr* targets)
   	      | Assign(expr* targets, expr value)
   	      | AugAssign(expr target, operator op, expr value)

   	      -- not sure if bool is allowed, can always use int
    	      | Print(expr? dest, expr* values, bool nl)

   	      -- use 'orelse' because else is a keyword in target languages
   	      | For(expr target, expr iter, stmt* body, stmt* orelse)
   	      | While(expr test, stmt* body, stmt* orelse)
   	      | If(expr test, stmt* body, stmt* orelse)
   	      | With(expr context_expr, expr? optional_vars, stmt* body)

   	      -- 'type' is a bad name
   	      | Raise(expr? type, expr? inst, expr? tback)
   	      | TryExcept(stmt* body, excepthandler* handlers, stmt* orelse)
   	      | TryFinally(stmt* body, stmt* finalbody)
   	      | Assert(expr test, expr? msg)

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

   	      -- Doesn't capture requirement that locals must be
   	      -- defined if globals is
   	      -- still supports use as a function!
   	      | Exec(expr body, expr? globals, expr? locals)

   	      | Global(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
   	     | Yield(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,
   			 expr? starargs, expr? kwargs)
   	     | Repr(expr value)
   	     | Num(object n) -- a number as a PyObject.
   	     | Str(string s) -- need to specify raw, unicode, etc?
   	     -- other literals? bools?

   	     -- the following expression can appear in assignment context
   	     | Attribute(expr value, identifier attr, expr_context ctx)
   	     | Subscript(expr value, slice slice, 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 = Ellipsis | Slice(expr? lower, expr? upper, expr? step) 
   	      | ExtSlice(slice* dims) 
   	      | Index(expr value) 

   	boolop = And | Or 

   	operator = Add | Sub | Mult | 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)

   	-- not sure what to call the first argument for raise and except
   	excepthandler = ExceptHandler(expr? type, expr? name, stmt* body)
   	                attributes (int lineno, int col_offset)

   	arguments = (expr* args, identifier? vararg, 
   		     identifier? kwarg, expr* defaults)

           -- keyword arguments supplied to call
           keyword = (identifier arg, expr value)

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


32.2.3. Outils du module "ast"
==============================

Nouveau dans la version 2.6.

Apart from the node classes, "ast" module defines these utility
functions and classes for traversing abstract syntax trees:

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: It is possible to crash the Python interpreter
     with a sufficiently large/complex string due to stack depth
     limitations in Python’s AST compiler.

ast.literal_eval(node_or_string)

   Safely evaluate an expression node or a Unicode or *Latin-1*
   encoded string containing a Python literal or container display.
   The string or node provided may only consist of the following
   Python literal structures: strings, numbers, tuples, lists, dicts,
   booleans, and "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: It is possible to crash the Python interpreter
     with a sufficiently large/complex string due to stack depth
     limitations in Python’s AST compiler.

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