ast — Abstrakte Syntaxbäume

Quellcode: Lib/ast.py

---

Das Modul ast hilft Python-Anwendungen bei der Verarbeitung von Bäumen der Python-Grammatik für abstrakte Syntax. Die abstrakte Syntax selbst kann sich mit jeder Python-Version ändern; dieses Modul hilft dabei, programmatisch herauszufinden, wie die aktuelle Grammatik aussieht.

Ein abstrakter Syntaxbaum kann durch Übergabe von ast.PyCF_ONLY_AST als Flag an die eingebaute Funktion compile() oder durch Verwendung der im Modul bereitgestellten Hilfsfunktion parse() generiert werden. Das Ergebnis ist ein Baum von Objekten, deren Klassen alle von ast.AST erben. Ein abstrakter Syntaxbaum kann mit der eingebauten Funktion compile() in ein Python-Codeobjekt kompiliert werden.

Abstrakte Grammatik

Die abstrakte Grammatik ist derzeit wie folgt definiert

-- 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, type_param* type_params)
          | AsyncFunctionDef(identifier name, arguments args,
                             stmt* body, expr* decorator_list, expr? returns,
                             string? type_comment, type_param* type_params)

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

          | Delete(expr* targets)
          | Assign(expr* targets, expr value, string? type_comment)
          | TypeAlias(expr name, type_param* type_params, expr value)
          | 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)
         | Interpolation(expr value, constant str, int conversion, expr? format_spec)
         | JoinedStr(expr* values)
         | TemplateStr(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)

    type_param = TypeVar(identifier name, expr? bound, expr? default_value)
               | ParamSpec(identifier name, expr? default_value)
               | TypeVarTuple(identifier name, expr? default_value)
               attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)
}

Klassendefinitionen für Knoten

class ast.AST

Dies ist die Basis aller AST-Knotenklassen. Die tatsächlichen Knotenklassen leiten sich von der Datei Parser/Python.asdl ab, die oben reproduziert wird. Sie sind im C-Modul _ast definiert und in ast neu exportiert.

Für jedes Symbol auf der linken Seite der abstrakten Grammatik (z. B. ast.stmt oder ast.expr) ist eine Klasse definiert. Zusätzlich ist für jeden Konstruktor auf der rechten Seite eine Klasse definiert; diese Klassen erben von den Klassen für die Bäume auf der linken Seite. Zum Beispiel erbt ast.BinOp von ast.expr. Bei Produktionsregeln mit Alternativen (auch "Summen" genannt) ist die Klasse auf der linken Seite abstrakt: nur Instanzen spezifischer Konstruktorknoten werden jemals erstellt.

_fields

Jede konkrete Klasse hat ein Attribut _fields, das die Namen aller Kindknoten angibt.

Jede Instanz einer konkreten Klasse hat ein Attribut für jeden Kindknoten vom Typ, wie er in der Grammatik definiert ist. Zum Beispiel haben Instanzen von ast.BinOp ein Attribut left vom Typ ast.expr.

Wenn diese Attribute in der Grammatik als optional markiert sind (mit einem Fragezeichen), kann der Wert None sein. Wenn Attribute null oder mehr Werte haben können (mit einem Sternchen markiert), werden die Werte als Python-Listen dargestellt. Alle möglichen Attribute müssen vorhanden sein und gültige Werte haben, wenn ein AST mit compile() kompiliert wird.

_field_types

Das Attribut _field_types jeder konkreten Klasse ist ein Wörterbuch, das Feldnamen (wie sie auch in _fields aufgeführt sind) ihren Typen zuordnet.

>>> ast.TypeVar._field_types
{'name': <class 'str'>, 'bound': ast.expr | None, 'default_value': ast.expr | None}

Hinzugefügt in Version 3.13.

lineno

col_offset

end_lineno

end_col_offset

Instanzen von Unterklassen von ast.expr und ast.stmt haben die Attribute lineno, col_offset, end_lineno und end_col_offset. Die Attribute lineno und end_lineno sind die erste und letzte Zeilennummer des Quelltextbereichs (1-indiziert, also ist die erste Zeile Zeile 1) und die Attribute col_offset und end_col_offset sind die entsprechenden UTF-8-Byte-Offsets der ersten und letzten Token, die den Knoten erzeugt haben. Der UTF-8-Offset wird aufgezeichnet, da der Parser intern UTF-8 verwendet.

Beachten Sie, dass die Endpositionen vom Compiler nicht benötigt werden und daher optional sind. Der Endoffset liegt *nach* dem letzten Symbol, zum Beispiel kann man mit source_line[node.col_offset : node.end_col_offset] das Quelltextsegment eines einzeiligen Ausdrucksknotens erhalten.

Der Konstruktor einer Klasse ast.T parst seine Argumente wie folgt

• Wenn Positionsargumente vorhanden sind, muss ihre Anzahl der Anzahl der Elemente in T._fields entsprechen; sie werden den Attributen dieser Namen zugewiesen.

• Wenn Schlüsselwortargumente vorhanden sind, werden die Attribute mit denselben Namen auf die angegebenen Werte gesetzt.

Zum Beispiel könnten Sie einen ast.UnaryOp-Knoten erstellen und füllen, indem Sie Folgendes verwenden

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

Wenn ein Feld, das in der Grammatik optional ist, im Konstruktor weggelassen wird, ist der Standardwert None. Wenn ein Listenfeld weggelassen wird, ist der Standardwert die leere Liste. Wenn ein Feld vom Typ ast.expr_context weggelassen wird, ist der Standardwert Load(). Wenn ein anderes Feld weggelassen wird, wird eine DeprecationWarning ausgelöst und der AST-Knoten wird dieses Feld nicht haben. In Python 3.15 wird diese Bedingung einen Fehler auslösen.

Geändert in Version 3.8: Die Klasse ast.Constant wird jetzt für alle Konstanten verwendet.

Geändert in Version 3.9: Einfache Indizes werden durch ihren Wert dargestellt, erweiterte Slices werden als Tupel dargestellt.

Geändert in Version 3.14: Die Ausgabe von __repr__() von AST-Knoten enthält die Werte der Knotenflelder.

Veraltet seit Version 3.8: Alte Klassen ast.Num, ast.Str, ast.Bytes, ast.NameConstant und ast.Ellipsis sind weiterhin verfügbar, werden aber in zukünftigen Python-Versionen entfernt. Bis dahin gibt die Instanziierung von ihnen eine Instanz einer anderen Klasse zurück.

Veraltet seit Version 3.9: Alte Klassen ast.Index und ast.ExtSlice sind weiterhin verfügbar, werden aber in zukünftigen Python-Versionen entfernt. Bis dahin gibt die Instanziierung von ihnen eine Instanz einer anderen Klasse zurück.

Veraltet seit Version 3.13, wird in Version 3.15 entfernt: Frühere Versionen von Python erlaubten die Erstellung von AST-Knoten, denen erforderliche Felder fehlten. Ebenso erlaubten AST-Knotenkonstruktoren beliebige Schlüsselwortargumente, die als Attribute des AST-Knotens gesetzt wurden, auch wenn sie keinen der Felder des AST-Knotens entsprachen. Dieses Verhalten ist veraltet und wird in Python 3.15 entfernt.

Hinweis

Die hier angezeigten Beschreibungen der spezifischen Knotentypen wurden ursprünglich aus dem fantastischen Green Tree Snakes-Projekt und all seinen Mitwirkenden übernommen.

Wurzelknoten

class ast.Module(body, type_ignores)

Ein Python-Modul, wie bei der Dateieingabe. Knotentyp, der von ast.parse() im Standardmodus "exec" generiert wird.

body ist eine Liste der Anweisungen des Moduls.

type_ignores ist eine Liste der Typ-Ignor-Kommentare des Moduls; siehe ast.parse() für weitere Details.

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

class ast.Expression(body)

Ein einzelner Python-Ausdruckseingabe. Knotentyp, der von ast.parse() generiert wird, wenn der Modus "eval" ist.

body ist ein einzelner Knoten, einer der Ausdruckstypen.

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

class ast.Interactive(body)

Eine einzelne interaktive Eingabe, wie im Interaktiven Modus. Knotentyp, der von ast.parse() generiert wird, wenn der Modus "single" ist.

body ist eine Liste von Anweisungsknoten.

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

Eine Darstellung von Typkommentaren älterer Art für Funktionen, da Python-Versionen vor 3.5 keine PEP 484-Annotationen unterstützten. Knotentyp, der von ast.parse() generiert wird, wenn der Modus "func_type" ist.

Solche Typkommentare würden wie folgt aussehen

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

argtypes ist eine Liste von Ausdrucksknoten.

returns ist ein einzelner Ausdrucksknoten.

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

Hinzugefügt in Version 3.8.

Literale

class ast.Constant(value)

Ein konstanter Wert. Das Attribut value des Literals Constant enthält das Python-Objekt, das es repräsentiert. Die dargestellten Werte können Instanzen von str, bytes, int, float, complex und bool sein, sowie die Konstanten None und Ellipsis.

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

class ast.FormattedValue(value, conversion, format_spec)

Knoten, der ein einzelnes Formatierungsfeld in einem f-String darstellt. Wenn der String ein einzelnes Formatierungsfeld und nichts anderes enthält, kann der Knoten isoliert werden, andernfalls erscheint er in JoinedStr.

• value ist jeder Ausdrucksknoten (wie ein Literal, eine Variable oder ein Funktionsaufruf).

• conversion ist eine Ganzzahl

  • -1: keine Formatierung

  • 97 (ord('a')): !a ASCII-Formatierung

  • 114 (ord('r')): !r repr()-Formatierung

  • 115 (ord('s')): !s String-Formatierung

• format_spec ist ein Knoten vom Typ JoinedStr, der die Formatierung des Werts darstellt, oder None, wenn keine Formatierung angegeben wurde. Sowohl conversion als auch format_spec können gleichzeitig gesetzt werden.

class ast.JoinedStr(values)

Ein f-String, bestehend aus einer Reihe von Knoten vom Typ FormattedValue und Constant.

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

class ast.TemplateStr(values, /)

Hinzugefügt in Version 3.14.

Knoten, der ein Template-String-Literal darstellt, bestehend aus einer Reihe von Knoten vom Typ Interpolation und Constant. Diese Knoten können in beliebiger Reihenfolge auftreten und müssen nicht verschachtelt sein.

>>> expr = ast.parse('t"{name} finished {place:ordinal}"', mode='eval')
>>> print(ast.dump(expr, indent=4))
Expression(
    body=TemplateStr(
        values=[
            Interpolation(
                value=Name(id='name', ctx=Load()),
                str='name',
                conversion=-1),
            Constant(value=' finished '),
            Interpolation(
                value=Name(id='place', ctx=Load()),
                str='place',
                conversion=-1,
                format_spec=JoinedStr(
                    values=[
                        Constant(value='ordinal')]))]))

class ast.Interpolation(value, str, conversion, format_spec=None)

Hinzugefügt in Version 3.14.

Knoten, der ein einzelnes Interpolationsfeld in einem Template-String-Literal darstellt.

• value ist jeder Ausdrucksknoten (wie ein Literal, eine Variable oder ein Funktionsaufruf). Dies hat die gleiche Bedeutung wie FormattedValue.value.

• str ist eine Konstante, die den Text des Interpolationsausdrucks enthält.

• conversion ist eine Ganzzahl

  • -1: keine Konvertierung

  • 97 (ord('a')): !a ASCII-Konvertierung

  • 114 (ord('r')): !r repr()-Konvertierung

  • 115 (ord('s')): !s String-Konvertierung

  Dies hat die gleiche Bedeutung wie FormattedValue.conversion.

• format_spec ist ein Knoten vom Typ JoinedStr, der die Formatierung des Werts darstellt, oder None, wenn keine Formatierung angegeben wurde. Sowohl conversion als auch format_spec können gleichzeitig gesetzt werden. Dies hat die gleiche Bedeutung wie FormattedValue.format_spec.

class ast.List(elts, ctx)

class ast.Tuple(elts, ctx)

Eine Liste oder ein Tupel. elts enthält eine Liste von Knoten, die die Elemente darstellen. ctx ist Store, wenn der Container ein Zuweisungsziel ist (d. h. (x,y)=something), und andernfalls 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)

Eine Menge. elts enthält eine Liste von Knoten, die die Elemente der Menge darstellen.

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

Ein Wörterbuch. keys und values enthalten Listen von Knoten, die die Schlüssel bzw. die Werte in übereinstimmender Reihenfolge darstellen (was bei Aufruf von dictionary.keys() und dictionary.values() zurückgegeben würde).

Beim Erweitern von Wörterbüchern mithilfe von Wörterbuchliteralen wird der zu erweiternde Ausdruck in die Liste values eingefügt, wobei eine None an der entsprechenden Position in keys steht.

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

Variablen

class ast.Name(id, ctx)

Ein Variablenname. id enthält den Namen als Zeichenkette, und ctx ist einer der folgenden Typen.

class ast.Load

class ast.Store

class ast.Del

Variablenreferenzen können verwendet werden, um den Wert einer Variable zu laden, ihr einen neuen Wert zuzuweisen oder sie zu löschen. Variablenreferenzen erhalten einen Kontext, um diese Fälle zu unterscheiden.

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

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

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

class ast.Starred(value, ctx)

Eine *var-Variablenreferenz. value enthält die Variable, typischerweise ein Knoten vom Typ Name. Dieser Typ muss verwendet werden, wenn ein Knoten vom Typ Call mit *args aufgebaut wird.

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

Ausdrücke

class ast.Expr(value)

Wenn ein Ausdruck, wie z. B. ein Funktionsaufruf, als eigenständige Anweisung erscheint und sein Rückgabewert nicht verwendet oder gespeichert wird, wird er in diesen Container verpackt. value enthält einen der anderen Knoten in diesem Abschnitt, einen Knoten vom Typ Constant, Name, Lambda, Yield oder YieldFrom.

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

class ast.UnaryOp(op, operand)

Eine unäre Operation. op ist der Operator und operand ein beliebiger Ausdrucksknoten.

class ast.UAdd

class ast.USub

class ast.Not

class ast.Invert

Uunäre Operator-Token. Not ist das Schlüsselwort not, Invert ist der Operator ~.

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

Eine binäre Operation (wie Addition oder Division). op ist der Operator und left und right sind beliebige Ausdrucksknoten.

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

Token für binäre Operatoren.

class ast.BoolOp(op, values)

Eine boolesche Operation, "oder" oder "und". op ist Or oder And. values sind die beteiligten Werte. Aufeinanderfolgende Operationen mit demselben Operator, wie z.B. a or b or c, werden zu einem Knoten mit mehreren Werten zusammengefasst.

Dies beinhaltet nicht not, welches ein UnaryOp ist.

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

Token für boolesche Operatoren.

class ast.Compare(left, ops, comparators)

Ein Vergleich von zwei oder mehr Werten. left ist der erste Wert im Vergleich, ops die Liste der Operatoren und comparators die Liste der Werte nach dem ersten Element im Vergleich.

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

Token für Vergleichsoperatoren.

class ast.Call(func, args, keywords)

Ein Funktionsaufruf. func ist die Funktion, die oft ein Name- oder Attribute-Objekt ist. Von den Argumenten

• args enthält eine Liste der positionsweise übergebenen Argumente.

• keywords enthält eine Liste von keyword-Objekten, die per Schlüsselwort übergebene Argumente darstellen.

Die Argumente args und keywords sind optional und standardmäßig leere Listen.

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

Ein Schlüsselwortargument für einen Funktionsaufruf oder eine Klassendefinition. arg ist ein Rohstring des Parameternamens, value ist ein zu übergebender Knoten.

class ast.IfExp(test, body, orelse)

Ein Ausdruck wie a if b else c. Jedes Feld enthält einen einzelnen Knoten, sodass im folgenden Beispiel alle drei Name-Knoten sind.

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

Attributzugriff, z.B. d.keys. value ist ein Knoten, typischerweise ein Name. attr ist ein reiner String, der den Namen des Attributs angibt, und ctx ist Load, Store oder Del, je nachdem, wie auf das Attribut zugegriffen wird.

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

Ein benannter Ausdruck. Dieser AST-Knoten wird durch den Zuweisungsoperator (auch bekannt als Walrus-Operator) erzeugt. Im Gegensatz zum Assign-Knoten, bei dem das erste Argument mehrere Knoten sein kann, müssen in diesem Fall sowohl target als auch value einzelne Knoten sein.

>>> print(ast.dump(ast.parse('(x := 4)', mode='eval'), indent=4))
Expression(
    body=NamedExpr(
        target=Name(id='x', ctx=Store()),
        value=Constant(value=4)))

Hinzugefügt in Version 3.8.

Subscripting

class ast.Subscript(value, slice, ctx)

Ein Subscript, z.B. l[1]. value ist das Objekt, auf das zugegriffen wird (normalerweise Sequenz oder Mapping). slice ist ein Index, Slice oder Schlüssel. Es kann ein Tuple sein und einen Slice enthalten. ctx ist Load, Store oder Del, je nach der mit dem Subscript ausgeführten Aktion.

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

Reguläres Slicing (in der Form lower:upper oder lower:upper:step). Kann nur innerhalb des Feldes *slice* von Subscript auftreten, entweder direkt oder als Element eines 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()))

Comprehensions

class ast.ListComp(elt, generators)

class ast.SetComp(elt, generators)

class ast.GeneratorExp(elt, generators)

class ast.DictComp(key, value, generators)

Listen- und Set-Comprehensions, Generatorausdrücke und Dictionary-Comprehensions. elt (oder key und value) ist ein einzelner Knoten, der den Teil darstellt, der für jedes Element ausgewertet wird.

generators ist eine Liste von comprehension-Knoten.

>>> 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()),
                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()),
                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()),
                is_async=0)]))

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

Eine for-Klausel in einer Comprehension. target ist die zu verwendende Referenz für jedes Element - typischerweise ein Name- oder Tuple-Knoten. iter ist das zu iterierende Objekt. ifs ist eine Liste von Testausdrücken: jede for-Klausel kann mehrere ifs haben.

is_async gibt an, dass die Comprehension asynchron ist (wobei async for anstelle von for verwendet wird). Der Wert ist eine Ganzzahl (0 oder 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())]),
        generators=[
            comprehension(
                target=Name(id='line', ctx=Store()),
                iter=Name(id='file', ctx=Load()),
                is_async=0),
            comprehension(
                target=Name(id='c', ctx=Store()),
                iter=Name(id='line', ctx=Load()),
                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()),
                is_async=1)]))

Statements

class ast.Assign(targets, value, type_comment)

Eine Zuweisung. targets ist eine Liste von Knoten und value ist ein einzelner Knoten.

Mehrere Knoten in targets repräsentieren die Zuweisung desselben Werts an jeden. Entpacken wird durch Platzieren eines Tuple oder einer List innerhalb von targets dargestellt.

type_comment

type_comment ist ein optionaler String mit der Typen-Annotation als Kommentar.

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

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

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

Eine Zuweisung mit Typen-Annotation. target ist ein einzelner Knoten und kann ein Name, ein Attribute oder ein Subscript sein. annotation ist die Annotation, z.B. ein Constant- oder Name-Knoten. value ist ein einzelner optionaler Knoten.

simple ist immer entweder 0 (was auf ein "komplexes" Ziel hinweist) oder 1 (was auf ein "einfaches" Ziel hinweist). Ein "einfaches" Ziel besteht ausschließlich aus einem Name-Knoten, der nicht in Klammern steht; alle anderen Ziele gelten als komplex. Nur einfache Ziele erscheinen im __annotations__-Dictionary von Modulen und Klassen.

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

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

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

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

class ast.AugAssign(target, op, value)

Erweiterte Zuweisung, z.B. a += 1. Im folgenden Beispiel ist target ein Name-Knoten für x (mit dem Store-Kontext), op ist Add und value ist ein Constant mit dem Wert 1.

Das Attribut target kann nicht von der Klasse Tuple oder List sein, im Gegensatz zu den Zielen von Assign.

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

class ast.Raise(exc, cause)

Eine raise-Anweisung. exc ist das zu auslösende Ausnahmeobjekt, normalerweise ein Call- oder Name-Knoten oder None für ein eigenständiges raise. cause ist der optionale Teil für y in raise x from y.

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

class ast.Assert(test, msg)

Eine Assertion. test enthält die Bedingung, z.B. einen Compare-Knoten. msg enthält die Fehlermeldung.

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

class ast.Delete(targets)

Repräsentiert eine del Anweisung. targets ist eine Liste von Nodes, wie z.B. Name, Attribute oder Subscript Nodes.

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

class ast.Pass

Eine pass Anweisung.

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

class ast.TypeAlias(name, type_params, value)

Ein Typalias, der durch die type Anweisung erstellt wurde. name ist der Name des Alias, type_params ist eine Liste von Typparametern und value ist der Wert des Typalias.

>>> print(ast.dump(ast.parse('type Alias = int'), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            value=Name(id='int', ctx=Load()))])

Hinzugefügt in Version 3.12.

Andere Anweisungen, die nur innerhalb von Funktionen oder Schleifen anwendbar sind, werden in anderen Abschnitten beschrieben.

Imports

class ast.Import(names)

Eine Importanweisung. names ist eine Liste von alias Nodes.

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

class ast.ImportFrom(module, names, level)

Repräsentiert from x import y. module ist ein Rohstring des 'from'-Namens, ohne führende Punkte, oder None für Anweisungen wie from . import foo. level ist eine ganze Zahl, die die Ebene des relativen Imports angibt (0 bedeutet absoluter Import).

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

class ast.alias(name, asname)

Beide Parameter sind Rohstrings der Namen. asname kann None sein, wenn der reguläre Name verwendet werden soll.

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

Kontrollfluss

Hinweis

Optionale Klauseln wie else werden als leere Liste gespeichert, wenn sie nicht vorhanden sind.

class ast.If(test, body, orelse)

Eine if Anweisung. test enthält einen einzelnen Node, wie z.B. einen Compare Node. body und orelse enthalten jeweils eine Liste von Nodes.

elif Klauseln haben keine spezielle Darstellung im AST, sondern erscheinen als zusätzliche If Nodes innerhalb des orelse Abschnitts des vorherigen.

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

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

Eine for Schleife. target enthält die Variable(n), an die die Schleife zuweist, als einzelnen Name, Tuple, List, Attribute oder Subscript Node. iter enthält das Element, über das iteriert wird, ebenfalls als einzelnen Node. body und orelse enthalten Listen von Nodes, die ausgeführt werden. Die in orelse enthaltenen werden ausgeführt, wenn die Schleife normal beendet wird, anstatt über eine break Anweisung.

type_comment

type_comment ist ein optionaler String mit der Typen-Annotation als Kommentar.

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

class ast.While(test, body, orelse)

Eine while Schleife. test enthält die Bedingung, wie z.B. einen Compare Node.

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

class ast.Break

class ast.Continue

Die break und continue Anweisungen.

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

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

try Blöcke. Alle Attribute sind Listen von auszuführenden Nodes, außer handlers, was eine Liste von ExceptHandler Nodes ist.

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

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

try Blöcke, die von except* Klauseln gefolgt werden. Die Attribute sind die gleichen wie für Try, aber die ExceptHandler Nodes in handlers werden als except* Blöcke anstatt except interpretiert.

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

Hinzugefügt in Version 3.11.

class ast.ExceptHandler(type, name, body)

Eine einzelne except Klausel. type ist der Exception-Typ, mit dem übereinstimmen soll, typischerweise ein Name Node (oder None für eine Catch-all except: Klausel). name ist ein Rohstring für den Namen, der die Exception aufnehmen soll, oder None, wenn die Klausel keine as foo hat. body ist eine Liste von Nodes.

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

class ast.With(items, body, type_comment)

Ein with Block. items ist eine Liste von withitem Nodes, die die Kontextmanager repräsentieren, und body ist der eingerückte Block innerhalb des Kontexts.

type_comment

type_comment ist ein optionaler String mit der Typen-Annotation als Kommentar.

class ast.withitem(context_expr, optional_vars)

Ein einzelner Kontextmanager in einem with Block. context_expr ist der Kontextmanager, oft ein Call Node. optional_vars ist ein Name, Tuple oder List für den as foo Teil, oder None, wenn dieser nicht verwendet wird.

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

Mustererkennung

class ast.Match(subject, cases)

Eine match Anweisung. subject enthält das Subjekt des Matches (das Objekt, das gegen die Fälle abgeglichen wird) und cases enthält ein Iterable von match_case Nodes mit den verschiedenen Fällen.

Hinzugefügt in Version 3.10.

class ast.match_case(pattern, guard, body)

Ein einzelnes Fallmuster in einer match Anweisung. pattern enthält das Muster, gegen das das Subjekt abgeglichen wird. Beachten Sie, dass die für Muster erzeugten AST Nodes von denen für Ausdrücke abweichen, auch wenn sie dieselbe Syntax teilen.

Das Attribut guard enthält einen Ausdruck, der ausgewertet wird, wenn das Muster mit dem Subjekt übereinstimmt.

body enthält eine Liste von Nodes, die ausgeführt werden, wenn das Muster übereinstimmt und das Ergebnis der Auswertung des Guard-Ausdrucks wahr ist.

>>> print(ast.dump(ast.parse("""
... match x:
...     case [x] if x>0:
...         ...
...     case tuple():
...         ...
... """), indent=4))
Module(
    body=[
        Match(
            subject=Name(id='x', ctx=Load()),
            cases=[
                match_case(
                    pattern=MatchSequence(
                        patterns=[
                            MatchAs(name='x')]),
                    guard=Compare(
                        left=Name(id='x', ctx=Load()),
                        ops=[
                            Gt()],
                        comparators=[
                            Constant(value=0)]),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))]),
                match_case(
                    pattern=MatchClass(
                        cls=Name(id='tuple', ctx=Load())),
                    body=[
                        Expr(
                            value=Constant(value=Ellipsis))])])])

Hinzugefügt in Version 3.10.

class ast.MatchValue(value)

Ein Match-Literal- oder Wertmuster, das auf Gleichheit vergleicht. value ist ein Ausdrucks-Node. Zulässige Wert-Nodes sind eingeschränkt, wie in der Dokumentation der Match-Anweisung beschrieben. Dieses Muster ist erfolgreich, wenn das Match-Subjekt gleich dem ausgewerteten Wert ist.

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

Hinzugefügt in Version 3.10.

class ast.MatchSingleton(value)

Ein Match-Literal-Muster, das auf Identität vergleicht. value ist das Singleton, mit dem verglichen werden soll: None, True oder False. Dieses Muster ist erfolgreich, wenn das Match-Subjekt die gegebene Konstante ist.

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

Hinzugefügt in Version 3.10.

class ast.MatchSequence(patterns)

Ein Match-Sequenzmuster. patterns enthält die Muster, die mit den Elementen des Subjekts abgeglichen werden, wenn das Subjekt eine Sequenz ist. Passt auf eine Sequenz variabler Länge, wenn eines der Untermuster ein MatchStar Node ist, andernfalls passt es auf eine Sequenz fester Länge.

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

Hinzugefügt in Version 3.10.

class ast.MatchStar(name)

Passt auf den Rest der Sequenz in einem variablen Längen-Sequenzmuster. Wenn name nicht None ist, wird eine Liste, die die verbleibenden Sequenzelemente enthält, an diesen Namen gebunden, wenn das gesamte Sequenzmuster erfolgreich ist.

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

Hinzugefügt in Version 3.10.

class ast.MatchMapping(keys, patterns, rest)

Ein Match-Mapping-Muster. keys ist eine Sequenz von Ausdrucks-Nodes. patterns ist eine entsprechende Sequenz von Muster-Nodes. rest ist ein optionaler Name, der angegeben werden kann, um die restlichen Mapping-Elemente zu erfassen. Zulässige Schlüssel-Ausdrücke sind eingeschränkt, wie in der Dokumentation der Match-Anweisung beschrieben. Dieses Muster ist erfolgreich, wenn das Subjekt ein Mapping ist, alle ausgewerteten Schlüssel-Ausdrücke im Mapping vorhanden sind und der Wert, der jedem Schlüssel entspricht, mit dem entsprechenden Untermuster übereinstimmt. Wenn rest nicht None ist, wird ein Wörterbuch mit den restlichen Mapping-Elementen an diesen Namen gebunden, wenn das gesamte Mapping-Muster erfolgreich ist.

Dieses Muster ist erfolgreich, wenn das Subjekt ein Mapping ist, alle ausgewerteten Schlüssel-Ausdrücke im Mapping vorhanden sind und der Wert, der jedem Schlüssel entspricht, mit dem entsprechenden Untermuster übereinstimmt. Wenn rest nicht None ist, wird ein Wörterbuch mit den restlichen Mapping-Elementen an diesen Namen gebunden, wenn das gesamte Mapping-Muster erfolgreich ist.

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

Hinzugefügt in Version 3.10.

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

Ein Match-Klassenmuster. cls ist ein Ausdruck, der die nominale Klasse angibt, die abgeglichen werden soll. patterns ist eine Sequenz von Muster-Nodes, die mit den positionsabhängigen Attributen der Klasse abgeglichen werden, die für die Mustererkennung definiert sind. kwd_attrs ist eine Sequenz von zusätzlichen Attributen, die abgeglichen werden sollen (angegeben als Schlüsselwortargumente im Klassenmuster), kwd_patterns sind die entsprechenden Muster (angegeben als Schlüsselwortwerte im Klassenmuster).

Dieses Muster ist erfolgreich, wenn das Subjekt eine Instanz der nominierten Klasse ist, alle Positionsmuster mit den entsprechenden klassen-definierten Attributen übereinstimmen und alle angegebenen Schlüsselwortattribute mit ihren entsprechenden Mustern übereinstimmen.

Hinweis: Klassen können eine Eigenschaft definieren, die self zurückgibt, um ein Muster-Node gegen die abgeglichene Instanz abzugleichen. Mehrere eingebaute Typen werden ebenfalls auf diese Weise abgeglichen, wie in der Dokumentation der Match-Anweisung beschrieben.

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

Hinzugefügt in Version 3.10.

class ast.MatchAs(pattern, name)

Ein Match "as-Muster", Erfassungsmuster oder Wildcard-Muster. pattern enthält das Muster, gegen das das Subjekt abgeglichen wird. Wenn das Muster None ist, repräsentiert der Node ein Erfassungsmuster (d.h. einen bloßen Namen) und ist immer erfolgreich.

Das Attribut name enthält den Namen, der gebunden wird, wenn das Muster erfolgreich ist. Wenn name None ist, muss auch pattern None sein und der Node repräsentiert das Wildcard-Muster.

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

Hinzugefügt in Version 3.10.

class ast.MatchOr(patterns)

Ein Match "or-Muster". Ein or-Muster gleicht nacheinander jedes seiner Untermuster mit dem Subjekt ab, bis eines erfolgreich ist. Das or-Muster gilt dann als erfolgreich. Wenn keines der Untermuster erfolgreich ist, schlägt das or-Muster fehl. Das Attribut patterns enthält eine Liste von Match-Muster-Nodes, die mit dem Subjekt abgeglichen werden.

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

Hinzugefügt in Version 3.10.

Typannotationen

class ast.TypeIgnore(lineno, tag)

Ein # type: ignore Kommentar an lineno. tag ist der optionale Tag, der in der Form # type: ignore <tag> angegeben wird.

>>> print(ast.dump(ast.parse('x = 1 # type: ignore', type_comments=True), indent=4))
Module(
    body=[
        Assign(
            targets=[
                Name(id='x', ctx=Store())],
            value=Constant(value=1))],
    type_ignores=[
        TypeIgnore(lineno=1, tag='')])
>>> print(ast.dump(ast.parse('x: bool = 1 # type: ignore[assignment]', type_comments=True), indent=4))
Module(
    body=[
        AnnAssign(
            target=Name(id='x', ctx=Store()),
            annotation=Name(id='bool', ctx=Load()),
            value=Constant(value=1),
            simple=1)],
    type_ignores=[
        TypeIgnore(lineno=1, tag='[assignment]')])

Hinweis

TypeIgnore Nodes werden nicht generiert, wenn der Parameter type_comments auf False (Standard) gesetzt ist. Siehe ast.parse() für weitere Details.

Hinzugefügt in Version 3.8.

Typparameter

Typparameter können in Klassen, Funktionen und Typaliase vorhanden sein.

class ast.TypeVar(name, bound, default_value)

Ein typing.TypeVar. name ist der Name der Typvariable. bound sind die Grenzen oder Einschränkungen, falls vorhanden. Wenn bound ein Tuple ist, repräsentiert es Einschränkungen; andernfalls repräsentiert es die Grenze. default_value ist der Standardwert; wenn die TypeVar keinen Standard hat, wird dieses Attribut auf None gesetzt.

>>> print(ast.dump(ast.parse("type Alias[T: int = bool] = list[T]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                TypeVar(
                    name='T',
                    bound=Name(id='int', ctx=Load()),
                    default_value=Name(id='bool', ctx=Load()))],
            value=Subscript(
                value=Name(id='list', ctx=Load()),
                slice=Name(id='T', ctx=Load()),
                ctx=Load()))])

Hinzugefügt in Version 3.12.

Geändert in Version 3.13: Parameter default_value hinzugefügt.

class ast.ParamSpec(name, default_value)

Ein typing.ParamSpec. name ist der Name der Parameterspezifikation. default_value ist der Standardwert; wenn die ParamSpec keinen Standard hat, wird dieses Attribut auf None gesetzt.

>>> print(ast.dump(ast.parse("type Alias[**P = [int, str]] = Callable[P, int]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                ParamSpec(
                    name='P',
                    default_value=List(
                        elts=[
                            Name(id='int', ctx=Load()),
                            Name(id='str', ctx=Load())],
                        ctx=Load()))],
            value=Subscript(
                value=Name(id='Callable', ctx=Load()),
                slice=Tuple(
                    elts=[
                        Name(id='P', ctx=Load()),
                        Name(id='int', ctx=Load())],
                    ctx=Load()),
                ctx=Load()))])

Hinzugefügt in Version 3.12.

Geändert in Version 3.13: Parameter default_value hinzugefügt.

class ast.TypeVarTuple(name, default_value)

Ein typing.TypeVarTuple. name ist der Name des Typvariablentupels. default_value ist der Standardwert; wenn die TypeVarTuple keinen Standard hat, wird dieses Attribut auf None gesetzt.

>>> print(ast.dump(ast.parse("type Alias[*Ts = ()] = tuple[*Ts]"), indent=4))
Module(
    body=[
        TypeAlias(
            name=Name(id='Alias', ctx=Store()),
            type_params=[
                TypeVarTuple(
                    name='Ts',
                    default_value=Tuple(ctx=Load()))],
            value=Subscript(
                value=Name(id='tuple', ctx=Load()),
                slice=Tuple(
                    elts=[
                        Starred(
                            value=Name(id='Ts', ctx=Load()),
                            ctx=Load())],
                    ctx=Load()),
                ctx=Load()))])

Hinzugefügt in Version 3.12.

Geändert in Version 3.13: Parameter default_value hinzugefügt.

Funktions- und Klassendefinitionen

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

Eine Funktionsdefinition.

• name ist ein Rohstring des Funktionsnamens.

• args ist ein arguments Node.

• body ist die Liste der Nodes innerhalb der Funktion.

• decorator_list ist die Liste der anzuwendenden Decorators, äußerste zuerst gespeichert (d.h. der erste in der Liste wird zuletzt angewendet).

• returns ist die Rückgabeannotation.

• type_params ist eine Liste von Typparametern.

type_comment

type_comment ist ein optionaler String mit der Typen-Annotation als Kommentar.

Geändert in Version 3.12: type_params hinzugefügt.

class ast.Lambda(args, body)

lambda ist eine minimale Funktionsdefinition, die innerhalb eines Ausdrucks verwendet werden kann. Im Gegensatz zu FunctionDef enthält body einen einzelnen Node.

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

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

Die Argumente einer Funktion.

• posonlyargs, args und kwonlyargs sind Listen von arg Nodes.

• vararg und kwarg sind einzelne arg Nodes, die sich auf die *args, **kwargs Parameter beziehen.

• kw_defaults ist eine Liste von Standardwerten für Keyword-Only-Argumente. Wenn einer davon None ist, ist das entsprechende Argument erforderlich.

• defaults ist eine Liste von Standardwerten für Argumente, die positionsweise übergeben werden können. Wenn es weniger Standardwerte gibt, entsprechen sie den letzten n Argumenten.

Klasse ast.arg(arg, annotation, type_comment)

Ein einzelnes Argument in einer Liste. arg ist ein roher String des Argumentnamens; annotation ist seine Annotation, z.B. ein Name-Knoten.

type_comment

type_comment ist ein optionaler String mit der Typ-Annotation als Kommentar

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

Klasse ast.Return(value)

Eine return-Anweisung.

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

Klasse ast.Yield(value)

Klasse ast.YieldFrom(value)

Ein yield- oder yield from-Ausdruck. Da dies Ausdrücke sind, müssen sie in einem Expr-Knoten verpackt werden, wenn der zurückgegebene Wert nicht verwendet wird.

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

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

Klasse ast.Global(names)

Klasse ast.Nonlocal(names)

global- und nonlocal-Anweisungen. names ist eine Liste von rohen Strings.

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

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

Klasse ast.ClassDef(name, bases, keywords, body, decorator_list, type_params)

Eine Klassendefinition.

• name ist ein roher String für den Klassennamen

• bases ist eine Liste von Knoten für explizit angegebene Basisklassen.

• keywords ist eine Liste von keyword-Knoten, hauptsächlich für 'metaclass'. Andere Schlüsselwörter werden an die Metaklasse weitergegeben, gemäß PEP 3115.

• body ist eine Liste von Knoten, die den Code innerhalb der Klassendefinition darstellen.

• decorator_list ist eine Liste von Knoten, wie in FunctionDef.

• type_params ist eine Liste von Typparametern.

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

Geändert in Version 3.12: type_params hinzugefügt.

Async und await

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

Eine async def-Funktionsdefinition. Hat die gleichen Felder wie FunctionDef.

Geändert in Version 3.12: type_params hinzugefügt.

Klasse ast.Await(value)

Ein await-Ausdruck. value ist, worauf gewartet wird. Nur gültig im Körper einer AsyncFunctionDef.

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

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

Klasse ast.AsyncWith(items, body, type_comment)

async for-Schleifen und async with-Kontextmanager. Sie haben die gleichen Felder wie For und With, jeweils. Nur gültig im Körper einer AsyncFunctionDef.

Hinweis

Wenn ein String von ast.parse() geparst wird, sind Operator-Knoten (Unterklassen von ast.operator, ast.unaryop, ast.cmpop, ast.boolop und ast.expr_context) im zurückgegebenen Baum Einzelstücke. Änderungen an einem werden sich in allen anderen Vorkommen desselben Werts widerspiegeln (z.B. ast.Add).

ast-Helfer

Abgesehen von den Knotentypen definiert das ast-Modul diese Hilfsfunktionen und Klassen zum Durchlaufen abstrakter Syntaxbäume

ast.parse(source, filename='<unbekannt>', mode='exec', *, type_comments=False, feature_version=None, optimize=-1)

Parst den Quellcode in einen AST-Knoten. Entspricht compile(source, filename, mode, flags=FLAGS_VALUE, optimize=optimize), wobei FLAGS_VALUE ast.PyCF_ONLY_AST ist, wenn optimize <= 0 und ast.PyCF_OPTIMIZED_AST andernfalls.

Wenn type_comments=True übergeben wird, wird der Parser modifiziert, um Typ-Kommentare gemäß PEP 484 und PEP 526 zu überprüfen und zurückzugeben. Dies entspricht dem Hinzufügen von ast.PyCF_TYPE_COMMENTS zu den an compile() übergebenen Flags. Dies meldet Syntaxfehler für fehlplatzierte Typ-Kommentare. Ohne dieses Flag werden Typ-Kommentare ignoriert, und das Feld type_comment auf ausgewählten AST-Knoten ist immer None. Zusätzlich werden die Positionen von # type: ignore-Kommentaren als type_ignores-Attribut von Module zurückgegeben (andernfalls ist es immer eine leere Liste).

Zusätzlich, wenn mode 'func_type' ist, wird die Eingabesyntax modifiziert, um den "Signaturtyp-Kommentaren" von PEP 484 zu entsprechen, z.B. (str, int) -> List[str].

Wenn feature_version auf ein Tupel (major, minor) gesetzt wird, wird ein "Best-Effort"-Versuch unternommen, die Grammatik dieser Python-Version zu parsen. Zum Beispiel wird durch Setzen von feature_version=(3, 9) versucht, das Parsen von match-Anweisungen zu unterbinden. Derzeit muss major gleich 3 sein. Die niedrigste unterstützte Version ist (3, 7) (und dies kann sich in zukünftigen Python-Versionen erhöhen); die höchste ist sys.version_info[0:2]. "Best-Effort"-Versuch bedeutet, dass keine Garantie besteht, dass das Parsen (oder der Erfolg des Parsens) derselbe ist wie bei Ausführung auf der Python-Version, die feature_version entspricht.

Wenn die Quelle ein Nullzeichen (\0) enthält, wird ValueError ausgelöst.

Warnung

Beachten Sie, dass das erfolgreiche Parsen von Quellcode in ein AST-Objekt nicht garantiert, dass der bereitgestellte Quellcode gültiger Python-Code ist, der ausgeführt werden kann, da der Kompilierungsschritt weitere SyntaxError-Ausnahmen auslösen kann. Zum Beispiel generiert der Quellcode return 42 einen gültigen AST-Knoten für eine return-Anweisung, aber er kann nicht allein kompiliert werden (er muss sich innerhalb eines Funktionsknotens befinden).

Insbesondere führt ast.parse() keine Gültigkeitsbereichsprüfungen durch, was der Kompilierungsschritt tut.

Warnung

Es ist möglich, den Python-Interpreter mit einem ausreichend großen/komplexen String aufgrund von Stapeltiefenbeschränkungen im AST-Compiler von Python zum Absturz zu bringen.

Geändert in Version 3.8: Hinzugefügt: type_comments, mode='func_type' und feature_version.

Geändert in Version 3.13: Die minimale unterstützte Version für feature_version ist jetzt (3, 7). Das Argument optimize wurde hinzugefügt.

ast.unparse(ast_obj)

Entparst ein ast.AST-Objekt und generiert einen String mit Code, der ein äquivalentes ast.AST-Objekt erzeugen würde, wenn es mit ast.parse() zurückgeparst wird.

Warnung

Der erzeugte Code-String wird nicht unbedingt mit dem ursprünglichen Code übereinstimmen, der das ast.AST-Objekt generiert hat (ohne Compiler-Optimierungen, wie z.B. konstante Tupel/Frozensets).

Warnung

Der Versuch, einen sehr komplexen Ausdruck zu entparsen, würde zu einem RecursionError führen.

Hinzugefügt in Version 3.9.

ast.literal_eval(node_or_string)

Wertet einen Ausdrucksknoten oder einen String aus, der nur ein Python-Literal oder eine Containeranzeige enthält. Der bereitgestellte String oder Knoten darf nur aus den folgenden Python-Literalstrukturen bestehen: Strings, Bytes, Zahlen, Tupel, Listen, Dictionaries, Sets, Booleans, None und Ellipsis.

Dies kann verwendet werden, um Strings auszuwerten, die Python-Werte enthalten, ohne dass die Werte selbst geparst werden müssen. Es ist nicht in der Lage, beliebig komplexe Ausdrücke auszuwerten, z.B. solche, die Operatoren oder Indizierungen beinhalten.

Diese Funktion wurde in der Vergangenheit als "sicher" dokumentiert, ohne zu definieren, was das bedeutet. Das war irreführend. Sie ist speziell dafür konzipiert, keinen Python-Code auszuführen, im Gegensatz zur allgemeineren Funktion eval(). Es gibt keinen Namensraum, keine Namensauflösungen und keine Möglichkeit, nach außen zu rufen. Aber sie ist nicht frei von Angriffen: Eine relativ kleine Eingabe kann zu Speichererschöpfung oder C-Stapelerschöpfung führen und den Prozess abstürzen lassen. Es gibt auch die Möglichkeit einer übermäßigen CPU-Auslastung als Denial-of-Service bei einigen Eingaben. Daher wird die Verwendung auf nicht vertrauenswürdigen Daten nicht empfohlen.

Warnung

Es ist möglich, den Python-Interpreter aufgrund von Stapeltiefenbeschränkungen im AST-Compiler von Python zum Absturz zu bringen.

Sie kann ValueError, TypeError, SyntaxError, MemoryError und RecursionError auslösen, abhängig von der fehlerhaften Eingabe.

Geändert in Version 3.2: Erlaubt jetzt Byte- und Set-Literale.

Geändert in Version 3.9: Unterstützt jetzt die Erstellung leerer Sets mit 'set()'.

Geändert in Version 3.10: Bei String-Eingaben werden führende Leerzeichen und Tabs jetzt gestrippt.

ast.get_docstring(node, clean=True)

Gibt den Docstring des gegebenen *Knotens* zurück (der ein FunctionDef-, AsyncFunctionDef-, ClassDef- oder Module-Knoten sein muss) oder None, wenn er keinen Docstring hat. Wenn *clean* wahr ist, wird die Einrückung des Docstrings mit inspect.cleandoc() bereinigt.

Geändert in Version 3.5: AsyncFunctionDef wird jetzt unterstützt.

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

Gibt das Quellcode-Segment des *Quellcodes* zurück, der *Knoten* generiert hat. Wenn einige Standortinformationen (lineno, end_lineno, col_offset oder end_col_offset) fehlen, wird None zurückgegeben.

Wenn *padded* True ist, wird die erste Zeile einer mehrzeiligen Anweisung mit Leerzeichen aufgefüllt, um ihre ursprüngliche Position anzupassen.

Hinzugefügt in Version 3.8.

ast.fix_missing_locations(node)

Wenn Sie einen Knotentreis mit compile() kompilieren, erwartet der Compiler lineno und col_offset Attribute für jeden unterstützenden Knoten. Dies ist mühsam für generierte Knoten, daher fügt dieser Helfer diese Attribute rekursiv hinzu, wo sie noch nicht gesetzt sind, indem er sie auf die Werte des Elternknotens setzt. Er arbeitet rekursiv beginnend bei *node*.

ast.increment_lineno(node, n=1)

Inkrementiert die Zeilennummer und die Endzeilennummer jedes Knotens im Baum, beginnend bei *node*, um *n* erhöht. Dies ist nützlich, um "Code" an eine andere Stelle in einer Datei zu verschieben.

ast.copy_location(new_node, old_node)

Kopiert die Quellposition (lineno, col_offset, end_lineno und end_col_offset) von *old_node* nach *new_node*, wenn möglich, und gibt *new_node* zurück.

ast.iter_fields(node)

Gibt ein Tupel aus (fieldname, value) für jedes Feld in node._fields zurück, das auf *node* vorhanden ist.

ast.iter_child_nodes(node)

Gibt alle direkten Kindknoten von *node* zurück, d.h. alle Felder, die Knoten sind, und alle Elemente von Feldern, die Listen von Knoten sind.

ast.walk(node)

Gibt rekursiv alle Nachfahrenknoten im Baum beginnend bei *node* (einschließlich *node* selbst) zurück, in keiner bestimmten Reihenfolge. Dies ist nützlich, wenn Sie nur Knoten vor Ort ändern möchten und sich nicht um den Kontext kümmern.

Klasse ast.NodeVisitor

Eine Basisklasse für Knotenviseure, die den abstrakten Syntaxbaum durchläuft und eine Viseurfunktion für jeden gefundenen Knoten aufruft. Diese Funktion kann einen Wert zurückgeben, der von der Methode visit() weitergegeben wird.

Diese Klasse ist zur Unterklassifizierung gedacht, wobei die Unterklasse Viseurmethoden hinzufügt.

visit(node)

Besucht einen Knoten. Die Standardimplementierung ruft die Methode namens self.visit_classname auf, wobei *classname* der Name der Knotenklasse ist, oder generic_visit(), wenn diese Methode nicht existiert.

generic_visit(node)

Dieser Viseur ruft visit() für alle Kinder des Knotens auf.

Beachten Sie, dass Kindknoten von Knoten, die eine benutzerdefinierte Viseurmethode haben, nicht besucht werden, es sei denn, der Viseur ruft generic_visit() auf oder besucht sie selbst.

visit_Constant(node)

Behandelt alle Konstantenknoten.

Verwenden Sie den NodeVisitor nicht, wenn Sie Änderungen an Knoten während der Traversal vornehmen möchten. Dafür gibt es einen speziellen Viseur (NodeTransformer), der Modifikationen erlaubt.

Veraltet seit Version 3.8: Die Methoden visit_Num(), visit_Str(), visit_Bytes(), visit_NameConstant() und visit_Ellipsis() sind veraltet und werden in zukünftigen Python-Versionen nicht mehr aufgerufen. Fügen Sie die Methode visit_Constant() hinzu, um alle Konstantenknoten zu behandeln.

Klasse ast.NodeTransformer

Eine NodeVisitor-Unterklasse, die den abstrakten Syntaxbaum durchläuft und die Modifikation von Knoten ermöglicht.

Der NodeTransformer durchläuft den AST und verwendet den Rückgabewert der Besuchermethoden, um den alten Knoten zu ersetzen oder zu entfernen. Wenn der Rückgabewert der Besuchermethode None ist, wird der Knoten an seiner Stelle entfernt, andernfalls wird er durch den Rückgabewert ersetzt. Der Rückgabewert kann der ursprüngliche Knoten sein, in diesem Fall findet keine Ersetzung statt.

Hier ist ein Beispiel-Transformer, der alle Vorkommen von Namensverweisen (foo) in data['foo'] umschreibt.

class RewriteName(NodeTransformer):

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

Beachten Sie, dass, wenn der Knoten, mit dem Sie arbeiten, Kindknoten hat, Sie entweder die Kindknoten selbst transformieren oder zuerst die Methode generic_visit() für den Knoten aufrufen müssen.

Für Knoten, die Teil einer Sammlung von Anweisungen waren (was auf alle Anweisungsknoten zutrifft), kann der Besucher auch eine Liste von Knoten anstelle eines einzelnen Knotens zurückgeben.

Wenn NodeTransformer neue Knoten einführt (die nicht Teil des ursprünglichen Baums waren), ohne ihnen Standortinformationen (wie lineno) zu geben, sollte fix_missing_locations() mit dem neuen Teilbaum aufgerufen werden, um die Standortinformationen neu zu berechnen.

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

Normalerweise verwendet man den Transformer so:

node = YourTransformer().visit(node)

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

Gibt eine formatierte Ausgabe des Baums in node zurück. Dies ist hauptsächlich für Debugging-Zwecke nützlich. Wenn annotate_fields auf wahr gesetzt ist (standardmäßig), zeigt die zurückgegebene Zeichenkette die Namen und Werte für Felder an. Wenn annotate_fields auf falsch gesetzt ist, ist die Ergebniszeichenkette kompakter, indem eindeutige Feldnamen weggelassen werden. Attribute wie Zeilennummern und Spaltenoffsets werden standardmäßig nicht ausgegeben. Wenn dies gewünscht wird, kann include_attributes auf wahr gesetzt werden.

Wenn indent eine nicht-negative Ganzzahl oder eine Zeichenkette ist, wird der Baum mit diesem Einrückungslevel schön formatiert. Ein Einrückungslevel von 0, negativ oder "" fügt nur Zeilenumbrüche ein. None (Standard) wählt die einzeilige Darstellung. Die Verwendung einer positiven Ganzzahl für die Einrückung rückt jeden Level um diese Anzahl von Leerzeichen ein. Wenn indent eine Zeichenkette ist (wie z.B. "\t"), wird diese Zeichenkette verwendet, um jeden Level einzurücken.

Wenn show_empty auf falsch gesetzt ist (Standard), werden optionale leere Listen aus der Ausgabe weggelassen. Optionale None-Werte werden immer weggelassen.

Geändert in Version 3.9: Die Option indent wurde hinzugefügt.

Geändert in Version 3.13: Die Option show_empty wurde hinzugefügt.

>>> print(ast.dump(ast.parse("""\
... async def f():
...     await other_func()
... """), indent=4, show_empty=True))
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_params=[])],
    type_ignores=[])

Compiler-Flags

Die folgenden Flags können an compile() übergeben werden, um die Auswirkungen auf die Kompilierung eines Programms zu ändern

ast.PyCF_ALLOW_TOP_LEVEL_AWAIT

Ermöglicht die Unterstützung für Top-Level await, async for, async with und asynchrone Comprehensions.

Hinzugefügt in Version 3.8.

ast.PyCF_ONLY_AST

Generiert und gibt einen abstrakten Syntaxbaum anstelle eines kompilierten Codeobjekts zurück.

ast.PyCF_OPTIMIZED_AST

Der zurückgegebene AST ist gemäß dem Argument optimize in compile() oder ast.parse() optimiert.

Hinzugefügt in Version 3.13.

ast.PyCF_TYPE_COMMENTS

Ermöglicht die Unterstützung für Typ-Kommentare im Stil von PEP 484 und PEP 526 (# type: <type>, # type: ignore <stuff>).

Hinzugefügt in Version 3.8.

ast.compare(a, b, /, *, compare_attributes=False)

Vergleicht rekursiv zwei ASTs.

compare_attributes beeinflusst, ob AST-Attribute beim Vergleich berücksichtigt werden. Wenn compare_attributes auf False (Standard) gesetzt ist, werden Attribute ignoriert. Andernfalls müssen sie alle gleich sein. Diese Option ist nützlich, um zu überprüfen, ob die ASTs strukturell gleich sind, sich aber in Leerzeichen oder ähnlichen Details unterscheiden. Attribute umfassen Zeilennummern und Spaltenoffsets.

Hinzugefügt in Version 3.14.

Verwendung über die Kommandozeile

Hinzugefügt in Version 3.9.

Das Modul ast kann als Skript über die Kommandozeile ausgeführt werden. Es ist so einfach wie

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

Die folgenden Optionen werden akzeptiert:

-h, --help

Zeigt die Hilfemeldung an und beendet das Programm.

-m <mode>

--mode <mode>

Gibt an, welche Art von Code kompiliert werden muss, ähnlich wie das mode-Argument in parse().

--no-type-comments

Typ-Kommentare nicht parsen.

-a, --include-attributes

Attribute wie Zeilennummern und Spaltenoffsets einschließen.

-i <indent>

--indent <indent>

Einrückung der Knoten im AST (Anzahl der Leerzeichen).

--feature-version <version>

Python-Version im Format 3.x (z.B. 3.10). Standardmäßig die aktuelle Version des Interpreters.

Hinzugefügt in Version 3.14.

-O <level>

--optimize <level>

Optimierungsstufe für den Parser. Standardmäßig keine Optimierung.

Hinzugefügt in Version 3.14.

--show-empty

Leere Listen und Felder, die None sind, anzeigen. Standardmäßig werden leere Objekte nicht angezeigt.

Hinzugefügt in Version 3.14.

Wenn infile angegeben ist, werden dessen Inhalte in einen AST geparst und auf stdout ausgegeben. Andernfalls werden die Inhalte von stdin gelesen.

Siehe auch

Green Tree Snakes, eine externe Dokumentationsressource, bietet gute Details zur Arbeit mit Python ASTs.

ASTTokens annotiert Python ASTs mit den Positionen von Tokens und Text im Quellcode, der sie generiert hat. Dies ist hilfreich für Werkzeuge, die Quellcode-Transformationen durchführen.

leoAst.py vereinheitlicht die tokenbasierte und die parse-tree-basierte Sicht von Python-Programmen, indem zweiseitige Links zwischen Tokens und AST-Knoten eingefügt werden.

LibCST parst Code als Concrete Syntax Tree, der einem AST ähnelt, und behält alle Formatierungsdetails bei. Es ist nützlich für die Erstellung automatisierter Refactoring- (Codemod-) Anwendungen und Linter.

Parso ist ein Python-Parser, der Fehlerkorrektur und Round-Trip-Parsing für verschiedene Python-Versionen (in mehreren Python-Versionen) unterstützt. Parso kann auch mehrere Syntaxfehler in Ihrer Python-Datei auflisten.