PEP 750: major updates to "Template Strings" based on community feedback

peps/pep-0750.rst

@@ -156,6 +156,9 @@ any interpolations in the literal:
 See `Interleaving of Template.args`_ below for more information on how the
 ``args`` attribute is structured.
 
+The ``Template`` type is immutable. ``Template.args`` cannot be reassigned
+or mutated.
+
 
 The ``Interpolation`` Type
 --------------------------
@@ -182,6 +185,10 @@ Like ``Template``, it is a new concrete type found in the ``types`` module:
         ):
             ...
 
+Like ``Template``, ``Interpolation`` is immutable. Its attributes cannot be
+reassigned. (The ``value`` attribute may of course itself be mutable, but 
+the ``Interpolation`` instance is not.)
+
 The ``value`` attribute is the evaluated result of the interpolation:
 
 .. code-block:: python
@@ -335,6 +342,45 @@ instances is maintained when concatenating. (See the
 `Interleaving of Template.args`_ section for more information.)
 
 
+Template and Interpolation Equality
+-----------------------------------
+
+Two instances of ``Template`` are defined to be equal if their ``args`` attributes
+contain the same strings and interpolations in the same order:
+
+.. code-block:: python
+
+    assert t"I love {stilton}" == t"I love {stilton}"
+    assert t"I love {stilton}" != t"I love {roquefort}"
+    assert t"I " + t"love {stilton}" == t"I love {stilton}"
+
+The implementation of ``Template.__eq__()`` is roughly as follows:
+
+.. code-block:: python
+
+    class Template:
+        def __eq__(self, other: object) -> bool:
+            if not isinstance(other, Template):
+                return NotImplemented
+            return self.args == other.args
+
+Two instances of ``Interpolation`` are defined to be equal if their ``value``,
+``expr``, ``conv``, and ``format_spec`` attributes are equal:
+
+.. code-block:: python
+
+    class Interpolation:
+        def __eq__(self, other: object) -> bool:
+            if not isinstance(other, Interpolation):
+                return NotImplemented
+            return (
+                self.value == other.value
+                and self.expr == other.expr
+                and self.conv == other.conv
+                and self.format_spec == other.format_spec
+            )
+
+
 Support for the debug specifier (``=``)
 ---------------------------------------