1:mod:`ast` --- Abstract Syntax Trees 2==================================== 3 4.. module:: ast 5 :synopsis: Abstract Syntax Tree classes and manipulation. 6 7.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de> 8.. sectionauthor:: Georg Brandl <georg@python.org> 9 10.. testsetup:: 11 12 import ast 13 14**Source code:** :source:`Lib/ast.py` 15 16-------------- 17 18The :mod:`ast` module helps Python applications to process trees of the Python 19abstract syntax grammar. The abstract syntax itself might change with each 20Python release; this module helps to find out programmatically what the current 21grammar looks like. 22 23An abstract syntax tree can be generated by passing :data:`ast.PyCF_ONLY_AST` as 24a flag to the :func:`compile` built-in function, or using the :func:`parse` 25helper provided in this module. The result will be a tree of objects whose 26classes all inherit from :class:`ast.AST`. An abstract syntax tree can be 27compiled into a Python code object using the built-in :func:`compile` function. 28 29 30.. _abstract-grammar: 31 32Abstract Grammar 33---------------- 34 35The abstract grammar is currently defined as follows: 36 37.. literalinclude:: ../../Parser/Python.asdl 38 :language: asdl 39 40 41Node classes 42------------ 43 44.. class:: AST 45 46 This is the base of all AST node classes. The actual node classes are 47 derived from the :file:`Parser/Python.asdl` file, which is reproduced 48 :ref:`below <abstract-grammar>`. They are defined in the :mod:`_ast` C 49 module and re-exported in :mod:`ast`. 50 51 There is one class defined for each left-hand side symbol in the abstract 52 grammar (for example, :class:`ast.stmt` or :class:`ast.expr`). In addition, 53 there is one class defined for each constructor on the right-hand side; these 54 classes inherit from the classes for the left-hand side trees. For example, 55 :class:`ast.BinOp` inherits from :class:`ast.expr`. For production rules 56 with alternatives (aka "sums"), the left-hand side class is abstract: only 57 instances of specific constructor nodes are ever created. 58 59 .. index:: single: ? (question mark); in AST grammar 60 .. index:: single: * (asterisk); in AST grammar 61 62 .. attribute:: _fields 63 64 Each concrete class has an attribute :attr:`_fields` which gives the names 65 of all child nodes. 66 67 Each instance of a concrete class has one attribute for each child node, 68 of the type as defined in the grammar. For example, :class:`ast.BinOp` 69 instances have an attribute :attr:`left` of type :class:`ast.expr`. 70 71 If these attributes are marked as optional in the grammar (using a 72 question mark), the value might be ``None``. If the attributes can have 73 zero-or-more values (marked with an asterisk), the values are represented 74 as Python lists. All possible attributes must be present and have valid 75 values when compiling an AST with :func:`compile`. 76 77 .. attribute:: lineno 78 col_offset 79 end_lineno 80 end_col_offset 81 82 Instances of :class:`ast.expr` and :class:`ast.stmt` subclasses have 83 :attr:`lineno`, :attr:`col_offset`, :attr:`end_lineno`, and 84 :attr:`end_col_offset` attributes. The :attr:`lineno` and 85 :attr:`end_lineno` are the first and last line numbers of the source 86 text span (1-indexed so the first line is line 1), and the 87 :attr:`col_offset` and :attr:`end_col_offset` are the corresponding 88 UTF-8 byte offsets of the first and last tokens that generated the node. 89 The UTF-8 offset is recorded because the parser uses UTF-8 internally. 90 91 Note that the end positions are not required by the compiler and are 92 therefore optional. The end offset is *after* the last symbol, for example 93 one can get the source segment of a one-line expression node using 94 ``source_line[node.col_offset : node.end_col_offset]``. 95 96 The constructor of a class :class:`ast.T` parses its arguments as follows: 97 98 * If there are positional arguments, there must be as many as there are items 99 in :attr:`T._fields`; they will be assigned as attributes of these names. 100 * If there are keyword arguments, they will set the attributes of the same 101 names to the given values. 102 103 For example, to create and populate an :class:`ast.UnaryOp` node, you could 104 use :: 105 106 node = ast.UnaryOp() 107 node.op = ast.USub() 108 node.operand = ast.Constant() 109 node.operand.value = 5 110 node.operand.lineno = 0 111 node.operand.col_offset = 0 112 node.lineno = 0 113 node.col_offset = 0 114 115 or the more compact :: 116 117 node = ast.UnaryOp(ast.USub(), ast.Constant(5, lineno=0, col_offset=0), 118 lineno=0, col_offset=0) 119 120.. versionchanged:: 3.8 121 122 Class :class:`ast.Constant` is now used for all constants. 123 124.. versionchanged:: 3.9 125 126 Simple indices are represented by their value, extended slices are 127 represented as tuples. 128 129.. deprecated:: 3.8 130 131 Old classes :class:`ast.Num`, :class:`ast.Str`, :class:`ast.Bytes`, 132 :class:`ast.NameConstant` and :class:`ast.Ellipsis` are still available, 133 but they will be removed in future Python releases. In the meantime, 134 instantiating them will return an instance of a different class. 135 136.. deprecated:: 3.9 137 138 Old classes :class:`ast.Index` and :class:`ast.ExtSlice` are still 139 available, but they will be removed in future Python releases. 140 In the meantime, instantiating them will return an instance of 141 a different class. 142 143.. note:: 144 The descriptions of the specific node classes displayed here 145 were initially adapted from the fantastic `Green Tree 146 Snakes <https://greentreesnakes.readthedocs.io/en/latest/>`__ project and 147 all its contributors. 148 149Literals 150^^^^^^^^ 151 152.. class:: Constant(value) 153 154 A constant value. The ``value`` attribute of the ``Constant`` literal contains the 155 Python object it represents. The values represented can be simple types 156 such as a number, string or ``None``, but also immutable container types 157 (tuples and frozensets) if all of their elements are constant. 158 159 .. doctest:: 160 161 >>> print(ast.dump(ast.parse('123', mode='eval'), indent=4)) 162 Expression( 163 body=Constant(value=123)) 164 165 166.. class:: FormattedValue(value, conversion, format_spec) 167 168 Node representing a single formatting field in an f-string. If the string 169 contains a single formatting field and nothing else the node can be 170 isolated otherwise it appears in :class:`JoinedStr`. 171 172 * ``value`` is any expression node (such as a literal, a variable, or a 173 function call). 174 * ``conversion`` is an integer: 175 176 * -1: no formatting 177 * 115: ``!s`` string formatting 178 * 114: ``!r`` repr formatting 179 * 97: ``!a`` ascii formatting 180 181 * ``format_spec`` is a :class:`JoinedStr` node representing the formatting 182 of the value, or ``None`` if no format was specified. Both 183 ``conversion`` and ``format_spec`` can be set at the same time. 184 185 186.. class:: JoinedStr(values) 187 188 An f-string, comprising a series of :class:`FormattedValue` and :class:`Constant` 189 nodes. 190 191 .. doctest:: 192 193 >>> print(ast.dump(ast.parse('f"sin({a}) is {sin(a):.3}"', mode='eval'), indent=4)) 194 Expression( 195 body=JoinedStr( 196 values=[ 197 Constant(value='sin('), 198 FormattedValue( 199 value=Name(id='a', ctx=Load()), 200 conversion=-1), 201 Constant(value=') is '), 202 FormattedValue( 203 value=Call( 204 func=Name(id='sin', ctx=Load()), 205 args=[ 206 Name(id='a', ctx=Load())], 207 keywords=[]), 208 conversion=-1, 209 format_spec=JoinedStr( 210 values=[ 211 Constant(value='.3')]))])) 212 213 214.. class:: List(elts, ctx) 215 Tuple(elts, ctx) 216 217 A list or tuple. ``elts`` holds a list of nodes representing the elements. 218 ``ctx`` is :class:`Store` if the container is an assignment target (i.e. 219 ``(x,y)=something``), and :class:`Load` otherwise. 220 221 .. doctest:: 222 223 >>> print(ast.dump(ast.parse('[1, 2, 3]', mode='eval'), indent=4)) 224 Expression( 225 body=List( 226 elts=[ 227 Constant(value=1), 228 Constant(value=2), 229 Constant(value=3)], 230 ctx=Load())) 231 >>> print(ast.dump(ast.parse('(1, 2, 3)', mode='eval'), indent=4)) 232 Expression( 233 body=Tuple( 234 elts=[ 235 Constant(value=1), 236 Constant(value=2), 237 Constant(value=3)], 238 ctx=Load())) 239 240 241.. class:: Set(elts) 242 243 A set. ``elts`` holds a list of nodes representing the set's elements. 244 245 .. doctest:: 246 247 >>> print(ast.dump(ast.parse('{1, 2, 3}', mode='eval'), indent=4)) 248 Expression( 249 body=Set( 250 elts=[ 251 Constant(value=1), 252 Constant(value=2), 253 Constant(value=3)])) 254 255 256.. class:: Dict(keys, values) 257 258 A dictionary. ``keys`` and ``values`` hold lists of nodes representing the 259 keys and the values respectively, in matching order (what would be returned 260 when calling :code:`dictionary.keys()` and :code:`dictionary.values()`). 261 262 When doing dictionary unpacking using dictionary literals the expression to be 263 expanded goes in the ``values`` list, with a ``None`` at the corresponding 264 position in ``keys``. 265 266 .. doctest:: 267 268 >>> print(ast.dump(ast.parse('{"a":1, **d}', mode='eval'), indent=4)) 269 Expression( 270 body=Dict( 271 keys=[ 272 Constant(value='a'), 273 None], 274 values=[ 275 Constant(value=1), 276 Name(id='d', ctx=Load())])) 277 278 279Variables 280^^^^^^^^^ 281 282.. class:: Name(id, ctx) 283 284 A variable name. ``id`` holds the name as a string, and ``ctx`` is one of 285 the following types. 286 287 288.. class:: Load() 289 Store() 290 Del() 291 292 Variable references can be used to load the value of a variable, to assign 293 a new value to it, or to delete it. Variable references are given a context 294 to distinguish these cases. 295 296 .. doctest:: 297 298 >>> print(ast.dump(ast.parse('a'), indent=4)) 299 Module( 300 body=[ 301 Expr( 302 value=Name(id='a', ctx=Load()))], 303 type_ignores=[]) 304 305 >>> print(ast.dump(ast.parse('a = 1'), indent=4)) 306 Module( 307 body=[ 308 Assign( 309 targets=[ 310 Name(id='a', ctx=Store())], 311 value=Constant(value=1))], 312 type_ignores=[]) 313 314 >>> print(ast.dump(ast.parse('del a'), indent=4)) 315 Module( 316 body=[ 317 Delete( 318 targets=[ 319 Name(id='a', ctx=Del())])], 320 type_ignores=[]) 321 322 323.. class:: Starred(value, ctx) 324 325 A ``*var`` variable reference. ``value`` holds the variable, typically a 326 :class:`Name` node. This type must be used when building a :class:`Call` 327 node with ``*args``. 328 329 .. doctest:: 330 331 >>> print(ast.dump(ast.parse('a, *b = it'), indent=4)) 332 Module( 333 body=[ 334 Assign( 335 targets=[ 336 Tuple( 337 elts=[ 338 Name(id='a', ctx=Store()), 339 Starred( 340 value=Name(id='b', ctx=Store()), 341 ctx=Store())], 342 ctx=Store())], 343 value=Name(id='it', ctx=Load()))], 344 type_ignores=[]) 345 346 347Expressions 348^^^^^^^^^^^ 349 350.. class:: Expr(value) 351 352 When an expression, such as a function call, appears as a statement by itself 353 with its return value not used or stored, it is wrapped in this container. 354 ``value`` holds one of the other nodes in this section, a :class:`Constant`, a 355 :class:`Name`, a :class:`Lambda`, a :class:`Yield` or :class:`YieldFrom` node. 356 357 .. doctest:: 358 359 >>> print(ast.dump(ast.parse('-a'), indent=4)) 360 Module( 361 body=[ 362 Expr( 363 value=UnaryOp( 364 op=USub(), 365 operand=Name(id='a', ctx=Load())))], 366 type_ignores=[]) 367 368 369.. class:: UnaryOp(op, operand) 370 371 A unary operation. ``op`` is the operator, and ``operand`` any expression 372 node. 373 374 375.. class:: UAdd 376 USub 377 Not 378 Invert 379 380 Unary operator tokens. :class:`Not` is the ``not`` keyword, :class:`Invert` 381 is the ``~`` operator. 382 383 .. doctest:: 384 385 >>> print(ast.dump(ast.parse('not x', mode='eval'), indent=4)) 386 Expression( 387 body=UnaryOp( 388 op=Not(), 389 operand=Name(id='x', ctx=Load()))) 390 391 392.. class:: BinOp(left, op, right) 393 394 A binary operation (like addition or division). ``op`` is the operator, and 395 ``left`` and ``right`` are any expression nodes. 396 397 .. doctest:: 398 399 >>> print(ast.dump(ast.parse('x + y', mode='eval'), indent=4)) 400 Expression( 401 body=BinOp( 402 left=Name(id='x', ctx=Load()), 403 op=Add(), 404 right=Name(id='y', ctx=Load()))) 405 406 407.. class:: Add 408 Sub 409 Mult 410 Div 411 FloorDiv 412 Mod 413 Pow 414 LShift 415 RShift 416 BitOr 417 BitXor 418 BitAnd 419 MatMult 420 421 Binary operator tokens. 422 423 424.. class:: BoolOp(op, values) 425 426 A boolean operation, 'or' or 'and'. ``op`` is :class:`Or` or :class:`And`. 427 ``values`` are the values involved. Consecutive operations with the same 428 operator, such as ``a or b or c``, are collapsed into one node with several 429 values. 430 431 This doesn't include ``not``, which is a :class:`UnaryOp`. 432 433 .. doctest:: 434 435 >>> print(ast.dump(ast.parse('x or y', mode='eval'), indent=4)) 436 Expression( 437 body=BoolOp( 438 op=Or(), 439 values=[ 440 Name(id='x', ctx=Load()), 441 Name(id='y', ctx=Load())])) 442 443 444.. class:: And 445 Or 446 447 Boolean operator tokens. 448 449 450.. class:: Compare(left, ops, comparators) 451 452 A comparison of two or more values. ``left`` is the first value in the 453 comparison, ``ops`` the list of operators, and ``comparators`` the list 454 of values after the first element in the comparison. 455 456 .. doctest:: 457 458 >>> print(ast.dump(ast.parse('1 <= a < 10', mode='eval'), indent=4)) 459 Expression( 460 body=Compare( 461 left=Constant(value=1), 462 ops=[ 463 LtE(), 464 Lt()], 465 comparators=[ 466 Name(id='a', ctx=Load()), 467 Constant(value=10)])) 468 469 470.. class:: Eq 471 NotEq 472 Lt 473 LtE 474 Gt 475 GtE 476 Is 477 IsNot 478 In 479 NotIn 480 481 Comparison operator tokens. 482 483 484.. class:: Call(func, args, keywords, starargs, kwargs) 485 486 A function call. ``func`` is the function, which will often be a 487 :class:`Name` or :class:`Attribute` object. Of the arguments: 488 489 * ``args`` holds a list of the arguments passed by position. 490 * ``keywords`` holds a list of :class:`keyword` objects representing 491 arguments passed by keyword. 492 493 When creating a ``Call`` node, ``args`` and ``keywords`` are required, but 494 they can be empty lists. ``starargs`` and ``kwargs`` are optional. 495 496 .. doctest:: 497 498 >>> print(ast.dump(ast.parse('func(a, b=c, *d, **e)', mode='eval'), indent=4)) 499 Expression( 500 body=Call( 501 func=Name(id='func', ctx=Load()), 502 args=[ 503 Name(id='a', ctx=Load()), 504 Starred( 505 value=Name(id='d', ctx=Load()), 506 ctx=Load())], 507 keywords=[ 508 keyword( 509 arg='b', 510 value=Name(id='c', ctx=Load())), 511 keyword( 512 value=Name(id='e', ctx=Load()))])) 513 514 515.. class:: keyword(arg, value) 516 517 A keyword argument to a function call or class definition. ``arg`` is a raw 518 string of the parameter name, ``value`` is a node to pass in. 519 520 521.. class:: IfExp(test, body, orelse) 522 523 An expression such as ``a if b else c``. Each field holds a single node, so 524 in the following example, all three are :class:`Name` nodes. 525 526 .. doctest:: 527 528 >>> print(ast.dump(ast.parse('a if b else c', mode='eval'), indent=4)) 529 Expression( 530 body=IfExp( 531 test=Name(id='b', ctx=Load()), 532 body=Name(id='a', ctx=Load()), 533 orelse=Name(id='c', ctx=Load()))) 534 535 536.. class:: Attribute(value, attr, ctx) 537 538 Attribute access, e.g. ``d.keys``. ``value`` is a node, typically a 539 :class:`Name`. ``attr`` is a bare string giving the name of the attribute, 540 and ``ctx`` is :class:`Load`, :class:`Store` or :class:`Del` according to how 541 the attribute is acted on. 542 543 .. doctest:: 544 545 >>> print(ast.dump(ast.parse('snake.colour', mode='eval'), indent=4)) 546 Expression( 547 body=Attribute( 548 value=Name(id='snake', ctx=Load()), 549 attr='colour', 550 ctx=Load())) 551 552 553.. class:: NamedExpr(target, value) 554 555 A named expression. This AST node is produced by the assignment expressions 556 operator (also known as the walrus operator). As opposed to the :class:`Assign` 557 node in which the first argument can be multiple nodes, in this case both 558 ``target`` and ``value`` must be single nodes. 559 560 .. doctest:: 561 562 >>> print(ast.dump(ast.parse('(x := 4)', mode='eval'), indent=4)) 563 Expression( 564 body=NamedExpr( 565 target=Name(id='x', ctx=Store()), 566 value=Constant(value=4))) 567 568 569Subscripting 570~~~~~~~~~~~~ 571 572.. class:: Subscript(value, slice, ctx) 573 574 A subscript, such as ``l[1]``. ``value`` is the subscripted object 575 (usually sequence or mapping). ``slice`` is an index, slice or key. 576 It can be a :class:`Tuple` and contain a :class:`Slice`. 577 ``ctx`` is :class:`Load`, :class:`Store` or :class:`Del` 578 according to the action performed with the subscript. 579 580 .. doctest:: 581 582 >>> print(ast.dump(ast.parse('l[1:2, 3]', mode='eval'), indent=4)) 583 Expression( 584 body=Subscript( 585 value=Name(id='l', ctx=Load()), 586 slice=Tuple( 587 elts=[ 588 Slice( 589 lower=Constant(value=1), 590 upper=Constant(value=2)), 591 Constant(value=3)], 592 ctx=Load()), 593 ctx=Load())) 594 595 596.. class:: Slice(lower, upper, step) 597 598 Regular slicing (on the form ``lower:upper`` or ``lower:upper:step``). 599 Can occur only inside the *slice* field of :class:`Subscript`, either 600 directly or as an element of :class:`Tuple`. 601 602 .. doctest:: 603 604 >>> print(ast.dump(ast.parse('l[1:2]', mode='eval'), indent=4)) 605 Expression( 606 body=Subscript( 607 value=Name(id='l', ctx=Load()), 608 slice=Slice( 609 lower=Constant(value=1), 610 upper=Constant(value=2)), 611 ctx=Load())) 612 613 614Comprehensions 615~~~~~~~~~~~~~~ 616 617.. class:: ListComp(elt, generators) 618 SetComp(elt, generators) 619 GeneratorExp(elt, generators) 620 DictComp(key, value, generators) 621 622 List and set comprehensions, generator expressions, and dictionary 623 comprehensions. ``elt`` (or ``key`` and ``value``) is a single node 624 representing the part that will be evaluated for each item. 625 626 ``generators`` is a list of :class:`comprehension` nodes. 627 628 .. doctest:: 629 630 >>> print(ast.dump(ast.parse('[x for x in numbers]', mode='eval'), indent=4)) 631 Expression( 632 body=ListComp( 633 elt=Name(id='x', ctx=Load()), 634 generators=[ 635 comprehension( 636 target=Name(id='x', ctx=Store()), 637 iter=Name(id='numbers', ctx=Load()), 638 ifs=[], 639 is_async=0)])) 640 >>> print(ast.dump(ast.parse('{x: x**2 for x in numbers}', mode='eval'), indent=4)) 641 Expression( 642 body=DictComp( 643 key=Name(id='x', ctx=Load()), 644 value=BinOp( 645 left=Name(id='x', ctx=Load()), 646 op=Pow(), 647 right=Constant(value=2)), 648 generators=[ 649 comprehension( 650 target=Name(id='x', ctx=Store()), 651 iter=Name(id='numbers', ctx=Load()), 652 ifs=[], 653 is_async=0)])) 654 >>> print(ast.dump(ast.parse('{x for x in numbers}', mode='eval'), indent=4)) 655 Expression( 656 body=SetComp( 657 elt=Name(id='x', ctx=Load()), 658 generators=[ 659 comprehension( 660 target=Name(id='x', ctx=Store()), 661 iter=Name(id='numbers', ctx=Load()), 662 ifs=[], 663 is_async=0)])) 664 665 666.. class:: comprehension(target, iter, ifs, is_async) 667 668 One ``for`` clause in a comprehension. ``target`` is the reference to use for 669 each element - typically a :class:`Name` or :class:`Tuple` node. ``iter`` 670 is the object to iterate over. ``ifs`` is a list of test expressions: each 671 ``for`` clause can have multiple ``ifs``. 672 673 ``is_async`` indicates a comprehension is asynchronous (using an 674 ``async for`` instead of ``for``). The value is an integer (0 or 1). 675 676 .. doctest:: 677 678 >>> print(ast.dump(ast.parse('[ord(c) for line in file for c in line]', mode='eval'), 679 ... indent=4)) # Multiple comprehensions in one. 680 Expression( 681 body=ListComp( 682 elt=Call( 683 func=Name(id='ord', ctx=Load()), 684 args=[ 685 Name(id='c', ctx=Load())], 686 keywords=[]), 687 generators=[ 688 comprehension( 689 target=Name(id='line', ctx=Store()), 690 iter=Name(id='file', ctx=Load()), 691 ifs=[], 692 is_async=0), 693 comprehension( 694 target=Name(id='c', ctx=Store()), 695 iter=Name(id='line', ctx=Load()), 696 ifs=[], 697 is_async=0)])) 698 699 >>> print(ast.dump(ast.parse('(n**2 for n in it if n>5 if n<10)', mode='eval'), 700 ... indent=4)) # generator comprehension 701 Expression( 702 body=GeneratorExp( 703 elt=BinOp( 704 left=Name(id='n', ctx=Load()), 705 op=Pow(), 706 right=Constant(value=2)), 707 generators=[ 708 comprehension( 709 target=Name(id='n', ctx=Store()), 710 iter=Name(id='it', ctx=Load()), 711 ifs=[ 712 Compare( 713 left=Name(id='n', ctx=Load()), 714 ops=[ 715 Gt()], 716 comparators=[ 717 Constant(value=5)]), 718 Compare( 719 left=Name(id='n', ctx=Load()), 720 ops=[ 721 Lt()], 722 comparators=[ 723 Constant(value=10)])], 724 is_async=0)])) 725 726 >>> print(ast.dump(ast.parse('[i async for i in soc]', mode='eval'), 727 ... indent=4)) # Async comprehension 728 Expression( 729 body=ListComp( 730 elt=Name(id='i', ctx=Load()), 731 generators=[ 732 comprehension( 733 target=Name(id='i', ctx=Store()), 734 iter=Name(id='soc', ctx=Load()), 735 ifs=[], 736 is_async=1)])) 737 738Statements 739^^^^^^^^^^ 740 741.. class:: Assign(targets, value, type_comment) 742 743 An assignment. ``targets`` is a list of nodes, and ``value`` is a single node. 744 745 Multiple nodes in ``targets`` represents assigning the same value to each. 746 Unpacking is represented by putting a :class:`Tuple` or :class:`List` 747 within ``targets``. 748 749 .. attribute:: type_comment 750 751 ``type_comment`` is an optional string with the type annotation as a comment. 752 753 .. doctest:: 754 755 >>> print(ast.dump(ast.parse('a = b = 1'), indent=4)) # Multiple assignment 756 Module( 757 body=[ 758 Assign( 759 targets=[ 760 Name(id='a', ctx=Store()), 761 Name(id='b', ctx=Store())], 762 value=Constant(value=1))], 763 type_ignores=[]) 764 765 >>> print(ast.dump(ast.parse('a,b = c'), indent=4)) # Unpacking 766 Module( 767 body=[ 768 Assign( 769 targets=[ 770 Tuple( 771 elts=[ 772 Name(id='a', ctx=Store()), 773 Name(id='b', ctx=Store())], 774 ctx=Store())], 775 value=Name(id='c', ctx=Load()))], 776 type_ignores=[]) 777 778 779.. class:: AnnAssign(target, annotation, value, simple) 780 781 An assignment with a type annotation. ``target`` is a single node and can 782 be a :class:`Name`, a :class:`Attribute` or a :class:`Subscript`. 783 ``annotation`` is the annotation, such as a :class:`Constant` or :class:`Name` 784 node. ``value`` is a single optional node. ``simple`` is a boolean integer 785 set to True for a :class:`Name` node in ``target`` that do not appear in 786 between parenthesis and are hence pure names and not expressions. 787 788 .. doctest:: 789 790 >>> print(ast.dump(ast.parse('c: int'), indent=4)) 791 Module( 792 body=[ 793 AnnAssign( 794 target=Name(id='c', ctx=Store()), 795 annotation=Name(id='int', ctx=Load()), 796 simple=1)], 797 type_ignores=[]) 798 799 >>> print(ast.dump(ast.parse('(a): int = 1'), indent=4)) # Annotation with parenthesis 800 Module( 801 body=[ 802 AnnAssign( 803 target=Name(id='a', ctx=Store()), 804 annotation=Name(id='int', ctx=Load()), 805 value=Constant(value=1), 806 simple=0)], 807 type_ignores=[]) 808 809 >>> print(ast.dump(ast.parse('a.b: int'), indent=4)) # Attribute annotation 810 Module( 811 body=[ 812 AnnAssign( 813 target=Attribute( 814 value=Name(id='a', ctx=Load()), 815 attr='b', 816 ctx=Store()), 817 annotation=Name(id='int', ctx=Load()), 818 simple=0)], 819 type_ignores=[]) 820 821 >>> print(ast.dump(ast.parse('a[1]: int'), indent=4)) # Subscript annotation 822 Module( 823 body=[ 824 AnnAssign( 825 target=Subscript( 826 value=Name(id='a', ctx=Load()), 827 slice=Constant(value=1), 828 ctx=Store()), 829 annotation=Name(id='int', ctx=Load()), 830 simple=0)], 831 type_ignores=[]) 832 833 834.. class:: AugAssign(target, op, value) 835 836 Augmented assignment, such as ``a += 1``. In the following example, 837 ``target`` is a :class:`Name` node for ``x`` (with the :class:`Store` 838 context), ``op`` is :class:`Add`, and ``value`` is a :class:`Constant` with 839 value for 1. 840 841 The ``target`` attribute connot be of class :class:`Tuple` or :class:`List`, 842 unlike the targets of :class:`Assign`. 843 844 .. doctest:: 845 846 >>> print(ast.dump(ast.parse('x += 2'), indent=4)) 847 Module( 848 body=[ 849 AugAssign( 850 target=Name(id='x', ctx=Store()), 851 op=Add(), 852 value=Constant(value=2))], 853 type_ignores=[]) 854 855 856.. class:: Raise(exc, cause) 857 858 A ``raise`` statement. ``exc`` is the exception object to be raised, normally a 859 :class:`Call` or :class:`Name`, or ``None`` for a standalone ``raise``. 860 ``cause`` is the optional part for ``y`` in ``raise x from y``. 861 862 .. doctest:: 863 864 >>> print(ast.dump(ast.parse('raise x from y'), indent=4)) 865 Module( 866 body=[ 867 Raise( 868 exc=Name(id='x', ctx=Load()), 869 cause=Name(id='y', ctx=Load()))], 870 type_ignores=[]) 871 872 873.. class:: Assert(test, msg) 874 875 An assertion. ``test`` holds the condition, such as a :class:`Compare` node. 876 ``msg`` holds the failure message. 877 878 .. doctest:: 879 880 >>> print(ast.dump(ast.parse('assert x,y'), indent=4)) 881 Module( 882 body=[ 883 Assert( 884 test=Name(id='x', ctx=Load()), 885 msg=Name(id='y', ctx=Load()))], 886 type_ignores=[]) 887 888 889.. class:: Delete(targets) 890 891 Represents a ``del`` statement. ``targets`` is a list of nodes, such as 892 :class:`Name`, :class:`Attribute` or :class:`Subscript` nodes. 893 894 .. doctest:: 895 896 >>> print(ast.dump(ast.parse('del x,y,z'), indent=4)) 897 Module( 898 body=[ 899 Delete( 900 targets=[ 901 Name(id='x', ctx=Del()), 902 Name(id='y', ctx=Del()), 903 Name(id='z', ctx=Del())])], 904 type_ignores=[]) 905 906 907.. class:: Pass() 908 909 A ``pass`` statement. 910 911 .. doctest:: 912 913 >>> print(ast.dump(ast.parse('pass'), indent=4)) 914 Module( 915 body=[ 916 Pass()], 917 type_ignores=[]) 918 919 920Other statements which are only applicable inside functions or loops are 921described in other sections. 922 923Imports 924~~~~~~~ 925 926.. class:: Import(names) 927 928 An import statement. ``names`` is a list of :class:`alias` nodes. 929 930 .. doctest:: 931 932 >>> print(ast.dump(ast.parse('import x,y,z'), indent=4)) 933 Module( 934 body=[ 935 Import( 936 names=[ 937 alias(name='x'), 938 alias(name='y'), 939 alias(name='z')])], 940 type_ignores=[]) 941 942 943.. class:: ImportFrom(module, names, level) 944 945 Represents ``from x import y``. ``module`` is a raw string of the 'from' name, 946 without any leading dots, or ``None`` for statements such as ``from . import foo``. 947 ``level`` is an integer holding the level of the relative import (0 means 948 absolute import). 949 950 .. doctest:: 951 952 >>> print(ast.dump(ast.parse('from y import x,y,z'), indent=4)) 953 Module( 954 body=[ 955 ImportFrom( 956 module='y', 957 names=[ 958 alias(name='x'), 959 alias(name='y'), 960 alias(name='z')], 961 level=0)], 962 type_ignores=[]) 963 964 965.. class:: alias(name, asname) 966 967 Both parameters are raw strings of the names. ``asname`` can be ``None`` if 968 the regular name is to be used. 969 970 .. doctest:: 971 972 >>> print(ast.dump(ast.parse('from ..foo.bar import a as b, c'), indent=4)) 973 Module( 974 body=[ 975 ImportFrom( 976 module='foo.bar', 977 names=[ 978 alias(name='a', asname='b'), 979 alias(name='c')], 980 level=2)], 981 type_ignores=[]) 982 983Control flow 984^^^^^^^^^^^^ 985 986.. note:: 987 Optional clauses such as ``else`` are stored as an empty list if they're 988 not present. 989 990.. class:: If(test, body, orelse) 991 992 An ``if`` statement. ``test`` holds a single node, such as a :class:`Compare` 993 node. ``body`` and ``orelse`` each hold a list of nodes. 994 995 ``elif`` clauses don't have a special representation in the AST, but rather 996 appear as extra :class:`If` nodes within the ``orelse`` section of the 997 previous one. 998 999 .. doctest:: 1000 1001 >>> print(ast.dump(ast.parse(""" 1002 ... if x: 1003 ... ... 1004 ... elif y: 1005 ... ... 1006 ... else: 1007 ... ... 1008 ... """), indent=4)) 1009 Module( 1010 body=[ 1011 If( 1012 test=Name(id='x', ctx=Load()), 1013 body=[ 1014 Expr( 1015 value=Constant(value=Ellipsis))], 1016 orelse=[ 1017 If( 1018 test=Name(id='y', ctx=Load()), 1019 body=[ 1020 Expr( 1021 value=Constant(value=Ellipsis))], 1022 orelse=[ 1023 Expr( 1024 value=Constant(value=Ellipsis))])])], 1025 type_ignores=[]) 1026 1027 1028.. class:: For(target, iter, body, orelse, type_comment) 1029 1030 A ``for`` loop. ``target`` holds the variable(s) the loop assigns to, as a 1031 single :class:`Name`, :class:`Tuple` or :class:`List` node. ``iter`` holds 1032 the item to be looped over, again as a single node. ``body`` and ``orelse`` 1033 contain lists of nodes to execute. Those in ``orelse`` are executed if the 1034 loop finishes normally, rather than via a ``break`` statement. 1035 1036 .. attribute:: type_comment 1037 1038 ``type_comment`` is an optional string with the type annotation as a comment. 1039 1040 .. doctest:: 1041 1042 >>> print(ast.dump(ast.parse(""" 1043 ... for x in y: 1044 ... ... 1045 ... else: 1046 ... ... 1047 ... """), indent=4)) 1048 Module( 1049 body=[ 1050 For( 1051 target=Name(id='x', ctx=Store()), 1052 iter=Name(id='y', ctx=Load()), 1053 body=[ 1054 Expr( 1055 value=Constant(value=Ellipsis))], 1056 orelse=[ 1057 Expr( 1058 value=Constant(value=Ellipsis))])], 1059 type_ignores=[]) 1060 1061 1062.. class:: While(test, body, orelse) 1063 1064 A ``while`` loop. ``test`` holds the condition, such as a :class:`Compare` 1065 node. 1066 1067 .. doctest:: 1068 1069 >> print(ast.dump(ast.parse(""" 1070 ... while x: 1071 ... ... 1072 ... else: 1073 ... ... 1074 ... """), indent=4)) 1075 Module( 1076 body=[ 1077 While( 1078 test=Name(id='x', ctx=Load()), 1079 body=[ 1080 Expr( 1081 value=Constant(value=Ellipsis))], 1082 orelse=[ 1083 Expr( 1084 value=Constant(value=Ellipsis))])], 1085 type_ignores=[]) 1086 1087 1088.. class:: Break 1089 Continue 1090 1091 The ``break`` and ``continue`` statements. 1092 1093 .. doctest:: 1094 1095 >>> print(ast.dump(ast.parse("""\ 1096 ... for a in b: 1097 ... if a > 5: 1098 ... break 1099 ... else: 1100 ... continue 1101 ... 1102 ... """), indent=4)) 1103 Module( 1104 body=[ 1105 For( 1106 target=Name(id='a', ctx=Store()), 1107 iter=Name(id='b', ctx=Load()), 1108 body=[ 1109 If( 1110 test=Compare( 1111 left=Name(id='a', ctx=Load()), 1112 ops=[ 1113 Gt()], 1114 comparators=[ 1115 Constant(value=5)]), 1116 body=[ 1117 Break()], 1118 orelse=[ 1119 Continue()])], 1120 orelse=[])], 1121 type_ignores=[]) 1122 1123 1124.. class:: Try(body, handlers, orelse, finalbody) 1125 1126 ``try`` blocks. All attributes are list of nodes to execute, except for 1127 ``handlers``, which is a list of :class:`ExceptHandler` nodes. 1128 1129 .. doctest:: 1130 1131 >>> print(ast.dump(ast.parse(""" 1132 ... try: 1133 ... ... 1134 ... except Exception: 1135 ... ... 1136 ... except OtherException as e: 1137 ... ... 1138 ... else: 1139 ... ... 1140 ... finally: 1141 ... ... 1142 ... """), indent=4)) 1143 Module( 1144 body=[ 1145 Try( 1146 body=[ 1147 Expr( 1148 value=Constant(value=Ellipsis))], 1149 handlers=[ 1150 ExceptHandler( 1151 type=Name(id='Exception', ctx=Load()), 1152 body=[ 1153 Expr( 1154 value=Constant(value=Ellipsis))]), 1155 ExceptHandler( 1156 type=Name(id='OtherException', ctx=Load()), 1157 name='e', 1158 body=[ 1159 Expr( 1160 value=Constant(value=Ellipsis))])], 1161 orelse=[ 1162 Expr( 1163 value=Constant(value=Ellipsis))], 1164 finalbody=[ 1165 Expr( 1166 value=Constant(value=Ellipsis))])], 1167 type_ignores=[]) 1168 1169 1170.. class:: ExceptHandler(type, name, body) 1171 1172 A single ``except`` clause. ``type`` is the exception type it will match, 1173 typically a :class:`Name` node (or ``None`` for a catch-all ``except:`` clause). 1174 ``name`` is a raw string for the name to hold the exception, or ``None`` if 1175 the clause doesn't have ``as foo``. ``body`` is a list of nodes. 1176 1177 .. doctest:: 1178 1179 >>> print(ast.dump(ast.parse("""\ 1180 ... try: 1181 ... a + 1 1182 ... except TypeError: 1183 ... pass 1184 ... """), indent=4)) 1185 Module( 1186 body=[ 1187 Try( 1188 body=[ 1189 Expr( 1190 value=BinOp( 1191 left=Name(id='a', ctx=Load()), 1192 op=Add(), 1193 right=Constant(value=1)))], 1194 handlers=[ 1195 ExceptHandler( 1196 type=Name(id='TypeError', ctx=Load()), 1197 body=[ 1198 Pass()])], 1199 orelse=[], 1200 finalbody=[])], 1201 type_ignores=[]) 1202 1203 1204.. class:: With(items, body, type_comment) 1205 1206 A ``with`` block. ``items`` is a list of :class:`withitem` nodes representing 1207 the context managers, and ``body`` is the indented block inside the context. 1208 1209 .. attribute:: type_comment 1210 1211 ``type_comment`` is an optional string with the type annotation as a comment. 1212 1213 1214.. class:: withitem(context_expr, optional_vars) 1215 1216 A single context manager in a ``with`` block. ``context_expr`` is the context 1217 manager, often a :class:`Call` node. ``optional_vars`` is a :class:`Name`, 1218 :class:`Tuple` or :class:`List` for the ``as foo`` part, or ``None`` if that 1219 isn't used. 1220 1221 .. doctest:: 1222 1223 >>> print(ast.dump(ast.parse("""\ 1224 ... with a as b, c as d: 1225 ... something(b, d) 1226 ... """), indent=4)) 1227 Module( 1228 body=[ 1229 With( 1230 items=[ 1231 withitem( 1232 context_expr=Name(id='a', ctx=Load()), 1233 optional_vars=Name(id='b', ctx=Store())), 1234 withitem( 1235 context_expr=Name(id='c', ctx=Load()), 1236 optional_vars=Name(id='d', ctx=Store()))], 1237 body=[ 1238 Expr( 1239 value=Call( 1240 func=Name(id='something', ctx=Load()), 1241 args=[ 1242 Name(id='b', ctx=Load()), 1243 Name(id='d', ctx=Load())], 1244 keywords=[]))])], 1245 type_ignores=[]) 1246 1247 1248Function and class definitions 1249^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1250 1251.. class:: FunctionDef(name, args, body, decorator_list, returns, type_comment) 1252 1253 A function definition. 1254 1255 * ``name`` is a raw string of the function name. 1256 * ``args`` is an :class:`arguments` node. 1257 * ``body`` is the list of nodes inside the function. 1258 * ``decorator_list`` is the list of decorators to be applied, stored outermost 1259 first (i.e. the first in the list will be applied last). 1260 * ``returns`` is the return annotation. 1261 1262 .. attribute:: type_comment 1263 1264 ``type_comment`` is an optional string with the type annotation as a comment. 1265 1266 1267.. class:: Lambda(args, body) 1268 1269 ``lambda`` is a minimal function definition that can be used inside an 1270 expression. Unlike :class:`FunctionDef`, ``body`` holds a single node. 1271 1272 .. doctest:: 1273 1274 >>> print(ast.dump(ast.parse('lambda x,y: ...'), indent=4)) 1275 Module( 1276 body=[ 1277 Expr( 1278 value=Lambda( 1279 args=arguments( 1280 posonlyargs=[], 1281 args=[ 1282 arg(arg='x'), 1283 arg(arg='y')], 1284 kwonlyargs=[], 1285 kw_defaults=[], 1286 defaults=[]), 1287 body=Constant(value=Ellipsis)))], 1288 type_ignores=[]) 1289 1290 1291.. class:: arguments(posonlyargs, args, vararg, kwonlyargs, kw_defaults, kwarg, defaults) 1292 1293 The arguments for a function. 1294 1295 * ``posonlyargs``, ``args`` and ``kwonlyargs`` are lists of :class:`arg` nodes. 1296 * ``vararg`` and ``kwarg`` are single :class:`arg` nodes, referring to the 1297 ``*args, **kwargs`` parameters. 1298 * ``kw_defaults`` is a list of default values for keyword-only arguments. If 1299 one is ``None``, the corresponding argument is required. 1300 * ``defaults`` is a list of default values for arguments that can be passed 1301 positionally. If there are fewer defaults, they correspond to the last n 1302 arguments. 1303 1304 1305.. class:: arg(arg, annotation, type_comment) 1306 1307 A single argument in a list. ``arg`` is a raw string of the argument 1308 name, ``annotation`` is its annotation, such as a :class:`Str` or 1309 :class:`Name` node. 1310 1311 .. attribute:: type_comment 1312 1313 ``type_comment`` is an optional string with the type annotation as a comment 1314 1315 .. doctest:: 1316 1317 >>> print(ast.dump(ast.parse("""\ 1318 ... @decorator1 1319 ... @decorator2 1320 ... def f(a: 'annotation', b=1, c=2, *d, e, f=3, **g) -> 'return annotation': 1321 ... pass 1322 ... """), indent=4)) 1323 Module( 1324 body=[ 1325 FunctionDef( 1326 name='f', 1327 args=arguments( 1328 posonlyargs=[], 1329 args=[ 1330 arg( 1331 arg='a', 1332 annotation=Constant(value='annotation')), 1333 arg(arg='b'), 1334 arg(arg='c')], 1335 vararg=arg(arg='d'), 1336 kwonlyargs=[ 1337 arg(arg='e'), 1338 arg(arg='f')], 1339 kw_defaults=[ 1340 None, 1341 Constant(value=3)], 1342 kwarg=arg(arg='g'), 1343 defaults=[ 1344 Constant(value=1), 1345 Constant(value=2)]), 1346 body=[ 1347 Pass()], 1348 decorator_list=[ 1349 Name(id='decorator1', ctx=Load()), 1350 Name(id='decorator2', ctx=Load())], 1351 returns=Constant(value='return annotation'))], 1352 type_ignores=[]) 1353 1354 1355.. class:: Return(value) 1356 1357 A ``return`` statement. 1358 1359 .. doctest:: 1360 1361 >>> print(ast.dump(ast.parse('return 4'), indent=4)) 1362 Module( 1363 body=[ 1364 Return( 1365 value=Constant(value=4))], 1366 type_ignores=[]) 1367 1368 1369.. class:: Yield(value) 1370 YieldFrom(value) 1371 1372 A ``yield`` or ``yield from`` expression. Because these are expressions, they 1373 must be wrapped in a :class:`Expr` node if the value sent back is not used. 1374 1375 .. doctest:: 1376 1377 >>> print(ast.dump(ast.parse('yield x'), indent=4)) 1378 Module( 1379 body=[ 1380 Expr( 1381 value=Yield( 1382 value=Name(id='x', ctx=Load())))], 1383 type_ignores=[]) 1384 1385 >>> print(ast.dump(ast.parse('yield from x'), indent=4)) 1386 Module( 1387 body=[ 1388 Expr( 1389 value=YieldFrom( 1390 value=Name(id='x', ctx=Load())))], 1391 type_ignores=[]) 1392 1393 1394.. class:: Global(names) 1395 Nonlocal(names) 1396 1397 ``global`` and ``nonlocal`` statements. ``names`` is a list of raw strings. 1398 1399 .. doctest:: 1400 1401 >>> print(ast.dump(ast.parse('global x,y,z'), indent=4)) 1402 Module( 1403 body=[ 1404 Global( 1405 names=[ 1406 'x', 1407 'y', 1408 'z'])], 1409 type_ignores=[]) 1410 1411 >>> print(ast.dump(ast.parse('nonlocal x,y,z'), indent=4)) 1412 Module( 1413 body=[ 1414 Nonlocal( 1415 names=[ 1416 'x', 1417 'y', 1418 'z'])], 1419 type_ignores=[]) 1420 1421 1422.. class:: ClassDef(name, bases, keywords, starargs, kwargs, body, decorator_list) 1423 1424 A class definition. 1425 1426 * ``name`` is a raw string for the class name 1427 * ``bases`` is a list of nodes for explicitly specified base classes. 1428 * ``keywords`` is a list of :class:`keyword` nodes, principally for 'metaclass'. 1429 Other keywords will be passed to the metaclass, as per `PEP-3115 1430 <https://www.python.org/dev/peps/pep-3115/>`_. 1431 * ``starargs`` and ``kwargs`` are each a single node, as in a function call. 1432 starargs will be expanded to join the list of base classes, and kwargs will 1433 be passed to the metaclass. 1434 * ``body`` is a list of nodes representing the code within the class 1435 definition. 1436 * ``decorator_list`` is a list of nodes, as in :class:`FunctionDef`. 1437 1438 .. doctest:: 1439 1440 >>> print(ast.dump(ast.parse("""\ 1441 ... @decorator1 1442 ... @decorator2 1443 ... class Foo(base1, base2, metaclass=meta): 1444 ... pass 1445 ... """), indent=4)) 1446 Module( 1447 body=[ 1448 ClassDef( 1449 name='Foo', 1450 bases=[ 1451 Name(id='base1', ctx=Load()), 1452 Name(id='base2', ctx=Load())], 1453 keywords=[ 1454 keyword( 1455 arg='metaclass', 1456 value=Name(id='meta', ctx=Load()))], 1457 body=[ 1458 Pass()], 1459 decorator_list=[ 1460 Name(id='decorator1', ctx=Load()), 1461 Name(id='decorator2', ctx=Load())])], 1462 type_ignores=[]) 1463 1464Async and await 1465^^^^^^^^^^^^^^^ 1466 1467.. class:: AsyncFunctionDef(name, args, body, decorator_list, returns, type_comment) 1468 1469 An ``async def`` function definition. Has the same fields as 1470 :class:`FunctionDef`. 1471 1472 1473.. class:: Await(value) 1474 1475 An ``await`` expression. ``value`` is what it waits for. 1476 Only valid in the body of an :class:`AsyncFunctionDef`. 1477 1478.. doctest:: 1479 1480 >>> print(ast.dump(ast.parse("""\ 1481 ... async def f(): 1482 ... await other_func() 1483 ... """), indent=4)) 1484 Module( 1485 body=[ 1486 AsyncFunctionDef( 1487 name='f', 1488 args=arguments( 1489 posonlyargs=[], 1490 args=[], 1491 kwonlyargs=[], 1492 kw_defaults=[], 1493 defaults=[]), 1494 body=[ 1495 Expr( 1496 value=Await( 1497 value=Call( 1498 func=Name(id='other_func', ctx=Load()), 1499 args=[], 1500 keywords=[])))], 1501 decorator_list=[])], 1502 type_ignores=[]) 1503 1504 1505.. class:: AsyncFor(target, iter, body, orelse, type_comment) 1506 AsyncWith(items, body, type_comment) 1507 1508 ``async for`` loops and ``async with`` context managers. They have the same 1509 fields as :class:`For` and :class:`With`, respectively. Only valid in the 1510 body of an :class:`AsyncFunctionDef`. 1511 1512.. note:: 1513 When a string is parsed by :func:`ast.parse`, operator nodes (subclasses 1514 of :class:`ast.operator`, :class:`ast.unaryop`, :class:`ast.cmpop`, 1515 :class:`ast.boolop` and :class:`ast.expr_context`) on the returned tree 1516 will be singletons. Changes to one will be reflected in all other 1517 occurrences of the same value (e.g. :class:`ast.Add`). 1518 1519 1520:mod:`ast` Helpers 1521------------------ 1522 1523Apart from the node classes, the :mod:`ast` module defines these utility functions 1524and classes for traversing abstract syntax trees: 1525 1526.. function:: parse(source, filename='<unknown>', mode='exec', *, type_comments=False, feature_version=None) 1527 1528 Parse the source into an AST node. Equivalent to ``compile(source, 1529 filename, mode, ast.PyCF_ONLY_AST)``. 1530 1531 If ``type_comments=True`` is given, the parser is modified to check 1532 and return type comments as specified by :pep:`484` and :pep:`526`. 1533 This is equivalent to adding :data:`ast.PyCF_TYPE_COMMENTS` to the 1534 flags passed to :func:`compile()`. This will report syntax errors 1535 for misplaced type comments. Without this flag, type comments will 1536 be ignored, and the ``type_comment`` field on selected AST nodes 1537 will always be ``None``. In addition, the locations of ``# type: 1538 ignore`` comments will be returned as the ``type_ignores`` 1539 attribute of :class:`Module` (otherwise it is always an empty list). 1540 1541 In addition, if ``mode`` is ``'func_type'``, the input syntax is 1542 modified to correspond to :pep:`484` "signature type comments", 1543 e.g. ``(str, int) -> List[str]``. 1544 1545 Also, setting ``feature_version`` to a tuple ``(major, minor)`` 1546 will attempt to parse using that Python version's grammar. 1547 Currently ``major`` must equal to ``3``. For example, setting 1548 ``feature_version=(3, 4)`` will allow the use of ``async`` and 1549 ``await`` as variable names. The lowest supported version is 1550 ``(3, 4)``; the highest is ``sys.version_info[0:2]``. 1551 1552 If source contains a null character ('\0'), :exc:`ValueError` is raised. 1553 1554 .. warning:: 1555 Note that successfully parsing source code into an AST object doesn't 1556 guarantee that the source code provided is valid Python code that can 1557 be executed as the compilation step can raise further :exc:`SyntaxError` 1558 exceptions. For instance, the source ``return 42`` generates a valid 1559 AST node for a return statement, but it cannot be compiled alone (it needs 1560 to be inside a function node). 1561 1562 In particular, :func:`ast.parse` won't do any scoping checks, which the 1563 compilation step does. 1564 1565 .. warning:: 1566 It is possible to crash the Python interpreter with a 1567 sufficiently large/complex string due to stack depth limitations 1568 in Python's AST compiler. 1569 1570 .. versionchanged:: 3.8 1571 Added ``type_comments``, ``mode='func_type'`` and ``feature_version``. 1572 1573 1574.. function:: unparse(ast_obj) 1575 1576 Unparse an :class:`ast.AST` object and generate a string with code 1577 that would produce an equivalent :class:`ast.AST` object if parsed 1578 back with :func:`ast.parse`. 1579 1580 .. warning:: 1581 The produced code string will not necessarily be equal to the original 1582 code that generated the :class:`ast.AST` object (without any compiler 1583 optimizations, such as constant tuples/frozensets). 1584 1585 .. warning:: 1586 Trying to unparse a highly complex expression would result with 1587 :exc:`RecursionError`. 1588 1589 .. versionadded:: 3.9 1590 1591 1592.. function:: literal_eval(node_or_string) 1593 1594 Safely evaluate an expression node or a string containing a Python literal or 1595 container display. The string or node provided may only consist of the 1596 following Python literal structures: strings, bytes, numbers, tuples, lists, 1597 dicts, sets, booleans, and ``None``. 1598 1599 This can be used for safely evaluating strings containing Python values from 1600 untrusted sources without the need to parse the values oneself. It is not 1601 capable of evaluating arbitrarily complex expressions, for example involving 1602 operators or indexing. 1603 1604 .. warning:: 1605 It is possible to crash the Python interpreter with a 1606 sufficiently large/complex string due to stack depth limitations 1607 in Python's AST compiler. 1608 1609 .. versionchanged:: 3.2 1610 Now allows bytes and set literals. 1611 1612 .. versionchanged:: 3.9 1613 Now supports creating empty sets with ``'set()'``. 1614 1615 1616.. function:: get_docstring(node, clean=True) 1617 1618 Return the docstring of the given *node* (which must be a 1619 :class:`FunctionDef`, :class:`AsyncFunctionDef`, :class:`ClassDef`, 1620 or :class:`Module` node), or ``None`` if it has no docstring. 1621 If *clean* is true, clean up the docstring's indentation with 1622 :func:`inspect.cleandoc`. 1623 1624 .. versionchanged:: 3.5 1625 :class:`AsyncFunctionDef` is now supported. 1626 1627 1628.. function:: get_source_segment(source, node, *, padded=False) 1629 1630 Get source code segment of the *source* that generated *node*. 1631 If some location information (:attr:`lineno`, :attr:`end_lineno`, 1632 :attr:`col_offset`, or :attr:`end_col_offset`) is missing, return ``None``. 1633 1634 If *padded* is ``True``, the first line of a multi-line statement will 1635 be padded with spaces to match its original position. 1636 1637 .. versionadded:: 3.8 1638 1639 1640.. function:: fix_missing_locations(node) 1641 1642 When you compile a node tree with :func:`compile`, the compiler expects 1643 :attr:`lineno` and :attr:`col_offset` attributes for every node that supports 1644 them. This is rather tedious to fill in for generated nodes, so this helper 1645 adds these attributes recursively where not already set, by setting them to 1646 the values of the parent node. It works recursively starting at *node*. 1647 1648 1649.. function:: increment_lineno(node, n=1) 1650 1651 Increment the line number and end line number of each node in the tree 1652 starting at *node* by *n*. This is useful to "move code" to a different 1653 location in a file. 1654 1655 1656.. function:: copy_location(new_node, old_node) 1657 1658 Copy source location (:attr:`lineno`, :attr:`col_offset`, :attr:`end_lineno`, 1659 and :attr:`end_col_offset`) from *old_node* to *new_node* if possible, 1660 and return *new_node*. 1661 1662 1663.. function:: iter_fields(node) 1664 1665 Yield a tuple of ``(fieldname, value)`` for each field in ``node._fields`` 1666 that is present on *node*. 1667 1668 1669.. function:: iter_child_nodes(node) 1670 1671 Yield all direct child nodes of *node*, that is, all fields that are nodes 1672 and all items of fields that are lists of nodes. 1673 1674 1675.. function:: walk(node) 1676 1677 Recursively yield all descendant nodes in the tree starting at *node* 1678 (including *node* itself), in no specified order. This is useful if you only 1679 want to modify nodes in place and don't care about the context. 1680 1681 1682.. class:: NodeVisitor() 1683 1684 A node visitor base class that walks the abstract syntax tree and calls a 1685 visitor function for every node found. This function may return a value 1686 which is forwarded by the :meth:`visit` method. 1687 1688 This class is meant to be subclassed, with the subclass adding visitor 1689 methods. 1690 1691 .. method:: visit(node) 1692 1693 Visit a node. The default implementation calls the method called 1694 :samp:`self.visit_{classname}` where *classname* is the name of the node 1695 class, or :meth:`generic_visit` if that method doesn't exist. 1696 1697 .. method:: generic_visit(node) 1698 1699 This visitor calls :meth:`visit` on all children of the node. 1700 1701 Note that child nodes of nodes that have a custom visitor method won't be 1702 visited unless the visitor calls :meth:`generic_visit` or visits them 1703 itself. 1704 1705 Don't use the :class:`NodeVisitor` if you want to apply changes to nodes 1706 during traversal. For this a special visitor exists 1707 (:class:`NodeTransformer`) that allows modifications. 1708 1709 .. deprecated:: 3.8 1710 1711 Methods :meth:`visit_Num`, :meth:`visit_Str`, :meth:`visit_Bytes`, 1712 :meth:`visit_NameConstant` and :meth:`visit_Ellipsis` are deprecated 1713 now and will not be called in future Python versions. Add the 1714 :meth:`visit_Constant` method to handle all constant nodes. 1715 1716 1717.. class:: NodeTransformer() 1718 1719 A :class:`NodeVisitor` subclass that walks the abstract syntax tree and 1720 allows modification of nodes. 1721 1722 The :class:`NodeTransformer` will walk the AST and use the return value of 1723 the visitor methods to replace or remove the old node. If the return value 1724 of the visitor method is ``None``, the node will be removed from its 1725 location, otherwise it is replaced with the return value. The return value 1726 may be the original node in which case no replacement takes place. 1727 1728 Here is an example transformer that rewrites all occurrences of name lookups 1729 (``foo``) to ``data['foo']``:: 1730 1731 class RewriteName(NodeTransformer): 1732 1733 def visit_Name(self, node): 1734 return Subscript( 1735 value=Name(id='data', ctx=Load()), 1736 slice=Constant(value=node.id), 1737 ctx=node.ctx 1738 ) 1739 1740 Keep in mind that if the node you're operating on has child nodes you must 1741 either transform the child nodes yourself or call the :meth:`generic_visit` 1742 method for the node first. 1743 1744 For nodes that were part of a collection of statements (that applies to all 1745 statement nodes), the visitor may also return a list of nodes rather than 1746 just a single node. 1747 1748 If :class:`NodeTransformer` introduces new nodes (that weren't part of 1749 original tree) without giving them location information (such as 1750 :attr:`lineno`), :func:`fix_missing_locations` should be called with 1751 the new sub-tree to recalculate the location information:: 1752 1753 tree = ast.parse('foo', mode='eval') 1754 new_tree = fix_missing_locations(RewriteName().visit(tree)) 1755 1756 Usually you use the transformer like this:: 1757 1758 node = YourTransformer().visit(node) 1759 1760 1761.. function:: dump(node, annotate_fields=True, include_attributes=False, *, indent=None) 1762 1763 Return a formatted dump of the tree in *node*. This is mainly useful for 1764 debugging purposes. If *annotate_fields* is true (by default), 1765 the returned string will show the names and the values for fields. 1766 If *annotate_fields* is false, the result string will be more compact by 1767 omitting unambiguous field names. Attributes such as line 1768 numbers and column offsets are not dumped by default. If this is wanted, 1769 *include_attributes* can be set to true. 1770 1771 If *indent* is a non-negative integer or string, then the tree will be 1772 pretty-printed with that indent level. An indent level 1773 of 0, negative, or ``""`` will only insert newlines. ``None`` (the default) 1774 selects the single line representation. Using a positive integer indent 1775 indents that many spaces per level. If *indent* is a string (such as ``"\t"``), 1776 that string is used to indent each level. 1777 1778 .. versionchanged:: 3.9 1779 Added the *indent* option. 1780 1781 1782.. _ast-compiler-flags: 1783 1784Compiler Flags 1785-------------- 1786 1787The following flags may be passed to :func:`compile` in order to change 1788effects on the compilation of a program: 1789 1790.. data:: PyCF_ALLOW_TOP_LEVEL_AWAIT 1791 1792 Enables support for top-level ``await``, ``async for``, ``async with`` 1793 and async comprehensions. 1794 1795 .. versionadded:: 3.8 1796 1797.. data:: PyCF_ONLY_AST 1798 1799 Generates and returns an abstract syntax tree instead of returning a 1800 compiled code object. 1801 1802.. data:: PyCF_TYPE_COMMENTS 1803 1804 Enables support for :pep:`484` and :pep:`526` style type comments 1805 (``# type: <type>``, ``# type: ignore <stuff>``). 1806 1807 .. versionadded:: 3.8 1808 1809 1810.. _ast-cli: 1811 1812Command-Line Usage 1813------------------ 1814 1815.. versionadded:: 3.9 1816 1817The :mod:`ast` module can be executed as a script from the command line. 1818It is as simple as: 1819 1820.. code-block:: sh 1821 1822 python -m ast [-m <mode>] [-a] [infile] 1823 1824The following options are accepted: 1825 1826.. program:: ast 1827 1828.. cmdoption:: -h, --help 1829 1830 Show the help message and exit. 1831 1832.. cmdoption:: -m <mode> 1833 --mode <mode> 1834 1835 Specify what kind of code must be compiled, like the *mode* argument 1836 in :func:`parse`. 1837 1838.. cmdoption:: --no-type-comments 1839 1840 Don't parse type comments. 1841 1842.. cmdoption:: -a, --include-attributes 1843 1844 Include attributes such as line numbers and column offsets. 1845 1846.. cmdoption:: -i <indent> 1847 --indent <indent> 1848 1849 Indentation of nodes in AST (number of spaces). 1850 1851If :file:`infile` is specified its contents are parsed to AST and dumped 1852to stdout. Otherwise, the content is read from stdin. 1853 1854 1855.. seealso:: 1856 1857 `Green Tree Snakes <https://greentreesnakes.readthedocs.io/>`_, an external 1858 documentation resource, has good details on working with Python ASTs. 1859 1860 `ASTTokens <https://asttokens.readthedocs.io/en/latest/user-guide.html>`_ 1861 annotates Python ASTs with the positions of tokens and text in the source 1862 code that generated them. This is helpful for tools that make source code 1863 transformations. 1864 1865 `leoAst.py <http://leoeditor.com/appendices.html#leoast-py>`_ unifies the 1866 token-based and parse-tree-based views of python programs by inserting 1867 two-way links between tokens and ast nodes. 1868 1869 `LibCST <https://libcst.readthedocs.io/>`_ parses code as a Concrete Syntax 1870 Tree that looks like an ast tree and keeps all formatting details. It's 1871 useful for building automated refactoring (codemod) applications and 1872 linters. 1873 1874 `Parso <https://parso.readthedocs.io>`_ is a Python parser that supports 1875 error recovery and round-trip parsing for different Python versions (in 1876 multiple Python versions). Parso is also able to list multiple syntax errors 1877 in your python file.