ast.diff

diff --git a/Doc/library/ast-nodes.rst b/Doc/library/ast-nodes.rst
new file mode 100644
--- /dev/null
+++ b/Doc/library/ast-nodes.rst
@@ -0,0 +1,321 @@
+.. currentmodule:: ast
+
+.. sectionauthor:: Thomas Kluyver <takowl@gmail.com>
+
+.. _ast-nodes:
+
+AST Nodes
+=========
+
+An AST represents each element in your code as an object. These are instances of
+the various subclasses of :class:`AST` described below. For instance, the code
+``a + 1`` is a :class:`BinOp`, with a :class:`Name` on the left, a :class:`Num`
+on the right, and an :class:`Add` operator.
+
+.. seealso::
+
+   AST manipulating examples at `greentreesnakes <https://bitbucket.org/takluyver/greentreesnakes/src/1b74e8139649f397e372c5395e983ab8466d0c0c/examples/?at=default>`_.
+
+
+.. _ast-nodes-literals:
+
+Literals
+--------
+
+.. class:: Num(n)
+
+   A number - integer, float, or complex. The ``n`` attribute stores the value,
+   already converted to the relevant type.
+
+.. class:: Str(s)
+
+   A string. The ``s`` attribute hold the value.
+
+.. class:: Bytes(s)
+
+   A :class:`bytes` object. The ``s`` attribute holds the value.
+
+.. class:: List(elts, ctx)
+           Tuple(elts, ctx)
+
+   A list or tuple. ``elts`` holds a list of nodes representing the elements.
+   ``ctx`` is :class:`Store` if the container is an assignment target (i.e.
+   ``(x,y)=pt``), and :class:`Load` otherwise.
+
+.. class:: Set(elts)
+
+   A set. ``elts`` holds a list of nodes representing the elements.
+
+.. class:: Dict(keys, values)
+
+   A dictionary. ``keys`` and ``values`` hold lists of nodes with matching order
+   (i.e. they could be paired with :func:`zip`).
+
+.. class:: Ellipsis()
+
+   Represents the ``...`` syntax for the ``Ellipsis`` singleton.
+
+.. class:: NameConstant(value)
+
+   :data:`True`, :data:`False` or :data:`None`. ``value`` holds one of those
+   constants.
+
+   .. versionadded:: 3.4
+      Previously, these constants were instances of :class:`Name`.
+
+
+.. _ast-nodes-variables:
+
+Variables
+---------
+
+.. class:: Name(id, ctx)
+
+   A variable name. ``id`` holds the name as a string, and ``ctx`` is one of
+   the following types.
+
+.. class:: Load()
+           Store()
+           Del()
+
+   Variable references can be used to load the value of a variable, to assign
+   a new value to it, or to delete it. Variable references are given a context
+   to distinguish these cases.
+
+   ::
+
+       # Loading a (equivalent to ``a``)
+       Module(body=[
+           Expr(value=Name(id='a', ctx=Load())),
+       ])
+
+       # Storing a (equivalent to ``a = 1``)
+       Module(body=[
+           Assign(targets=[
+               Name(id='a', ctx=Store()),
+           ], value=Num(n=1)),
+       ])
+
+       # Deleting a (equivalent to ``del a``)
+       Module(body=[
+           Delete(targets=[
+               Name(id='a', ctx=Del()),
+           ]),
+       ])
+
+.. class:: Starred(value, ctx)
+
+   A ``*var`` variable reference. ``value`` holds the variable, typically a
+   :class:`Name` node.
+
+   Note that this *isn't* needed to call or define a function with ``*args`` -
+   the :class:`Call` and :class:`FunctionDef` nodes have special fields for that.
+
+   ::
+
+       # a, *b = it
+       Module(body=[
+           Assign(targets=[
+               Tuple(elts=[
+                   Name(id='a', ctx=Store()),
+                   Starred(value=Name(id='b', ctx=Store()), ctx=Store()),
+               ],
+               ctx=Store()),
+           ],
+           value=Name(id='it', ctx=Load())),
+       ])
+
+
+.. _ast-nodes-expressions:
+
+Expressions
+-----------
+
+.. class:: Expr(value)
+
+   When an expression, such as a function call, appears as a statement by itself
+   (an :ref:`expression statement <python:exprstmts>`),
+   with its return value not used or stored, it is wrapped in this container.
+   ``value`` holds one of the other nodes in this section, or a literal, a
+   :class:`Name`, a :class:`Lambda`, or a :class:`Yield` or :class:`YieldFrom`
+   node.
+
+   ::
+
+       # -a
+       Module(body=[
+           Expr(value=UnaryOp(op=USub(), operand=Name(id='a', ctx=Load()))),
+       ])
+
+.. class:: UnaryOp(op, operand)
+
+   A unary operation. ``op`` is the operator, and ``operand`` any expression
+   node.
+
+.. class:: UAdd
+           USub
+           Not
+           Invert
+
+   Unary operator tokens. :class:`Not` is the ``not`` keyword, :class:`Invert`
+   is the ``~`` operator.
+
+.. class:: BinOp(left, op, right)
+
+   A binary operation (like addition or division). ``op`` is the operator, and
+   ``left`` and ``right`` are any expression nodes.
+
+.. class:: Add
+           Sub
+           Mult
+           Div
+           FloorDiv
+           Mod
+           Pow
+           LShift
+           RShift
+           BitOr
+           BitXor
+           BitAnd
+
+   Binary operator tokens.
+
+.. class:: BoolOp(op, values)
+
+   A boolean operation, 'or' or 'and'. ``op`` is :class:`Or` or
+   :class:`And`. ``values`` are the values involved. Consecutive operations
+   with the same operator, such as ``a or b or c``, are collapsed into one node
+   with several values.
+
+   This doesn't include ``not``, which is a :class:`UnaryOp`.
+
+.. class:: And
+           Or
+
+   Boolean operator tokens.
+
+.. class:: Compare(left, ops, comparators)
+
+   A comparison of two or more values. ``left`` is the first value in the
+   comparison, ``ops`` the list of operators, and ``comparators`` the list of
+   values after the first. If that sounds awkward, that's because it is::
+
+      # 1 < a < 10
+      Module(body=[
+        Expr(value=Compare(left=Num(n=1), ops=[
+            Lt(),
+            Lt(),
+          ], comparators=[
+            Name(id='a', ctx=Load()),
+            Num(n=10),
+          ])),
+        ])
+
+.. class:: Eq
+           NotEq
+           Lt
+           LtE
+           Gt
+           GtE
+           Is
+           IsNot
+           In
+           NotIn
+
+   Comparison operator tokens.
+
+.. class:: Call(func, args, keywords, starargs, kwargs)
+
+   A function call. ``func`` is the function, which will often be a
+   :class:`Name` or :class:`Attribute` object. Of the arguments:
+
+   * ``args`` holds a list of the arguments passed by position.
+   * ``keywords`` holds a list of :class:`keyword` objects representing
+     arguments passed by keyword.%
+   * ``starargs`` and ``kwargs`` each hold a single node, for arguments passed
+     as ``*args`` and ``**kwargs``.
+
+   When constructing a Call node, ``args`` and ``kwargs`` are required, but they
+   can be empty lists. ``starargs`` and ``kwargs`` are optional.
+
+   ::
+
+       # func(a, b=c, *d, **e)
+       Module(body=[
+           Expr(value=Call(func=Name(id='func', ctx=Load()),
+                           args=[Name(id='a', ctx=Load())],
+                           keywords=[keyword(arg='b', value=Name(id='c', ctx=Load()))],
+                           starargs=Name(id='d', ctx=Load()),
+                           kwargs=Name(id='e', ctx=Load()))),
+         ])
+
+.. class:: keyword(arg, value)
+
+   A keyword argument to a function call or class definition. ``arg`` is a raw
+   string of the parameter name, ``value`` is a node to pass in.
+
+.. class:: IfExp(test, body, orelse)
+
+   An expression such as ``a if b else c``. Each field holds a single node, so
+   in that example, all three are :class:`Name` nodes.
+
+.. class:: Attribute(value, attr, ctx)
+
+   Attribute access, e.g. ``d.keys``. ``value`` is a node, typically a
+   :class:`Name`. ``attr`` is a bare string giving the name of the attribute,
+   and ``ctx`` is :class:`Load`, :class:`Store` or :class:`Del` according to
+   how the attribute is acted on.
+
+   ::
+
+       # snake.colour
+       Module(body=[
+           Expr(value=Attribute(value=Name(id='snake', ctx=Load()), attr='colour', ctx=Load())),
+         ])
+
+
+.. _ast-nodes-subscripting:
+
+Subscripting
+~~~~~~~~~~~~
+
+.. class:: Subscript(value, slice, ctx)
+
+   A subscript, such as ``l[1]``. ``value`` is the object, often a
+   :class:`Name`. ``slice`` is one of :class:`Index`, :class:`Slice`
+   or :class:`ExtSlice`. ``ctx`` is :class:`Load`, :class:`Store` or :class:`Del`
+   according to what it does with the subscript.
+
+.. class:: Index(value)
+
+   Simple subscripting with a single value::
+
+       # l[1]
+       Module(body=[
+         Expr(value=Subscript(value=Name(id='l', ctx=Load()),
+                              slice=Index(value=Num(n=1)), ctx=Load())),
+       ])
+
+.. class:: Slice(lower, upper, step)
+
+   Regular slicing::
+
+       # l[1:2]
+       Module(body=[
+         Expr(value=Subscript(value=Name(id='l', ctx=Load()),
+                         slice=Slice(lower=Num(n=1), upper=Num(n=2), step=None),
+                         ctx=Load())),
+         ])
+
+.. class:: ExtSlice(dims)
+
+   Advanced slicing. ``dims`` holds a list of :class:`Slice` and
+   :class:`Index` nodes::
+
+       # l[1:2, 3]
+       Module(body=[
+           Expr(value=Subscript(value=Name(id='l', ctx=Load()), slice=ExtSlice(dims=[
+               Slice(lower=Num(n=1), upper=Num(n=2), step=None),
+               Index(value=Num(n=3)),
+             ]), ctx=Load())),
+         ])
diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -86,24 +86,23 @@ Node classes
       node.col_offset = 0
 
    or the more compact ::
 
       node = ast.UnaryOp(ast.USub(), ast.Num(5, lineno=0, col_offset=0),
                          lineno=0, col_offset=0)
 
 
-.. _abstract-grammar:
+AST nodes documentation
+~~~~~~~~~~~~~~~~~~~~~~~
 
-Abstract Grammar
-----------------
+.. toctree::
+   :maxdepth: 2
 
-The abstract grammar is currently defined as follows:
-
-.. literalinclude:: ../../Parser/Python.asdl
+   ast-nodes.rst
 
 
 :mod:`ast` Helpers
 ------------------
 
 Apart from the node classes, :mod:`ast` module defines these utility functions
 and classes for traversing abstract syntax trees:
 
@@ -242,8 +241,18 @@ and classes for traversing abstract synt
 .. function:: dump(node, annotate_fields=True, include_attributes=False)
 
    Return a formatted dump of the tree in *node*.  This is mainly useful for
    debugging purposes.  The returned string will show the names and the values
    for fields.  This makes the code impossible to evaluate, so if evaluation is
    wanted *annotate_fields* must be set to ``False``.  Attributes such as line
    numbers and column offsets are not dumped by default.  If this is wanted,
    *include_attributes* can be set to ``True``.
+
+
+.. _abstract-grammar:
+
+Abstract Grammar
+----------------
+
+The abstract grammar is currently defined as follows:
+
+.. literalinclude:: ../../Parser/Python.asdl

• L22: The name can be spelled as three words, capitalised: 'Green Tree Snakes'
• 239: Stray trailing %. I'll check if this is in the original.
• 243: I think it should say keywords, not kwargs. Will fix in the original.

Also, your diff has only added part of my 'Meet the nodes' page - everything from 'comprehensions' downwards is missing. I assume that's just because it's a WIP.