@@ -400,37 +400,44 @@ Template String Concatenation
400400-----------------------------
401401
402402Template strings support explicit concatenation using ``+ ``. Concatenation is
403- supported for two ``Template `` instances as well as for a ``Template `` instance
404- and a ``str ``:
403+ supported for two ``Template `` instances via ``Template.__add__() ``:
405404
406405.. code-block :: python
407406
408407 name = " World"
409- template = t" {name} "
410408
411- assert isinstance (t" Hello " + template , Template)
412- assert (t" Hello " + template ).strings == (" Hello " " "
413- assert (t" Hello " + template).interpolations [0 ].value == " World"
409+ assert isinstance (t" Hello " + t " {name} "
410+ assert (t" Hello " + t " {name} " == (" Hello " " "
411+ assert (t" Hello " + t " {name} " ).values [0 ] == " World"
414412
415- assert isinstance (" Hello " + template, Template)
416- assert (" Hello " + template).strings == (" Hello " " "
417- assert (" Hello " + template).interpolations[0 ].value == " World"
413+
418414
419- Template `` and
420- a ``str `` always results in a ``Template `` instance.
415+ .. code-block :: python
416+
417+ name = " World"
418+ assert isinstance (t" Hello " " {name} "
419+ assert (t" Hello " " {name} " == (" Hello " " "
420+ assert (t" Hello " " {name} " 0 ] == " World"
421+
422+ Template `` and ``str `` is
423+ prohibited. This is because it is ambiguous whether the ``str `` should be
424+ treated as a static string part or as an interpolation.
421425
422- Python's implicit concatenation syntax is also supported. The following code
423- will work as expected:
426+ To combine a ``Template `` and a ``str ``, developers must explicitly decide how
427+ to treat the ``str ``. If the ``str `` is intended to be a static string part,
428+ it should be wrapped in a ``Template ``. If the ``str `` is intended to be an
429+ interpolation value, it should be wrapped in an ``Interpolation `` and
430+ passed to the ``Template `` constructor. For example:
424431
425432.. code-block :: python
426433
427434 name = " World"
428- assert (t" Hello " " World" == (" Hello World"
429- assert (" Hello " " World" == (" Hello World"
430435
431- Template `` type supports the ``__add__() `` and ``__radd__() `` methods
432- between two ``Template `` instances and between a ``Template `` instance and a
433- ``str ``.
436+ # Treat `name` as a static string part
437+ template = t" Hello " + Template(name)
438+
439+ # Treat `name` as an interpolation
440+ template = t" Hello " + Template(Interpolation(name, " name"
434441
435442
436443
@@ -1360,11 +1367,12 @@ Developers who need to obtain the original template string literal can always
13601367use ``inspect.getsource() `` or similar tools.
13611368
13621369
1363- Disallowing String Concatenation
1364- --------------------------------
1370+ Disallowing Template Concatenation
1371+ ----------------------------------
13651372
1366- Earlier versions of this PEP proposed that template strings should not support
1367- concatenation. This was rejected in favor of allowing concatenation.
1373+ Earlier versions of this PEP proposed that ``Template `` instances should not
1374+ support concatenation. This was rejected in favor of allowing concatenating
1375+ multiple ``Template `` instances.
13681376
13691377There are reasonable arguments in favor of rejecting one or all forms of
13701378concatenation: namely, that it cuts off a class of potential bugs, particularly
@@ -1378,13 +1386,16 @@ return a type that supported concatenation.
13781386
13791387In the end, we decided that the surprise to developers of a new string type
13801388*not * supporting concatenation was likely to be greater than the theoretical
1381- harm caused by supporting it. (Developers concatenate f-strings all the time,
1382- after all, and while we are sure there are cases where this introduces bugs,
1383- it's not clear that those bugs outweigh the benefits of supporting concatenation.)
1389+ harm caused by supporting it.
1390+
1391+ While concatenation of two ``Templates `` is supported by this PEP, concatenation
1392+ of a ``Template `` and a ``str `` is not supported. This is because it is
1393+ ambiguous whether ``str `` should be treated as a static string or an
1394+ interpolation. Developers must wrap the ``str `` in a ``Template `` instance
1395+ before concatenating it with another ``Template ``, as described above.
13841396
1385- While concatenation is supported, we expect that code that uses template strings
1386- will more commonly build up larger templates through nesting and composition
1387- rather than concatenation.
1397+ We expect that code that uses template strings will more commonly build up
1398+ larger templates through nesting and composition rather than concatenation.
13881399
13891400
13901401Arbitrary Conversion Values
0 commit comments