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

          | Match(expr subject, match_case* cases)

          | Raise(expr? exc, expr? cause)
          | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
          | TryStar(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)
             attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)

    withitem = (expr context_expr, expr? optional_vars)

    match_case = (pattern pattern, expr? guard, stmt* body)

    pattern = MatchValue(expr value)
            | MatchSingleton(constant value)
            | MatchSequence(pattern* patterns)
            | MatchMapping(expr* keys, pattern* patterns, identifier? rest)
            | MatchClass(expr cls, pattern* patterns, identifier* kwd_attrs, pattern* kwd_patterns)

            | MatchStar(identifier? name)
            -- The optional "rest" MatchMapping parameter handles capturing extra mapping keys

            | MatchAs(pattern? pattern, identifier? name)
            | MatchOr(pattern* patterns)

             attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)

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

Екземпляри підкласів ast.expr і ast.stmt мають атрибути lineno, col_offset, end_lineno і end_col_offset . lineno і end_lineno — це номери першого й останнього рядків вихідного текстового діапазону (з індексом 1, тому перший рядок — рядок 1), а також col_offset і end_col_offset — це відповідні зміщення байтів UTF-8 для першого й останнього маркерів, які створили вузол. Зсув UTF-8 записується, оскільки аналізатор використовує UTF-8 внутрішньо.

Зауважте, що кінцеві позиції не потрібні компілятору і тому є необов’язковими. Кінцеве зміщення вказується після останнього символу, наприклад, можна отримати вихідний сегмент вузла однорядкового виразу за допомогою 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 та всіх його учасників.

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 Заяви.

type_ignores is a list of the module’s type ignore comments; see ast.parse() for more details.

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

class ast.Expression(body)¶

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 Інтерактивний режим. 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".

Such type comments would look like this:

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.

Літерали¶

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

Виклик функції. 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.

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

Атрибут target не може належати до класу Tuple або List, на відміну від цілей Assign.

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

class ast.Raise(exc, cause)¶

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

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

class ast.Assert(test, msg)¶

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

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

class ast.Delete(targets)¶

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

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

class ast.Pass¶

Заява pass.

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

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

Імпорт¶

class ast.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.TryStar(body, handlers, orelse, finalbody)¶

try blocks which are followed by except* clauses. The attributes are the same as for Try but the ExceptHandler nodes in handlers are interpreted as except* blocks rather then except.

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

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.Match(subject, cases)¶: Оператор збігу. subject містить предмет відповідності (об’єкт, який зіставляється з регістрами), а cases містить ітерацію вузлів match_case з різними регістрами.

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

Шаблон одного регістру в операторі match. шаблон містить шаблон відповідності, з яким буде зіставлятися предмет. Зверніть увагу, що вузли AST, створені для шаблонів, відрізняються від вузлів, створених для виразів, навіть якщо вони мають однаковий синтаксис.

Атрибут guard містить вираз, який буде оцінено, якщо шаблон відповідає темі.

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()),
                        patterns=[],
                        kwd_attrs=[],
                        kwd_patterns=[]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])],
    type_ignores=[])

class ast.MatchValue(value)¶

Літерал відповідності або шаблон значення, який порівнює за рівністю. значення є вузлом виразу. Дозволені вузли значень обмежені, як описано в документації оператора відповідності. Цей шаблон успішно працює, якщо суб’єкт відповідності дорівнює оцінюваному значенню.

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

class ast.MatchSingleton(value)¶

Зразок буквального збігу, який порівнює за ідентичністю. value — це синглтон, з яким слід порівнювати: None, True або False. Цей шаблон успішний, якщо суб’єкт відповідності є заданою константою.

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

class ast.MatchSequence(patterns)¶

Шаблон послідовності відповідності. patterns містить шаблони, які потрібно зіставити з елементами теми, якщо тема є послідовністю. Відповідає послідовності змінної довжини, якщо один із підшаблонів є вузлом MatchStar, інакше відповідає послідовності фіксованої довжини.

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

class ast.MatchStar(name)¶

Збігається з рештою послідовності в шаблоні послідовності відповідності змінної довжини. Якщо name не None, список, що містить решту елементів послідовності, прив’язується до цього імені, якщо загальний шаблон послідовності успішний.

>>> print(ast.dump(ast.parse("""
... match x:
...     case [1, 2, *rest]:
...         ...
...     case [*_]:
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchValue(
                                value=Constant(value=1)),
                            MatchValue(
                                value=Constant(value=2)),
                            MatchStar(name='rest')]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchStar()]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])],
    type_ignores=[])

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

Шаблон відображення відповідності. ключі - це послідовність вузлів експресії. паттерни - це відповідна послідовність вузлів шаблону. rest - це необов’язкове ім’я, яке можна вказати для захоплення решти елементів відображення. Дозволені ключові вирази обмежені, як описано в документації оператора відповідності.

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

>>> print(ast.dump(ast.parse("""
... match x:
...     case {1: _, 2: _}:
...         ...
...     case {**rest}:
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchMapping(
                        keys=[
                            Constant(value=1),
                            Constant(value=2)],
                        patterns=[
                            MatchAs(),
                            MatchAs()]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchMapping(keys=[], patterns=[], rest='rest'),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])],
    type_ignores=[])

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

Шаблон класу відповідності. cls - це вираз, який дає номінальний клас, який потрібно знайти. шаблони - це послідовність вузлів шаблону, які потрібно зіставити з визначеною класом послідовністю атрибутів відповідності шаблону. kwd_attrs — це послідовність додаткових атрибутів, які потрібно зіставити (зазначені як аргументи ключових слів у шаблоні класу), kwd_patterns — це відповідні шаблони (зазначені як значення ключових слів у шаблоні класу).

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

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

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

class ast.MatchAs(pattern, name)¶

Збіг «як шаблон», шаблон захоплення або шаблон підстановки. шаблон містить шаблон відповідності, з яким буде зіставлятися предмет. Якщо шаблон None, вузол представляє шаблон захоплення (тобто голе ім’я) і завжди матиме успіх.

Атрибут name містить ім’я, яке буде зв’язано, якщо шаблон буде успішним. Якщо name має значення None, pattern також має бути None, а вузол представляє шаблон підстановки.

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

class ast.MatchOr(patterns)¶

Збіг «або шаблон». Або-шаблон по черзі зіставляє кожен із своїх підшаблонів із суб’єктом, поки один не досягне успіху. Після цього шаблон або вважається успішним. Якщо жоден із підшаблонів не вдався, шаблон or-не вдається. Атрибут patterns містить список вузлів шаблону відповідності, які будуть зіставлятися з предметом.

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

Setting feature_version to a tuple (major, minor) will result in a «best-effort» attempt to parse using that Python version’s grammar. For example, setting feature_version=(3, 9) will attempt to disallow parsing of match statements. Currently major must equal to 3. The lowest supported version is (3, 4) (and this may increase in future Python versions); the highest is sys.version_info[0:2]. «Best-effort» attempt means there is no guarantee that the parse (or success of the parse) is the same as when run on the Python version corresponding to feature_version.

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

Evaluate an expression node or a string containing only 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, None and Ellipsis.

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

This function had been documented as «safe» in the past without defining what that meant. That was misleading. This is specifically designed not to execute Python code, unlike the more general eval(). There is no namespace, no name lookups, or ability to call out. But it is not free from attack: A relatively small input can lead to memory exhaustion or to C stack exhaustion, crashing the process. There is also the possibility for excessive CPU consumption denial of service on some inputs. Calling it on untrusted data is thus not recommended.

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

It is possible to crash the Python interpreter due to stack depth limitations in Python’s AST compiler.

Він може викликати ValueError, TypeError, SyntaxError, MemoryError і RecursionError залежно від неправильного введення.

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

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

Змінено в версії 3.10: Для вводу рядків початкові пробіли та табуляції тепер видалені.

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() або відвідає їх сам.

visit_Constant(node)¶: Handles all constant nodes.

Не використовуйте 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.

`ast` — Abstract Syntax Trees¶

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

Класи вузлів¶

Root nodes¶

Літерали¶

Змінні¶

Вирази¶

Підписка¶

Осягнення¶

Заяви¶

Імпорт¶

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

Зіставлення шаблону¶

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

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

`ast` Помічники¶

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

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

Table of Contents

Попередній розділ

Наступна тема

Ця сторінка

ast — Abstract Syntax Trees¶

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

Класи вузлів¶

Root nodes¶

Літерали¶

Змінні¶

Вирази¶

Підписка¶

Осягнення¶

Заяви¶

Імпорт¶

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

Зіставлення шаблону¶

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

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

ast Помічники¶

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

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

`ast` — Abstract Syntax Trees¶

`ast` Помічники¶