ast — Arbres Syntaxiques Abstraits

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

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

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

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

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)

Affectation accompagnée d'une annotation de type. La cible target est un nœud de type Name, Attribute ou Subscript. annotation est le contenu de l'annotation, par exemple un nœud Constant ou Name. Le champ value est facultatif et peut contenir un nœud, la valeur affectée à la cible. simple est une valeur booléenne sous forme d'entier, 0 ou 1, qui vaut 1 si et seulement si target est de type Name et provient d'un nom sans parenthèses, donc un nom simple plutôt qu'une expression.

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

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)

Boucle for. Elle porte sur l'itérable donné par le nœud iter. La cible des affectations successives est target, qui est un nœud de type Name, Tuple ou List. Les instructions du bloc for forment la liste body. Celles de la liste orelse proviennent d'une éventuelle clause else et sont exécutées si la boucle se termine par épuisement de l'itérable, et non pas par un break.

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

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

Définition de fonctions et de classes

class ast.FunctionDef(name, args, body, decorator_list, returns, type_comment)

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

Expression yield ou yield from. Ce sont bien des expressions, non pas des instructions. Il faut donc les placer dans un nœud Expr si la valeur qu'elles renvoient n'est pas utilisée dans une expression plus large.

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

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.

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

async et await

class ast.AsyncFunctionDef(name, args, body, decorator_list, returns, type_comment)

Fonction déclarée avec async def. Les champs sont les mêmes que dans FunctionDef.

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

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

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

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

Nouveau dans la version 3.8.

Utilisation en ligne de commande

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