# `ast` — Árboles de sintaxis abstracta

Código fuente: Lib/ast.py

El módulo `ast` ayuda a las aplicaciones de Python a procesar árboles de la gramática de sintaxis abstracta de Python. La sintaxis abstracta en sí misma puede cambiar con cada versión de Python; Este módulo ayuda a descubrir mediante programación cómo se ve la gramática actual.

Se puede generar un árbol de sintaxis abstracta pasando `ast.PyCF_ONLY_AST` como un indicador de la función incorporada `compile()`, o usando el ayudante `parse()` provisto en este módulo. El resultado será un árbol de objetos cuyas clases todas heredan de `ast.AST`. Se puede compilar un árbol de sintaxis abstracta en un objeto de código Python utilizando la función incorporada `compile()`.

## Clases Nodo

class `ast.``AST`

  Esta es la base de todas las clases de nodo AST. Las clases de nodo reales se derivan del archivo `Parser/Python.asdl`, que se reproduce abajo. Se definen en el módulo `_ast` C y se reexportan en `ast`.

  Hay una clase definida para cada símbolo del lado izquierdo en la gramática abstracta (por ejemplo, `ast.stmt` o `ast.expr`). Además, hay una clase definida para cada constructor en el lado derecho; estas clases heredan de las clases para los árboles del lado izquierdo. Por ejemplo, `ast.BinOp` hereda de `ast.expr`. Para las reglas de producción con alternativas (también conocidas como «sumas»), la clase del lado izquierdo es abstracta: solo se crean instancias de nodos de constructor específicos.

  `_fields`

    Cada clase concreta tiene un atributo `_fields` que proporciona los nombres de todos los nodos secundarios.

    Cada instancia de una clase concreta tiene un atributo para cada nodo secundario, del tipo definido en la gramática. Por ejemplo, las instancias `ast.BinOp` tienen un atributo `left` de tipo `ast.expr`.

    Si estos atributos están marcados como opcionales en la gramática (usando un signo de interrogación), el valor podría ser `None`. Si los atributos pueden tener cero o más valores (marcados con un asterisco), los valores se representan como listas de Python. Todos los atributos posibles deben estar presentes y tener valores válidos al compilar un AST con `compile()`.

  `lineno`
  `col_offset`
  `end_lineno`
  `end_col_offset`

    Las instancias de las subclases `ast.expr` y `ast.stmt` tienen atributos `lineno`, `col_offset`, `lineno`, y `col_offset`. Los `lineno` y `end_lineno` son los números de la primera y última línea del intervalo de texto de origen (1 indexado, por lo que la primera línea es la línea 1) y el `col_offset` y `end_col_offset` son las correspondientes compensaciones de bytes UTF-8 del primer y último token que generó el nodo. El desplazamiento UTF-8 se registra porque el analizador utiliza UTF-8 internamente.

    Tenga en cuenta que el compilador no requiere las posiciones finales y, por lo tanto, son opcionales. El desplazamiento final es después del último símbolo, por ejemplo, uno puede obtener el segmento fuente de un nodo de expresión de una línea usando `source_line[node.col_offset: node.end_col_offset]`.

  El constructor de una clase `ast.T` analiza sus argumentos de la siguiente manera:

  - Si hay argumentos posicionales, debe haber tantos como elementos en `T._fields`; serán asignados como atributos de estos nombres.

  - Si hay argumentos de palabras clave, establecerán los atributos de los mismos nombres a los valores dados.

  Por ejemplo, para crear y completar un nodo `ast.UnaryOp`, puede usar

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

  o la más compacta

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

Distinto en la versión 3.8: La clase `ast.Constant` ahora se usa para todas las constantes.

Obsoleto desde la versión 3.8: Las clases antiguas `ast.Num`, `ast.Str`, `ast.Bytes`, `ast.NameConstant` y `ast.Ellipsis` todavía están disponibles, pero se eliminarán en futuras versiones de Python. Mientras tanto, instanciarlos retornará una instancia de una clase diferente.

## Gramática abstracta

La gramática abstracta se define actualmente de la siguiente manera:

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

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

            -- not really an actual node but useful in Jython's typesystem.
            | Suite(stmt* body)

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

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

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

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

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

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

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

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

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

             -- the following expression can appear in assignment context
             | Attribute(expr value, identifier attr, expr_context ctx)
             | Subscript(expr value, slice 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)

              -- 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 | AugLoad | AugStore | Param

        slice = Slice(expr? lower, expr? upper, expr? step)
              | ExtSlice(slice* dims)
              | Index(expr value)

        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)

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

        withitem = (expr context_expr, expr? optional_vars)

        type_ignore = TypeIgnore(int lineno, string tag)
    }

## Ayudantes de `ast`

Además de las clases de nodo, el módulo `ast` define estas funciones y clases de utilidad para atravesar árboles de sintaxis abstracta:

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

  Analiza la fuente en un nodo AST. Equivalente a `compile(source, filename, mode, ast.PyCF_ONLY_AST)`.

  Si se proporciona `type_comments=True`, el analizador se modifica para verificar y retornar los comentarios de tipo según lo especificado por PEP 484 y PEP 526. Esto es equivalente a agregar `ast.PyCF_TYPE_COMMENTS` a los flags pasados a `compile()`. Esto informará errores de sintaxis para comentarios de tipo fuera de lugar. Sin este flag, los comentarios de tipo se ignorarán y el campo `type_comment` en los nodos AST seleccionados siempre será `None`. Además, las ubicaciones de los comentarios `# type: ignore` se retornarán como el atributo `type_ignores` de `Module` (de lo contrario, siempre es una lista vacía).

  Además, si `modo` es `'func_type'`, la sintaxis de entrada se modifica para corresponder a PEP 484 «comentarios de tipo de firma», por ejemplo `(str, int) -> List[str]`.

  Además, establece `feature_version` en una tupla `(major, minor)` intentará analizar usando la gramática de esa versión de Python. Actualmente `major` debe ser igual a `3`. Por ejemplo, establece `feature_version=(3, 4)` permitirá el uso de `async` y `await` como nombres de variables. La versión más baja admitida es `(3, 4)`; la más alto es `sys.version_info[0:2]`.

  Advertencia

  Es posible bloquear el intérprete de Python con una cadena de caracteres suficientemente grande/compleja debido a las limitaciones de profundidad de pila en el compilador AST de Python.

  Distinto en la versión 3.8: Se agregaron `type_comments`, `mode='func_type'` y `feature_version`.

`ast.``literal_eval`(node_or_string)

  Evalúa de forma segura un nodo de expresión o una cadena de caracteres que contenga un literal de Python o un visualizador de contenedor. La cadena o nodo proporcionado solo puede consistir en las siguientes estructuras literales de Python: cadenas de caracteres, bytes, números, tuplas, listas, diccionarios, conjuntos, booleanos y `None`.

  Esto se puede usar para evaluar de forma segura las cadenas de caracteres que contienen valores de Python de fuentes no confiables sin la necesidad de analizar los valores uno mismo. No es capaz de evaluar expresiones complejas arbitrariamente, por ejemplo, que involucran operadores o indexación.

  Advertencia

  Es posible bloquear el intérprete de Python con una cadena de caracteres suficientemente grande/compleja debido a las limitaciones de profundidad de pila en el compilador AST de Python.

  Distinto en la versión 3.2: Ahora permite bytes y establece literales.

`ast.``get_docstring`(node, clean=True)

  Retorna la cadena de caracteres de documentación del node dado (que debe ser un nodo `FunctionDef`, `AsyncFunctionDef`, `ClassDef`, o `Module`), o `None` si no tiene docstring. Si clean es verdadero, limpia la sangría del docstring con `inspect.cleandoc()`.

  Distinto en la versión 3.5: `AsyncFunctionDef` ahora está soportada.

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

  Obtenga el segmento de código fuente del source que generó node. Si falta información de ubicación (`lineno`, `end_lineno`, `col_offset`, o `end_col_offset`), retorna `None`.

  Si padded es `True`, la primera línea de una declaración de varias líneas se rellenará con espacios para que coincidan con su posición original.

  Nuevo en la versión 3.8.

`ast.``fix_missing_locations`(node)

  Cuando compila un árbol de nodos con `compile()`, el compilador espera los atributos `lineno` y `col_offset` para cada nodo que los soporta. Es bastante tedioso completar los nodos generados, por lo que este ayudante agrega estos atributos de forma recursiva donde aún no están establecidos, configurándolos en los valores del nodo principal. Funciona de forma recursiva comenzando en node.

`ast.``increment_lineno`(node, n=1)

  Incremente el número de línea y el número de línea final de cada nodo en el árbol comenzando en node por n. Esto es útil para «mover código» a una ubicación diferente en un archivo.

`ast.``copy_location`(new_node, old_node)

  Copia la ubicación de origen (`lineno`, `col_offset`, `end_lineno`, y `end_col_offset`) de old_node a new_node si es posible, y retorna new_node.

`ast.``iter_fields`(node)

  Produce (yield) una tupla de `(fieldname, value)` para cada campo en `node._fields` que está presente en node.

`ast.``iter_child_nodes`(node)

  Cede todos los nodos secundarios directos de node, es decir, todos los campos que son nodos y todos los elementos de campos que son listas de nodos.

`ast.``walk`(node)

  Recursivamente produce todos los nodos descendientes en el árbol comenzando en node (incluido node en sí mismo), en ningún orden especificado. Esto es útil si solo desea modificar los nodos en su lugar y no le importa el contexto.

class `ast.``NodeVisitor`

  Una clase base de visitante de nodo que recorre el árbol de sintaxis abstracta y llama a una función de visitante para cada nodo encontrado. Esta función puede retornar un valor que se reenvía mediante el método `visit()`.

  Esta clase está destinada a ser subclase, con la subclase agregando métodos de visitante.

  `visit`(node)

    Visita un nodo. La implementación predeterminada llama al método llamado `self.visit_classname` donde classname es el nombre de la clase de nodo, o `generic_visit()` si ese método no existe.

  `generic_visit`(node)

    Este visitante llama `visit()` en todos los hijos del nodo.

    Tenga en cuenta que los nodos secundarios de los nodos que tienen un método de visitante personalizado no se visitarán a menos que el visitante llame `generic_visit()` o los visite a sí mismo.

  No use `NodeVisitor` si desea aplicar cambios a los nodos durante el recorrido. Para esto existe un visitante especial (`NodeTransformer`) que permite modificaciones.

  Obsoleto desde la versión 3.8: Los métodos `visit_Num()`, `visit_Str()`, `visit_Bytes()`, `visit_NameConstant()` y `visit_Ellipsis()` están en desuso ahora y no serán llamados en futuras versiones de Python. Agregue el método `visit_Constant()` para manejar todos los nodos constantes.

class `ast.``NodeTransformer`

  Una subclase de `NodeVisitor` que recorre el árbol de sintaxis abstracta y permite la modificación de nodos.

  La clase `NodeTransformer` recorrerá el AST y usará el valor de retorno de los métodos del visitante para reemplazar o eliminar el nodo anterior. Si el valor de retorno del método de visitante es `None`, el nodo se eliminará de su ubicación; de lo contrario, se reemplazará con el valor de retorno. El valor de retorno puede ser el nodo original, en cuyo caso no se realiza ningún reemplazo.

  Aquí hay un transformador de ejemplo que reescribe todas las apariciones de búsquedas de nombres (`foo`) en `data['foo']`:

      class RewriteName(NodeTransformer):

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

  Tenga en cuenta que si el nodo en el que está operando tiene nodos secundarios, debe transformar los nodos secundarios usted mismo o llamar primero al método `generic_visit()` para el nodo.

  Para los nodos que formaban parte de una colección de declaraciones (que se aplica a todos los nodos de declaración), el visitante también puede retornar una lista de nodos en lugar de solo un nodo.

  Si `NodeTransformer` introduce nuevos nodos (que no eran parte del árbol original) sin darles información de ubicación (como `lineno`), `fix_missing_locations()` debería llamarse con el nuevo sub-árbol para recalcular la información de ubicación

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

  Usualmente usas el transformador así:

      node = YourTransformer().visit(node)

`ast.``dump`(node, annotate_fields=True, include_attributes=False)

  Retorna un volcado formateado del árbol en node. Esto es principalmente útil para propósitos de depuración. Si annotate_fields es verdadero (por defecto), la cadena de caracteres retornada mostrará los nombres y los valores de los campos. Si annotate_fields es falso, la cadena de resultados será más compacta omitiendo nombres de campo no ambiguos. Los atributos como los números de línea y las compensaciones de columna no se vuelcan de forma predeterminada. Si esto se desea, include_attributes se puede establecer en verdadero.

Ver también

Green Tree Snakes, un recurso de documentación externo, tiene buenos detalles sobre cómo trabajar con Python AST.

ASTTokens annotates Python ASTs with the positions of tokens and text in the source code that generated them. This is helpful for tools that make source code transformations.

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

LibCST parses code as a Concrete Syntax Tree that looks like an ast tree and keeps all formatting details. It’s useful for building automated refactoring (codemod) applications and linters.

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