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