ast — Абстрактные синтаксические деревья

Корневые узлы

class ast.Module(body, type_ignores)

Модуль Python, как и в случае с вводом из файла. Тип узла, генерируемый ast.parse() в режиме "exec".

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))],
    type_ignores=[])

class ast.Expression(body)

Одно выражение Python ввода выражения. Тип узла, генерируемый ast.parse(), когда mode равен "eval".

body — единственный узел, один из типов выражений.

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

class ast.Interactive(body)

Один ввод в интерактивном режиме, как в Режим интерактивного режима. Тип узла, генерируемый ast.parse(), когда mode равен "single".

body — список 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)

Представление комментариев старого стиля для функций, так как версии Python до 3.5 не поддерживали PEP 484 аннотации. Тип узла, генерируемый ast.parse(), когда mode равен "func_type".

Комментарии такого типа выглядели бы так:

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.

Литералы

class ast.Constant(value)

Постоянное значение. Атрибут value литерала Constant содержит представляемый им объект Python. Представляемые значения могут быть простыми типами, такими как число, строка или None, а также неизменяемыми контейнерными типами (кортежи и замороженные множества), если все их элементы являются константами.

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

class ast.FormattedValue(value, conversion, format_spec)

Узел, представляющий одно поле форматирования в f-строке. Если строка содержит одно поле форматирования и ничего больше, узел может быть изолирован, в противном случае он появляется в JoinedStr.

• value — это любой узел выражения (например, литерал, переменная или вызов функции).

• conversion — это целое число:

  • -1: без форматирования
  • 115: форматирование строк !s
  • 114: форматирование repr !r
  • 97: форматирование ascii !a
• 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())],
                    keywords=[]),
                conversion=-1,
                format_spec=JoinedStr(
                    values=[
                        Constant(value='.3')]))]))

class ast.List(elts, ctx)

class ast.Tuple(elts, ctx)

Список или кортеж. elts содержит список узлов, представляющих элементы. ctx — это Store, если контейнер является целевым значением присваивания (т.е. (x,y)=something), и 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)

Словарь. keys и values содержат списки узлов, представляющих ключи и значения соответственно, в соответствии с порядком (то, что возвращалось бы при вызове dictionary.keys() и dictionary.values()).

При распаковке словарей с использованием литералов словарей выражение, которое должно быть расширено, помещается в список values, а None — в соответствующей позиции в keys.

>>> print(ast.dump(ast.parse('{"a":1, **d}', mode='eval'), indent=4))
Expression(
    body=Dict(
        keys=[
            Constant(value='a'),
            None],
        values=[
            Constant(value=1),
            Name(id='d', ctx=Load())]))

Переменные

class ast.Name(id, ctx)

Имя переменной. id содержит имя как строку, а ctx — один из следующих типов.

class ast.Load

class ast.Store

class ast.Del

Ссылки на переменные могут использоваться для загрузки значения переменной, для присваивания ей нового значения или для удаления. Ссылки на переменные получают контекст, чтобы различать эти случаи.

>>> print(ast.dump(ast.parse('a'), indent=4))
Module(
    body=[
        Expr(
            value=Name(id='a', ctx=Load()))],
    type_ignores=[])

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

>>> print(ast.dump(ast.parse('del a'), indent=4))
Module(
    body=[
        Delete(
            targets=[
                Name(id='a', ctx=Del())])],
    type_ignores=[])

class ast.Starred(value, ctx)

Ссылка на переменную *var. value содержит переменную, обычно узел Name. Этот тип должен использоваться при построении узла Call с *args.

>>> print(ast.dump(ast.parse('a, *b = it'), indent=4))
Module(
    body=[
        Assign(
            targets=[
                Tuple(
                    elts=[
                        Name(id='a', ctx=Store()),
                        Starred(
                            value=Name(id='b', ctx=Store()),
                            ctx=Store())],
                    ctx=Store())],
            value=Name(id='it', ctx=Load()))],
    type_ignores=[])

Выражения

class ast.Expr(value)

Когда выражение, такое как вызов функции, появляется как оператор само по себе, без использования или хранения его возвращаемого значения, оно обертывается в этот контейнер. value содержит один из других узлов в этом разделе, Constant, Name, Lambda, Yield или YieldFrom узел.

>>> print(ast.dump(ast.parse('-a'), indent=4))
Module(
    body=[
        Expr(
            value=UnaryOp(
                op=USub(),
                operand=Name(id='a', ctx=Load())))],
    type_ignores=[])

class ast.UnaryOp(op, operand)

Унарная операция. op — оператор, а operand — любой узел выражения.

class ast.UAdd

class ast.USub

class ast.Not

class ast.Invert

Унарные операторные токены. Not — это ключевое слово not, Invert — это оператор ~.

>>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4))
Expression(
    body=UnaryOp(
        op=Not(),
        operand=Name(id='x', ctx=Load())))

class ast.BinOp(left, op, right)

Бинарная операция (например, сложение или деление). op — оператор, а left и right — любые узлы выражений.

>>> print(ast.dump(ast.parse('x + y', mode='eval'), indent=4))
Expression(
    body=BinOp(
        left=Name(id='x', ctx=Load()),
        op=Add(),
        right=Name(id='y', ctx=Load())))

class ast.Add

class ast.Sub

class ast.Mult

class ast.Div

class ast.FloorDiv

class ast.Mod

class ast.Pow

class ast.LShift

class ast.RShift

class ast.BitOr

class ast.BitXor

class ast.BitAnd

class ast.MatMult

Бинарные операторные токены.

class ast.BoolOp(op, values)

Булева операция, «или» или «и». 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)

Сравнение двух или более значений. 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

Токены операторов сравнения.

class ast.Call(func, args, keywords)

Вызов функции. func — функция, которая часто будет объектом Name или Attribute. Из аргументов:

• args содержит список аргументов, переданных по позиции.
• keywords содержит список объектов keyword, представляющих аргументы, переданные по имени.

При создании узла Call, 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)

Именованное выражение. Этот узел AST создаётся оператором присваивания выражений (также известным как оператор walrus). В отличие от узла 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 представляют присваивание одного и того же значения каждому. Расширение представлено размещением Tuple или List внутри targets.

type_comment

type_comment — это необязательная строка с аннотацией типа в виде комментария.

>>> print(ast.dump(ast.parse('a = b = 1'), indent=4)) # Multiple assignment
Module(
    body=[
        Assign(
            targets=[
                Name(id='a', ctx=Store()),
                Name(id='b', ctx=Store())],
            value=Constant(value=1))],
    type_ignores=[])

>>> print(ast.dump(ast.parse('a,b = c'), indent=4)) # Unpacking
Module(
    body=[
        Assign(
            targets=[
                Tuple(
                    elts=[
                        Name(id='a', ctx=Store()),
                        Name(id='b', ctx=Store())],
                    ctx=Store())],
            value=Name(id='c', ctx=Load()))],
    type_ignores=[])

class ast.AnnAssign(target, annotation, value, simple)

Присваивание с аннотацией типа. target — это один узел, который может быть Name, Attribute или Subscript. annotation — это аннотация, например, узел Constant или 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)],
    type_ignores=[])

>>> print(ast.dump(ast.parse('(a): int = 1'), indent=4)) # Annotation with parenthesis
Module(
    body=[
        AnnAssign(
            target=Name(id='a', ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            value=Constant(value=1),
            simple=0)],
    type_ignores=[])

>>> print(ast.dump(ast.parse('a.b: int'), indent=4)) # Attribute annotation
Module(
    body=[
        AnnAssign(
            target=Attribute(
                value=Name(id='a', ctx=Load()),
                attr='b',
                ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            simple=0)],
    type_ignores=[])

>>> print(ast.dump(ast.parse('a[1]: int'), indent=4)) # Subscript annotation
Module(
    body=[
        AnnAssign(
            target=Subscript(
                value=Name(id='a', ctx=Load()),
                slice=Constant(value=1),
                ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            simple=0)],
    type_ignores=[])

class ast.AugAssign(target, op, value)

Усиленное присваивание, например, a += 1. В следующем примере target — это узел Name для x (с контекстом Store), op — это Add, а value — это Constant со значением 1.

Атрибут target не может быть класса Tuple или List, в отличие от целевых объектов Assign.

>>> print(ast.dump(ast.parse('x += 2'), indent=4))
Module(
    body=[
        AugAssign(
            target=Name(id='x', ctx=Store()),
            op=Add(),
            value=Constant(value=2))],
    type_ignores=[])

class ast.Raise(exc, cause)

Оператор raise. exc — это объект исключения, который необходимо поднять, обычно Call или Name, или None для самостоятельного raise. cause — это необязательная часть для y в raise x from y.

>>> print(ast.dump(ast.parse('raise x from y'), indent=4))
Module(
    body=[
        Raise(
            exc=Name(id='x', ctx=Load()),
            cause=Name(id='y', ctx=Load()))],
    type_ignores=[])

class ast.Assert(test, msg)

Утверждение. test содержит условие, например, узел Compare. msg содержит сообщение об ошибке.

>>> print(ast.dump(ast.parse('assert x,y'), indent=4))
Module(
    body=[
        Assert(
            test=Name(id='x', ctx=Load()),
            msg=Name(id='y', ctx=Load()))],
    type_ignores=[])

class ast.Delete(targets)

Представляет оператор del. targets — это список узлов, таких как Name, Attribute или Subscript узлы.

>>> print(ast.dump(ast.parse('del x,y,z'), indent=4))
Module(
    body=[
        Delete(
            targets=[
                Name(id='x', ctx=Del()),
                Name(id='y', ctx=Del()),
                Name(id='z', ctx=Del())])],
    type_ignores=[])

class ast.Pass

Оператор pass.

>>> print(ast.dump(ast.parse('pass'), indent=4))
Module(
    body=[
        Pass()],
    type_ignores=[])

class ast.TypeAlias(name, type_params, value)

Псевдоним типа type alias, созданный с помощью оператора type. name — это имя псевдонима, type_params — это список параметров типа, а value — это значение псевдонима типа.

>>> print(ast.dump(ast.parse('type Alias = int'), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[],
            value=Name(id='int', ctx=Load()))],
    type_ignores=[])

Добавлен в версии 3.12.

Другие операторы, которые применимы только внутри функций или циклов, описаны в других разделах.

Управление потоком

class ast.If(test, body, orelse)

Оператор if. test содержит один узел, например, узел Compare. body и orelse содержат списки узлов.

Фрагменты elif не имеют специального представления в AST, а вместо этого появляются как дополнительные узлы If в разделе orelse предыдущего.

>>> print(ast.dump(ast.parse("""
... if x:
...    ...
... elif y:
...    ...
... else:
...    ...
... """), indent=4))
Module(
    body=[
        If(
            test=Name(id='x', ctx=Load()),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                If(
                    test=Name(id='y', ctx=Load()),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))],
                    orelse=[
                        Expr(
                            value=Constant(value=Ellipsis))])])],
    type_ignores=[])

class ast.For(target, iter, body, orelse, type_comment)

Цикл for. target содержит переменную(ые), к которой(ым) цикл присваивает значения, в виде одного узла Name, Tuple, List, 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))])],
    type_ignores=[])

class ast.While(test, body, orelse)

Цикл while. test содержит условие, например, узел Compare.

>> print(ast.dump(ast.parse("""
... while x:
...    ...
... else:
...    ...
... """), indent=4))
Module(
    body=[
        While(
            test=Name(id='x', ctx=Load()),
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))])],
    type_ignores=[])

class ast.Break

class ast.Continue

Операторы break и continue.

>>> print(ast.dump(ast.parse("""\
... for a in b:
...     if a > 5:
...         break
...     else:
...         continue
...
... """), indent=4))
Module(
    body=[
        For(
            target=Name(id='a', ctx=Store()),
            iter=Name(id='b', ctx=Load()),
            body=[
                If(
                    test=Compare(
                        left=Name(id='a', ctx=Load()),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=5)]),
                    body=[
                        Break()],
                    orelse=[
                        Continue()])],
            orelse=[])],
    type_ignores=[])

class ast.Try(body, handlers, orelse, finalbody)

Блоки try. Все атрибуты — списки узлов для выполнения, за исключением 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))])],
    type_ignores=[])

class ast.TryStar(body, handlers, orelse, finalbody)

Блоки try, за которыми следуют фрагменты except*. Атрибуты такие же, как у Try, но узлы ExceptHandler в handlers интерпретируются как блоки 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))])],
            orelse=[],
            finalbody=[])],
    type_ignores=[])

Добавлен в версии 3.11.

class ast.ExceptHandler(type, name, body)

Один фрагмент except. type — это тип исключения, с которым он будет совпадать, обычно узел Name (или None для универсального фрагмента обработки except:). name — это строка для имени, в котором будет храниться исключение, или None если у фрагмента нет as foo. body — это список узлов.

>>> print(ast.dump(ast.parse("""\
... try:
...     a + 1
... except TypeError:
...     pass
... """), indent=4))
Module(
    body=[
        Try(
            body=[
                Expr(
                    value=BinOp(
                        left=Name(id='a', ctx=Load()),
                        op=Add(),
                        right=Constant(value=1)))],
            handlers=[
                ExceptHandler(
                    type=Name(id='TypeError', ctx=Load()),
                    body=[
                        Pass()])],
            orelse=[],
            finalbody=[])],
    type_ignores=[])

class ast.With(items, body, type_comment)

Блок with. items — это список узлов withitem, представляющих управляющие контекстом, а body — это отстуженный блок внутри контекста.

type_comment

type_comment — это необязательная строка с аннотацией типа в виде комментария.

class ast.withitem(context_expr, optional_vars)

Один управляющий контекстом в блоке with. context_expr — это управляющий контекстом, часто узел Call. optional_vars — это Name, Tuple или List для части as foo, или None если она не используется.

>>> print(ast.dump(ast.parse("""\
... with a as b, c as d:
...    something(b, d)
... """), indent=4))
Module(
    body=[
        With(
            items=[
                withitem(
                    context_expr=Name(id='a', ctx=Load()),
                    optional_vars=Name(id='b', ctx=Store())),
                withitem(
                    context_expr=Name(id='c', ctx=Load()),
                    optional_vars=Name(id='d', ctx=Store()))],
            body=[
                Expr(
                    value=Call(
                        func=Name(id='something', ctx=Load()),
                        args=[
                            Name(id='b', ctx=Load()),
                            Name(id='d', ctx=Load())],
                        keywords=[]))])],
    type_ignores=[])

Сопоставление с образцом

class ast.Match(subject, cases)

Оператор match. subject содержит предмет сопоставления (объект, который сопоставляется с вариантами), а cases содержит итерируемый список узлов match_case с различными вариантами.

Добавлен в версии 3.10.

class ast.match_case(pattern, guard, body)

Один вариант шаблона в операторе match. pattern содержит шаблон сопоставления, с которым будет сопоставляться предмет. Обратите внимание, что узлы AST, генерируемые для шаблонов, отличаются от узлов, генерируемых для выражений, даже если у них одинаковый синтаксис.

Атрибут guard содержит выражение, которое будет вычислено, если шаблон соответствует предмету.

body содержит список узлов, которые будут выполнены, если шаблон соответствует и результат вычисления выражения условия равен true.

>>> print(ast.dump(ast.parse("""
... match x:
...     case [x] if x>0:
...         ...
...     case tuple():
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchAs(name='x')]),
                    guard=Compare(
                        left=Name(id='x', ctx=Load()),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=0)]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='tuple', ctx=Load()),
                        patterns=[],
                        kwd_attrs=[],
                        kwd_patterns=[]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])],
    type_ignores=[])

Добавлен в версии 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))])])],
    type_ignores=[])

Добавлен в версии 3.10.

class ast.MatchSingleton(value)

Шаблон соответствия литералу, сравнивающий по идентичности. value — это единственный объект для сравнения: None, True, или False. Этот шаблон срабатывает, если предмет сопоставления является заданной константой.

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

Добавлен в версии 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))])])],
    type_ignores=[])

Добавлен в версии 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))])])],
    type_ignores=[])

Добавлен в версии 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(keys=[], patterns=[], rest='rest'),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])],
    type_ignores=[])

Добавлен в версии 3.10.

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

Шаблон соответствия классу. cls — это выражение, указывающее номинальный класс, который нужно сопоставить. patterns — это последовательность узлов шаблонов, которые нужно сопоставить с определённой последовательностью атрибутов класса. kwd_attrs — это последовательность дополнительных атрибутов, которые нужно сопоставить (указанных как ключевые аргументы в шаблоне класса), kwd_patterns — соответствующие шаблоны (указанные как ключевые значения в шаблоне класса).

Этот шаблон срабатывает, если предмет является экземпляром указанного класса, все позиционные шаблоны соответствуют соответствующим атрибутам класса и все указанные ключевые атрибуты соответствуют их соответствующим шаблонам.

Примечание: классы могут определять свойство, которое возвращает self, чтобы сопоставить узел шаблона с экземпляром, который сопоставляется. Также несколько встроенных типов сопоставляются таким образом, как описано в документации к оператору сопоставления.

>>> print(ast.dump(ast.parse("""
... match x:
...     case Point2D(0, 0):
...         ...
...     case Point3D(x=0, y=0, z=0):
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='Point2D', ctx=Load()),
                        patterns=[
                            MatchValue(
                                value=Constant(value=0)),
                            MatchValue(
                                value=Constant(value=0))],
                        kwd_attrs=[],
                        kwd_patterns=[]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='Point3D', ctx=Load()),
                        patterns=[],
                        kwd_attrs=[
                            'x',
                            'y',
                            'z'],
                        kwd_patterns=[
                            MatchValue(
                                value=Constant(value=0)),
                            MatchValue(
                                value=Constant(value=0)),
                            MatchValue(
                                value=Constant(value=0))]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])],
    type_ignores=[])

Добавлен в версии 3.10.

class ast.MatchAs(pattern, name)

Шаблон «как», шаблон захвата или шаблон подстановки. pattern содержит шаблон соответствия, с которым будет сопоставляться предмет. Если шаблон None, узел представляет шаблон захвата (т.е. простое имя) и всегда будет успешным.

Атрибут 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))])])],
    type_ignores=[])

Добавлен в версии 3.10.

class ast.MatchOr(patterns)

Шаблон «или». Шаблон «или» последовательно сопоставляет каждый из своих подшаблонов с предметом, пока один из них не совпадёт. Шаблон «или» считается успешным. Если ни один из подшаблонов не совпадёт, шаблон «или» считается неуспешным. Атрибут 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))])])],
    type_ignores=[])

Добавлен в версии 3.10.

Параметры типов

Параметры типов могут существовать в классах, функциях и псевдонимах типов.

class ast.TypeVar(name, bound)

Переменная типа typing.TypeVar. name — имя переменной типа. bound — ограничение, если таковое имеется. Если bound — это Tuple, это ограничение; в противном случае это ограничение.

>>> print(ast.dump(ast.parse("type Alias[T: int] = list[T]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                TypeVar(
                    name='T',
                    bound=Name(id='int', ctx=Load()))],
            value=Subscript(
                value=Name(id='list', ctx=Load()),
                slice=Name(id='T', ctx=Load()),
                ctx=Load()))],
    type_ignores=[])

Добавлен в версии 3.12.

class ast.ParamSpec(name)

Спецификация параметра typing.ParamSpec. name — имя спецификации параметра.

>>> print(ast.dump(ast.parse("type Alias[**P] = Callable[P, int]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                ParamSpec(name='P')],
            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()))],
    type_ignores=[])

Добавлен в версии 3.12.

class ast.TypeVarTuple(name)

Кортеж переменных типа typing.TypeVarTuple. name — имя кортежа переменных типа.

>>> 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')],
            value=Subscript(
                value=Name(id='tuple', ctx=Load()),
                slice=Tuple(
                    elts=[
                        Starred(
                            value=Name(id='Ts', ctx=Load()),
                            ctx=Load())],
                    ctx=Load()),
                ctx=Load()))],
    type_ignores=[])

Добавлен в версии 3.12.

Определения функций и классов

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(
                    posonlyargs=[],
                    args=[
                        arg(arg='x'),
                        arg(arg='y')],
                    kwonlyargs=[],
                    kw_defaults=[],
                    defaults=[]),
                body=Constant(value=Ellipsis)))],
    type_ignores=[])

class ast.arguments(posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults)

Аргументы функции.

• posonlyargs, args и kwonlyargs — это списки узлов arg.
• vararg и kwarg — это отдельные узлы arg, относящиеся к *args, **kwargs параметрам.
• kw_defaults — это список значений по умолчанию для ключевых аргументов. Если значение отсутствует, соответствующий аргумент обязателен.
• 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(
                posonlyargs=[],
                args=[
                    arg(
                        arg='a',
                        annotation=Constant(value='annotation')),
                    arg(arg='b'),
                    arg(arg='c')],
                vararg=arg(arg='d'),
                kwonlyargs=[
                    arg(arg='e'),
                    arg(arg='f')],
                kw_defaults=[
                    None,
                    Constant(value=3)],
                kwarg=arg(arg='g'),
                defaults=[
                    Constant(value=1),
                    Constant(value=2)]),
            body=[
                Pass()],
            decorator_list=[
                Name(id='decorator1', ctx=Load()),
                Name(id='decorator2', ctx=Load())],
            returns=Constant(value='return annotation'),
            type_params=[])],
    type_ignores=[])

class ast.Return(value)

Оператор return.

>>> print(ast.dump(ast.parse('return 4'), indent=4))
Module(
    body=[
        Return(
            value=Constant(value=4))],
    type_ignores=[])

class ast.Yield(value)

class ast.YieldFrom(value)

Выражение yield или yield from. Поскольку это выражения, они должны быть обернуты в узел Expr, если возвращаемое значение не используется.

>>> print(ast.dump(ast.parse('yield x'), indent=4))
Module(
    body=[
        Expr(
            value=Yield(
                value=Name(id='x', ctx=Load())))],
    type_ignores=[])

>>> print(ast.dump(ast.parse('yield from x'), indent=4))
Module(
    body=[
        Expr(
            value=YieldFrom(
                value=Name(id='x', ctx=Load())))],
    type_ignores=[])

class ast.Global(names)

class ast.Nonlocal(names)

Операторы global и nonlocal. names — это список строк.

>>> print(ast.dump(ast.parse('global x,y,z'), indent=4))
Module(
    body=[
        Global(
            names=[
                'x',
                'y',
                'z'])],
    type_ignores=[])

>>> print(ast.dump(ast.parse('nonlocal x,y,z'), indent=4))
Module(
    body=[
        Nonlocal(
            names=[
                'x',
                'y',
                'z'])],
    type_ignores=[])

class ast.ClassDef(name, bases, keywords, body, decorator_list, type_params)

Определение класса.

• name — это строка с именем класса
• bases — это список узлов для явно указанных базовых классов.
• keywords — это список узлов keyword, в основном для 'метакласса'. Другие ключевые слова будут переданы метаклассу в соответствии с PEP-3115.
• 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())],
            type_params=[])],
    type_ignores=[])

Изменено в версии 3.12: Добавлен type_params.

Асинхронные и ожидающие операции

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.

>>> print(ast.dump(ast.parse("""\
... async def f():
...     await other_func()
... """), indent=4))
Module(
    body=[
        AsyncFunctionDef(
            name='f',
            args=arguments(
                posonlyargs=[],
                args=[],
                kwonlyargs=[],
                kw_defaults=[],
                defaults=[]),
            body=[
                Expr(
                    value=Await(
                        value=Call(
                            func=Name(id='other_func', ctx=Load()),
                            args=[],
                            keywords=[])))],
            decorator_list=[],
            type_params=[])],
    type_ignores=[])

class ast.AsyncFor(target, iter, body, orelse, type_comment)

class ast.AsyncWith(items, body, type_comment)

Циклы async for и операторы контекста async with. Они имеют те же поля, что и For и With соответственно. Допустимы только в теле AsyncFunctionDef.