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.