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, 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)
}
Node クラス¶
- class ast.AST¶
このクラスは全ての AST ノード・クラスの基底です。実際のノード・クラスは 先に 示した
Parser/Python.asdl
ファイルから派生したものです。これらのクラスは_ast
C モジュールで定義され、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()
でコンパイルする際には存在しなければならず、そして妥当な値でなければなりません。
- _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}
Added in version 3.13.
- 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(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.
バージョン 3.8 で変更: ast.Constant
が全ての定数に使われるようになりました。
バージョン 3.9 で変更: 単純なインデックスはその値で表現され、幅を持つスライスはタプルで表現されます。
バージョン 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.
バージョン 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.
注釈
ここに示されている特定のノードクラスについての記述は、素晴らしい Green Tree Snakes プロジェクトとそのすべての貢献者の成果物をもとにしています。
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 文 (Statements).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 対話モード. 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()))
Added in version 3.8.
リテラル¶
- 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:
!r
repr 書式指定97:
!a
ascii 書式指定
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())]), 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()))]) >>> 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)¶
*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()))])
式 (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())))])
- 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)¶
関数呼び出しをあらわします。
func
は関数で、多くの場合Name
またはAttribute
のオブジェクトです。 関数呼び出しの引数:args
は位置引数のリストを保持します。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)¶
関数呼び出しまたはクラス定義のキーワード引数をあらわします。
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)))
Added in version 3.8.
配列要素の参照 (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()), 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)¶
内包表記におけるひとつの
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())]), 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)]))
文 (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))]) >>> 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)¶
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))])
- 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()))])
- 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()))])
- 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())])])
- class ast.Pass¶
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()))])
Added in version 3.12.
関数またはループの内部でのみ適用可能な他の文は、別のセクションで説明します。
インポート¶
- 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')])])
- 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)])
- 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)])
制御フロー¶
注釈
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))])])])
- 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¶
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))])])
- 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))])])
- 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()])])])
- 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))])])
- 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))])])])
Added in version 3.11.
- 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()])])])
- 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())]))])])
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.Added in 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))])])])
Added in 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))])])])
Added in 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))])])])
Added in 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))])])])
Added in 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))])])])
Added in 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))])])])
Added in 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))])])])
Added in 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))])])])
Added in 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))])])])
Added in 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()))])
Added in version 3.12.
バージョン 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()))])
Added in version 3.12.
バージョン 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()))])
Added in version 3.12.
バージョン 3.13 で変更: Added the default_value parameter.
関数およびクラス定義¶
- class ast.FunctionDef(name, args, body, decorator_list, returns, type_comment, type_params)¶
関数定義です。
name
は関数名をあらわす生の文字列です。args
は引数をあらわすarguments
ノードです。body
は関数の本体をあらわすノードのリストです。decorator_list
は関数に適用されるデコレータのリストで、外側のデコレータがリストの先頭に保存されます (すなわち、リストの先頭にあるデコレータが最後に適用されます)。returns
は戻り値に対する注釈です。type_params
is a list of type parameters.
- type_comment¶
type_comment
はコメントとして型アノテーションをあらわすオプション文字列です。
バージョン 3.12 で変更: Added
type_params
.
- 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( args=[ arg(arg='x'), arg(arg='y')]), body=Constant(value=Ellipsis)))])
- class ast.arguments(posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, 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¶
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( 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)¶
return
文です。>>> 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)¶
global
およびnonlocal
文です。names
は生の文字列のリストです。>>> 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)¶
クラス定義です。
name
はクラス名をあらわす生の文字列です。bases
は明示的に指定された基底クラスをあらわすノードのリストです。keywords
is a list ofkeyword
nodes, principally for 'metaclass'. Other keywords will be passed to the metaclass, as per PEP 3115.body
はクラス定義に含まれるコードをあらわすノードのリストです。decorator_list
はノードのリストで、関数定義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())])])
バージョン 3.12 で変更: Added
type_params
.
async と await¶
- class ast.AsyncFunctionDef(name, args, body, decorator_list, returns, type_comment, type_params)¶
async def
形式の関数定義です。通常の関数定義FunctionDef
と同じフィールドを持ちます。バージョン 3.12 で変更: Added
type_params
.
- 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(),
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)¶
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, 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).さらに
mode
が'func_type'
の場合、入力構文は、たとえば(str, int) -> List[str]
のような PEP 484 の "シグネチャ型コメント (signature type comments)" に対応するように修正されます。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.警告
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.警告
十分に大きい文字列や複雑な文字列によって Python の抽象構文木コンパイラのスタックの深さの限界を越えることで、 Python インタプリタをクラッシュさせることができます。
バージョン 3.8 で変更:
type_comments
、mode='func_type'
、feature_version
が追加されました。バージョン 3.13 で変更: The minimum supported version for
feature_version
is now(3, 7)
. Theoptimize
argument was added.
- ast.unparse(ast_obj)¶
ast.AST
オブジェクトを逆に構文解析して、ast.parse()
が元のast.AST
と等価なオブジェクトを生成できるような文字列を生成します。警告
生成されたコード文字列は、生成元のコードである
ast.AST
オブジェクトと必ずしも等価であるとは限りません (定数タプルや frozenset などに対するコンパイラ最適化なしのコードです)。警告
非常に複雑な式を逆構文解析すると
RecursionError
となることがあります。Added in version 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
,MemoryError
andRecursionError
depending 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)¶
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
.padded が
True
の場合、複数行にわたる文の最初の行が元の位置に一致するように空白文字でパディングされます。Added in 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)¶
node で始まるツリー内の各ノードの行番号と終了行番号を n ずつ増やします。これはファイルの中で別の場所に "コードを移動する" ときに便利です。
- 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)¶
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()
を呼び出すかそれ自身で子ノードを訪れない限り訪れられないということです。
- visit_Constant(node)¶
Handles all constant nodes.
トラバースの途中でノードを変化させたいならば
NodeVisitor
を使ってはいけません。そうした目的のために変更を許す特別なビジター (NodeTransformer
) があります。バージョン 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¶
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 )
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.文のコレクションであるようなノード (全ての文のノードが当てはまります) に対して、このビジターは単独のノードではなくノードのリストを返すかもしれません。
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))
たいてい、変換器の使い方は次のようになります:
node = YourTransformer().visit(node)
- ast.dump(node, annotate_fields=True, include_attributes=False, *, indent=None, show_empty=False)¶
node 内のツリーのフォーマットされたダンプを返します。主な使い道はデバッグです。 annotate_fields が true の場合 (デフォルト)、返される文字列はフィールドの名前と値を示します。 annotate_fields が false の場合、あいまいさのないフィールド名を省略することにより、結果文字列はよりコンパクトになります。行番号や列オフセットのような属性はデフォルトではダンプされません。これが必要であれば、 include_attributes を true にすると表示できます。
indent が非負の整数または文字列の場合、ツリーは指定されたインデントレベルで整形されて出力されます (pretty-printed)。インデントレベルがゼロ、負の数、または
""
の場合は改行だけを挿入します。None
(デフォルト値) は単一行での表記になります。正の整数を指定すると各インデントレベルでその数だけの空白でインデントされます。 indent が文字列 ("\t"
など) の場合、その文字列が各レベルのインデントに使われます。If show_empty is
False
(the default), empty lists and fields that areNone
will be omitted from the output.バージョン 3.9 で変更: indent オプションを追加しました。
バージョン 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=[])
コンパイラフラグ¶
以下のフラグはプログラムのコンパイルにおける効果を変更するために compile()
に渡すことができます:
- ast.PyCF_ALLOW_TOP_LEVEL_AWAIT¶
トップレベルの
await
,async for
,async with
および async 内包表記のサポートを有効化します。Added in version 3.8.
- ast.PyCF_ONLY_AST¶
コンパイルされたコードオブジェクトの代わりに抽象構文木を生成して返します。
- ast.PyCF_OPTIMIZED_AST¶
The returned AST is optimized according to the optimize argument in
compile()
orast.parse()
.Added in version 3.13.
コマンドラインからの使用¶
Added in version 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 unifies the token-based and parse-tree-based views of python programs by inserting two-way links between tokens and ast nodes.
LibCST はコードを ast ツリーに似た構文木 (Concrete Syntax Tree) にパースし、かつ全ての書式設定の詳細を保持します。これは自動リファクタリングアプリケーション (codemod) やリンタを作成する際に有用です。
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.