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

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

class ast.Module(body, type_ignores)

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

body — это list операторов модуля (Statements).

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. Тип узла, создаваемый функцией 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, kind)

Постоянное значение. Атрибут value литерала Constant содержит представляемый им объект Python. Представленными значениями могут быть экземпляры str, bytes, int, float, complex и bool, а также константы None и Ellipsis.

Атрибут kind — необязательная строка. Для строковых литералов с префиксом u атрибуту kind присваивается значение 'u'. Для всех остальных констант kind имеет значение None.

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

class ast.FormattedValue(value, conversion, format_spec)

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

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

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

  • -1: без форматирования
  • 97 (ord('a')): форматирование !a ASCII
  • 114 (ord('r')): форматирование !r repr()
  • 115 (ord('s')): форматирование !s string
• 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.TemplateStr(values, /)

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

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

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

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

Узел, представляющий отдельное поле интерполяции в строковом литерале-шаблоне.

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

• str — это константа, содержащая текст выражения интерполяции.

  Если str имеет значение None, при вызове ast.unparse() для создания кода используется value. В этом случае больше не гарантируется, что сгенерированный код будет идентичен исходному; эта возможность предназначена для генерации кода.

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

  • -1: без преобразования
  • 97 (ord('a')): преобразование !a ASCII
  • 114 (ord('r')): преобразование !r repr()
  • 115 (ord('s')): преобразование !s string

  Он имеет тот же смысл, что и FormattedValue.conversion.

• format_spec — это узел JoinedStr, представляющий форматирование значения, или None, если формат не указан. conversion и format_spec могут быть заданы одновременно. Этот атрибут имеет тот же смысл, что и FormattedValue.format_spec.

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, а в соответствующей позиции списка 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

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

>>> 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. Этот тип необходимо использовать при создании узла 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()))])

Выражения

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)

Сравнение двух или более значений. 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, представляющих аргументы, переданные по ключевому слову.

Аргументы 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 создаётся оператором выражений присваивания (также известным как оператор-морж). В отличие от узла 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))])

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

Расширенное присваивание, например 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))])

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

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)

Псевдоним типа, созданный с помощью инструкции type. name — имя псевдонима, type_params — список параметров типа, а 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 специального представления, а представлены дополнительными узлами 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))])])])

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, но узлы 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))])])])

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

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

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

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

Шаблон сопоставления с литералом, сравниваемым по идентичности. 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))])])])

Добавлено в версии 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 — это выражение, задающее класс, с которым выполняется сопоставление. 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))]),
                    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», шаблон захвата или шаблон-заполнитель. 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))])])])

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

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

Аннотации типов

class ast.TypeIgnore(lineno, tag)

Комментарий # type: ignore, расположенный на строке lineno. tag — необязательная метка, указанная в форме # 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 не создаются, если параметр type_comments установлен в False (значение по умолчанию). Дополнительные сведения см. в разделе ast.parse().

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

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

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

class ast.TypeVar(name, bound, default_value)

Объект typing.TypeVar. name — имя переменной типа. bound — ограничение или ограничения, если они есть. Если 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.
• 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.

Асинхронность и 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.

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