Skip to content

Commit e817d1a

Browse files
miss-islingtonAA-Turner
miss-islington
and
AA-Turner
authored
[3.14] gh-132661: PEP 750 documentation: second pass (GH-137020) (#137392)
gh-132661: PEP 750 documentation: second pass (GH-137020) (cherry picked from commit 4dae9b1) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
1 parent 7b56d08 commit e817d1a

File tree

8 files changed

+295
-253
lines changed

8 files changed

+295
-253
lines changed

‎Doc/glossary.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -467,6 +467,7 @@ Glossary
467467
core and with user code.
468468

469469
f-string
470+
f-strings
470471
String literals prefixed with ``f`` or ``F`` are commonly called
471472
"f-strings" which is short for
472473
:ref:`formatted string literals <f-strings>`. See also :pep:`498`.
@@ -1328,6 +1329,7 @@ Glossary
13281329
See also :term:`borrowed reference`.
13291330

13301331
t-string
1332+
t-strings
13311333
String literals prefixed with ``t`` or ``T`` are commonly called
13321334
"t-strings" which is short for
13331335
:ref:`template string literals <t-strings>`.

‎Doc/library/ast.rst

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -290,9 +290,9 @@ Literals
290290
* ``conversion`` is an integer:
291291

292292
* -1: no formatting
293-
* 115 (``ord('s')``): ``!s`` string formatting
294-
* 114 (``ord('r')``): ``!r`` repr formatting
295-
* 97 (``ord('a')``): ``!a`` ASCII formatting
293+
* 97 (``ord('a')``): ``!a`` :func:`ASCII <ascii>` formatting
294+
* 114 (``ord('r')``): ``!r`` :func:`repr` formatting
295+
* 115 (``ord('s')``): ``!s`` :func:`string <str>` formatting
296296

297297
* ``format_spec`` is a :class:`JoinedStr` node representing the formatting
298298
of the value, or ``None`` if no format was specified. Both
@@ -326,14 +326,18 @@ Literals
326326
Constant(value='.3')]))]))
327327

328328

329-
.. class:: TemplateStr(values)
329+
.. class:: TemplateStr(values, /)
330330

331-
A t-string, comprising a series of :class:`Interpolation` and :class:`Constant`
332-
nodes.
331+
.. versionadded:: 3.14
332+
333+
Node representing a template string literal, comprising a series of
334+
:class:`Interpolation` and :class:`Constant` nodes.
335+
These nodes may be any order, and do not need to be interleaved.
333336

334337
.. doctest::
335338

336-
>>> print(ast.dump(ast.parse('t"{name} finished {place:ordinal}"', mode='eval'), indent=4))
339+
>>> expr = ast.parse('t"{name} finished {place:ordinal}"', mode='eval')
340+
>>> print(ast.dump(expr, indent=4))
337341
Expression(
338342
body=TemplateStr(
339343
values=[
@@ -350,28 +354,28 @@ Literals
350354
values=[
351355
Constant(value='ordinal')]))]))
352356

353-
.. versionadded:: 3.14
354-
357+
.. class:: Interpolation(value, str, conversion, format_spec=None)
355358

356-
.. class:: Interpolation(value, str, conversion, format_spec)
359+
.. versionadded:: 3.14
357360

358-
Node representing a single interpolation field in a t-string.
361+
Node representing a single interpolation field in a template string literal.
359362

360363
* ``value`` is any expression node (such as a literal, a variable, or a
361364
function call).
365+
This has the same meaning as ``FormattedValue.value``.
362366
* ``str`` is a constant containing the text of the interpolation expression.
363367
* ``conversion`` is an integer:
364368

365369
* -1: no conversion
366-
* 115: ``!s`` string conversion
367-
* 114: ``!r`` repr conversion
368-
* 97: ``!a`` ascii conversion
370+
* 97 (``ord('a')``): ``!a`` :func:`ASCII <ascii>` conversion
371+
* 114 (``ord('r')``): ``!r`` :func:`repr` conversion
372+
* 115 (``ord('s')``): ``!s`` :func:`string <str>` conversion
369373

374+
This has the same meaning as ``FormattedValue.conversion``.
370375
* ``format_spec`` is a :class:`JoinedStr` node representing the formatting
371376
of the value, or ``None`` if no format was specified. Both
372377
``conversion`` and ``format_spec`` can be set at the same time.
373-
374-
.. versionadded:: 3.14
378+
This has the same meaning as ``FormattedValue.format_spec``.
375379

376380

377381
.. class:: List(elts, ctx)

‎Doc/library/dis.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1122,8 +1122,8 @@ iterations of the loop.
11221122

11231123
.. opcode:: BUILD_TEMPLATE
11241124

1125-
Constructs a new :class:`~string.templatelib.Template` from a tuple
1126-
of strings and a tuple of interpolations and pushes the resulting instance
1125+
Constructs a new :class:`~string.templatelib.Template` instance from a tuple
1126+
of strings and a tuple of interpolations and pushes the resulting object
11271127
onto the stack::
11281128

11291129
interpolations = STACK.pop()
@@ -1135,8 +1135,8 @@ iterations of the loop.
11351135

11361136
.. opcode:: BUILD_INTERPOLATION (format)
11371137

1138-
Constructs a new :class:`~string.templatelib.Interpolation` from a
1139-
value and its source expression and pushes the resulting instance onto the
1138+
Constructs a new :class:`~string.templatelib.Interpolation` instance from a
1139+
value and its source expression and pushes the resulting object onto the
11401140
stack.
11411141

11421142
If no conversion or format specification is present, ``format`` is set to

‎Doc/library/stdtypes.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2673,9 +2673,10 @@ For example:
26732673

26742674
The formatting operations described here exhibit a variety of quirks that
26752675
lead to a number of common errors (such as failing to display tuples and
2676-
dictionaries correctly). Using the newer :ref:`formatted string literals
2677-
<f-strings>`, the :meth:`str.format` interface, or :ref:`template strings
2678-
($-strings) <template-strings-pep292>` may help avoid these errors.
2676+
dictionaries correctly).
2677+
2678+
Using :ref:`formatted string literals <f-strings>`, the :meth:`str.format`
2679+
interface, or :class:`string.Template` may help avoid these errors.
26792680
Each of these alternatives provides their own trade-offs and benefits of
26802681
simplicity, flexibility, and/or extensibility.
26812682

‎Doc/library/string.rst

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -200,7 +200,7 @@ syntax for format strings (although in the case of :class:`Formatter`,
200200
subclasses can define their own format string syntax). The syntax is
201201
related to that of :ref:`formatted string literals <f-strings>` and
202202
:ref:`template string literals <t-strings>`, but it is less sophisticated
203-
and, in particular, does not support arbitrary expressions.
203+
and, in particular, does not support arbitrary expressions in interpolations.
204204

205205
.. index::
206206
single: {} (curly brackets); in string formatting
@@ -799,13 +799,15 @@ Template strings ($-strings)
799799

800800
.. note::
801801

802-
The feature described here was introduced in Python 2.4. It is unrelated
803-
to, and should not be confused with, the newer
804-
:ref:`template strings <template-strings>` and
805-
:ref:`t-string literal syntax <t-strings>` introduced in Python 3.14.
806-
T-string literals evaluate to instances of a different
807-
:class:`~string.templatelib.Template` class, found in the
808-
:mod:`string.templatelib` module.
802+
The feature described here was introduced in Python 2.4;
803+
a simple templating method based upon regular expressions.
804+
It predates :meth:`str.format`, :ref:`formatted string literals <f-strings>`,
805+
and :ref:`template string literals <template-strings>`.
806+
807+
It is unrelated to template string literals (t-strings),
808+
which were introduced in Python 3.14.
809+
These evaluate to :class:`string.templatelib.Template` objects,
810+
found in the :mod:`string.templatelib` module.
809811

810812
Template strings provide simpler string substitutions as described in
811813
:pep:`292`. A primary use case for template strings is for

0 commit comments

Comments
 (0)