Review feedback

Author: AA-Turner

Doc/library/ast.rst

@@ -361,17 +361,20 @@ Literals
 
    * ``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
-     * 97: ``!a`` :func:`ASCII <ascii>` conversion (``ord('a')``)
-     * 114: ``!r`` :func:`repr` conversion (``ord('r')``)
-     * 115: ``!s`` :func:`string <str>` conversion (``ord('s')``)
+     * 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.
+     This has the same meaning as ``FormattedValue.format_spec``.
 
 
 .. class:: List(elts, ctx)

Doc/library/string.templatelib.rst

@@ -34,7 +34,7 @@ To write a t-string, use a ``'t'`` prefix instead of an ``'f'``, like so:
    >>> pi = 3.14
    >>> t't-strings are new in Python {pi!s}!'
    Template(
-      strings=('t-strings are new in Python ', '!'),
+      strings=('t-strings are new in Python ', '.'),
       interpolations=(Interpolation(3.14, 'pi', 's', ''),)
    )
 
@@ -51,32 +51,32 @@ Types
    This syntax is identical to that of :ref:`f-strings <f-strings>`,
    except that it uses a ``t`` prefix in place of an ``f``:
 
-   >>> name = 'World'
-   >>> template = t'Hello, {name}!'
+   >>> cheese = 'Red Leicester'
+   >>> template = t"We're fresh out of {cheese}, sir."
    >>> type(template)
    <class 'string.templatelib.Template'>
 
    Templates are stored as sequences of literal :attr:`~Template.strings`
    and dynamic :attr:`~Template.interpolations`.
    A :attr:`~Template.values` attribute holds the values of the interpolations:
 
-   >>> name = 'World'
-   >>> template = t'Hello, {name}!'
+   >>> cheese = 'Camembert'
+   >>> template = t'Ah! We do have {cheese}.'
    >>> template.strings
-   ('Hello, ', '!')
+   ('Ah! We do have ', '.')
    >>> template.interpolations
-   (Interpolation('World', ...),)
+   (Interpolation('Camembert', ...),)
    >>> template.values
-   ('World',)
+   ('Camembert',)
 
    The :attr:`!strings` tuple has one more element than :attr:`!interpolations`
    and :attr:`!values`; the interpolations “belong” between the strings.
    This may be easier to understand when tuples are aligned
 
    .. code-block:: python
 
-      template.strings:  ('Hello, ',          '!')
-      template.values:   (           'World',    )
+      template.strings:  ('Ah! We do have ',              '.')
+      template.values:   (                   'Camembert',    )
 
    .. rubric:: Attributes
 
@@ -85,17 +85,18 @@ Types
 
       A :class:`tuple` of the static strings in the template.
 
-      >>> name = 'World'
-      >>> template = t'Hello, {name}!'
+      >>> cheese = 'Camembert'
+      >>> template = t'Ah! We do have {cheese}.'
       >>> template.strings
-      ('Hello, ', '!')
+      ('Ah! We do have ', '.')
 
       Empty strings *are* included in the tuple:
 
-      >>> name = 'World'
-      >>> template = t'Hello, {name}{name}!'
+      >>> response = 'We do have '
+      >>> cheese = 'Camembert'
+      >>> template = t'Ah! {response}{cheese}.'
       >>> template.strings
-      ('Hello, ', '', '!')
+      ('Ah! ', '', '.')
 
       The ``strings`` tuple is never empty, and always contains one more
       string than the ``interpolations`` and ``values`` tuples:
@@ -114,26 +115,26 @@ Types
 
       A :class:`tuple` of the interpolations in the template.
 
-      >>> name = 'World'
-      >>> template = t'Hello, {name}!'
+      >>> cheese = 'Camembert'
+      >>> template = t'Ah! We do have {cheese}.'
       >>> template.interpolations
-      (Interpolation('World', 'name', None, ''),)
+      (Interpolation('Camembert', 'cheese', None, ''),)
 
       The ``interpolations`` tuple may be empty and always contains one fewer
       values than the ``strings`` tuple:
 
-      >>> t'Hello!'.interpolations
+      >>> t'Red Leicester'.interpolations
       ()
 
    .. attribute:: values
       :type: tuple[object, ...]
 
       A tuple of all interpolated values in the template.
 
-      >>> name = 'World'
-      >>> template = t'Hello, {name}!'
+      >>> cheese = 'Camembert'
+      >>> template = t'Ah! We do have {cheese}.'
       >>> template.values
-      ('World',)
+      ('Camembert',)
 
       The ``values`` tuple always has the same length as the
       ``interpolations`` tuple. It is always equivalent to
@@ -147,19 +148,21 @@ Types
       it is also possible to create them directly using the constructor:
 
       >>> from string.templatelib import Interpolation, Template
-      >>> name = 'World'
-      >>> template = Template('Hello, ', Interpolation(name, 'name'), '!')
+      >>> cheese = 'Camembert'
+      >>> template = Template(
+      ...     'Ah! We do have ', Interpolation(cheese, 'cheese'), '.'
+      ... )
       >>> list(template)
-      ['Hello, ', Interpolation('World', 'name', None, ''), '!']
+      ['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']
 
       If multiple strings are passed consecutively, they will be concatenated
       into a single value in the :attr:`~Template.strings` attribute. For example,
       the following code creates a :class:`Template` with a single final string:
 
       >>> from string.templatelib import Template
-      >>> template = Template('Hello, ', 'World', '!')
+      >>> template = Template('Ah! We do have ', 'Camembert', '.')
       >>> template.strings
-      ('Hello, World!',)
+      ('Ah! We do have Camembert.',)
 
       If multiple interpolations are passed consecutively, they will be treated
       as separate interpolations and an empty string will be inserted between them.
@@ -168,8 +171,8 @@ Types
 
       >>> from string.templatelib import Interpolation, Template
       >>> template = Template(
-      ...     Interpolation('World', 'name'),
-      ...     Interpolation('!', 'punctuation'),
+      ...     Interpolation('Camembert', 'cheese'),
+      ...     Interpolation('.', 'punctuation'),
       ... )
       >>> template.strings
       ('', '', '')
@@ -179,30 +182,31 @@ Types
       Iterate over the template, yielding each non-empty string and
       :class:`Interpolation` in the correct order:
 
-      >>> name = 'World'
-      >>> list(t'Hello, {name}!')
-      ['Hello, ', Interpolation('World', 'name', None, ''), '!']
+      >>> cheese = 'Camembert'
+      >>> list(t'Ah! We do have {cheese}.')
+      ['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']
 
       .. caution::
 
          Empty strings are **not** included in the iteration:
 
-         >>> name = 'World'
-         >>> list(t'Hello, {name}{name}!')  # doctest: +NORMALIZE_WHITESPACE
-         ['Hello, ',
-          Interpolation('World', 'name', None, ''),
-          Interpolation('World', 'name', None, ''),
-          '!']
+         >>> response = 'We do have '
+         >>> cheese = 'Camembert'
+         >>> list(t'Ah! {response}{cheese}.')  # doctest: +NORMALIZE_WHITESPACE
+         ['Ah! ',
+          Interpolation('We do have ', 'response', None, ''),
+          Interpolation('Camembert', 'cheese', None, ''),
+          '.']
 
    .. describe:: template + other
                  template += other
 
       Concatenate this template with another, returning a new
       :class:`!Template` instance:
 
-      >>> name = 'World'
-      >>> list(t'Hello ' + t'there {name}!')
-      ['Hello there ', Interpolation('World', 'name', None, ''), '!']
+      >>> cheese = 'Camembert'
+      >>> list(t'Ah! ' + t'We do have {cheese}.')
+      ['Ah! We do have ', Interpolation('Camembert', 'cheese', None, ''), '.']
 
       Concatenating a :class:`!Template` and a ``str`` is **not** supported.
       This is because it is unclear whether the string should be treated as
@@ -212,15 +216,15 @@ Types
       (to treat it as a static string)
       or use an :class:`!Interpolation` (to treat it as dynamic):
 
-      >>> from string.templatelib import Template, Interpolation
-      >>> template = t'Hello '
-      >>> # Treat 'there ' as a static string
-      >>> template += Template('there ')
-      >>> # Treat name as an interpolation
-      >>> name = 'World'
-      >>> template += Template(Interpolation(name, 'name'))
+      >>> from string.templatelib import Interpolation, Template
+      >>> template = t'Ah! '
+      >>> # Treat 'We do have ' as a static string
+      >>> template += Template('We do have ')
+      >>> # Treat cheese as an interpolation
+      >>> cheese = 'Camembert'
+      >>> template += Template(Interpolation(cheese, 'cheese'))
       >>> list(template)
-      ['Hello there ', Interpolation('World', 'name', None, '')]
+      ['Ah! We do have ', Interpolation('Camembert', 'cheese', None, '')]
 
 
 .. class:: Interpolation

Doc/reference/lexical_analysis.rst

@@ -599,9 +599,9 @@ The allowed prefixes are:
 
 See the linked sections for details on each type.
 
-Prefixes are case-insensitive (for example, ``B`` works the same as ``b``).
-The ``r`` prefix can be combined with ``f``, ``t`` or ``b``, so ``fr``,
-``rf``, ``tr``, ``rt``, ``br`` and ``rb`` are also valid prefixes.
+Prefixes are case-insensitive (for example, '``B``' works the same as '``b``').
+The '``r``' prefix can be combined with '``f``', '``t``' or '``b``', so '``fr``',
+'``rf``', '``tr``', '``rt``', '``br``', and '``rb``' are also valid prefixes.
 
 .. versionadded:: 3.3
    The ``'rb'`` prefix of raw bytes literals has been added as a synonym
@@ -661,7 +661,7 @@ quote.
 Escape sequences
 ----------------
 
-Unless an ``'r'`` or ``'R'`` prefix is present, escape sequences in string and
+Unless an '``r``' or '``R``' prefix is present, escape sequences in string and
 bytes literals are interpreted according to rules similar to those used by
 Standard C.  The recognized escape sequences are:
 
@@ -852,7 +852,7 @@ unrecognized escapes.
 Bytes literals
 --------------
 
-:dfn:`Bytes literals` are always prefixed with ``'b'`` or ``'B'``; they produce an
+:dfn:`Bytes literals` are always prefixed with '``b``' or '``B``'; they produce an
 instance of the :class:`bytes` type instead of the :class:`str` type.
 They may only contain ASCII characters; bytes with a numeric value of 128
 or greater must be expressed with escape sequences (typically
@@ -878,8 +878,8 @@ Similarly, a zero byte must be expressed using an escape sequence (typically
 Raw string literals
 -------------------
 
-Both string and bytes literals may optionally be prefixed with a letter ``'r'``
-or ``'R'``; such constructs are called :dfn:`raw string literals`
+Both string and bytes literals may optionally be prefixed with a letter '``r``'
+or '``R``'; such constructs are called :dfn:`raw string literals`
 and :dfn:`raw bytes literals` respectively and treat backslashes as
 literal characters.
 As a result, in raw string literals, :ref:`escape sequences <escape-sequences>`
@@ -923,7 +923,7 @@ f-strings
 .. versionadded:: 3.6
 
 A :dfn:`formatted string literal` or :dfn:`f-string` is a string literal
-that is prefixed with ``'f'`` or ``'F'``.  These strings may contain
+that is prefixed with '``f``' or '``F``'.  These strings may contain
 replacement fields, which are expressions delimited by curly braces ``{}``.
 While other string literals always have a constant value, formatted strings
 are really expressions evaluated at run time.
@@ -1089,7 +1089,7 @@ t-strings
 .. versionadded:: 3.14
 
 A :dfn:`template string literal` or :dfn:`t-string` is a string literal
-that is prefixed with ``'t'`` or ``'T'``.
+that is prefixed with '``t``' or '``T``'.
 These strings follow the same syntax and evaluation rules as
 :ref:`formatted string literals <f-strings>`, with the following differences:
 
@@ -1117,7 +1117,7 @@ These strings follow the same syntax and evaluation rules as
   This includes the equals sign and any surrounding whitespace.
   The :class:`!Interpolation` instance for the expression will be created as
   normal, except that :attr:`~string.templatelib.Interpolation.conversion` will
-  be set to ``'r'`` (:func:`repr`) by default.
+  be set to '``r``' (:func:`repr`) by default.
   If an explicit conversion or format specifier are provided,
   this will override the default behaviour.