"ast" --- Abstract syntax trees
*******************************

**ソースコード:** 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)
            | Interpolation(expr value, constant str, int conversion, expr? format_spec)
            | JoinedStr(expr* values)
            | TemplateStr(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 type "ast.expr_context"
   is omitted, it defaults to "Load()". If any other field is omitted,
   a "DeprecationWarning" 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.14 で変更: The "__repr__()" output of "AST" nodes
includes the values of the node fields.

Deprecated since version 3.8, removed in version 3.14: Previous
versions of Python provided the AST classes "ast.Num", "ast.Str",
"ast.Bytes", "ast.NameConstant" and "ast.Ellipsis", which were
deprecated in Python 3.8. These classes were removed in Python 3.14,
and their functionality has been replaced with "ast.Constant".

バージョン 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 a "list" of the module's 文 (Statements).

   "type_ignores" is a "list" of the module's type ignore comments;
   see "ast.parse()" for more details.

      >>> print(ast.dump(ast.parse('x = 1'), indent=4))
      Module(
          body=[
              Assign(
                  targets=[
                      Name(id='x', ctx=Store())],
                  value=Constant(value=1))])

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 a "list" of statement nodes.

      >>> print(ast.dump(ast.parse('x = 1; y = 2', mode='single'), indent=4))
      Interactive(
          body=[
              Assign(
                  targets=[
                      Name(id='x', ctx=Store())],
                  value=Constant(value=1)),
              Assign(
                  targets=[
                      Name(id='y', ctx=Store())],
                  value=Constant(value=2))])

class ast.FunctionType(argtypes, returns)

   A representation of an old-style type comments for functions, as
   Python versions prior to 3.5 didn't support **PEP 484**
   annotations. Node type generated by "ast.parse()" when *mode* is
   ""func_type"".

   Such type comments would look like this:

      def sum_two_number(a, b):
          # type: (int, int) -> int
          return a + b

   "argtypes" is a "list" of expression nodes.

   "returns" is a single expression node.

      >>> print(ast.dump(ast.parse('(int, str) -> List[int]', mode='func_type'), indent=4))
      FunctionType(
          argtypes=[
              Name(id='int', ctx=Load()),
              Name(id='str', ctx=Load())],
          returns=Subscript(
              value=Name(id='List', ctx=Load()),
              slice=Name(id='int', ctx=Load()),
              ctx=Load()))

   Added in version 3.8.


リテラル
--------

class ast.Constant(value)

   A constant value. The "value" attribute of the "Constant" literal
   contains the Python object it represents. The values represented
   can be instances of "str", "bytes", "int", "float", "complex", and
   "bool", and the constants "None" and "Ellipsis".

      >>> 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: 書式指定なし

     * 97 ("ord('a')"): "!a" "ASCII" formatting

     * 114 ("ord('r')"): "!r" "repr()" formatting

     * 115 ("ord('s')"): "!s" "string" formatting

   * "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.TemplateStr(values, /)

   Added in version 3.14.

   Node representing a template string literal, comprising a series of
   "Interpolation" and "Constant" nodes. These nodes may be any order,
   and do not need to be interleaved.

      >>> expr = ast.parse('t"{name} finished {place:ordinal}"', mode='eval')
      >>> print(ast.dump(expr, indent=4))
      Expression(
          body=TemplateStr(
              values=[
                  Interpolation(
                      value=Name(id='name', ctx=Load()),
                      str='name',
                      conversion=-1),
                  Constant(value=' finished '),
                  Interpolation(
                      value=Name(id='place', ctx=Load()),
                      str='place',
                      conversion=-1,
                      format_spec=JoinedStr(
                          values=[
                              Constant(value='ordinal')]))]))

class ast.Interpolation(value, str, conversion, format_spec=None)

   Added in version 3.14.

   Node representing a single interpolation field in a template string
   literal.

   * "value" is any expression node (such as a literal, a variable, or
     a function call). This has the same meaning as
     "FormattedValue.value".

   * "str" is a constant containing the text of the interpolation
     expression.

     If "str" is set to "None", then "value" is used to generate code
     when calling "ast.unparse()". This no longer guarantees that the
     generated code is identical to the original and is intended for
     code generation.

   * "conversion" は整数です:

     * -1: no conversion

     * 97 ("ord('a')"): "!a" "ASCII" conversion

     * 114 ("ord('r')"): "!r" "repr()" conversion

     * 115 ("ord('s')"): "!s" "string" conversion

     This has the same meaning as "FormattedValue.conversion".

   * "format_spec" is a "JoinedStr" node representing the formatting
     of the value, or "None" if no format was specified. Both
     "conversion" and "format_spec" can be set at the same time. This
     has the same meaning as "FormattedValue.format_spec".

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.And
class ast.Or

   論理演算の演算子をあらわします。

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 of "keyword" objects representing
     arguments passed by keyword.

   The "args" and "keywords" 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 a "Name", an "Attribute" or a "Subscript". "annotation" is
   the annotation, such as a "Constant" or "Name" 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 a "Name" 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" 属性は class "Tuple" や "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, and
   "value" 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 single "Name", "Tuple", "List", "Attribute" or "Subscript"
   node. "iter" holds the item to be looped over, again as a single
   node. "body" and "orelse" contain lists of nodes to execute. Those
   in "orelse" are executed if the loop finishes normally, rather than
   via a "break" 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 by "except*" clauses. The
   attributes are the same as for "Try" but the "ExceptHandler" nodes
   in "handlers" are interpreted as "except*" blocks rather then
   "except".

      >>> print(ast.dump(ast.parse("""
      ... try:
      ...    ...
      ... except* Exception:
      ...    ...
      ... """), indent=4))
      Module(
          body=[
              TryStar(
                  body=[
                      Expr(
                          value=Constant(value=Ellipsis))],
                  handlers=[
                      ExceptHandler(
                          type=Name(id='Exception', ctx=Load()),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

   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) and "cases"
   contains an iterable of "match_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 the "AST" nodes produced for patterns differ from those
   produced for expressions, even when they share the same syntax.

   The "guard" attribute contains an expression that will be evaluated
   if the pattern matches the subject.

   "body" contains a list of nodes to execute if the pattern matches
   and the result of evaluating the guard expression is true.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case [x] if x>0:
      ...         ...
      ...     case tuple():
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchSequence(
                              patterns=[
                                  MatchAs(name='x')]),
                          guard=Compare(
                              left=Name(id='x', ctx=Load()),
                              ops=[
                                  Gt()],
                              comparators=[
                                  Constant(value=0)]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))]),
                      match_case(
                          pattern=MatchClass(
                              cls=Name(id='tuple', ctx=Load())),
                          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", or "False". This
   pattern succeeds if the match subject is the given constant.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case None:
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchSingleton(value=None),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

   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 a
   "MatchStar" node, otherwise matches a fixed length sequence.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case [1, 2]:
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchSequence(
                              patterns=[
                                  MatchValue(
                                      value=Constant(value=1)),
                                  MatchValue(
                                      value=Constant(value=2))]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

   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 not "None", a list containing the
   remaining sequence elements is bound to that name if the overall
   sequence pattern is successful.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case [1, 2, *rest]:
      ...         ...
      ...     case [*_]:
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchSequence(
                              patterns=[
                                  MatchValue(
                                      value=Constant(value=1)),
                                  MatchValue(
                                      value=Constant(value=2)),
                                  MatchStar(name='rest')]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))]),
                      match_case(
                          pattern=MatchSequence(
                              patterns=[
                                  MatchStar()]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

   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 not "None", a dict containing the remaining mapping
   elements is bound to that name if the overall mapping pattern is
   successful.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case {1: _, 2: _}:
      ...         ...
      ...     case {**rest}:
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchMapping(
                              keys=[
                                  Constant(value=1),
                                  Constant(value=2)],
                              patterns=[
                                  MatchAs(),
                                  MatchAs()]),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))]),
                      match_case(
                          pattern=MatchMapping(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 is "None", the node represents a
   capture pattern (i.e a bare name) and will always succeed.

   The "name" attribute contains the name that will be bound if the
   pattern is successful. If "name" is "None", "pattern" must also be
   "None" and the node represents the wildcard pattern.

      >>> print(ast.dump(ast.parse("""
      ... match x:
      ...     case [x] as y:
      ...         ...
      ...     case _:
      ...         ...
      ... """), indent=4))
      Module(
          body=[
              Match(
                  subject=Name(id='x', ctx=Load()),
                  cases=[
                      match_case(
                          pattern=MatchAs(
                              pattern=MatchSequence(
                                  patterns=[
                                      MatchAs(name='x')]),
                              name='y'),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))]),
                      match_case(
                          pattern=MatchAs(),
                          body=[
                              Expr(
                                  value=Constant(value=Ellipsis))])])])

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

class ast.TypeIgnore(lineno, tag)

   A "# type: ignore" comment located at *lineno*. *tag* is the
   optional tag specified by the form "# type: ignore <tag>".

      >>> print(ast.dump(ast.parse('x = 1 # type: ignore', type_comments=True), indent=4))
      Module(
          body=[
              Assign(
                  targets=[
                      Name(id='x', ctx=Store())],
                  value=Constant(value=1))],
          type_ignores=[
              TypeIgnore(lineno=1, tag='')])
      >>> print(ast.dump(ast.parse('x: bool = 1 # type: ignore[assignment]', type_comments=True), indent=4))
      Module(
          body=[
              AnnAssign(
                  target=Name(id='x', ctx=Store()),
                  annotation=Name(id='bool', ctx=Load()),
                  value=Constant(value=1),
                  simple=1)],
          type_ignores=[
              TypeIgnore(lineno=1, tag='[assignment]')])

   注釈:

     "TypeIgnore" nodes are not generated when the *type_comments*
     parameter is set to "False" (default).  See "ast.parse()" for
     more details.

   Added in version 3.8.


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. If "bound" is a
   "Tuple", it represents constraints; otherwise it represents the
   bound. "default_value" is the default value; if the "TypeVar" has
   no default, this attribute will be set to "None".

      >>> 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 the
   "ParamSpec" has no default, this attribute will be set to "None".

      >>> 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=List(
                              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 the "TypeVarTuple"
   has no default, this attribute will be set to "None".

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

   関数の引数

   * "posonlyargs", "args" および "kwonlyargs" はそれぞれ "arg" ノード
     のリストです。

   * "vararg" と "kwarg" はそれぞれ単一の "arg" ノードで、 "*args,
     **kwargs" パラメータに相当します。

   * "kw_defaults" はキーワード専用引数に対するデフォルト値のリストで
     す。値が "None" の場合、対応する引数は必須となります。

   * "defaults" は位置引数として渡すことのできる引数に対するデフォルト
     値のリストです。デフォルト値の数nが位置引数の数より少ない場合、そ
     れらは最後のn個の引数に割り当てられます。

class ast.arg(arg, annotation, type_comment)

   A single argument in a list. "arg" is a raw string of the argument
   name; "annotation" is its annotation, such as a "Name" node.

   type_comment

      "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" or "yield from" expression. Because these are
   expressions, they must be wrapped in an "Expr" 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 of "keyword" 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) の中でのみ有効です。

注釈:

  When a string is parsed by "ast.parse()", operator nodes (subclasses
  of "ast.operator", "ast.unaryop", "ast.cmpop", "ast.boolop" and
  "ast.expr_context") on the returned tree will be singletons. Changes
  to one will be reflected in all other occurrences of the same value
  (for example, "ast.Add").


"ast" helpers
=============

ノード・クラスの他に、 "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)", where
   "FLAGS_VALUE" is "ast.PyCF_ONLY_AST" if "optimize <= 0" and
   "ast.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 adding "ast.PyCF_TYPE_COMMENTS" to the
   flags passed to "compile()".  This will report syntax errors for
   misplaced type comments.  Without this flag, type comments will be
   ignored, and the "type_comment" field on selected AST nodes will
   always be "None".  In addition, the locations of "# type: ignore"
   comments will be returned as the "type_ignores" attribute of
   "Module" (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, setting "feature_version=(3, 9)" will attempt
   to disallow parsing of "match" statements. Currently "major" must
   equal to "3". The lowest supported version is "(3, 7)" (and this
   may increase in future Python versions); the highest is
   "sys.version_info[0:2]". "Best-effort" attempt means there is no
   guarantee that the parse (or success of the parse) is the same as
   when run on the Python version corresponding to "feature_version".

   If source contains a null character ("\0"), "ValueError" is raised.

   警告:

     Note that successfully parsing source code into an AST object
     doesn't guarantee that the source code provided is valid Python
     code that can be executed as the compilation step can raise
     further "SyntaxError" exceptions. For instance, the source
     "return 42" generates a valid AST node for a return statement,
     but it cannot be compiled alone (it needs to be inside a function
     node).In particular, "ast.parse()" won't do any scoping checks,
     which the compilation step does.

   警告:

     十分に大きい文字列や複雑な文字列によって Python の抽象構文木コン
     パイラのスタックの深さの限界を越えることで、 Python インタプリタ
     をクラッシュさせることができます。

   バージョン 3.8 で変更: "type_comments"、"mode='func_type'"、
   "feature_version" が追加されました。

   バージョン 3.13 で変更: The minimum supported version for
   "feature_version" is now "(3, 7)". The "optimize" 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" and
     "RecursionError" 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", or
   "end_col_offset") is missing, return "None".

   *padded* が "True" の場合、複数行にわたる文の最初の行が元の位置に一
   致するように空白文字でパディングされます。

   Added in version 3.8.

ast.fix_missing_locations(node)

   When you compile a node tree with "compile()", the compiler expects
   "lineno" and "col_offset" attributes for every node that supports
   them.  This is rather tedious to fill in for generated nodes, so
   this helper adds these attributes recursively where not already
   set, by setting them to the values of the parent node.  It works
   recursively starting at *node*.

ast.increment_lineno(node, n=1)

   *node* で始まるツリー内の各ノードの行番号と終了行番号を *n* ずつ増
   やします。これはファイルの中で別の場所に "コードを移動する" ときに
   便利です。

ast.copy_location(new_node, old_node)

   Copy source location ("lineno", "col_offset", "end_lineno", and
   "end_col_offset") from *old_node* to *new_node* if possible, and
   return *new_node*.

ast.iter_fields(node)

   *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") があります。

   Deprecated since version 3.8, removed in version 3.14: Methods
   "visit_Num()", "visit_Str()", "visit_Bytes()",
   "visit_NameConstant()" and "visit_Ellipsis()" will not be called in
   Python 3.14+.  Add the "visit_Constant()" method instead 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 as
   "lineno"), "fix_missing_locations()" should be called with the new
   sub-tree to recalculate the location information:

      tree = ast.parse('foo', mode='eval')
      new_tree = fix_missing_locations(RewriteName().visit(tree))

   たいてい、変換器の使い方は次のようになります:

      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), optional empty lists will
   be omitted from the output. Optional "None" values are always
   omitted.

   バージョン 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=[])


Compiler flags
==============

以下のフラグはプログラムのコンパイルにおける効果を変更するために
"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()" or "ast.parse()".

   Added in version 3.13.

ast.PyCF_TYPE_COMMENTS

   **PEP 484** および **PEP 526** 形式の型コメント ("# type: <type>",
   "# type: ignore <stuff>") のサポートを有効化します。

   Added in version 3.8.

ast.compare(a, b, /, *, compare_attributes=False)

   Recursively compares two ASTs.

   *compare_attributes* affects whether AST attributes are considered
   in the comparison. If *compare_attributes* is "False" (default),
   then attributes are ignored. Otherwise they must all be equal. This
   option is useful to check whether the ASTs are structurally equal
   but differ in whitespace or similar details. Attributes include
   line numbers and column offsets.

   Added in version 3.14.


コマンドラインでの使用
======================

Added in version 3.9.

"ast" モジュールはコマンドラインからスクリプトとして実行することができ
ます。実行方法は単純です:

   python -m ast [-m <mode>] [-a] [infile]

以下のオプションが使用できます:

-h, --help

   ヘルプメッセージを表示して終了します。

-m <mode>
--mode <mode>

   "parse()" 関数の *mode* 引数と同様、コンパイルするコードの種類を指
   定します。

--no-type-comments

   型コメントをパースしません。

-a, --include-attributes

   行番号や列オフセットなどの属性を含めます。

-i <indent>
--indent <indent>

   AST におけるノードのインデント (空白の数) です。

--feature-version <version>

   Python version in the format 3.x (for example, 3.10). Defaults to
   the current version of the interpreter.

   Added in version 3.14.

-O <level>
--optimize <level>

   Optimization level for parser. Defaults to no optimization.

   Added in version 3.14.

--show-empty

   Show empty lists and fields that are "None". Defaults to not
   showing empty objects.

   Added in version 3.14.

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