ast – Абстрактные синтаксические деревья¶ast – Abstract syntax trees

Корневые узлы¶Root nodes

class ast.Module(body, type_ignores)¶

A Python module, as with file input. Node type generated by ast.parse() in the default "exec" mode.

body is a list of the module’s Statements.

type_ignores – это список 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)¶

A single Python expression input. Node type generated by ast.parse() when mode is "eval".

body is a single node, one of the expression types.

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

class ast.Interactive(body)¶

A single interactive input, like in Interactive Mode. Node type generated by ast.parse() when mode is "single".

body is a list of statement nodes.

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

class ast.FunctionType(argtypes, returns)¶

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

Такие комментарии о типах выглядели следующим образом:

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

argtypes is a list of expression nodes.

returns is a single expression node.

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

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

Литералы¶Literals

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, то value используется для генерации кода при вызове ast.unparse(). Это больше не гарантирует, что сгенерированный код идентичен исходному, и предназначено для генерации кода.

• 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, а 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())]))

Переменные¶Variables

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

Выражения¶Expressions

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.

Инструкции¶Statements

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)) # множественное присваивание
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)) # распаковка
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)) # аннотация со скобками
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)) # аннотация атрибута
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)) # аннотация подписки
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 – это узел Имя для x (с контекстом Store), op – это Сложение, а value – это Константа со значением 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 – объект исключения, который необходимо возбудить, обычно Вызов или Имя, или None для отдельного raise. cause – необязательная часть для 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.

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

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

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

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

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

class ast.Match(subject, cases)¶

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

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

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

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

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

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

>>> 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 – это узел выражения. Допустимые узлы значений ограничены, как описано в документации оператора match. Этот шаблон успешно срабатывает, если subject сопоставления равен вычисленному значению.

>>> 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. Этот шаблон успешно срабатывает, если subject сопоставления является заданной константой.

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

Шаблон последовательности (sequence pattern) в match. patterns содержит шаблоны, которые будут сопоставляться с элементами subject, если subject является последовательностью. Сопоставляется с последовательностью переменной длины, если один из подшаблонов является узлом 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)¶

Шаблон отображения (mapping pattern) в match. keys – последовательность узлов выражений. patterns – соответствующая последовательность узлов шаблонов. rest – необязательное имя, которое можно указать для захвата оставшихся элементов отображения. Допустимые ключевые выражения ограничены, как описано в документации оператора match.

Этот шаблон успешно срабатывает, если subject является отображением, все вычисленные ключевые выражения присутствуют в отображении, а значение, соответствующее каждому ключу, совпадает с соответствующим подшаблоном. Если 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)¶

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

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

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

>>> 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», шаблон захвата (capture pattern) или шаблон-заменитель (wildcard pattern). pattern содержит шаблон match, с которым будет сопоставлен subject. Если шаблон равен None, узел представляет собой шаблон захвата (т.е. просто имя) и всегда успешно срабатывает.

Атрибут name содержит имя, которое будет привязано при успешном сопоставлении шаблона. Если name равно None, то pattern также должно быть None, и узел представляет собой шаблон-заменитель (wildcard).

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

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

class ast.MatchOr(patterns)¶

Сопоставление «or-pattern» (шаблон ИЛИ). Or-pattern последовательно сопоставляет каждый из своих подшаблонов с subject, пока один из них не сработает. Тогда считается, что or-pattern сработал. Если ни один из подшаблонов не сработал, or-pattern не срабатывает. Атрибут patterns содержит список узлов шаблонов match, которые будут сопоставляться с subject.

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

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

Аннотации типов¶Type annotations

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.

Параметры типа¶Type parameters

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

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.

Определения функций и классов¶Function and class definitions

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 – это список значений по умолчанию для keyword-only аргументов. Если один из них равен 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.

async и await¶Async and 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.