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


Les classes nœud
================

class ast.AST

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

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

   _fields

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

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

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

   lineno
   col_offset
   end_lineno
   end_col_offset

      Instances of "ast.expr" and "ast.stmt" subclasses have "lineno",
      "col_offset", "lineno", and "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 "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".

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
meanwhile, instantiating them will return an instance of a different
class.


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

La grammaire abstraite est actuellement définie comme suit :

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

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

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

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

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

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

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

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

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

             -- XXX Jython will be different
             -- 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, 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, int? end_lineno, int? end_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, 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)

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

       withitem = (expr context_expr, expr? optional_vars)

       type_ignore = TypeIgnore(int lineno, string tag)
   }


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

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

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

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

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

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

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

   Avertissement:

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

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

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

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

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

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

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

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

   Nouveau dans la version 3.8.

ast.fix_missing_locations(node)

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

ast.increment_lineno(node, n=1)

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

ast.copy_location(new_node, old_node)

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

ast.iter_fields(node)

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

ast.iter_child_nodes(node)

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

ast.walk(node)

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

class ast.NodeVisitor

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

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

   visit(node)

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

   generic_visit(node)

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

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

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

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

class ast.NodeTransformer

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

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

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

      class RewriteName(NodeTransformer):

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

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

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

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

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

   Utilisation typique du *transformer* :

      node = YourTransformer().visit(node)

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

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

Voir aussi:

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

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

  leoAst.py unifies the token-based and parse-tree-based views of
  python programs by inserting two-way links between tokens and ast
  nodes.

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

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