ast — Abstract Syntax Trees

Вихідний код: Lib/ast.py

---

Модуль ast допомагає програмам Python обробляти дерева граматики абстрактного синтаксису Python. Сам абстрактний синтаксис може змінюватися з кожним випуском Python; цей модуль допомагає програмно дізнатися, як виглядає поточна граматика.

Абстрактне синтаксичне дерево можна створити, передавши ast.PyCF_ONLY_AST як прапорець вбудованій функції compile() або використовуючи помічник parse(), наданий у цьому модулі. Результатом буде дерево об’єктів, усі класи яких успадковуються від ast.AST. Абстрактне синтаксичне дерево можна скомпілювати в об’єкт коду Python за допомогою вбудованої функції compile().

Абстрактна граматика

Наразі абстрактна граматика визначається наступним чином:

-- ASDL's 4 builtin types are:
-- identifier, int, string, constant

module Python
{
    mod = Module(stmt* body, type_ignore* type_ignores)
        | Interactive(stmt* body)
        | Expression(expr body)
        | FunctionType(expr* argtypes, expr returns)

    stmt = FunctionDef(identifier name, arguments args,
                       stmt* body, expr* decorator_list, expr? returns,
                       string? type_comment)
          | AsyncFunctionDef(identifier name, arguments args,
                             stmt* body, expr* decorator_list, expr? returns,
                             string? type_comment)

          | ClassDef(identifier name,
             expr* bases,
             keyword* keywords,
             stmt* body,
             expr* decorator_list)
          | Return(expr? value)

          | Delete(expr* targets)
          | Assign(expr* targets, expr value, string? type_comment)
          | AugAssign(expr target, operator op, expr value)
          -- 'simple' indicates that we annotate simple name without parens
          | AnnAssign(expr target, expr annotation, expr? value, int simple)

          -- use 'orelse' because else is a keyword in target languages
          | For(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
          | AsyncFor(expr target, expr iter, stmt* body, stmt* orelse, string? type_comment)
          | While(expr test, stmt* body, stmt* orelse)
          | If(expr test, stmt* body, stmt* orelse)
          | With(withitem* items, stmt* body, string? type_comment)
          | AsyncWith(withitem* items, stmt* body, string? type_comment)

          | Raise(expr? exc, expr? cause)
          | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
          | Assert(expr test, expr? msg)

          | Import(alias* names)
          | ImportFrom(identifier? module, alias* names, int? level)

          | Global(identifier* names)
          | Nonlocal(identifier* names)
          | Expr(expr value)
          | Pass | Break | Continue

          -- col_offset is the byte offset in the utf8 string the parser uses
          attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

          -- BoolOp() can use left & right?
    expr = BoolOp(boolop op, expr* values)
         | NamedExpr(expr target, expr value)
         | BinOp(expr left, operator op, expr right)
         | UnaryOp(unaryop op, expr operand)
         | Lambda(arguments args, expr body)
         | IfExp(expr test, expr body, expr orelse)
         | Dict(expr* keys, expr* values)
         | Set(expr* elts)
         | ListComp(expr elt, comprehension* generators)
         | SetComp(expr elt, comprehension* generators)
         | DictComp(expr key, expr value, comprehension* generators)
         | GeneratorExp(expr elt, comprehension* generators)
         -- the grammar constrains where yield expressions can occur
         | Await(expr value)
         | Yield(expr? value)
         | YieldFrom(expr value)
         -- need sequences for compare to distinguish between
         -- x < 4 < 3 and (x < 4) < 3
         | Compare(expr left, cmpop* ops, expr* comparators)
         | Call(expr func, expr* args, keyword* keywords)
         | FormattedValue(expr value, int? conversion, expr? format_spec)
         | JoinedStr(expr* values)
         | Constant(constant value, string? kind)

         -- the following expression can appear in assignment context
         | Attribute(expr value, identifier attr, expr_context ctx)
         | Subscript(expr value, expr slice, expr_context ctx)
         | Starred(expr value, expr_context ctx)
         | Name(identifier id, expr_context ctx)
         | List(expr* elts, expr_context ctx)
         | Tuple(expr* elts, expr_context ctx)

         -- can appear only in Subscript
         | Slice(expr? lower, expr? upper, expr? step)

          -- col_offset is the byte offset in the utf8 string the parser uses
          attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    expr_context = Load | Store | Del

    boolop = And | Or

    operator = Add | Sub | Mult | MatMult | Div | Mod | Pow | LShift
                 | RShift | BitOr | BitXor | BitAnd | FloorDiv

    unaryop = Invert | Not | UAdd | USub

    cmpop = Eq | NotEq | Lt | LtE | Gt | GtE | Is | IsNot | In | NotIn

    comprehension = (expr target, expr iter, expr* ifs, int is_async)

    excepthandler = ExceptHandler(expr? type, identifier? name, stmt* body)
                    attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    arguments = (arg* posonlyargs, arg* args, arg? vararg, arg* kwonlyargs,
                 expr* kw_defaults, arg? kwarg, expr* defaults)

    arg = (identifier arg, expr? annotation, string? type_comment)
           attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    -- keyword arguments supplied to call (NULL identifier for **kwargs)
    keyword = (identifier? arg, expr value)
               attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    -- import name with optional 'as' alias.
    alias = (identifier name, identifier? asname)

    withitem = (expr context_expr, expr? optional_vars)

    type_ignore = TypeIgnore(int lineno, string tag)
}

Класи вузлів

class ast.AST

This is the base of all AST node classes. The actual node classes are derived from the Parser/Python.asdl file, which is reproduced below. They are defined in the _ast C module and re-exported in ast.

Для кожного лівого символу в абстрактній граматиці визначено один клас (наприклад, ast.stmt або ast.expr). Крім того, є один клас, визначений для кожного конструктора в правій частині; ці класи успадковують класи для лівих дерев. Наприклад, ast.BinOp успадковується від ast.expr. Для виробничих правил з альтернативами (він же «суми») лівий клас є абстрактним: створюються лише екземпляри конкретних вузлів конструктора.

_fields

Each concrete class has an attribute _fields which gives the names of all child nodes.

Кожен екземпляр конкретного класу має один атрибут для кожного дочірнього вузла типу, визначеного в граматиці. Наприклад, екземпляри ast.BinOp мають атрибут left типу ast.expr.

Якщо ці атрибути позначені як необов’язкові в граматиці (використовуючи знак питання), значенням може бути None. Якщо атрибути можуть мати нуль або більше значень (позначених зірочкою), значення представлені у вигляді списків Python. Під час компіляції AST за допомогою compile() усі можливі атрибути повинні бути присутніми та мати дійсні значення.

lineno

col_offset

end_lineno

end_col_offset

Instances of ast.expr and ast.stmt subclasses have lineno, col_offset, end_lineno, and end_col_offset attributes. The lineno and end_lineno are the first and last line numbers of the source text span (1-indexed so the first line is line 1), and the col_offset and end_col_offset are the corresponding UTF-8 byte offsets of the first and last tokens that generated the node. The UTF-8 offset is recorded because the parser uses UTF-8 internally.

Зауважте, що кінцеві позиції не потрібні компілятору і тому є необов’язковими. Кінцеве зміщення вказується після останнього символу, наприклад, можна отримати вихідний сегмент вузла однорядкового виразу за допомогою source_line[node.col_offset : node.end_col_offset].

Конструктор класу ast.T аналізує його аргументи наступним чином:

• Якщо є позиційні аргументи, їх має бути стільки, скільки елементів у T._fields; вони будуть призначені як атрибути цих імен.

• Якщо є ключові аргументи, вони встановлять атрибути з однаковими іменами на задані значення.

Наприклад, щоб створити та заповнити вузол ast.UnaryOp, ви можете використати

node = ast.UnaryOp()
node.op = ast.USub()
node.operand = ast.Constant()
node.operand.value = 5
node.operand.lineno = 0
node.operand.col_offset = 0
node.lineno = 0
node.col_offset = 0

or the more compact

node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0),
                   lineno=0, col_offset=0)

Змінено в версії 3.8: Клас ast.Constant тепер використовується для всіх констант.

Змінено в версії 3.9: Прості індекси представлені їх значеннями, розширені зрізи представлені у вигляді кортежів.

Застаріло починаючи з версії 3.8: Old classes ast.Num, ast.Str, ast.Bytes, ast.NameConstant and ast.Ellipsis are still available, but they will be removed in future Python releases. In the meantime, instantiating them will return an instance of a different class.

Застаріло починаючи з версії 3.9: Old classes ast.Index and ast.ExtSlice are still available, but they will be removed in future Python releases. In the meantime, instantiating them will return an instance of a different class.

Примітка

Описи конкретних класів вузлів, відображені тут, спочатку були адаптовані з фантастичного проекту Green Tree Snakes та всіх його учасників.

Літерали

class ast.Constant(value)

Постійне значення. Атрибут value літералу Constant містить об’єкт Python, який він представляє. Представлені значення можуть бути простими типами, такими як число, рядок або None, а також незмінними типами контейнерів (кортежі та заморожені набори), якщо всі їхні елементи постійні.

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

class ast.FormattedValue(value, conversion, format_spec)

Вузол, що представляє одне поле форматування в f-рядку. Якщо рядок містить одне поле форматування та нічого іншого, вузол можна ізолювати, інакше він з’являється в JoinedStr.

• значення - будь-який вузол виразу (наприклад, літерал, змінна або виклик функції).

• перетворення є цілим числом:

  • -1: без форматування

  • 115: форматування рядка !s

  • 114: форматування !r repr

  • 97: !a форматування ascii

• format_spec — це вузол JoinedStr, який представляє форматування значення, або None, якщо формат не вказано. І conversion, і format_spec можна встановити одночасно.

class ast.JoinedStr(values)

F-рядок, що містить ряд вузлів FormattedValue і Constant.

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

class ast.List(elts, ctx)

class ast.Tuple(elts, ctx)

Список або кортеж. elts містить список вузлів, що представляють елементи. ctx є Store, якщо контейнер є метою призначення (тобто (x,y)=something), і Load інакше.

>>> print(ast.dump(ast.parse('[1, 2, 3]', mode='eval'), indent=4))
Expression(
    body=List(
        elts=[
            Constant(value=1),
            Constant(value=2),
            Constant(value=3)],
        ctx=Load()))
>>> print(ast.dump(ast.parse('(1, 2, 3)', mode='eval'), indent=4))
Expression(
    body=Tuple(
        elts=[
            Constant(value=1),
            Constant(value=2),
            Constant(value=3)],
        ctx=Load()))

class ast.Set(elts)

Набір. elts містить список вузлів, що представляють елементи набору.

>>> print(ast.dump(ast.parse('{1, 2, 3}', mode='eval'), indent=4))
Expression(
    body=Set(
        elts=[
            Constant(value=1),
            Constant(value=2),
            Constant(value=3)]))

class ast.Dict(keys, values)

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

Під час розпакування словника за допомогою словникових літералів вираз, який потрібно розгорнути, потрапляє до списку значень із 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()))],
    type_ignores=[])

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

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

class ast.Starred(value, ctx)

Посилання на змінну *var. value містить змінну, як правило, вузол Name. Цей тип необхідно використовувати під час створення вузла Call з *args.

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

Вирази

class ast.Expr(value)

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

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

class ast.UnaryOp(op, operand)

Унарна операція. op є оператором, а operand будь-яким вузлом виразу.

class ast.UAdd

class ast.USub

class ast.Not

class ast.Invert

Унарні маркери оператора. Not - це ключове слово not, Invert - це оператор ~.

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

class ast.BinOp(left, op, right)

Двійкова операція (наприклад, додавання або ділення). op є оператором, left і right є будь-якими вузлами виразу.

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

class ast.Add

class ast.Sub

class ast.Mult

class ast.Div

class ast.FloorDiv

class ast.Mod

class ast.Pow

class ast.LShift

class ast.RShift

class ast.BitOr

class ast.BitXor

class ast.BitAnd

class ast.MatMult

Бінарні операторські токени.

class ast.BoolOp(op, values)

Логічна операція «або» або «і». op - це Or або And. values - це значення, які беруть участь. Послідовні операції з тим самим оператором, наприклад a або b або 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, starargs, kwargs)

Виклик функції. func – це функція, яка часто буде об’єктом Name або Attribute. З аргументів:

• args містить список аргументів, переданих за позицією.

• keywords holds a list of keyword objects representing arguments passed by keyword.

When creating a Call node, args and keywords are required, but they can be empty lists. starargs and kwargs are optional.

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

Підписка

class ast.Subscript(value, slice, ctx)

Нижній індекс, наприклад «l[1]». значення - це об’єкт з індексом (зазвичай послідовність або відображення). slice - це індекс, зріз або ключ. Це може бути Tuple і містити Slice. ctx - це Load, Store або Del відповідно до дії, виконаної з нижнім індексом.

>>> print(ast.dump(ast.parse('l[1:2, 3]', mode='eval'), indent=4))
Expression(
    body=Subscript(
        value=Name(id='l', ctx=Load()),
        slice=Tuple(
            elts=[
                Slice(
                    lower=Constant(value=1),
                    upper=Constant(value=2)),
                Constant(value=3)],
            ctx=Load()),
        ctx=Load()))

class ast.Slice(lower, upper, step)

Звичайна нарізка (за формою lower:upper або lower:upper:step). Може зустрічатися лише всередині поля slice Subscript, або безпосередньо, або як елемент Tuple.

>>> print(ast.dump(ast.parse('l[1:2]', mode='eval'), indent=4))
Expression(
    body=Subscript(
        value=Name(id='l', ctx=Load()),
        slice=Slice(
            lower=Constant(value=1),
            upper=Constant(value=2)),
        ctx=Load()))

Осягнення

class ast.ListComp(elt, generators)

class ast.SetComp(elt, generators)

class ast.GeneratorExp(elt, generators)

class ast.DictComp(key, value, generators)

Список і набір розуміння, генератор виразів і словник розуміння. elt (або key і value) — це один вузол, що представляє частину, яка буде оцінюватися для кожного елемента.

generators - це список вузлів comprehension.

>>> print(ast.dump(ast.parse('[x for x in numbers]', mode='eval'), indent=4))
Expression(
    body=ListComp(
        elt=Name(id='x', ctx=Load()),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers', ctx=Load()),
                ifs=[],
                is_async=0)]))
>>> print(ast.dump(ast.parse('{x: x**2 for x in numbers}', mode='eval'), indent=4))
Expression(
    body=DictComp(
        key=Name(id='x', ctx=Load()),
        value=BinOp(
            left=Name(id='x', ctx=Load()),
            op=Pow(),
            right=Constant(value=2)),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers', ctx=Load()),
                ifs=[],
                is_async=0)]))
>>> print(ast.dump(ast.parse('{x for x in numbers}', mode='eval'), indent=4))
Expression(
    body=SetComp(
        elt=Name(id='x', ctx=Load()),
        generators=[
            comprehension(
                target=Name(id='x', ctx=Store()),
                iter=Name(id='numbers', ctx=Load()),
                ifs=[],
                is_async=0)]))

class ast.comprehension(target, iter, ifs, is_async)

Одне речення за для розуміння. target - це посилання для використання для кожного елемента - зазвичай Name або Tuple вузол. iter - це об’єкт для повторення. ifs — це список перевірочних виразів: кожен пункт for може мати кілька ifs.

is_async вказує, що розуміння є асинхронним (використовуючи async for замість for). Значення є цілим числом (0 або 1).

>>> print(ast.dump(ast.parse('[ord(c) for line in file for c in line]', mode='eval'),
...                indent=4)) # Multiple comprehensions in one.
Expression(
    body=ListComp(
        elt=Call(
            func=Name(id='ord', ctx=Load()),
            args=[
                Name(id='c', ctx=Load())],
            keywords=[]),
        generators=[
            comprehension(
                target=Name(id='line', ctx=Store()),
                iter=Name(id='file', ctx=Load()),
                ifs=[],
                is_async=0),
            comprehension(
                target=Name(id='c', ctx=Store()),
                iter=Name(id='line', ctx=Load()),
                ifs=[],
                is_async=0)]))

>>> print(ast.dump(ast.parse('(n**2 for n in it if n>5 if n<10)', mode='eval'),
...                indent=4)) # generator comprehension
Expression(
    body=GeneratorExp(
        elt=BinOp(
            left=Name(id='n', ctx=Load()),
            op=Pow(),
            right=Constant(value=2)),
        generators=[
            comprehension(
                target=Name(id='n', ctx=Store()),
                iter=Name(id='it', ctx=Load()),
                ifs=[
                    Compare(
                        left=Name(id='n', ctx=Load()),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=5)]),
                    Compare(
                        left=Name(id='n', ctx=Load()),
                        ops=[
                            Lt()],
                        comparators=[
                            Constant(value=10)])],
                is_async=0)]))

>>> print(ast.dump(ast.parse('[i async for i in soc]', mode='eval'),
...                indent=4)) # Async comprehension
Expression(
    body=ListComp(
        elt=Name(id='i', ctx=Load()),
        generators=[
            comprehension(
                target=Name(id='i', ctx=Store()),
                iter=Name(id='soc', ctx=Load()),
                ifs=[],
                is_async=1)]))

Заяви

class ast.Assign(targets, value, type_comment)

Доручення. targets — це список вузлів, а value — один вузол.

Кілька вузлів у цілях представляють призначення однакового значення кожному. Розпакування представлено розміщенням Tuple або List у targets.

type_comment

type_comment – необов’язковий рядок із анотацією типу як коментаря.

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

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

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

An assignment with a type annotation. target is a single node and can be a Name, a Attribute or a Subscript. annotation is the annotation, such as a Constant or Name node. value is a single optional node. simple is a boolean integer set to True for a Name node in target that do not appear in between parenthesis and are hence pure names and not expressions.

>>> print(ast.dump(ast.parse('c: int'), indent=4))
Module(
    body=[
        AnnAssign(
            target=Name(id='c', ctx=Store()),
            annotation=Name(id='int', ctx=Load()),
            simple=1)],
    type_ignores=[])

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

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

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

class ast.AugAssign(target, op, value)

Доповнене присвоювання, наприклад a += 1. У наступному прикладі target є вузлом Name для x (з контекстом Store), op це Add, а значення є Constant зі значенням 1.

The target attribute connot be of class Tuple or List, unlike the targets of Assign.

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

class ast.Raise(exc, cause)

Оператор raise. exc — це об’єкт винятку, який потрібно викликати, зазвичай це Call або Name, або None для окремого raise. cause є необов’язковою частиною для y у raise x from y.

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

class ast.Assert(test, msg)

Твердження. test містить умову, як-от вузол Compare. msg містить повідомлення про помилку.

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

class ast.Delete(targets)

Представляє оператор del. targets – це список вузлів, наприклад вузли Name, Attribute або Subscript.

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

class ast.Pass

Заява pass.

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

Інші оператори, які застосовуються лише всередині функцій або циклів, описані в інших розділах.

Імпорт

class ast.Import(names)

Заява про імпорт. names - це список вузлів alias.

>>> print(ast.dump(ast.parse('import x,y,z'), indent=4))
Module(
    body=[
        Import(
            names=[
                alias(name='x'),
                alias(name='y'),
                alias(name='z')])],
    type_ignores=[])

class ast.ImportFrom(module, names, level)

Представляє from x import y. module — це необроблений рядок назви „from“ без будь-яких крапок на початку або None для операторів, таких як from . імпортувати foo. level — це ціле число, що містить рівень відносного імпорту (0 означає абсолютний імпорт).

>>> print(ast.dump(ast.parse('from y import x,y,z'), indent=4))
Module(
    body=[
        ImportFrom(
            module='y',
            names=[
                alias(name='x'),
                alias(name='y'),
                alias(name='z')],
            level=0)],
    type_ignores=[])

class ast.alias(name, asname)

Обидва параметри є необробленими рядками імен. asname може бути None, якщо має використовуватися звичайна назва.

>>> print(ast.dump(ast.parse('from ..foo.bar import a as b, c'), indent=4))
Module(
    body=[
        ImportFrom(
            module='foo.bar',
            names=[
                alias(name='a', asname='b'),
                alias(name='c')],
            level=2)],
    type_ignores=[])

Контроль потоку

Примітка

Необов’язкові пропозиції, такі як else, зберігаються як порожній список, якщо їх немає.

class ast.If(test, body, orelse)

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

Речення elif не мають спеціального представлення в AST, а радше з’являються як додаткові вузли If у розділі orelse попереднього.

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

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

A for loop. target holds the variable(s) the loop assigns to, as a single Name, Tuple or List node. iter holds the item to be looped over, again as a single node. body and orelse contain lists of nodes to execute. Those in orelse are executed if the loop finishes normally, rather than via a break statement.

type_comment

type_comment – необов’язковий рядок із анотацією типу як коментаря.

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

class ast.While(test, body, orelse)

Цикл while. test містить умову, як-от вузол Compare.

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

class ast.Break

class ast.Continue

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

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

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

блоки try. Усі атрибути є списком вузлів для виконання, за винятком обробників, який є списком ExceptHandler вузлів.

>>> print(ast.dump(ast.parse("""
... try:
...    ...
... except Exception:
...    ...
... except OtherException as e:
...    ...
... else:
...    ...
... finally:
...    ...
... """), indent=4))
Module(
    body=[
        Try(
            body=[
                Expr(
                    value=Constant(value=Ellipsis))],
            handlers=[
                ExceptHandler(
                    type=Name(id='Exception', ctx=Load()),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                ExceptHandler(
                    type=Name(id='OtherException', ctx=Load()),
                    name='e',
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])],
            orelse=[
                Expr(
                    value=Constant(value=Ellipsis))],
            finalbody=[
                Expr(
                    value=Constant(value=Ellipsis))])],
    type_ignores=[])

class ast.ExceptHandler(type, name, body)

Єдине речення крім. type — це тип винятку, якому він відповідатиме, як правило, вузол Name (або None для речення catch-all except:). name — це необроблений рядок для імені, який містить виняток, або None, якщо в пропозиції немає as foo. body - це список вузлів.

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

class ast.With(items, body, type_comment)

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

type_comment

type_comment – необов’язковий рядок із анотацією типу як коментаря.

class ast.withitem(context_expr, optional_vars)

Єдиний контекстний менеджер у блоці with. context_expr - це менеджер контексту, часто вузол Call. optional_vars — це Name, Tuple або List для частини as foo, або None, якщо вона не використовується.

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

Визначення функцій і класів

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

Визначення функції.

• name - це необроблений рядок назви функції.

• args є вузлом arguments.

• body - це список вузлів усередині функції.

• decorator_list — це список декораторів, які будуть застосовані, зберігаються в першу чергу (тобто перший у списку буде застосовано останнім).

• returns - це анотація повернення.

type_comment

type_comment – необов’язковий рядок із анотацією типу як коментаря.

class ast.Lambda(args, body)

лямбда - це мінімальне визначення функції, яке можна використовувати всередині виразу. На відміну від FunctionDef, body містить один вузол.

>>> print(ast.dump(ast.parse('lambda x,y: ...'), indent=4))
Module(
    body=[
        Expr(
            value=Lambda(
                args=arguments(
                    posonlyargs=[],
                    args=[
                        arg(arg='x'),
                        arg(arg='y')],
                    kwonlyargs=[],
                    kw_defaults=[],
                    defaults=[]),
                body=Constant(value=Ellipsis)))],
    type_ignores=[])

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

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

• posonlyargs, args і kwonlyargs - це списки вузлів arg.

• vararg і kwarg є окремими вузлами arg, які посилаються на параметри *args, **kwargs.

• kw_defaults - це список значень за замовчуванням для аргументів, що містять лише ключові слова. Якщо одне значення None, потрібен відповідний аргумент.

• defaults - це список значень за замовчуванням для аргументів, які можна передати позиційно. Якщо стандартних значень менше, вони відповідають останнім n аргументам.

class ast.arg(arg, annotation, type_comment)

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

type_comment

type_comment – необов’язковий рядок із анотацією типу як коментаря

>>> print(ast.dump(ast.parse("""\
... @decorator1
... @decorator2
... def f(a: 'annotation', b=1, c=2, *d, e, f=3, **g) -> 'return annotation':
...     pass
... """), indent=4))
Module(
    body=[
        FunctionDef(
            name='f',
            args=arguments(
                posonlyargs=[],
                args=[
                    arg(
                        arg='a',
                        annotation=Constant(value='annotation')),
                    arg(arg='b'),
                    arg(arg='c')],
                vararg=arg(arg='d'),
                kwonlyargs=[
                    arg(arg='e'),
                    arg(arg='f')],
                kw_defaults=[
                    None,
                    Constant(value=3)],
                kwarg=arg(arg='g'),
                defaults=[
                    Constant(value=1),
                    Constant(value=2)]),
            body=[
                Pass()],
            decorator_list=[
                Name(id='decorator1', ctx=Load()),
                Name(id='decorator2', ctx=Load())],
            returns=Constant(value='return annotation'))],
    type_ignores=[])

class ast.Return(value)

Оператор повернення.

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

class ast.Yield(value)

class ast.YieldFrom(value)

A yield or yield from expression. Because these are expressions, they must be wrapped in a Expr node if the value sent back is not used.

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

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

class ast.Global(names)

class ast.Nonlocal(names)

глобальні і нелокальні заяви. names - це список необроблених рядків.

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

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

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

Визначення класу.

• name - це необроблений рядок для імені класу

• бази - це список вузлів для явно визначених базових класів.

• keywords is a list of keyword nodes, principally for „metaclass“. Other keywords will be passed to the metaclass, as per PEP-3115.

• starargs and kwargs are each a single node, as in a function call. starargs will be expanded to join the list of base classes, and kwargs will be passed to the metaclass.

• body - це список вузлів, що представляють код у визначенні класу.

• decorator_list - це список вузлів, як у FunctionDef.

>>> print(ast.dump(ast.parse("""\
... @decorator1
... @decorator2
... class Foo(base1, base2, metaclass=meta):
...     pass
... """), indent=4))
Module(
    body=[
        ClassDef(
            name='Foo',
            bases=[
                Name(id='base1', ctx=Load()),
                Name(id='base2', ctx=Load())],
            keywords=[
                keyword(
                    arg='metaclass',
                    value=Name(id='meta', ctx=Load()))],
            body=[
                Pass()],
            decorator_list=[
                Name(id='decorator1', ctx=Load()),
                Name(id='decorator2', ctx=Load())])],
    type_ignores=[])

Async і очікування

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

Визначення функції async def. Має ті самі поля, що й FunctionDef.

class ast.Await(value)

Вираз очікування. value це те, на що він чекає. Дійсний лише в тілі AsyncFunctionDef.

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

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

class ast.AsyncWith(items, body, type_comment)

async for цикли async with контекстні менеджери. Вони мають ті самі поля, що й For і With відповідно. Дійсний лише в тілі AsyncFunctionDef.

Примітка

Коли рядок аналізується ast.parse(), вузли оператора (підкласи ast.operator, ast.unaryop, ast.cmpop, ast.boolop і ast.expr_context) у повернутому дереві будуть одиночними елементами. Зміни в одному буде відображено в усіх інших входженнях того самого значення (наприклад, ast.Add).

ast Помічники

Окрім класів вузлів, модуль ast визначає ці службові функції та класи для обходу абстрактних синтаксичних дерев:

ast.parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None)

Parse the source into an AST node. Equivalent to compile(source, filename, mode, ast.PyCF_ONLY_AST).

If type_comments=True is given, the parser is modified to check and return type comments as specified by PEP 484 and PEP 526. This is equivalent to adding ast.PyCF_TYPE_COMMENTS to the flags passed to compile(). This will report syntax errors for misplaced type comments. Without this flag, type comments will be ignored, and the type_comment field on selected AST nodes will always be None. In addition, the locations of # type: ignore comments will be returned as the type_ignores attribute of Module (otherwise it is always an empty list).

Крім того, якщо mode є 'func_type', синтаксис введення змінюється відповідно до PEP 484 «коментарів типу підпису», напр. (str, int) -> Список[str].

Also, setting feature_version to a tuple (major, minor) will attempt to parse using that Python version’s grammar. Currently major must equal to 3. For example, setting feature_version=(3, 4) will allow the use of async and await as variable names. The lowest supported version is (3, 4); the highest is sys.version_info[0:2].

If source contains a null character („0“), ValueError is raised.

Попередження

Зауважте, що успішний розбір вихідного коду в об’єкт AST не гарантує, що наданий вихідний код є дійсним кодом Python, який можна виконати, оскільки етап компіляції може викликати подальші винятки SyntaxError. Наприклад, вихідний return 42 генерує дійсний вузол AST для оператора return, але його не можна скомпілювати окремо (він має бути всередині функціонального вузла).

Зокрема, ast.parse() не виконуватиме жодних перевірок обсягу, що робить крок компіляції.

Попередження

Можливий збій інтерпретатора Python із досить великим/складним рядком через обмеження глибини стеку в компіляторі AST Python.

Змінено в версії 3.8: Додано type_comments, mode='func_type' і feature_version.

ast.unparse(ast_obj)

Розберіть об’єкт ast.AST і згенеруйте рядок із кодом, який створить еквівалентний об’єкт ast.AST, якщо його проаналізувати назад за допомогою ast.parse().

Попередження

Створений рядок коду не обов’язково дорівнюватиме вихідному коду, який згенерував об’єкт ast.AST (без будь-яких оптимізацій компілятора, таких як константні кортежі/заморожені набори).

Попередження

Спроба розібрати дуже складний вираз призведе до RecursionError.

Нове в версії 3.9.

ast.literal_eval(node_or_string)

Safely evaluate an expression node or a string containing a Python literal or container display. The string or node provided may only consist of the following Python literal structures: strings, bytes, numbers, tuples, lists, dicts, sets, booleans, and None.

This can be used for safely evaluating strings containing Python values from untrusted sources without the need to parse the values oneself. It is not capable of evaluating arbitrarily complex expressions, for example involving operators or indexing.

Попередження

Можливий збій інтерпретатора Python із досить великим/складним рядком через обмеження глибини стеку в компіляторі AST Python.

Змінено в версії 3.2: Тепер дозволяє байти та встановлені літерали.

Змінено в версії 3.9: Тепер підтримується створення порожніх наборів за допомогою 'set()'.

ast.get_docstring(node, clean=True)

Повертає рядок документації даного вузла (який має бути FunctionDef, AsyncFunctionDef, ClassDef або Module вузол), або None, якщо він не має рядка документації. Якщо clean має значення true, очистіть відступ у рядку документа за допомогою inspect.cleandoc().

Змінено в версії 3.5: AsyncFunctionDef тепер підтримується.

ast.get_source_segment(source, node, *, padded=False)

Get source code segment of the source that generated node. If some location information (lineno, end_lineno, col_offset, or end_col_offset) is missing, return None.

Якщо paded має значення True, перший рядок багаторядкового оператора буде доповнено пробілами відповідно до його вихідної позиції.

Нове в версії 3.8.

ast.fix_missing_locations(node)

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

ast.increment_lineno(node, n=1)

Збільште номер рядка та номер кінцевого рядка кожного вузла в дереві, починаючи з вузла, на n. Це корисно для «переміщення коду» в інше місце у файлі.

ast.copy_location(new_node, old_node)

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

ast.iter_fields(node)

Отримайте кортеж (fieldname, value) для кожного поля node._fields, який присутній на node.

ast.iter_child_nodes(node)

Видає всі прямі дочірні вузли node, тобто всі поля, які є вузлами, і всі елементи полів, які є списками вузлів.

ast.walk(node)

Рекурсивно створювати всі вузли-нащадки в дереві, починаючи з node (включаючи сам node), у невизначеному порядку. Це корисно, якщо ви хочете лише змінити вузли на місці й не дбаєте про контекст.

class ast.NodeVisitor

Базовий клас відвідувача вузла, який проходить абстрактне синтаксичне дерево та викликає функцію відвідувача для кожного знайденого вузла. Ця функція може повертати значення, яке пересилається методом visit().

Цей клас призначений для створення підкласу, який додає методи відвідувачів.

visit(node)

Відвідайте вузол. Стандартна реалізація викликає метод під назвою self.visit_classname, де classname є назвою класу вузла, або generic_visit(), якщо цей метод не існує.

generic_visit(node)

Цей відвідувач викликає visit() для всіх дітей вузла.

Зауважте, що дочірні вузли вузлів, які мають спеціальний метод відвідувача, не будуть відвідані, якщо відвідувач не викличе generic_visit() або відвідає їх сам.

Не використовуйте NodeVisitor, якщо ви хочете застосувати зміни до вузлів під час обходу. Для цього існує спеціальний відвідувач (NodeTransformer), який дозволяє вносити зміни.

Застаріло починаючи з версії 3.8: Methods visit_Num(), visit_Str(), visit_Bytes(), visit_NameConstant() and visit_Ellipsis() are deprecated now and will not be called in future Python versions. Add the visit_Constant() method to handle all constant nodes.

class ast.NodeTransformer

Підклас NodeVisitor, який проходить абстрактне синтаксичне дерево та дозволяє модифікувати вузли.

NodeTransformer пройде AST і використає значення, що повертається методами відвідувача, щоб замінити або видалити старий вузол. Якщо значенням, що повертається методом відвідувача, є None, вузол буде видалено зі свого розташування, інакше він замінюється значенням, що повертається. Поверненим значенням може бути вихідний вузол, і в цьому випадку заміна не відбувається.

Ось приклад трансформатора, який переписує всі випадки пошуку імен (foo) на data['foo']:

class RewriteName(NodeTransformer):

    def visit_Name(self, node):
        return Subscript(
            value=Name(id='data', ctx=Load()),
            slice=Constant(value=node.id),
            ctx=node.ctx
        )

Keep in mind that if the node you’re operating on has child nodes you must either transform the child nodes yourself or call the generic_visit() method for the node first.

Для вузлів, які були частиною набору операторів (що стосується всіх вузлів операторів), відвідувач також може повернути список вузлів, а не лише один вузол.

If NodeTransformer introduces new nodes (that weren’t part of original tree) without giving them location information (such as lineno), fix_missing_locations() should be called with the new sub-tree to recalculate the location information:

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

Зазвичай ви використовуєте трансформатор таким чином:

node = YourTransformer().visit(node)

ast.dump(node, annotate_fields=True, include_attributes=False, *, indent=None)

Повернути відформатований дамп дерева у node. Це в основному корисно для цілей налагодження. Якщо annotate_fields має значення true (за замовчуванням), у поверненому рядку відображатимуться імена та значення для полів. Якщо annotate_fields має значення false, рядок результату буде більш компактним за рахунок пропуску однозначних імен полів. Такі атрибути, як номери рядків і зміщення стовпців, не скидаються за замовчуванням. Якщо це потрібно, include_attributes можна встановити на true.

Якщо indent є невід’ємним цілим числом або рядком, то дерево буде надруковано з таким рівнем відступу. Рівень відступу 0, негативний або "" вставлятиме лише нові рядки. None (за замовчуванням) вибирає однорядкове представлення. Використання додатного цілого відступу робить стільки відступів на рівень. Якщо indent є рядком (наприклад, "\t"), цей рядок використовується для відступу кожного рівня.

Змінено в версії 3.9: Додано параметр відступ.

Прапори компілятора

Наступні прапорці можуть бути передані compile(), щоб змінити вплив на компіляцію програми:

ast.PyCF_ALLOW_TOP_LEVEL_AWAIT

Вмикає підтримку await верхнього рівня, async for, async with та асинхронне розуміння.

Нове в версії 3.8.

ast.PyCF_ONLY_AST

Створює та повертає абстрактне синтаксичне дерево замість повернення скомпільованого об’єкта коду.

ast.PyCF_TYPE_COMMENTS

Вмикає підтримку коментарів типу PEP 484 і PEP 526 (# type: <type>, # type: ignore <stuff>).

Нове в версії 3.8.

Використання командного рядка

Нове в версії 3.9.

Модуль ast можна запустити як скрипт із командного рядка. Це так просто:

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

Приймаються такі варіанти:

-h, --help

Показати довідкове повідомлення та вийти.

-m <mode>

--mode <mode>

Укажіть тип коду, який потрібно скомпілювати, наприклад аргумент mode у parse().

--no-type-comments

Не аналізуйте коментарі типу.

-a, --include-attributes

Додайте такі атрибути, як номери рядків і зміщення стовпців.

-i <indent>

--indent <indent>

Відступ вузлів в AST (кількість пробілів).

Якщо вказано infile, його вміст аналізується в AST і скидається в stdout. В іншому випадку вміст читається зі стандартного вводу.

Дивись також

Green Tree Snakes, зовнішній ресурс документації, містить хороші відомості про роботу з Python AST.

ASTTokens анотує AST Python за допомогою позицій токенів і тексту у вихідному коді, який їх створив. Це корисно для інструментів, які здійснюють перетворення вихідного коду.

leoAst.py unifies the token-based and parse-tree-based views of python programs by inserting two-way links between tokens and ast nodes.

LibCST аналізує код як конкретне синтаксичне дерево, яке виглядає як дерево ast і зберігає всі деталі форматування. Це корисно для створення додатків і лінтерів для автоматизованого рефакторинга (codemod).

Parso is a Python parser that supports error recovery and round-trip parsing for different Python versions (in multiple Python versions). Parso is also able to list multiple syntax errors in your python file.