[3.14] pythongh-132661: PEP 750 documentation: second pass (pythonGH-137020) (python#137392)

pythongh-132661: PEP 750 documentation: second pass (pythonGH-137020)
(cherry picked from commit 4dae9b1)

Co-authored-by: Adam Turner <[email protected]>

Author: 2 people

Doc/glossary.rst

@@ -467,6 +467,7 @@ Glossary
       core and with user code.
 
    f-string
+   f-strings
       String literals prefixed with ``f`` or ``F`` are commonly called
       "f-strings" which is short for
       :ref:`formatted string literals <f-strings>`.  See also :pep:`498`.
@@ -1328,6 +1329,7 @@ Glossary
       See also :term:`borrowed reference`.
 
    t-string
+   t-strings
       String literals prefixed with ``t`` or ``T`` are commonly called
       "t-strings" which is short for
       :ref:`template string literals <t-strings>`.

Doc/library/ast.rst

@@ -290,9 +290,9 @@ Literals
    * ``conversion`` is an integer:
 
      * -1: no formatting
-     * 115 (``ord('s')``): ``!s`` string formatting
-     * 114 (``ord('r')``): ``!r`` repr formatting
-     * 97 (``ord('a')``): ``!a`` ASCII formatting
+     * 97 (``ord('a')``): ``!a`` :func:`ASCII <ascii>` formatting
+     * 114 (``ord('r')``): ``!r`` :func:`repr` formatting
+     * 115 (``ord('s')``): ``!s`` :func:`string <str>` formatting
 
    * ``format_spec`` is a :class:`JoinedStr` node representing the formatting
      of the value, or ``None`` if no format was specified. Both
@@ -326,14 +326,18 @@ Literals
                                 Constant(value='.3')]))]))
 
 
-.. class:: TemplateStr(values)
+.. class:: TemplateStr(values, /)
 
-   A t-string, comprising a series of :class:`Interpolation` and :class:`Constant`
-   nodes.
+   .. versionadded:: 3.14
+
+   Node representing a template string literal, comprising a series of
+   :class:`Interpolation` and :class:`Constant` nodes.
+   These nodes may be any order, and do not need to be interleaved.
 
    .. doctest::
 
-        >>> print(ast.dump(ast.parse('t"{name} finished {place:ordinal}"', mode='eval'), indent=4))
+        >>> expr = ast.parse('t"{name} finished {place:ordinal}"', mode='eval')
+        >>> print(ast.dump(expr, indent=4))
         Expression(
             body=TemplateStr(
                 values=[
@@ -350,28 +354,28 @@ Literals
                             values=[
                                 Constant(value='ordinal')]))]))
 
-   .. versionadded:: 3.14
-
+.. class:: Interpolation(value, str, conversion, format_spec=None)
 
-.. class:: Interpolation(value, str, conversion, format_spec)
+   .. versionadded:: 3.14
 
-   Node representing a single interpolation field in a t-string.
+   Node representing a single interpolation field in a template string literal.
 
    * ``value`` is any expression node (such as a literal, a variable, or a
      function call).
+     This has the same meaning as ``FormattedValue.value``.
    * ``str`` is a constant containing the text of the interpolation expression.
    * ``conversion`` is an integer:
 
      * -1: no conversion
-     * 115: ``!s`` string conversion
-     * 114: ``!r`` repr conversion
-     * 97: ``!a`` ascii conversion
+     * 97 (``ord('a')``): ``!a`` :func:`ASCII <ascii>` conversion
+     * 114 (``ord('r')``): ``!r`` :func:`repr` conversion
+     * 115 (``ord('s')``): ``!s`` :func:`string <str>` conversion
 
+     This has the same meaning as ``FormattedValue.conversion``.
    * ``format_spec`` is a :class:`JoinedStr` node representing the formatting
      of the value, or ``None`` if no format was specified. Both
      ``conversion`` and ``format_spec`` can be set at the same time.
-
-   .. versionadded:: 3.14
+     This has the same meaning as ``FormattedValue.format_spec``.
 
 
 .. class:: List(elts, ctx)

Doc/library/dis.rst

@@ -1122,8 +1122,8 @@ iterations of the loop.
 
 .. opcode:: BUILD_TEMPLATE
 
-   Constructs a new :class:`~string.templatelib.Template` from a tuple
-   of strings and a tuple of interpolations and pushes the resulting instance
+   Constructs a new :class:`~string.templatelib.Template` instance from a tuple
+   of strings and a tuple of interpolations and pushes the resulting object
    onto the stack::
 
       interpolations = STACK.pop()
@@ -1135,8 +1135,8 @@ iterations of the loop.
 
 .. opcode:: BUILD_INTERPOLATION (format)
 
-   Constructs a new :class:`~string.templatelib.Interpolation` from a
-   value and its source expression and pushes the resulting instance onto the
+   Constructs a new :class:`~string.templatelib.Interpolation` instance from a
+   value and its source expression and pushes the resulting object onto the
    stack.
 
    If no conversion or format specification is present, ``format`` is set to

Doc/library/stdtypes.rst

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

Doc/library/string.rst

@@ -200,7 +200,7 @@ syntax for format strings (although in the case of :class:`Formatter`,
 subclasses can define their own format string syntax).  The syntax is
 related to that of :ref:`formatted string literals <f-strings>` and
 :ref:`template string literals <t-strings>`, but it is less sophisticated
-and, in particular, does not support arbitrary expressions.
+and, in particular, does not support arbitrary expressions in interpolations.
 
 .. index::
    single: {} (curly brackets); in string formatting
@@ -799,13 +799,15 @@ Template strings ($-strings)
 
 .. note::
 
-   The feature described here was introduced in Python 2.4.  It is unrelated
-   to, and should not be confused with, the newer
-   :ref:`template strings <template-strings>` and
-   :ref:`t-string literal syntax <t-strings>` introduced in Python 3.14.
-   T-string literals evaluate to instances of a different
-   :class:`~string.templatelib.Template` class, found in the
-   :mod:`string.templatelib` module.
+   The feature described here was introduced in Python 2.4;
+   a simple templating method based upon regular expressions.
+   It predates :meth:`str.format`, :ref:`formatted string literals <f-strings>`,
+   and :ref:`template string literals <template-strings>`.
+
+   It is unrelated to template string literals (t-strings),
+   which were introduced in Python 3.14.
+   These evaluate to  :class:`string.templatelib.Template` objects,
+   found in the :mod:`string.templatelib` module.
 
 Template strings provide simpler string substitutions as described in
 :pep:`292`.  A primary use case for template strings is for