ast — Abstract syntax trees¶

Nodos raíz¶

class ast.Module(body, type_ignores)¶

Un módulo de Python, como con archivo-entrada. Tipo de nodo generado por ast.parse() en el modo por defecto "exec" mode.*mode*.

body is a list of the module’s Declaraciones.

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

class ast.Expression(body)¶

Una única expression input de Python. Tipo de nodo generado por ast.parse() cuando mode es "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)¶

Una única entrada interactiva, como en Modo interactivo. Tipo de nodo generado por ast.parse() cuando mode es "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)¶

Una interpretación de un comentario de tipo de estilo antiguo para funciones, ya que las versiones de Python anteriores a la 3.5 no soportaban anotaciones PEP 484. Tipo de nodo generado por ast.parse() cuando mode es "func_type".

Los comentarios de este tipo tendrían el siguiente aspecto:

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

Added in version 3.8.

Literales¶

class ast.Constant(value)¶

A constant value. The value attribute of the Constant literal contains the Python object it represents. The values represented can be instances of str, bytes, int, float, complex, and bool, and the constants None and Ellipsis.

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

class ast.FormattedValue(value, conversion, format_spec)¶

Nodo que representa un único campo de formato en una f-string. Si la cadena de caracteres contiene un único campo de formato y nada más, el nodo puede estar aislado de otra manera aparece en JoinedStr.

• value es cualquier nodo de expresión (como un literal, una variable o una llamada a función).

• conversion es un entero:

  • -1: sin formato

  • 97 (ord('a')): !a ASCII formatting

  • 114 (ord('r')): !r repr() formatting

  • 115 (ord('s')): !s string formatting

• format_spec es un nodo JoinedStr que representa el formato del valor, o None si no se ha especificado un formato. Ambos, conversion y format_spec, pueden estar especificados al mismo tiempo.

class ast.JoinedStr(values)¶

Un f-string que comprende una serie de nodos FormattedValue y 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, /)¶

Added in version 3.14.

Node representing a template string literal, comprising a series of Interpolation and Constant nodes. These nodes may be any order, and do not need to be interleaved.

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

Added in version 3.14.

Node representing a single interpolation field in a template string literal.

• value is any expression node (such as a literal, a variable, or a function call). This has the same meaning as FormattedValue.value.

• str is a constant containing the text of the interpolation expression.

  If str is set to None, then value is used to generate code when calling ast.unparse(). This no longer guarantees that the generated code is identical to the original and is intended for code generation.

• conversion es un entero:

  • -1: no conversion

  • 97 (ord('a')): !a ASCII conversion

  • 114 (ord('r')): !r repr() conversion

  • 115 (ord('s')): !s string conversion

  This has the same meaning as FormattedValue.conversion.

• format_spec is a JoinedStr node representing the formatting of the value, or None if no format was specified. Both conversion and format_spec can be set at the same time. This has the same meaning as FormattedValue.format_spec.

class ast.List(elts, ctx)¶

class ast.Tuple(elts, ctx)¶

Una lista o tupla. elts contiene una lista de nodos que representa a los elementos. ctx es Store si el contenedor es un objetivo de asignación (por ejemplo (x,y)=something), y Load en cualquier otro caso.

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

Un set. elts contiene una lista de nodos que representa a un set de elementos.

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

Un diccionario. keys y values contienen listas de nodos que representan las claves y los valores respectivamente en el orden correspondiente (el orden que retornaría dictionary.keys() y dictionary.values()).

Cuando se desempaqueta un diccionario utilizando literales de diccionario, la expresión a ser expandida va en la lista values, con None en la posición correspondiente en keys.

>>> print(ast.dump(ast.parse('{"a":1, **d}', mode='eval'), indent=4))
Expression(
    body=Dict(
        keys=[
            Constant(value='a'),
            None],
        values=[
            Constant(value=1),
            Name(id='d', ctx=Load())]))

Variables¶

class ast.Name(id, ctx)¶

Un nombre de variable. id contiene el nombre de una cadena de caracteres y ctx es uno de los siguientes tipos.

class ast.Load¶

class ast.Store¶

class ast.Del¶

Referencias a variables que pueden ser usadas para cargar el valor de una variable, asignar un nuevo valor o borrarlo. Las referencias a variables reciben un contexto para distinguir entre estos casos.

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

Una referencia a variable *var. value contiene la variable, típicamente un nodo Name. Este tipo puede ser usado cuando se construye un nodo Call con *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()))])

Expresiones¶

class ast.Expr(value)¶

Cuando una expresión, como un llamado a función, aparece como una declaración por sí misma sin que su valor de retorno se use o se almacene, está dentro de este contenedor. value contiene uno de los otros nodos en esta sección, un nodo Constant, Name, Lambda, Yield o 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)¶

Una operación unaria. op es el operador y operand es cualquier nodo de expresión.

class ast.UAdd¶

class ast.USub¶

class ast.Not¶

class ast.Invert¶

Tokens de operador unario. Not es la palabra clave not, Invert es el operador ~.

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

Una operación binaria (como la suma o división(. op es el operador, y left y right son cualquier nodo de expresión.

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

Tokens de operador binario.

class ast.BoolOp(op, values)¶

Una operación booleana, “or” y “and”. op es Or o And. values son los valores involucrados. Operaciones consecutivas con el mismo operador, como a or b or c, colapsan en un nodo con varios valores.

Esto no incluye not, el cual es un 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¶

Tokens de operador booleano.

class ast.Compare(left, ops, comparators)¶

Una comparación de dos o más valores. left es el primer valor en la comparación, ops es la lista de operadores, y comparators es la lista de valores después de el primer elemento en la comparación.

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

Tokens de operador de comparación.

class ast.Call(func, args, keywords)¶

Un llamado a función. func is la función, la cual suele ser un objeto Name o Attribute. De los argumentos:

• args contiene una lista de argumentos pasados por posición.

• keywords contiene una lista de objetos keyword que representan argumentos pasados por nombre clave.

The args and keywords arguments are optional and default to 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)¶

Un argumento de palabra clave para una llamada de función o definición de clase. arg es una cadena de caracteres sin formato del nombre del parámetro, valor es un nodo para pasar.

class ast.IfExp(test, body, orelse)¶

Una expresión como a if b else c. Cada campo contiene un único nodo, por lo que en el siguiente ejemplo, todos son nodos 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)¶

Acceso a atributos, por ejemplo d.keys. value es un nodo, típicamente un Name. attr es una simple cadena de caracteres que da el nombre del atributo, y ctx es Load, Store o Del de acuerdo a cómo se actúe sobre el atributo.

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

Una expresión con nombre. Este nodo AST es producido por el operador de expresiones de asignación (también conocido como el operador walrus). A diferencia del nodo Assign en el cual el primer argumento puede ser varios nodos, en este caso target y value deben ser nodos únicos.

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

Added in version 3.8.

Declaraciones¶

class ast.Assign(targets, value, type_comment)¶

Una asignación. targets es una lista de nodos, y value es un nodo único.

Nodos múltiples en targets representa asignar el mismo valor a cada uno. El desempaquetado se representa poniendo una Tuple o List en targets.

type_comment¶

type_comment es una cadena de caracteres opcional con la anotación de tipos como comentario.

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

An assignment with a type annotation. target is a single node and can be a Name, an Attribute or a Subscript. annotation is the annotation, such as a Constant or Name node. value is a single optional node.

simple is always either 0 (indicating a «complex» target) or 1 (indicating a «simple» target). A «simple» target consists solely of a Name node that does not appear between parentheses; all other targets are considered complex. Only simple targets appear in the __annotations__ dictionary of modules and classes.

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

Asignación aumentada, como a+=1. En el siguiente ejemplo, target es un nodo Name para x (con el contexto Store), op es Add y value es un Constant con valor 1.

El atributo target no puede ser de clase Tuple o List, a diferencia de los objetivos de 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)¶

Una declaración raise. exc es el objeto de excepción a ser lanzado, normalmente un Call or Name, o None para un raise solo. cause es la parte opcional para y en 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)¶

Una aserción. test contiene la condición, como un nodo Compare. msg contiene el mensaje de fallo.

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

Contiene una declaración del. targets es una lista de nodos, como nodos Name, Attribute o Subscript.

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

class ast.Pass¶

Una declaración pass.

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

class ast.TypeAlias(name, type_params, value)¶

Un alias type alias creado mediante la sentencia type. name es el nombre del alias, type_params es una lista de parámetros type, y value es el valor del alias de tipo.

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

Added in version 3.12.

Otras declaraciones que solo son aplicables dentro de funciones o bucles descritos en otras secciones.

Control de flujo¶

class ast.If(test, body, orelse)¶

Una declaración if. test contiene un único nodo, como un nodo Compare. body y orelse contiene cada uno una lista de nodos.

Cláusulas elif no tienen una representación especial en AST, pero pueden aparecer como nodos extra If dentro de la sección orelse del nodo anterior.

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

Un bucle for. target contiene las variables a las que asigna el bucle, como un único nodo Name, Tuple, List, Attribute o Subscript. iter contiene el elemento sobre el que se realizará el bucle, nuevamente como un solo nodo. body y orelse contienen listas de nodos para ejecutar. Los de orelse se ejecutan si el ciclo finaliza normalmente, en lugar de mediante una instrucción break.

type_comment¶

type_comment es una cadena de caracteres opcional con la anotación de tipos como comentario.

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

Un bucle while. test contiene la condición, como un nodo Compare.

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

class ast.Break¶

class ast.Continue¶

Las declaraciones break y continue.

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

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

Bloques try. Todos los atributos son listas de nodos a ejecutar, excepto para handlers, el cual es una lista de nodos ExceptHandler.

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

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

Bloques try que van seguidos de cláusulas except*. Los atributos son los mismos que para Try pero los nodos ExceptHandler en handlers se interpretan como bloques except* en lugar de 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))])])])

Added in version 3.11.

class ast.ExceptHandler(type, name, body)¶

Una sola cláusula except. type es el tipo de excepción con el que coincidirá, normalmente un nodo Name (o None para una cláusula except: generalizada). name es una cadena sin formato para que el nombre contenga la excepción, o None si la cláusula no tiene as foo. body es una lista de nodos.

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

Un bloque with. items es una lista de nodos withitem que representan los administradores de contexto, y body es el bloque con sangría dentro del contexto.

type_comment¶

type_comment es una cadena de caracteres opcional con la anotación de tipos como comentario.

class ast.withitem(context_expr, optional_vars)¶

Un administrador de contexto único en un bloque with. context_expr es el administrador de contexto, a menudo un nodo Call. optional_vars es un Name, Tuple o List para la parte as foo, o None si no se usa.

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

La coincidencia de patrones¶

class ast.Match(subject, cases)¶

Una declaración match. subject contiene el sujeto de la coincidencia (el objeto que se compara con los casos) y cases contiene un iterable de nodos match_case con los diferentes casos.

Added in version 3.10.

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

Un patrón de caso único en una declaración match. pattern contiene el patrón de coincidencia con el que se comparará el sujeto. Tenga en cuenta que los nodos AST producidos para patrones difieren de los producidos para expresiones, incluso cuando comparten la misma sintaxis.

El atributo guard contiene una expresión que se evaluará si el patrón coincide con el sujeto.

body contiene una lista de nodos para ejecutar si el patrón coincide y el resultado de evaluar la expresión de protección es verdadero.

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

Added in version 3.10.

class ast.MatchValue(value)¶

Un patrón de valor o literal de coincidencia que se compara por igualdad. value es un nodo de expresión. Los nodos de valores permitidos están restringidos como se describe en la documentación de la declaración de coincidencia. Este patrón tiene éxito si el sujeto de la coincidencia es igual al valor evaluado.

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

Added in version 3.10.

class ast.MatchSingleton(value)¶

Un patrón literal de coincidencia que se compara por identidad. value es el singleton que se va a comparar con: None, True o False. Este patrón tiene éxito si el sujeto de la coincidencia es la constante dada.

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

Added in version 3.10.

class ast.MatchSequence(patterns)¶

Un patrón de secuencia de coincidencia. patterns contiene los patrones que se compararán con los elementos del sujeto si el sujeto es una secuencia. Coincide con una secuencia de longitud variable si uno de los subpatrones es un nodo MatchStar; de lo contrario, coincide con una secuencia de longitud fija.

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

Added in version 3.10.

class ast.MatchStar(name)¶

Coincide con el resto de la secuencia en un patrón de secuencia de coincidencia de longitud variable. Si name no es None, una lista que contiene los elementos de secuencia restantes está vinculada a ese nombre si el patrón de secuencia general es exitoso.

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

Added in version 3.10.

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

Un patrón de mapeo de coincidencias. keys es una secuencia de nodos de expresión. patterns es una secuencia correspondiente de nodos de patrón. rest es un nombre opcional que se puede especificar para capturar los elementos de mapeo restantes. Las expresiones clave permitidas están restringidas como se describe en la documentación de la declaración de coincidencia.

Este patrón tiene éxito si el sujeto es un mapeo, todas las expresiones clave evaluadas están presentes en el mapeo y el valor correspondiente a cada clave coincide con el subpatrón correspondiente. Si rest no es None, un dict que contiene los elementos de mapeo restantes se vincula a ese nombre si el patrón de mapeo general es exitoso.

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

Added in version 3.10.

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

Un patrón de clase coincidente. cls es una expresión que da la clase nominal que se va a emparejar. patterns es una secuencia de nodos de patrón que se compararán con la secuencia definida por la clase de atributos de coincidencia de patrones. kwd_attrs es una secuencia de atributos adicionales que deben coincidir (especificados como argumentos de palabra clave en el patrón de clase), kwd_patterns son los patrones correspondientes (especificados como valores de palabras clave en el patrón de clase).

Este patrón tiene éxito si el sujeto es una instancia de la clase nominada, todos los patrones posicionales coinciden con los atributos definidos por la clase correspondientes y cualquier atributo de palabra clave especificado coincide con su patrón correspondiente.

Nota: las clases pueden definir una propiedad que retorna self para hacer coincidir un nodo de patrón con la instancia que se está comparando. Varios tipos incorporados también se combinan de esa manera, como se describe en la documentación de la declaración de coincidencia.

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

Added in version 3.10.

class ast.MatchAs(pattern, name)¶

Una coincidencia «como patrón», patrón de captura o patrón comodín. pattern contiene el patrón de coincidencia con el que se comparará el sujeto. Si el patrón es None, el nodo representa un patrón de captura (es decir, un nombre simple) y siempre tendrá éxito.

El atributo name contiene el nombre que se vinculará si el patrón tiene éxito. Si name es None, pattern también debe ser None y el nodo representa el patrón comodín.

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

Added in version 3.10.

class ast.MatchOr(patterns)¶

Una coincidencia «o patrón». Un patrón-o hace coincidir cada uno de sus subpatrones con el sujeto, hasta que uno tiene éxito. Entonces se considera que el patrón-o tiene éxito. Si ninguno de los subpatrones tiene éxito, el patrón o falla. El atributo patterns contiene una lista de nodos de patrones de coincidencia que se compararán con el sujeto.

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

Added in version 3.10.

Type annotations¶

class ast.TypeIgnore(lineno, tag)¶

A # type: ignore comment located at lineno. tag is the optional tag specified by the form # type: ignore <tag>.

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

Nota

TypeIgnore nodes are not generated when the type_comments parameter is set to False (default). See ast.parse() for more details.

Added in version 3.8.

Tipos de parámetro¶

«Parámetros de tipo pueden existir en clases, funciones y tipos de alias»

class ast.TypeVar(name, bound, default_value)¶

A typing.TypeVar. name is the name of the type variable. bound is the bound or constraints, if any. If bound is a Tuple, it represents constraints; otherwise it represents the bound. default_value is the default value; if the TypeVar has no default, this attribute will be set to None.

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

Added in version 3.12.

Distinto en la versión 3.13: Added the default_value parameter.

class ast.ParamSpec(name, default_value)¶

A typing.ParamSpec. name is the name of the parameter specification. default_value is the default value; if the ParamSpec has no default, this attribute will be set to None.

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

Added in version 3.12.

Distinto en la versión 3.13: Added the default_value parameter.

class ast.TypeVarTuple(name, default_value)¶

A typing.TypeVarTuple. name is the name of the type variable tuple. default_value is the default value; if the TypeVarTuple has no default, this attribute will be set to None.

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

Added in version 3.12.

Distinto en la versión 3.13: Added the default_value parameter.

Definiciones de función y clase¶

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

Una definición de función.

• name es una cadena de caracteres sin formato del nombre de la función.

• args es un nodo arguments.

• body es la lista de nodos dentro de la función.

• decorator_list es la lista de decoradores que se aplicarán, almacenados en el exterior primero (es decir, el primero de la lista se aplicará al final).

• returns es la anotación de retorno.

• type_params es una lista de parametros de tipo.

type_comment¶

type_comment es una cadena de caracteres opcional con la anotación de tipos como comentario.

Distinto en la versión 3.12: Se ha añadido type_params.

class ast.Lambda(args, body)¶

lambda es una definición de función mínima que se puede utilizar dentro de una expresión. A diferencia de FunctionDef, body tiene un solo nodo.

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

Los argumentos para una función.

• posonlyargs, args y kwonlyargs son listas de nodos arg.

• vararg y kwarg son nodos arg únicos, en referencia a los parámetros *args, **kwargs.

• kw_defaults es una lista de valores predeterminados para argumentos de solo palabras clave. Si uno es None, se requiere el argumento correspondiente.

• defaults es una lista de valores predeterminados para argumentos que se pueden pasar posicionalmente. Si hay menos valores predeterminados, corresponden a los últimos n argumentos.

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 es una cadena opcional con la anotación de tipo como comentario

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

class ast.Return(value)¶

Una declaración return.

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

class ast.Yield(value)¶

class ast.YieldFrom(value)¶

A yield or yield from expression. Because these are expressions, they must be wrapped in an 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())))])

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

class ast.Global(names)¶

class ast.Nonlocal(names)¶

Declaraciones global y nonlocal. names es una lista de cadenas sin formato.

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

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

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

Una definición de clase.

• name es una cadena sin formato para el nombre de la clase

• bases es una lista de nodos para clases base especificadas explícitamente.

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

• body es una lista de nodos que representan el código dentro de la definición de clase.

• decorator_list es una lista de nodos, como en FunctionDef.

• type_params es una lista de parametros de tipo.

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

Distinto en la versión 3.12: Se ha añadido type_params.

Async y await¶

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

Una definición de función async def. Tiene los mismos campos que FunctionDef.

Distinto en la versión 3.12: Se ha añadido type_params.

class ast.Await(value)¶

Una expresión await. value es lo que espera. Solo válido en el cuerpo de un AsyncFunctionDef.

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

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

class ast.AsyncWith(items, body, type_comment)¶

Bucles async for y administradores de contexto async with. Tienen los mismos campos que For y With, respectivamente. Solo válido en el cuerpo de un AsyncFunctionDef.