ast --- 抽象構文木¶
ソースコード: Lib/ast.py
ast モジュールは、Python アプリケーションで Python の抽象構文木を処理しやすくするものです。抽象構文そのものは、Python のリリースごとに変化する可能性があります。このモジュールを使用すると、現在の文法をプログラム上で知る助けになるでしょう。
抽象構文木を作成するには、 ast.PyCF_ONLY_AST を組み込み関数 compile() のフラグとして渡すか、あるいはこのモジュールで提供されているヘルパー関数 parse() を使います。その結果は、 ast.AST を継承したクラスのオブジェクトのツリーとなります。抽象構文木は組み込み関数 compile() を使って Python コード・オブジェクトにコンパイルすることができます。
抽象文法 (Abstract Grammar)¶
抽象文法は、現在次のように定義されています:
-- 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)
| 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)
}
Node クラス¶
-
class
ast.AST¶ このクラスは全ての AST ノード・クラスの基底です。実際のノード・クラスは 先に 示した
Parser/Python.asdlファイルから派生したものです。これらのクラスは_astC モジュールで定義され、astにもエクスポートし直されています。抽象文法の左辺のシンボル一つずつにそれぞれ一つのクラスがあります (たとえば
ast.stmtやast.expr)。それに加えて、右辺のコンストラクタ一つずつにそれぞれ一つのクラスがあり、これらのクラスは左辺のツリーのクラスを継承しています。たとえば、ast.BinOpはast.exprから継承しています。代替を伴った生成規則 (production rules with alternatives) (別名 "sums") の場合、左辺は抽象クラスとなり、特定のコンストラクタ・ノードのインスタンスのみが作成されます。-
_fields¶ 各具象クラスは属性
_fieldsを持っており、すべての子ノードの名前をそこに保持しています。具象クラスのインスタンスは、各子ノードに対してそれぞれひとつの属性を持っています。この属性は、文法で定義された型となります。たとえば
ast.BinOpのインスタンスはleftという属性を持っており、その型はast.exprです。これらの属性が、文法上 (クエスチョンマークを用いて) オプションであるとマークされている場合は、その値が
Noneとなることもあります。属性が0個以上の複数の値をとりうる場合 (アスタリスクでマークされている場合) は、値は Python のリストで表されます。全ての属性は AST をcompile()でコンパイルする際には存在しなければならず、そして妥当な値でなければなりません。
-
lineno¶ -
col_offset¶ -
end_lineno¶ -
end_col_offset¶ ast.exprやast.stmtのサブクラスのインスタンスはlineno,col_offset,end_lineno, およびend_col_offset属性を持ちます。linenoとend_linenoはソーステキストの範囲を最初と最後の行番号で表し (1 から数え始めるので、最初の行の行番号は 1 となります)、col_offsetとend_col_offsetはノードが生成した最初と最後のトークンの UTF-8 バイトオフセットです。 UTF-8 オフセットはパーサが内部で使用するので記録されます。コンパイラは終了位置を必要としないことに注意してください。このため終了位置は省略可能です。終了位置を示すオフセットは最後のシンボルの 後の位置 になります。例えば一行で書かれた式のソースコードのセグメントは
source_line[node.col_offset : node.end_col_offset]により取得できます。
クラス
ast.Tのコンストラクタは引数を次のように解析します:位置引数があるとすれば、
T._fieldsにあるのと同じだけの個数が無ければなりません。これらの引数はそこにある名前を持った属性として割り当てられます。キーワード引数があるとすれば、それらはその名前の属性にその値を割り当てられます。
たとえば、
ast.UnaryOpノードを生成して属性を埋めるには、次のようにすることができます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
もしくはよりコンパクトにも書けます
node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0), lineno=0, col_offset=0)
-
バージョン 3.8 で変更: ast.Constant が全ての定数に使われるようになりました。
バージョン 3.9 で変更: 単純なインデックスはその値で表現され、幅を持つスライスはタプルで表現されます。
バージョン 3.8 で非推奨: 古いクラスである ast.Num, ast.Str, ast.Bytes, ast.NameConstant および ast.Ellipsis は現バージョンでは利用可能ですが、将来の Python リリースで削除される予定です。それまでは、これらのクラスをインスタンス化すると異なるクラスのインスタンスが返されます。
バージョン 3.9 で非推奨: 古いクラスである ast.Index と ast.ExtSlice は現バージョンでは利用可能ですが、将来の Python リリースで削除される予定です。それまでは、これらのクラスをインスタンス化すると異なるクラスのインスタンスが返されます。
注釈
ここに示されている特定のノードクラスについての記述は、素晴らしい Green Tree Snakes プロジェクトとそのすべての貢献者の成果物をもとにしています。
リテラル¶
-
class
ast.Constant(value)¶ 定数です。
Constantリテラルのvalue属性は定数値を表す Python オブジェクトを保持します。定数として表現される値は数値、文字列、またはNoneのような単純な型のほかに、全ての要素が定数であるイミュータブルなコンテナ型 (tuples および frozensets) も設定可能です。>>> print(ast.dump(ast.parse('123', mode='eval'), indent=4)) Expression( body=Constant(value=123))
-
class
ast.FormattedValue(value, conversion, format_spec)¶ このノードは f-string における単一の書式指定置換フィールドを表現します。文字列が単一の置換フィールドしか持たず、他に何も含まない場合は、ノードは単独で存在できます。そうでない場合は
JoinedStrの一部としてあらわれます。valueは式ツリーのノードのいずれか (リテラル、変数、関数呼び出しなど) です。conversionは整数です:-1: 書式指定なし
115:
!s文字列書式指定114:
!rrepr 書式指定97:
!aascii 書式指定
format_specは値の書式指定を表現するJoinedStrノード、もしくは書式指定がない場合はNoneです。conversionとformat_specを同時に設定することができます。
-
class
ast.JoinedStr(values)¶ FormattedValueノードとConstantノードの集まりからなる f-string です。>>> 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)¶ リストまたはタプルをあらわします。
eltsは内包する要素を表現するノードのリストを保持します。ctxはコンテナが代入のターゲットである場合 (たとえば(x,y)=somethingのような場合) はStoreであり、そうでない場合は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)¶ 集合 (set) をあらわします。
eltsは集合の各要素を表現するノードのリストを保持します。>>> 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)¶ 辞書をあらわします。
keysとvaluesはそれぞれキーと値のノードのリスト を順序が一致した形で (それぞれdictionary.keys()とdictionary.values()を呼び出したときに返される順序で) 保持します。辞書リテラルを使って辞書を展開した場合、展開された式ツリーにおいて辞書は
valuesリストに入り、keysの対応する位置にはNoneが入ります。>>> 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())]))
変数¶
-
class
ast.Name(id, ctx)¶ 変数名をあらわします。
idは変数名を文字列で保持し、ctxは以下に示す型のいずれかです。
-
class
ast.Load¶ -
class
ast.Store¶ -
class
ast.Del¶ 変数の参照は変数の値をロードするか、新しい値を割り当てるか、または値を削除するために使うことができます。変数の参照はこれら3つの場合を区別するためのコンテキストによって与えられます。
>>> 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)¶ *var形式の変数の参照をあらわします。valueは変数、典型的にはNameノード、を保持します。この型は*argsを伴う関数呼び出しノード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=[])
式 (expression)¶
-
class
ast.Expr(value)¶ 関数呼び出しのような式がそれ自身で文となり、戻り値が使われないかまたは保存されないとき、その式はこのコンテナでラップされます。
valueはこの節で説明する他のノード、Constantノード、Nameノード、LambdaノードYieldノードまたは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)¶ 単項演算をあらわします。
opは演算子で、operandは任意の式ツリーのノードです。
-
class
ast.UAdd¶ -
class
ast.USub¶ -
class
ast.Not¶ -
class
ast.Invert¶ 単項演算の演算子をあらわします。
Notは論理否定キーワードnotであり、Invertはビット反転演算子~です。>>> 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は演算子、leftとrightは任意の式ツリーのノードです。>>> 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¶ 二項演算の演算子をあらわします。
-
class
ast.BoolOp(op, values)¶ 'or' や 'and' のような論理演算をあらわします。
opはOrまたはAndです。valuesは必要な値のリストです。a or b or cのように同じ演算子を使う連続した演算は、複数の値を持った単一のノードとして表現されます。notは単項演算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.Compare(left, ops, comparators)¶ 2つ以上の値の比較をあらわします。
left比較の中の最初の値、opsは演算子のリスト、comparatorsは2つ目以降の値のリストです。>>> 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¶ 比較演算の演算子をあらわします。
-
class
ast.Call(func, args, keywords, starargs, kwargs)¶ 関数呼び出しをあらわします。
funcは関数で、多くの場合NameまたはAttributeのオブジェクトです。 関数呼び出しの引数:argsは位置引数のリストを保持します。keywordsはkeywordクラスのオブジェクトのリスト保持し、キーワード引数をあらわします。
Callノードを生成するときにargsとkeywordsは必須ですが、空のリストであってもかまいません。starargsとkwargsはオプション引数です。>>> 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)¶ 関数呼び出しまたはクラス定義のキーワード引数をあらわします。
argはパラメータ名をあらわす文字列、valueは引数に渡す値をあらわすノードです。
-
class
ast.IfExp(test, body, orelse)¶ a if b else cのような式をあらわします。各フィールドは単一のノードを保持します。以下の例では、3つの式ノードはすべて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)¶ たとえば
d.keysのような属性へのアクセスです。valueはノードで、典型的にはNameです。attrは属性名を与える生の文字列で、ctxはその属性がどのように振る舞うかに応じてLoad、StoreまたはDelのいずれかです。>>> 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)¶ 代入式です。この AST ノードは代入式演算子（ウォルラス演算子、または「セイウチ演算子」としても知られています）によって生成されます。第一引数が複数のノードであってもよい
Assignノードと異なり、このノードの場合はtargetとvalueの両方が単一のノードでなければなりません。>>> print(ast.dump(ast.parse('(x := 4)', mode='eval'), indent=4)) Expression( body=NamedExpr( target=Name(id='x', ctx=Store()), value=Constant(value=4)))
配列要素の参照 (Subscripting)¶
-
class
ast.Subscript(value, slice, ctx)¶ l[1]のような配列要素の参照をあらわします。valueは参照元のオブジェクトです (通常シーケンス型またはマッピング型)。sliceはインデックス、スライス、またはキーです。Sliceを含むTupleでもかまいません。ctxは要素の参照により実行されるアクションに応じてLoad、StoreまたはDelのいずれかです。>>> 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)¶ 基本的なスライス操作 (
lower:upperやlower:upper:stepの形式) をあらわします。Subscriptの slice フィールドでの直接指定か、または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()))
内包表記 (Comprehension)¶
-
class
ast.ListComp(elt, generators)¶ -
class
ast.SetComp(elt, generators)¶ -
class
ast.GeneratorExp(elt, generators)¶ -
class
ast.DictComp(key, value, generators)¶ リストや集合の内包表記、ジェネレータ、および辞書の内包表記です。
elt(またはkeyとvalue) は各要素として評価される部品をあらわす単一のノードです。generatorsは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)¶ 内包表記におけるひとつの
for節をあらわします。targetは各要素への参照です - 典型的にはNameまたはTupleノードです。iterはイテレートする対象のオブジェクトです。ifsは条件節のリストです: 各for節は複数のifsを持つことができます。is_asyncは内包表記が非同期であることを示します (async forをforの代わりに使います)。値は整数です (0 または 1)。>>> 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)]))
文 (Statements)¶
-
class
ast.Assign(targets, value, type_comment)¶ 代入です。
targetsはノードのリスト、valueは単一のノードです。targetsの複数のノードは、それぞれに対して同じ値を代入することをあらわします。分割代入はtargets内にTupleまたはListを置くことで表現されます。-
type_comment¶ type_commentはコメントとして型アノテーションをあらわすオプション文字列です。
>>> 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)¶ 型アノテーションを伴う代入です。
targetは単一のノードで、Name,AttributeまたはSubscriptのいずれかです。annotationはConstantやNamenode のようなアノテーションです。valueはオプションで、代入する値を単一のノードであらわしたものです。simple真偽値と解釈される整数で、targetのNameノードが丸かっこに囲まれておらず、したがって式ではなく純粋な名前である場合に True を設定します。>>> 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)¶ a += 1のような累積代入をあらわします。下記の例では、targetは (Storeコンテキストを伴う)xのためのNameノード、opはAdd演算子、そしてvalueは定数1をあらわすConstantノードです。Assignと異なり、target属性は classTupleやListであってはいけません。>>> 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)¶ raise文をあらわします。excは送出される例外オブジェクトで、通常はCallまたはName、 もしくは単独のraiseではNoneを指定します。causeはオプションで、raise x from yのyにあたります。>>> 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)¶ アサーションです。
testはCompareノードなどのような条件を保持します。msgは失敗した時のメッセージを保持します。>>> 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)¶ del文をあらわします。targetsはName,Attribute,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¶ pass文をあらわします。>>> print(ast.dump(ast.parse('pass'), indent=4)) Module( body=[ Pass()], type_ignores=[])
関数またはループの内部でのみ適用可能な他の文は、別のセクションで説明します。
インポート¶
-
class
ast.Import(names)¶ インポート文です。
namesは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)¶ from x import yをあらわします。moduleは 'from' でインポートする先頭がドットでないモジュール名をあらわす文字列か、またはfrom . import fooのような構文の場合はNoneを指定します。levelは相対インポートのレベルを表す整数を保持します (0 は絶対インポートを意味します)。>>> 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)¶ いずれのパラメータも名前をあらわす生の文字列です。
asnameは標準の名前を使う場合は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=[])
制御フロー¶
注釈
else 節のようなオプションの節が存在しない場合は、空のリストとして保存されます。
-
class
ast.If(test, body, orelse)¶ if文です。testはCompareノードなどの単一のノードを保持します。bodyとorelseはそれぞれノードのリストを保持します。elif節は AST において固有の表現を持たず、先行する節をあらわすノードのorelseセクションに追加の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)¶ forループです。targetはループが割り当てる単一または複数の変数をName,TupleまたはListのいずれかを単一のノードで保持します。iterはループ対象の変数を、同じく単一のノードで保持します。bodyとorelseは実行するノードのリストを含んでいます。orelseに含まれるノードは、ループがbreak文によって中断せず、正常終了した場合に実行されます。-
type_comment¶ type_commentはコメントとして型アノテーションをあらわすオプション文字列です。
>>> 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)¶ whileループです。testはCompareのような条件をあらわすノードを保持します。>> 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¶ break文および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)¶ tryブロックです。ExceptHandlerノードのリストであるhandlersを除き、全ての属性はそれぞれの節で実行するノードのリストです。>>> 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.ExceptHandler(type, name, body)¶ 単一の
except節をあらわします。typeはこの節にマッチする例外のタイプで、典型的にはNameノードです (Noneを指定すると全ての例外をキャッチするexcept:節をあらわします)。nameは例外オブジェクトを保持する変数の名前をあらわす生の文字列で、as fooを持たない節の場合はNoneを指定します。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)¶ withブロックです。itemsはwithitemノードのリストで、コンテキストマネージャのリストをあらわします。またbodyはコンテキスト内にインデントされたブロックです。-
type_comment¶ type_commentはコメントとして型アノテーションをあらわすオプション文字列です。
-
-
class
ast.withitem(context_expr, optional_vars)¶ withブロックにおける単一のコンテキストマネージャをあらわします。context_exprはコンテキストマネージャで、しばしばCallノードが設定されます。optional_varsはas fooに相当するName,TupleまたはListのいずれかのノードか、または、この部分が不要な場合は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
matchstatement.subjectholds the subject of the match (the object that is being matched against the cases) andcasescontains an iterable ofmatch_casenodes with the different cases.
-
class
ast.match_case(pattern, guard, body)¶ A single case pattern in a
matchstatement.patterncontains the match pattern that the subject will be matched against. Note that theASTnodes produced for patterns differ from those produced for expressions, even when they share the same syntax.The
guardattribute contains an expression that will be evaluated if the pattern matches the subject.bodycontains 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.
valueis 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.
valueis 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))])])], type_ignores=[])
-
class
ast.MatchSequence(patterns)¶ A match sequence pattern.
patternscontains 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 aMatchStarnode, 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
nameis 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))])])], type_ignores=[])
-
class
ast.MatchMapping(keys, patterns, rest)¶ A match mapping pattern.
keysis a sequence of expression nodes.patternsis a corresponding sequence of pattern nodes.restis 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
restis 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(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.
clsis an expression giving the nominal class to be matched.patternsis a sequence of pattern nodes to be matched against the class defined sequence of pattern matching attributes.kwd_attrsis a sequence of additional attributes to be matched (specified as keyword arguments in the class pattern),kwd_patternsare 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.
patterncontains 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
nameattribute contains the name that will be bound if the pattern is successful. IfnameisNone,patternmust also beNoneand 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
patternsattribute 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=[])
関数およびクラス定義¶
-
class
ast.FunctionDef(name, args, body, decorator_list, returns, type_comment)¶ 関数定義です。
nameは関数名をあらわす生の文字列です。argsは引数をあらわすargumentsノードです。bodyは関数の本体をあらわすノードのリストです。decorator_listは関数に適用されるデコレータのリストで、外側のデコレータがリストの先頭に保存されます (すなわち、リストの先頭にあるデコレータが最後に適用されます)。returnsは戻り値に対する注釈です。
-
type_comment¶ type_commentはコメントとして型アノテーションをあらわすオプション文字列です。
-
class
ast.Lambda(args, body)¶ lambdaは式の中で使うことができる最小限の関数定義です。FunctionDefノードと異なり、bodyは単一のノードとなります。>>> 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)¶ 関数の引数
-
class
ast.arg(arg, annotation, type_comment)¶ 単一の引数をあらわします。
argは引数名をあらわす生の文字列、annotationは、StrやNameノードのような引数に対する注釈です。-
type_comment¶ type_commentはコメントとして型アノテーションをあらわすオプション文字列です。
>>> 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)¶ return文です。>>> 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)¶ yieldまたはyield from式をあらわします。これらは式なので、送り返される値が使われない場合はExprノードでラップされなければなりません。>>> 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)¶ globalおよびnonlocal文です。namesは生の文字列のリストです。>>> 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, starargs, kwargs, body, decorator_list)¶ クラス定義です。
nameはクラス名をあらわす生の文字列です。basesは明示的に指定された基底クラスをあらわすノードのリストです。keywordsはkeywordノードのリストで、主に 'metaclass' の指定のために使います。その他のキーワードは PEP-3115 に従ってメタクラスに渡されます。starargsとkwargsは、関数呼び出しの場合と同様にそれぞれ単一のノードです。 starargs はベースクラスのリストと結合するために展開され、 kwargs はメタクラスに渡されます。bodyはクラス定義に含まれるコードをあらわすノードのリストです。decorator_listはノードのリストで、関数定義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 と await¶
-
class
ast.AsyncFunctionDef(name, args, body, decorator_list, returns, type_comment)¶ async def形式の関数定義です。通常の関数定義FunctionDefと同じフィールドを持ちます。
-
class
ast.Await(value)¶ await式をあらわします。valueは待ち受ける値です。AsyncFunctionDefの本体 (body) の中でのみ有効です。
>>> 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)¶ async forループとasync withコンテキストマネージャです。それぞれForおよびWithと同じフィールドを持ちます。AsyncFunctionDefの本体 (body) の中でのみ有効です。
注釈
文字列が ast.parse() によってパースされたとき、戻り値のツリーに含まれる演算子ノード (ast.operator, ast.unaryop, ast.cmpop, ast.boolop および ast.expr_context のサブクラス) はシングルトンです。したがっていずれかの演算子ノードを変更すると、その変更は他の全ての同じ値 (たとえば ast.Add ノードを変更した場合はその他全ての ast.Add ノード) に反映されます。
ast ヘルパー¶
ノード・クラスの他に、 ast モジュールは以下のような抽象構文木をトラバースするためのユーティリティ関数やクラスも定義しています:
-
ast.parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None)¶ source を解析して AST ノードにします。
compile(source, filename, mode, ast.PyCF_ONLY_AST)と等価です。type_comments=Trueが与えられると、パーサは PEP 484 および PEP 526 で規定された型コメントをチェックし、返すように修正されます。これはast.PyCF_TYPE_COMMENTSを追加したフラグをcompile()に渡すことと等価です。パーサは不適切な場所に配置された型コメントに対してシンタックスエラーをレポートします。 このフラグがない場合、型コメントは無視されて AST ノードのtype_commentフィールドは常にNoneになります。さらに、# type: ignoreコメントの位置はModuleのtype_ignores属性として返されます (それ以外の場合は常に空のリストになります)。さらに
modeが'func_type'の場合、入力構文は、たとえば(str, int) -> List[str]のような PEP 484 の "シグネチャ型コメント (signature type comments)" に対応するように修正されます。また、
feature_versionを(major, minor)のタプルに設定すると、パーサは指定された Python バージョンの文法で構文解析を試みます。今のところmajorは3でなければなりません。たとえば、feature_version=(3, 4)と設定するとasyncとawaitを変数名として使うことが可能になります。 サポートされている最低のバージョンは(3, 4); 最高のバージョンはsys.version_info[0:2]です。If source contains a null character ('0'),
ValueErroris raised.警告
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
SyntaxErrorexceptions. For instance, the sourcereturn 42generates 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.警告
十分に大きい文字列や複雑な文字列によって Python の抽象構文木コンパイラのスタックの深さの限界を越えることで、 Python インタプリタをクラッシュさせることができます。
バージョン 3.8 で変更:
type_comments、mode='func_type'、feature_versionが追加されました。
-
ast.unparse(ast_obj)¶ ast.ASTオブジェクトを逆に構文解析して、ast.parse()が元のast.ASTと等価なオブジェクトを生成できるような文字列を生成します。警告
生成されたコード文字列は、生成元のコードである
ast.ASTオブジェクトと必ずしも等価であるとは限りません (定数タプルや frozenset などに対するコンパイラ最適化なしのコードです)。警告
非常に複雑な式を逆構文解析すると
RecursionErrorとなることがあります。バージョン 3.9 で追加.
-
ast.literal_eval(node_or_string)¶ Python のリテラルやコンテナ表現のみを含む式ノードまたは文字列を評価します。与えられる文字列またはノードは次の Python リテラル構造のみからなるものに限られます: 文字列、バイト列、数、タプル、リスト、辞書、集合、ブール値、
None、Ellipsis。この関数は Python の式を含んだ文字列を、値自身を解析することなしに評価するのに使えます。この関数は、例えば演算や添え字を含んだ任意の複雑な表現を評価するのには使えません。
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.警告
Python の抽象構文木コンパイラのスタックの深さの限界を越えることで、 Python インタプリタをクラッシュさせる可能性があります。
It can raise
ValueError,TypeError,SyntaxError,MemoryErrorandRecursionErrordepending on the malformed input.バージョン 3.2 で変更: バイト列リテラルと集合リテラルが受け取れるようになりました。
バージョン 3.9 で変更:
'set()'による空の集合の生成をサポートするようになりました。バージョン 3.10 で変更: For string inputs, leading spaces and tabs are now stripped.
-
ast.get_docstring(node, clean=True)¶ 与えられた node (これは
FunctionDef,AsyncFunctionDef,ClassDef,Moduleのいずれかのノードでなければなりません) のドキュメント文字列を返します。もしドキュメント文字列が無ければNoneを返します。 clean が真ならば、ドキュメント文字列のインデントをinspect.cleandoc()を用いて一掃します。バージョン 3.5 で変更:
AsyncFunctionDefがサポートされました。
-
ast.get_source_segment(source, node, *, padded=False)¶ source のうちで node を生成したソースコードのセグメントを取得します。位置情報 (
lineno,end_lineno,col_offset, またはend_col_offset) が欠けている場合Noneを返します。padded が
Trueの場合、複数行にわたる文の最初の行が元の位置に一致するように空白文字でパディングされます。バージョン 3.8 で追加.
-
ast.fix_missing_locations(node)¶ compile()はノード・ツリーをコンパイルする際、linenoとcol_offset両属性をサポートする全てのノードに対しそれが存在するものと想定します。生成されたノードに対しこれらを埋めて回るのはどちらかというと退屈な作業なので、このヘルパーが再帰的に二つの属性がセットされていないものに親ノードと同じ値をセットしていきます。再帰の出発点が node です。
-
ast.increment_lineno(node, n=1)¶ node で始まるツリー内の各ノードの行番号と終了行番号を n ずつ増やします。これはファイルの中で別の場所に "コードを移動する" ときに便利です。
-
ast.copy_location(new_node, old_node)¶ ソースの場所 (
lineno,col_offset,end_lineno, およびend_col_offset) を old_node から new_node に可能ならばコピーし、 new_node を返します。
-
ast.iter_fields(node)¶ node にある
node._fieldsのそれぞれのフィールドを(フィールド名, 値)のタプルとして yield します。
-
ast.iter_child_nodes(node)¶ node の直接の子ノード全てを yield します。すなわち、yield されるのは、ノードであるような全てのフィールドおよびノードのリストであるようなフィールドの全てのアイテムです。
-
ast.walk(node)¶ node の全ての子孫ノード(node 自体を含む)を再帰的に yield します。順番は決められていません。この関数はノードをその場で変更するだけで文脈を気にしないような場合に便利です。
-
class
ast.NodeVisitor¶ 抽象構文木を渡り歩いてビジター関数を見つけたノードごとに呼び出すノード・ビジターの基底クラスです。この関数は
visit()メソッドに送られる値を返してもかまいません。このクラスはビジター・メソッドを付け加えたサブクラスを派生させることを意図しています。
-
visit(node)¶ ノードを訪れます。デフォルトの実装では
self.visit_classnameというメソッド (ここで classname はノードのクラス名です) を呼び出すか、そのメソッドがなければgeneric_visit()を呼び出します。
-
generic_visit(node)¶ このビジターはノードの全ての子について
visit()を呼び出します。注意して欲しいのは、専用のビジター・メソッドを具えたノードの子ノードは、このビジターが
generic_visit()を呼び出すかそれ自身で子ノードを訪れない限り訪れられないということです。
トラバースの途中でノードを変化させたいならば
NodeVisitorを使ってはいけません。そうした目的のために変更を許す特別なビジター (NodeTransformer) があります。バージョン 3.8 で非推奨:
visit_Num(),visit_Str(),visit_Bytes(),visit_NameConstant()およびvisit_Ellipsis()の各メソッドは非推奨です。また将来の Python バージョンでは呼び出されなくなります。全ての定数ノードを扱うにはvisit_Constant()を追加してください。-
-
class
ast.NodeTransformer¶ NodeVisitorのサブクラスで抽象構文木を渡り歩きながらノードを変更することを許すものです。NodeTransformerは抽象構文木(AST)を渡り歩き、ビジター・メソッドの戻り値を使って古いノードを置き換えたり削除したりします。ビジター・メソッドの戻り値がNoneならば、ノードはその場から取り去られ、そうでなければ戻り値で置き換えられます。置き換えない場合は戻り値が元のノードそのものであってもかまいません。それでは例を示しましょう。Name (たとえば
foo) を見つけるたび全てdata['foo']に書き換える変換器 (transformer) です:class RewriteName(NodeTransformer): def visit_Name(self, node): return Subscript( value=Name(id='data', ctx=Load()), slice=Constant(value=node.id), ctx=node.ctx )
操作しようとしているノードが子ノードを持つならば、その子ノードの変形も自分で行うか、またはそのノードに対し最初に
generic_visit()メソッドを呼び出すか、それを行うのはあなたの責任だということを肝に銘じましょう。文のコレクションであるようなノード (全ての文のノードが当てはまります) に対して、このビジターは単独のノードではなくノードのリストを返すかもしれません。
NodeTransformerが(たとえば、linenoのような)位置情報を与えずに(元の木の一部ではなく)新しいノードを導入する場合、fix_missing_locations()を新しいサブツリーで呼び出して、位置情報を再計算する必要があります。tree = ast.parse('foo', mode='eval') new_tree = fix_missing_locations(RewriteName().visit(tree))
たいてい、変換器の使い方は次のようになります:
node = YourTransformer().visit(node)
-
ast.dump(node, annotate_fields=True, include_attributes=False, *, indent=None)¶ node 内のツリーのフォーマットされたダンプを返します。主な使い道はデバッグです。 annotate_fields が true の場合 (デフォルト)、返される文字列はフィールドの名前と値を示します。 annotate_fields が false の場合、あいまいさのないフィールド名を省略することにより、結果文字列はよりコンパクトになります。行番号や列オフセットのような属性はデフォルトではダンプされません。これが必要であれば、 include_attributes を true にすると表示できます。
indent が非負の整数または文字列の場合、ツリーは指定されたインデントレベルで整形されて出力されます (pretty-printed)。インデントレベルがゼロ、負の数、または
""の場合は改行だけを挿入します。None(デフォルト値) は単一行での表記になります。正の整数を指定すると各インデントレベルでその数だけの空白でインデントされます。 indent が文字列 ("\t"など) の場合、その文字列が各レベルのインデントに使われます。バージョン 3.9 で変更: indent オプションを追加しました。
コンパイラフラグ¶
以下のフラグはプログラムのコンパイルにおける効果を変更するために compile() に渡すことができます:
-
ast.PyCF_ALLOW_TOP_LEVEL_AWAIT¶ トップレベルの
await,async for,async withおよび async 内包表記のサポートを有効化します。バージョン 3.8 で追加.
-
ast.PyCF_ONLY_AST¶ コンパイルされたコードオブジェクトの代わりに抽象構文木を生成して返します。
コマンドラインからの使用¶
バージョン 3.9 で追加.
ast モジュールはコマンドラインからスクリプトとして実行することができます。実行方法は単純です:
python -m ast [-m <mode>] [-a] [infile]
以下のオプションが使用できます:
-
-h,--help¶ ヘルプメッセージを表示して終了します。
-
--no-type-comments¶ 型コメントをパースしません。
-
-a,--include-attributes¶ 行番号や列オフセットなどの属性を含めます。
infile を指定するとその内容が AST にパースされて標準出力に出力されます。そうでない場合は標準入力から入力を読み込みます。
参考
外部ドキュメント Green Tree Snakes には Python AST についての詳細が書かれています。
ASTTokens は Python AST を、生成元のソースコードのトークン位置やテキストで注解します。これはソースコード変換を行うツールで有用です。
leoAst.py は ast ノードとトークンの間の双方向リンクを挿入することにより、Python プログラムに対するトークンベースの視点と構文木ベースの視点を統合します。
LibCST はコードを ast ツリーに似た構文木 (Concrete Syntax Tree) にパースし、かつ全ての書式設定の詳細を保持します。これは自動リファクタリングアプリケーション (codemod) やリンタを作成する際に有用です。
Parso はエラーリカバリや異なる Python バージョン (複数の Python バージョン) での復元可能なパース (round-trip parsing) をサポートします。また、 Parso は Python ファイル内の複数の文法エラーをリストすることもできます。