First cut at more detailed section on __iter__()

Author: davepeck

peps/pep-0750.rst

@@ -284,10 +284,11 @@ It would be surprising if, for example, a template string that uses ``{value:.2f
 did not round the value to two decimal places when processed.
 
 
-Convenience Accessors in ``Template``
--------------------------------------
+The ``Template.values`` Property
+--------------------------------
 
-The ``Template.values`` property is equivalent to:
+The ``Template.values`` property is a shortcut for accessing the ``value`` 
+attribute of each ``Interpolation`` in the template and is equivalent to:
 
 .. code-block:: python
 
@@ -296,7 +297,14 @@ The ``Template.values`` property is equivalent to:
         return tuple(i.value for i in self.interpolations)
 
 
-The ``Template.__iter__()`` method is equivalent to:
+Iterating ``Template`` Contents
+-------------------------------
+
+The ``Template.__iter__()`` method provides a simple way to access the full
+contents of a template. It yields the string parts and interpolations in
+the order they appear, with empty strings omitted.
+
+The ``__iter__()`` method is equivalent to:
 
 .. code-block:: python
 
@@ -308,6 +316,46 @@ The ``Template.__iter__()`` method is equivalent to:
                 yield i
 
 
+The following examples show the ``__iter__()`` method in action:
+
+.. code-block:: python
+
+    assert list(t"") == []
+
+    assert list(t"Hello") == ["Hello"]
+
+    name = "World"
+    template = t"Hello {name}!"
+    contents = list(template)
+    assert len(contents) == 3
+    assert contents[0] == "Hello "
+    assert contents[1].value == "World"
+    assert contents[1].expression == "name"
+    assert contents[2] == "!"
+
+Empty strings, which may be present in ``Template.strings``, are not included
+in the output of the ``__iter__()`` method:
+
+.. code-block:: python
+
+    first = "Eat"
+    second = "Roquefort"
+    template = t"{first}{second}"
+    contents = list(template)
+    assert len(contents) == 2
+    assert contents[0].value == "Eat"
+    assert contents[0].expression == "first"
+    assert contents[1].value == "Roquefort"
+    assert contents[1].expression == "second"
+
+    # However, the strings attribute contains empty strings:
+    assert template.strings == ("", "", "")
+
+Template processing code can choose to work with any combination of  
+``strings``, ``interpolations``, ``values``, and ``__iter__()`` based on 
+requirements and convenience.
+
+
 Processing Template Strings
 ---------------------------