PEP 750: restrict support for Template + str addition

peps/pep-0750.rst

@@ -394,38 +394,41 @@ Template String Concatenation
 -----------------------------
 
 Template strings support explicit concatenation using ``+``. Concatenation is
-supported for two ``Template`` instances as well as for a ``Template`` instance
-and a ``str``:
+supported for two ``Template`` instances via ``Template.__add__()``:
 
 .. code-block:: python
 
     name = "World"
-    template = t"{name}"
 
-    assert isinstance(t"Hello " + template, Template)
-    assert (t"Hello " + template).strings == ("Hello ", "")
-    assert (t"Hello " + template).interpolations[0].value == "World"
+    assert isinstance(t"Hello " + t"{name}", Template)
+    assert (t"Hello " + t"{name}").strings == ("Hello ", "")
+    assert (t"Hello " + t"{name}").values[0] == "World"
 
-    assert isinstance("Hello " + template, Template)
-    assert ("Hello " + template).strings == ("Hello ", "")
-    assert ("Hello " + template).interpolations[0].value == "World"
+Concatenation of a ``Template`` and a ``str`` is not supported. This is because
+it is ambiguous whether the ``str`` should be treated as a static string part
+or as an interpolation. Developers can effectively mark a ``str`` by directly
+constructing a ``Template`` instance:
 
-Concatenation of templates is "viral": the concatenation of a ``Template`` and
-a ``str`` always results in a ``Template`` instance.
+.. code-block:: python
+
+    name = "World"
+
+    # Treat `name` as a static string part
+    template = t"Hello " + Template(name)
 
-Python's implicit concatenation syntax is also supported. The following code
-will work as expected:
+    # Treat `name` as an interpolation
+    template = t"Hello " + Template(Interpolation(name, "name"))
+
+Python's implicit concatenation syntax is supported between any combination
+of ``Template`` and ``str``:
 
 .. code-block:: python
 
     name = "World"
     assert (t"Hello " t"World").strings == ("Hello World",)
+    assert (t"Hello " "World").strings == ("Hello World",)
     assert ("Hello " t"World").strings == ("Hello World",)
 
-The ``Template`` type supports the ``__add__()`` and ``__radd__()`` methods
-between two ``Template`` instances and between a ``Template`` instance and a
-``str``.
-
 
 Template and Interpolation Equality
 -----------------------------------
@@ -1349,11 +1352,12 @@ Developers who need to obtain the original template string literal can always
 use ``inspect.getsource()`` or similar tools.
 
 
-Disallowing String Concatenation
---------------------------------
+Disallowing Template Concatenation
+----------------------------------
 
-Earlier versions of this PEP proposed that template strings should not support
-concatenation. This was rejected in favor of allowing concatenation.
+Earlier versions of this PEP proposed that ``Template`` instances should not
+support concatenation. This was rejected in favor of allowing concatenating
+multiple ``Template`` instances.
 
 There are reasonable arguments in favor of rejecting one or all forms of
 concatenation: namely, that it cuts off a class of potential bugs, particularly
@@ -1367,13 +1371,16 @@ return a type that supported concatenation.
 
 In the end, we decided that the surprise to developers of a new string type
 *not* supporting concatenation was likely to be greater than the theoretical
-harm caused by supporting it. (Developers concatenate f-strings all the time,
-after all, and while we are sure there are cases where this introduces bugs,
-it's not clear that those bugs outweigh the benefits of supporting concatenation.)
+harm caused by supporting it.
+
+While concatenation of two ``Templates`` is supported by this PEP, concatenation
+via ``+`` of a ``Template`` and a ``str`` is not supported. This is because it
+is ambiguous whether  ``str`` should be treated as a static string or an
+interpolation. Developers must wrap the ``str`` in a ``Template`` instance before
+concatenating it with another ``Template``, as described above.
 
-While concatenation is supported, we expect that code that uses template strings
-will more commonly build up larger templates through nesting and composition
-rather than concatenation.
+We expect that code that uses template strings will more commonly build up
+larger templates through nesting and composition rather than concatenation.
 
 
 Arbitrary Conversion Values