ast --- 抽象語法樹 (Abstract Syntax Trees)¶

根節點¶

class ast.Module(body, type_ignores)¶

一個 Python 模組，與檔案輸入 一樣。由 ast.parse() 在預設的 "exec" mode 下生成的節點型別。

body 是模組的陳述式 的一個 list。

type_ignores 是模組的忽略型別註解的 list；有關更多詳細資訊，請參閱 ast.parse()。

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

單個 Python 運算式輸入。當 mode 是 "eval" 時節點型別由 ast.parse() 生成。

body 是單個節點，是運算式型別的其中之一。

>>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))
Expression(
    body=Constant(value=123))

class ast.Interactive(body)¶

單個互動式輸入，和互動模式中所述的相似。當 mode 是 "single" 時節點型別由 ast.parse() 生成。

body 是陳述式節點 (statement nodes) 的 list。

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

函式的舊式型別註解的表示法，因為 3.5 之前的 Python 版本不支援 PEP 484 註釋。當 mode 是 "func_type" 時節點型別由 ast.parse() 生成。

這種型別的註解看起來像這樣：

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

argtypes 是運算式節點的 list。

returns 是單個運算式節點。

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

在 3.8 版被加入.

文本 (Literals)¶

class ast.Constant(value)¶

一個常數值。Constant 文本的 value 屬性包含它所代表的 Python 物件。表示的值可以是簡單型別，例如數字、字串或 None，但如果它們的所有元素都是常數，也可以是不可變的 (immutable) 容器型別（元組和凍結集合 (frozensets)）。

>>> print(ast.dump(ast.parse('123', mode='eval'), indent=4))
Expression(
    body=Constant(value=123))

class ast.FormattedValue(value, conversion, format_spec)¶

表示 f 字串 (f-string) 中的單個格式化欄位的節點。如果字串包含單個格式欄位並且沒有其他內容，則可以隔離 (isolate) 該節點，否則它將出現在 JoinedStr 中。

• value 為任何運算式節點（例如文字、變數或函式呼叫）。

• conversion 是一個整數：

  • -1: 無格式化

  • 115: !s 字串格式化

  • 114:!r 重複格式化化

  • 97: ！a ascii 格式化

• format_spec 是一個 JoinedStr 節點，表示值的格式，若未指定格式則為 None。conversion 和 format_spec 可以同時設定。

class ast.JoinedStr(values)¶

一個 f 字串，包含一系列 FormattedValue 和 Constant 節點。

>>> print(ast.dump(ast.parse('f"sin({a}) is {sin(a):.3}"', mode='eval'), indent=4))
Expression(
    body=JoinedStr(
        values=[
            Constant(value='sin('),
            FormattedValue(
                value=Name(id='a', ctx=Load()),
                conversion=-1),
            Constant(value=') is '),
            FormattedValue(
                value=Call(
                    func=Name(id='sin', ctx=Load()),
                    args=[
                        Name(id='a', ctx=Load())]),
                conversion=-1,
                format_spec=JoinedStr(
                    values=[
                        Constant(value='.3')]))]))

class ast.List(elts, ctx)¶

class ast.Tuple(elts, ctx)¶

串列或元組。elts 保存表示元素的節點串列。如果容器是賦值目標（即 (x,y)=something ），則 ctx 是 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)¶

一個集合。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)¶

一個字典 (dictionary)。keys 和 values 分別按匹配順序保存表示鍵和值的節點串列（為呼叫 dictionary.keys() 和 dictionary.values() 時將回傳的內容）。

當使用字典文本進行字典解包 (unpack) 時，要擴充的運算式位於 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¶

變數參照可用於載入變數的值、為其分配新值或刪除它。變數參照被賦予情境 (context) 來區分這些情況。

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

運算式¶

class ast.Expr(value)¶

當運算式（例如函式呼叫）本身作為陳述式出現且未使用或儲存其回傳值時，它將被包裝在此容器中。value 保存此區段 (section) 中的一個其他節點：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)¶

一元運算 (unary operation)。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)¶

二元運算 (binary operation)（如加法或除法）。 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¶

二元運算子 token。

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¶

布林運算子 token。

class ast.Compare(left, ops, comparators)¶

兩個或多個值的比較。left 是比較中的第一個值、ops 是運算子串列、comparators 是要比較的第一個元素之後值的串列。

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

比較運算子 token。

class ast.Call(func, args, keywords)¶

一個函式呼叫。func 是該函式，通常是一個 Name 或 Attribute 物件。而在引數中：

• args 保存按位置傳遞的引數串列。

• keywords 保存一個 keyword 物件串列，表示透過關鍵字傳遞的引數。

args 和 keywords 引數是可選的，預設為空串列。

>>> 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 之類的運算式。每個欄位都保存一個節點，因此在以下範例中，所有三個都是 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)¶

一個附名運算式 (named expression)。該 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)))

在 3.8 版被加入.

陳述式¶

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

帶有型別註釋的賦值。target 是單個節點，可以是 Name、Attribute 或 Subscript。annotation 是註釋，例如 Constant 或 Name 節點。value 是單個可選節點。

simple 總會是 0（表示一個「複雜」目標）或 1（表示一個「簡單」目標）。一個「簡單」目標僅包含一個 Name 節點，且不出現在括號之間；所有其他目標都被視為是複雜的。只有簡單目標會出現在模組和類別的 __annotations__ 字典中。

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

增加賦值 (augmented assignment)，例如 a += 1。在下面的範例中，target 是 x 的 Name 節點（帶有 Store 情境），op 是 Add，value 是一個值為 1 的 Constant。

與 Assign 的目標不同，target 屬性不能屬於 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)¶

一個斷言 (assertion)。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)¶

透過 type 陳述式建立的型別別名 (type alias)。name 是別名的名稱、type_params 是型別參數 (type parameter) 的串列、value 是型別別名的值。

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

在 3.12 版被加入.

其他僅適用於函式或迴圈內部的陳述式將在其他部分中描述。

流程控制¶

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

一個 for 迴圈。 target 保存迴圈賦予的變數，為單個 Name、Tuple、List、Attribute 或 Subscript 節點。iter 保存要迴圈跑過的項目，也為單個節點。body 和 orelse 包含要執行的節點串列。如果迴圈正常完成，則執行 orelse 中的內容，而不是透過 break 陳述式執行。

type_comment¶

type_comment 是一個可選字串，其中的註解為型別註釋。

>>> print(ast.dump(ast.parse("""
... for x in y:
...     ...
... else:
...     ...
... """), indent=4))
Module(
    body=[
        For(
            target=Name(id='x', ctx=Store()),
            iter=Name(id='y', ctx=Load()),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))])])

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 區塊。除 handlers 是 ExceptHandler 節點的串列外，其他所有屬性都是要執行之節點的串列。

>>> 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 區塊，後面跟著 except* 子句。這些屬性與 Try 相同，但是 handlers 中的 ExceptHandler 節點被直譯 (interpret) 為 except* 區塊而不是 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))])])])

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

一個 match 陳述式。subject 保存匹配的主題（與案例匹配的物件），cases 包含具有不同案例的 match_case 節點的可疊代物件。

在 3.10 版被加入.

class ast.match_case(pattern, guard, body)¶

match 陳述式中的單個案例模式。pattern 包含主題將與之匹配的匹配模式。請注意，為模式生成的 AST 節點與為運算式生成的節點不同，即使它們共享相同的語法。

guard 屬性包含一個運算式，如果模式與主題匹配，則將對該運算式求值。

body 包含一個節點串列，如果模式匹配並且為防護運算式 (guard expression) 的求值 (evaluate) 結果為真，則會執行該節點串列。

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

在 3.10 版被加入.

class ast.MatchValue(value)¶

以相等性進行比較的匹配文本或值的模式。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))])])])

在 3.10 版被加入.

class ast.MatchSingleton(value)¶

按識別性 (identity) 進行比較的匹配文本模式。value 是要與 None、True 或 False 進行比較的單例 (singleton)。如果匹配主題是給定的常數，則此模式成功。

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

在 3.10 版被加入.

class ast.MatchSequence(patterns)¶

匹配序列模式。如果主題是一個序列，patterns 包含與主題元素匹配的模式。如果子模式之一是 MatchStar 節點，則匹配可變長度序列，否則匹配固定長度序列。

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

在 3.10 版被加入.

class ast.MatchStar(name)¶

以可變長度匹配序列模式匹配序列的其餘部分。如果 name 不是 None，則如果整體序列模式成功，則包含其餘序列元素的串列將綁定到該名稱。

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

在 3.10 版被加入.

class ast.MatchMapping(keys, patterns, rest)¶

匹配對映模式。keys 是運算式節點的序列。patterns 是相應的模式節點序列。rest 是一個可選名稱，可以指定它來捕獲剩餘的對映元素。允許的鍵運算式受到匹配陳述式文件中所述的限制。

如果主題是對映，所有求值出的鍵運算式都存在於對映中，並且與每個鍵對應的值與相應的子模式匹配，則此模式成功。如果 rest 不是 None，則如果整體對映模式成功，則包含其餘對映元素的字典將綁定到該名稱。

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

在 3.10 版被加入.

class ast.MatchClass(cls, patterns, kwd_attrs, kwd_patterns)¶

匹配類別模式。cls 是一個給定要匹配的名義類別 (nominal class) 的運算式。patterns 是要與類別定義的模式匹配屬性序列進行匹配的模式節點序列。kwd_attrs 是要匹配的附加屬性序列（在類別模式中指定為關鍵字引數），kwd_patterns 是相應的模式（在類別模式中指定為關鍵字的值）。

如果主題是指定類別的實例，所有位置模式都與相應的類別定義屬性匹配，並且任何指定的關鍵字屬性與其相應模式匹配，則此模式成功。

注意：類別可以定義一個回傳 self 的特性 (property)，以便將模式節點與正在匹配的實例進行匹配。一些內建型別也以這種方式匹配，如同匹配陳述式文件中所述。

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

在 3.10 版被加入.

class ast.MatchAs(pattern, name)¶

匹配的 「as 模式 (as-pattern)」，為捕獲模式 (capture pattern) 或通配模式 (wildcard pattern)。pattern 包含主題將與之匹配的匹配模式。如果模式為 None，則該節點代表捕獲模式（即裸名 (bare name)）並且始終會成功。

name 屬性包含模式成功時將綁定的名稱。如果 name 為 None，則 pattern 也必須為 None，並且節點代表通配模式。

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

在 3.10 版被加入.

class ast.MatchOr(patterns)¶

匹配的 「or 模式 (or-pattern)」。 or 模式依次將其每個子模式與主題進行匹配，直到成功為止，然後 or 模式就會被認為是成功的。如果沒有一個子模式成功，則 or 模式將失敗。 patterns 屬性包含將與主題進行匹配的匹配模式節點串列。

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

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

在 3.8 版被加入.

型別參數 (type parameters)¶

型別參數可以存在於類別、函式和型別別名上。

class ast.TypeVar(name, bound, default_value)¶

一個 typing.TypeVar。name 是型別變數的名稱。bound 是（如果有存在的）界限 (bound) 或約束 (constraint)。如果 bound 是一個 Tuple，它代表約束；否則它代表界限。default_value 為預設值；如果 TypeVar 沒有預設值，那此屬性會被設為 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()))])

在 3.12 版被加入.

在 3.13 版的變更: 新增 default_value 參數。

class ast.ParamSpec(name, default_value)¶

一個 typing.ParamSpec。name 是參數規範的名稱。default_value 是預設值；如果 ParamSpec 沒有預設值，則該屬性將設定為 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()))])

在 3.12 版被加入.

在 3.13 版的變更: 新增 default_value 參數。

class ast.TypeVarTuple(name, default_value)¶

一個 typing.TypeVarTuple。name 是型別變數元組的名稱。default_value 為預設值；如果 TypeVarTuple 沒有預設值，那此屬性會被設為 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()))])

在 3.12 版被加入.

在 3.13 版的變更: 新增 default_value 參數。

函式和類別定義¶

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

一個函式定義。

• name 是函式名稱的原始字串。

• args 是一個 arguments 節點。

• body 是函式內節點的串列。

• decorator_list 是要應用的裝飾器串列，在最外層者會被儲存在首位（即串列中首位將會是最後一個被應用的那個）。

• returns 是回傳註釋。

• type_params 是型別參數的串列。

type_comment¶

type_comment 是一個可選字串，其中的註解為型別註釋。

在 3.12 版的變更: 新增了 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 個引數。

class ast.arg(arg, annotation, type_comment)¶

串列中的單個引數。arg 是引數名稱的原始字串，annotation 是它的註釋，例如 Name 節點。

type_comment¶

type_comment 是一個可選字串，其註解為型別註釋

>>> print(ast.dump(ast.parse("""\
... @decorator1
... @decorator2
... def f(a: 'annotation', b=1, c=2, *d, e, f=3, **g) -> 'return annotation':
...     pass
... """), indent=4))
Module(
    body=[
        FunctionDef(
            name='f',
            args=arguments(
                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)¶

一個 yield 或 yield from 運算式。因為這些是運算式，所以如果不使用發送回來的值，則必須將它們包裝在 Expr 節點中。

>>> 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 是一個 keyword 節點的串列，主要用於 'metaclass'（元類別）。如 PEP 3115 所述，其他關鍵字將被傳遞到 metaclass。

• body 是表示類別定義中程式碼的節點串列。

• decorator_list 是一個節點串列，如 FunctionDef 中所示。

• type_params 是型別參數的串列。

>>> 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 版的變更: 新增了 type_params。

async 和 await¶

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

一個 async def 函式定義。與 FunctionDef 具有相同的欄位。

在 3.12 版的變更: 新增了 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 主體中有效。