Skip to content

Commit 4dae9b1

Browse files
AA-TurnerAA-Turner
authored
gh-132661: PEP 750 documentation: second pass (#137020)
1 parent c5cebe1 commit 4dae9b1

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
@@ -462,6 +462,7 @@ Glossary
462462
core and with user code.
463463

464464
f-string
465+
f-strings
465466
String literals prefixed with ``f`` or ``F`` are commonly called
466467
"f-strings" which is short for
467468
:ref:`formatted string literals <f-strings>`. See also :pep:`498`.
@@ -1323,6 +1324,7 @@ Glossary
13231324
See also :term:`borrowed reference`.
13241325

13251326
t-string
1327+
t-strings
13261328
String literals prefixed with ``t`` or ``T`` are commonly called
13271329
"t-strings" which is short for
13281330
:ref:`template string literals <t-strings>`.

‎Doc/library/ast.rst

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

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

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

327327

328-
.. class:: TemplateStr(values)
328+
.. class:: TemplateStr(values, /)
329329

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

333336
.. doctest::
334337

335-
>>> print(ast.dump(ast.parse('t"{name} finished {place:ordinal}"', mode='eval'), indent=4))
338+
>>> expr = ast.parse('t"{name} finished {place:ordinal}"', mode='eval')
339+
>>> print(ast.dump(expr, indent=4))
336340
Expression(
337341
body=TemplateStr(
338342
values=[
@@ -349,28 +353,28 @@ Literals
349353
values=[
350354
Constant(value='ordinal')]))]))
351355

352-
.. versionadded:: 3.14
353-
356+
.. class:: Interpolation(value, str, conversion, format_spec=None)
354357

355-
.. class:: Interpolation(value, str, conversion, format_spec)
358+
.. versionadded:: 3.14
356359

357-
Node representing a single interpolation field in a t-string.
360+
Node representing a single interpolation field in a template string literal.
358361

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

364368
* -1: no conversion
365-
* 115: ``!s`` string conversion
366-
* 114: ``!r`` repr conversion
367-
* 97: ``!a`` ascii conversion
369+
* 97 (``ord('a')``): ``!a`` :func:`ASCII <ascii>` conversion
370+
* 114 (``ord('r')``): ``!r`` :func:`repr` conversion
371+
* 115 (``ord('s')``): ``!s`` :func:`string <str>` conversion
368372

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

375379

376380
.. 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)