ast
--- Abstract Syntax Trees¶
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, type_param* type_params)
| AsyncFunctionDef(identifier name, arguments args,
stmt* body, expr* decorator_list, expr? returns,
string? type_comment, type_param* type_params)
| ClassDef(identifier name,
expr* bases,
keyword* keywords,
stmt* body,
expr* decorator_list,
type_param* type_params)
| Return(expr? value)
| Delete(expr* targets)
| Assign(expr* targets, expr value, string? type_comment)
| TypeAlias(expr name, type_param* type_params, expr value)
| AugAssign(expr target, operator op, expr value)
-- 'simple' indicates that we annotate simple name without parens
| AnnAssign(expr target, expr annotation, expr? value, int simple)
-- use 'orelse' because else is a keyword in target languages
| For(expr target, expr iter, stmt* body, stmt* orelse, 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)
type_param = TypeVar(identifier name, expr? bound, expr? default_value)
| ParamSpec(identifier name, expr? default_value)
| TypeVarTuple(identifier name, expr? default_value)
attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)
}
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 inast
.Il y a une classe définie pour chacun des symboles présents à gauche dans la grammaire abstraite (par exemple
ast.stmt
ouast.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 classeast.BinOp
hérite de la classeast.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¶
Each concrete class has an attribute
_fields
which gives the names of all child nodes.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 attributleft
de typeast.expr
.Si un attribut est marqué comme optionnel dans la grammaire (avec un point d'interrogation
?
), sa valeur peut êtreNone
. 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 aveccompile()
.
- _field_types¶
The
_field_types
attribute on each concrete class is a dictionary mapping field names (as also listed in_fields
) to their types.>>> ast.TypeVar._field_types {'name': <class 'str'>, 'bound': ast.expr | None, 'default_value': ast.expr | None}
Ajouté dans la version 3.13.
- lineno¶
- col_offset¶
- end_lineno¶
- end_col_offset¶
Instances of
ast.expr
andast.stmt
subclasses havelineno
,col_offset
,end_lineno
, andend_col_offset
attributes. Thelineno
andend_lineno
are the first and last line numbers of source text span (1-indexed so the first line is line 1) and thecol_offset
andend_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 utilisernode = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0), lineno=0, col_offset=0)
If a field that is optional in the grammar is omitted from the constructor, it defaults to
None
. If a list field is omitted, it defaults to the empty list. If a field of typeast.expr_context
is omitted, it defaults toLoad()
. If any other field is omitted, aDeprecationWarning
is raised and the AST node will not have this field. In Python 3.15, this condition will raise an error.
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.
Deprecated since version 3.13, will be removed in version 3.15: Previous versions of Python allowed the creation of AST nodes that were missing required fields. Similarly, AST node constructors allowed arbitrary keyword arguments that were set as attributes of the AST node, even if they did not match any of the fields of the AST node. This behavior is deprecated and will be removed in Python 3.15.
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 alist
of the module's Instructions.type_ignores
is alist
of the module's type ignore comments; seeast.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))])
- 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 alist
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 alist
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()))
Ajouté 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 vautNone
. 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
etConstant
.>>> 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())]), 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 deLoad
.>>> 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()
etdictionnaire.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()))]) >>> print(ast.dump(ast.parse('a = 1'), indent=4)) Module( body=[ Assign( targets=[ Name(id='a', ctx=Store())], value=Constant(value=1))]) >>> print(ast.dump(ast.parse('del a'), indent=4)) Module( body=[ Delete( targets=[ Name(id='a', ctx=Del())])])
- 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 exemplefonction(*args)
; voir aussiCall
).>>> 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()))])
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
etYieldFrom
.>>> print(ast.dump(ast.parse('-a'), indent=4)) Module( body=[ Expr( value=UnaryOp( op=USub(), operand=Name(id='a', ctx=Load())))])
- 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
ouor
, entre op et les éléments de values. Les deux opérateurs sont distingués par le type de op, à savoirAnd
ouOr
. Les applications successives du même opérateur (commea 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 dansUnaryOp
.>>> 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.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
ouAttribute
. Les arguments sont contenus dans :args, la liste des arguments passés sans les nommer (arguments positionnels) ;
keywords
holds a list ofkeyword
objects representing arguments passed by keyword.
The
args
andkeywords
arguments are optional and default to 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 classeName
.>>> 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 classeName
. attr est le nom de l'attribut, sous forme de chaîne de caractères. ctx est de classeLoad
,Store
ouDel
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)))
Ajouté dans la version 3.8.
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 deTuple
pour slice peuvent contenir des objetsSlice
. ctx est de typeLoad
,Store
ouDel
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
oudébut:fin:pas
). Les instances de cette classe ne peuvent apparaître que dans le champ slice d'unSubscript
, que ce soit directement ou en tant qu'élément d'unTuple
.>>> 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()), 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()), 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()), 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œudName
ouTuple
). ifs contient les tests qui décident si l'élément doit être inséré. C'est une liste, car chaquefor
peut être suivi de plusieursif
.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 defor
.>>> 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())]), generators=[ comprehension( target=Name(id='line', ctx=Store()), iter=Name(id='file', ctx=Load()), is_async=0), comprehension( target=Name(id='c', ctx=Store()), iter=Name(id='line', ctx=Load()), 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()), 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
ouList
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))]) >>> 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()))])
- class ast.AnnAssign(target, annotation, value, simple)¶
An assignment with a type annotation.
target
is a single node and can be aName
, anAttribute
or aSubscript
.annotation
is the annotation, such as aConstant
orName
node.value
is a single optional node.simple
is always either 0 (indicating a "complex" target) or 1 (indicating a "simple" target). A "simple" target consists solely of aName
node that does not appear between parentheses; all other targets are considered complex. Only simple targets appear in the__annotations__
dictionary of modules and classes.>>> 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)]) >>> 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)]) >>> 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)]) >>> 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)])
- class ast.AugAssign(target, op, value)¶
Affectation incrémentale, par exemple
a += 1
. Dans l'exemple qui suit, target est un nœud de typeName
avec le nom'x'
(de contexteStore
), op est une instance deAdd
, et value est un nœudConstant
contenant la valeur 1.The
target
attribute cannot be of classTuple
orList
, unlike the targets ofAssign
.>>> print(ast.dump(ast.parse('x += 2'), indent=4)) Module( body=[ AugAssign( target=Name(id='x', ctx=Store()), op=Add(), value=Constant(value=2))])
- class ast.Raise(exc, cause)¶
Instruction
raise
. exc est l'exception à lever, la plupart du temps un nœud de typeCall
ouName
. Ce champ vautNone
dans le cas d'unraise
sans rien d'autre. Le champ facultatif cause correspond à la partie après lefrom
dansraise ... 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()))])
- 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()))])
- 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 typeName
,Attribute
ouSubscript
.>>> 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())])])
- class ast.Pass¶
Instruction
pass
.>>> print(ast.dump(ast.parse('pass'), indent=4)) Module( body=[ Pass()])
- class ast.TypeAlias(name, type_params, value)¶
A type alias created through the
type
statement.name
is the name of the alias,type_params
is a list of type parameters, andvalue
is the value of the type alias.>>> print(ast.dump(ast.parse('type Alias = int'), indent=4)) Module( body=[ TypeAlias( name=Name(id='Alias', ctx=Store()), value=Name(id='int', ctx=Load()))])
Ajouté dans la version 3.12.
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œudsalias
.>>> print(ast.dump(ast.parse('import x,y,z'), indent=4)) Module( body=[ Import( names=[ alias(name='x'), alias(name='y'), alias(name='z')])])
- class ast.ImportFrom(module, names, level)¶
Instruction
from ... import ...
. La partie aprèsfrom
est mise dans module comme une simple chaîne de caractères. Dans le cas des importations relatives, commefrom ..module import quelque_chose
, module ne contient pas les points au début. Dans les instructions de la formefrom . import toto
, module vautNone
. 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)])
- 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 sansas
(où le module n'est pas renommé), asname vautNone
.>>> 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)])
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 deCompare
. body est la liste des instructions du bloc. orelse contient les instructions dans leelse
(liste vide s'il n'y a pas deelse
).Les clauses
elif
ne possèdent pas de représentation particulière. Elles sont simplement mises dans le orelse duif
ouelif
précédent, comme nœuds de typeIf
.>>> 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))])])])
- class ast.For(target, iter, body, orelse, type_comment)¶
A
for
loop.target
holds the variable(s) the loop assigns to, as a singleName
,Tuple
,List
,Attribute
orSubscript
node.iter
holds the item to be looped over, again as a single node.body
andorelse
contain lists of nodes to execute. Those inorelse
are executed if the loop finishes normally, rather than via abreak
statement.- 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))])])
- class ast.While(test, body, orelse)¶
Boucle
while
. test est la condition évaluée à chaque itération, par exemple un nœudCompare
. body contient les instructions du bloc, et orelse celles d'un éventuel blocelse
, exécuté lorsque la boucle termine parce que la condition devient fausse et non pas à cause d'une instructionbreak
.>> 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))])])
- class ast.Break¶
- class ast.Continue¶
Instructions
break
etcontinue
.>>> 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()])])])
- 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œudsExceptHandler
, un parexcept
. Les listes orelse et finalbody contiennent respectivement les instructions se trouvant dans d'éventuels blocselse
etfinally
.>>> 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))])])
- class ast.TryStar(body, handlers, orelse, finalbody)¶
try
blocks which are followed byexcept*
clauses. The attributes are the same as forTry
but theExceptHandler
nodes inhandlers
are interpreted asexcept*
blocks rather thenexcept
.>>> 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))])])])
Ajouté dans la version 3.11.
- 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œudName
ou bienNone
(cette dernière valeur pour les clauses fourre-toutexcept:
). 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 deas
). Les instructions sous leexcept
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()])])])
- class ast.With(items, body, type_comment)¶
Bloc
with
. Les gestionnaires de contexte sont stockés dans items comme instances dewithitem
. Les instructions sous lewith
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 deCall
. S'il y a affectation avecas
, optional_vars contient sa cible, qui est un nœud de typeName
,Tuple
ouList
. Sinon, optional_vars vautNone
.>>> 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())]))])])
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) andcases
contains an iterable ofmatch_case
nodes with the different cases.Ajouté dans la version 3.10.
- 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 theAST
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())), body=[ Expr( value=Constant(value=Ellipsis))])])])
Ajouté dans la version 3.10.
- 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))])])])
Ajouté dans la version 3.10.
- class ast.MatchSingleton(value)¶
A match literal pattern that compares by identity.
value
is the singleton to be compared against:None
,True
, orFalse
. 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))])])])
Ajouté dans la version 3.10.
- 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 aMatchStar
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))])])])
Ajouté dans la version 3.10.
- class ast.MatchStar(name)¶
Matches the rest of the sequence in a variable length match sequence pattern. If
name
is notNone
, 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))])])])
Ajouté dans la version 3.10.
- 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 notNone
, 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(rest='rest'), body=[ Expr( value=Constant(value=Ellipsis))])])])
Ajouté dans la version 3.10.
- 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))]), body=[ Expr( value=Constant(value=Ellipsis))]), match_case( pattern=MatchClass( cls=Name(id='Point3D', ctx=Load()), 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))])])])
Ajouté dans la version 3.10.
- 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 isNone
, 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. Ifname
isNone
,pattern
must also beNone
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))])])])
Ajouté dans la version 3.10.
- 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))])])])
Ajouté dans la version 3.10.
Type parameters¶
Type parameters can exist on classes, functions, and type aliases.
- class ast.TypeVar(name, bound, default_value)¶
A
typing.TypeVar
.name
is the name of the type variable.bound
is the bound or constraints, if any. Ifbound
is aTuple
, it represents constraints; otherwise it represents the bound.default_value
is the default value; if theTypeVar
has no default, this attribute will be set toNone
.>>> print(ast.dump(ast.parse("type Alias[T: int = bool] = list[T]"), indent=4)) Module( body=[ TypeAlias( name=Name(id='Alias', ctx=Store()), type_params=[ TypeVar( name='T', bound=Name(id='int', ctx=Load()), default_value=Name(id='bool', ctx=Load()))], value=Subscript( value=Name(id='list', ctx=Load()), slice=Name(id='T', ctx=Load()), ctx=Load()))])
Ajouté dans la version 3.12.
Modifié dans la version 3.13: Added the default_value parameter.
- class ast.ParamSpec(name, default_value)¶
A
typing.ParamSpec
.name
is the name of the parameter specification.default_value
is the default value; if theParamSpec
has no default, this attribute will be set toNone
.>>> print(ast.dump(ast.parse("type Alias[**P = (int, str)] = Callable[P, int]"), indent=4)) Module( body=[ TypeAlias( name=Name(id='Alias', ctx=Store()), type_params=[ ParamSpec( name='P', default_value=Tuple( elts=[ Name(id='int', ctx=Load()), Name(id='str', ctx=Load())], ctx=Load()))], value=Subscript( value=Name(id='Callable', ctx=Load()), slice=Tuple( elts=[ Name(id='P', ctx=Load()), Name(id='int', ctx=Load())], ctx=Load()), ctx=Load()))])
Ajouté dans la version 3.12.
Modifié dans la version 3.13: Added the default_value parameter.
- class ast.TypeVarTuple(name, default_value)¶
A
typing.TypeVarTuple
.name
is the name of the type variable tuple.default_value
is the default value; if theTypeVarTuple
has no default, this attribute will be set toNone
.>>> print(ast.dump(ast.parse("type Alias[*Ts = ()] = tuple[*Ts]"), indent=4)) Module( body=[ TypeAlias( name=Name(id='Alias', ctx=Store()), type_params=[ TypeVarTuple( name='Ts', default_value=Tuple(ctx=Load()))], value=Subscript( value=Name(id='tuple', ctx=Load()), slice=Tuple( elts=[ Starred( value=Name(id='Ts', ctx=Load()), ctx=Load())], ctx=Load()), ctx=Load()))])
Ajouté dans la version 3.12.
Modifié dans la version 3.13: Added the default_value parameter.
Définition de fonctions et de classes¶
- class ast.FunctionDef(name, args, body, decorator_list, returns, type_comment, type_params)¶
Définition d'une fonction.
name donne le nom de la fonction sous forme d'une chaîne de caractères.
args
is anarguments
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_params
is a list of type parameters.
- 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.
Modifié dans la version 3.12: Added
type_params
.
- 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 dearguments
qui contient les arguments de la signature.>>> print(ast.dump(ast.parse('lambda x,y: ...'), indent=4)) Module( body=[ Expr( value=Lambda( args=arguments( args=[ arg(arg='x'), arg(arg='y')]), body=Constant(value=Ellipsis)))])
- 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 aName
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( 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'))])
- 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))])
- class ast.Yield(value)¶
- class ast.YieldFrom(value)¶
A
yield
oryield from
expression. Because these are expressions, they must be wrapped in anExpr
node if the value sent back is not used.>>> print(ast.dump(ast.parse('yield x'), indent=4)) Module( body=[ Expr( value=Yield( value=Name(id='x', ctx=Load())))]) >>> print(ast.dump(ast.parse('yield from x'), indent=4)) Module( body=[ Expr( value=YieldFrom( value=Name(id='x', ctx=Load())))])
- class ast.Global(names)¶
- class ast.Nonlocal(names)¶
Instruction
global
ounonlocal
. 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'])]) >>> print(ast.dump(ast.parse('nonlocal x,y,z'), indent=4)) Module( body=[ Nonlocal( names=[ 'x', 'y', 'z'])])
- class ast.ClassDef(name, bases, keywords, body, decorator_list, type_params)¶
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 ofkeyword
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
.type_params
is a list of type parameters.
>>> 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())])])
Modifié dans la version 3.12: Added
type_params
.
async
et await
¶
- class ast.AsyncFunctionDef(name, args, body, decorator_list, returns, type_comment, type_params)¶
Fonction déclarée avec
async def
. Les champs sont les mêmes que dansFunctionDef
.Modifié dans la version 3.12: Added
type_params
.
- class ast.Await(value)¶
Expression
await
, qui attend value. Ces nœuds ne peuvent apparaître qu'à l'intérieur deAsyncFunctionDef
.
>>> print(ast.dump(ast.parse("""\
... async def f():
... await other_func()
... """), indent=4))
Module(
body=[
AsyncFunctionDef(
name='f',
args=arguments(),
body=[
Expr(
value=Await(
value=Call(
func=Name(id='other_func', ctx=Load()))))])])
- class ast.AsyncFor(target, iter, body, orelse, type_comment)¶
- class ast.AsyncWith(items, body, type_comment)¶
Instruction
async for
ouasync with
. Les champs sont les mêmes que ceux deFor
etWith
. Ces nœuds ne peuvent apparaître qu'à l'intérieur deAsyncFunctionDef
.
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, optimize=-1)¶
Parse the source into an AST node. Equivalent to
compile(source, filename, mode, flags=FLAGS_VALUE, optimize=optimize)
, whereFLAGS_VALUE
isast.PyCF_ONLY_AST
ifoptimize <= 0
andast.PyCF_OPTIMIZED_AST
otherwise.If
type_comments=True
is given, the parser is modified to check and return type comments as specified by PEP 484 and PEP 526. This is equivalent to addingast.PyCF_TYPE_COMMENTS
to the flags passed tocompile()
. This will report syntax errors for misplaced type comments. Without this flag, type comments will be ignored, and thetype_comment
field on selected AST nodes will always beNone
. In addition, the locations of# type: ignore
comments will be returned as thetype_ignores
attribute ofModule
(otherwise it is always an empty list).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, settingfeature_version=(3, 9)
will attempt to disallow parsing ofmatch
statements. Currentlymajor
must equal to3
. The lowest supported version is(3, 7)
(and this may increase in future Python versions); the highest issys.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 tofeature_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 sourcereturn 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.Modifié dans la version 3.13: The minimum supported version for
feature_version
is now(3, 7)
. Theoptimize
argument was added.
- 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 arbreast.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.Ajouté 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
andEllipsis
.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
andRecursionError
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
orModule
), ouNone
s'il n'a pas de docstring. Si clean est vrai, cette fonction nettoie l'indentation de la docstring avecinspect.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
, orend_col_offset
) is missing, returnNone
.If padded is
True
, the first line of a multi-line statement will be padded with spaces to match its original position.Ajouté dans la version 3.8.
- ast.fix_missing_locations(node)¶
When you compile a node tree with
compile()
, the compiler expectslineno
andcol_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
, andend_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 denode._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, ougeneric_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()
andvisit_Ellipsis()
are deprecated now and will not be called in future Python versions. Add thevisit_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 estNone
, 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
endata['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 aslineno
),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, show_empty=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
.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 deNone
, la sortie tient sur une seule ligne.If show_empty is
False
(the default), empty lists and fields that areNone
will be omitted from the output.Modifié dans la version 3.9: ajout du paramètre indent.
Modifié dans la version 3.13: Added the show_empty option.
>>> print(ast.dump(ast.parse("""\ ... async def f(): ... await other_func() ... """), indent=4, show_empty=True)) 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_params=[])], type_ignores=[])
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.Ajouté 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_OPTIMIZED_AST¶
The returned AST is optimized according to the optimize argument in
compile()
orast.parse()
.Ajouté dans la version 3.13.
Utilisation en ligne de commande¶
Ajouté 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.
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 is a Python parser that supports error recovery and round-trip parsing for different Python versions (in multiple Python versions). Parso is also able to list multiple syntax errors in your Python file.