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.