Major rewrite, modernisation

Author: AA-Turner

Doc/library/dis.rst

@@ -1667,7 +1667,7 @@ iterations of the loop.
    * ``oparg == 2``: call :func:`repr` on *value*
    * ``oparg == 3``: call :func:`ascii` on *value*
 
-   Used for implementing formatted literal strings (f-strings).
+   Used for implementing formatted string literals (f-strings).
 
    .. versionadded:: 3.13
 
@@ -1680,7 +1680,7 @@ iterations of the loop.
       result = value.__format__("")
       STACK.append(result)
 
-   Used for implementing formatted literal strings (f-strings).
+   Used for implementing formatted string literals (f-strings).
 
    .. versionadded:: 3.13
 
@@ -1693,7 +1693,7 @@ iterations of the loop.
       result = value.__format__(spec)
       STACK.append(result)
 
-   Used for implementing formatted literal strings (f-strings).
+   Used for implementing formatted string literals (f-strings).
 
    .. versionadded:: 3.13
 

Doc/library/stdtypes.rst

@@ -2658,194 +2658,138 @@ that ``'\0'`` is the end of the string.
 
 
 .. index::
-   single: buffer protocol; binary sequence types
-
-
-.. index::
-   single: formatted string literal
+   single: ! formatted string literal
+   single: formatted string literals
+   single: ! f-string
+   single: f-strings
+   single: fstring
    single: interpolated string literal
    single: string; formatted literal
    single: string; interpolated literal
-   single: f-string
-   single: fstring
    single: {} (curly brackets); in formatted string literal
-   single: ! (exclamation); in formatted string literal
+   single: ! (exclamation mark); in formatted string literal
    single: : (colon); in formatted string literal
    single: = (equals); in debug string literal
-.. _f-string-formated-string-literal:
 
-``f-string``-Formatted String Literal
+Formatted String Literals (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 replacement
-fields, which are expressions delimited by curly braces ``{}``. While other
-string literals always have a constant value, formatted strings are expressions
-evaluated at run time.::
+An :dfn:`f-string` (formally a :dfn:`formatted string literal`) is
+a string literal that is prefixed with ``f`` or ``F``.
+This type of string literal allows embedding arbitrary Python expressions
+within *replacement fields*, which are delimited by curly brackets (``{}``).
+These expressions are evaluated at runtime, similarly to :meth:`str.format`,
+and are converted into regular :class:`str` objects.
+For example:
+
+.. code-block:: pycon
+
+   >>> who = 'nobody'
+   >>> nationality = 'Spanish'
+   >>> f'{who.title()} expects the {nationality} Inquisition!'
+   'Nobody expects the Spanish Inquisition!'
 
-   >>> f"This is an f-string"
-   'This is an f-string'
-   >>> F"This is also an f-string"
-   'This is also an f-string'
+It is also possible to use a multi line f-string:
 
-It is also possible to have a multi line string.::
+.. code-block:: pycon
 
    >>> f'''This is a string
    ... on two lines'''
    'This is a string\non two lines'
 
-A single opening curly bracket, ``'{'``, marks a replacement field that contains
-a python expression.::
-
-   >>> name = "Fred"
-   >>> f"He said his name is {name}"
-   'He said his name is Fred'
-
-Everything outside the braces is treated as a literal::
-
-   >>> a = 4
-   >>> b = 3
-   >>> f"The product of {a} and {b} is {a * b}"
-   'The product of 4 and 3 is 12'
-
-If you want to include a literal ``{`` or ``}``, you can double the curly
-brackets to escape them::
-
-   >>> f'{{a}} is {a}'
-   '{a} is 4'
-
-Functions can also be used.::
-
-   >>> s = "Python"
-   >>> f"The string {s.upper()} contains {len(s)} characters."
-   'The string PYTHON contains 6 characters.'
-
-By default the :func:`str` format of a variable is presented when using
-f-strings::
-
-   >>> import datetime
-   >>> now = datetime.datetime.now()
-   >>> f"{now}"
-   '2020-07-28 04:33:08.629606'
+A single opening curly bracket, ``'{'``, marks a *replacement field* that
+can contain any Python expression:
 
-Note that this is the :func:`str` format of a :mod:`datetime`. To show a
-different format you use a conversion. There are three conversions beginning
-with the ``'!'`` (exclamation) mark.
+.. code-block:: pycon
 
-============ ===============
- Conversion   Meaning
-============ ===============
- ``!r``       :func:`repr`
- ``!s``       :func:`str`
- ``!a``       :func:`ascii`
-============ ===============
+   >>> nationality = 'Spanish'
+   >>> f'The {name} Inquisition!'
+   'The Spanish Inquisition!'
 
-::
+To include a literal ``{`` or ``}``, use a double bracket:
 
-   >>> f"{now!r}"
-   'datetime.datetime(2020, 7, 28, 4, 33, 8, 629606)'
-   >>> hello = "你好"
-   >>> f"The ASCII version of {hello!r} is {hello!a}."
-   "The ASCII version of '你好' is '\\u4f60\\u597d'."
+.. code-block:: pycon
 
-While debugging it may be helpful to see both the expression and its value.::
+   >>> x = 42
+   >>> f'{{x}} is {x}'
+   '{x} is 42'
 
-   >>> f"now={now}"
-   'now=2020-07-28 04:33:08.629606'
+Functions can also be used, and :ref:`format specifier <formatstrings>`:
 
-The new way to do this is to use the equal sign ``=`` after the expression.
+.. code-block:: pycon
 
-.. versionadded:: 3.8
+   >>> from math import sqrt
+   >>> f'√2 \N{ALMOST EQUAL TO} {sqrt(2):.5f}'
+   '√2 ≈ 1.41421'
 
-::
+Any non-string expression is converted using :func:`str`, by default:
 
-   >>> f"{now = }" # spaces within braces are maintained.
-   'now = datetime.datetime(2020, 7, 28, 4, 33, 8, 629606)'
+.. code-block:: pycon
 
+   >>> from fractions import Fraction
+   >>> f'{Fraction(1, 3)}'
+   '1/3'
 
-When used by its own, the debugging operator ``=``, outputs the :func:`repr` of
-the expression. A converter can be used to change it::
+To use an explicit conversion, use the ``!`` (exclamation mark) operator,
+followed by any of the valid formats, which are:
 
-   >>> f"{now=!s}"
-   'now=2020-07-28 04:33:08.629606'
+========== ==============
+Conversion  Meaning
+========== ==============
+``!a``      :func:`ascii`
+``!r``      :func:`repr`
+``!s``      :func:`str`
+========== ==============
 
-Once the output has been evaluated it can then be formatted using a formatting
-specifier that is appended preceeded by a ``':'`` (colon).
-
-The format specifier is passed to the :meth:`__format__` method of the
-expression or conversion result. An empty string is passed when the format
-specifier is omitted. The formatted result is then returned as the final value
-of the whole string.
-
-As an example for :mod:`datetime` we could use format specifiers described in
-:ref:`strftime-strptime-behavior`::
-
-   >>> f"{now:%B %d, %Y}"
-   'July 28, 2020'
-
-Most built-in types will comply with the :ref:`formatspec`::
-
-   >>> num = 12.3456
-   >>> f"{num:20}"
-   '             12.3456'
-   >>> f"{num:<20}"
-   '12.3456             '
-   >>> f"{num:e}"
-   '1.234560e+01'
-
-When a format specifier is given together with the equal sign ``'='`` the
-default conversion for the expressions' is :func:`str`. Conversion can be used
-to show the :func:`repr` form::
-
-   >>> import decimal
-   >>> value = decimal.Decimal("12.34567")
-   >>> f"{value=}"
-   "value=Decimal('12.34567')"
-   >>> f"{value=:20}"
-   'value=            12.34567'
-   >>> f"{value=!r:20}"
-   "value=Decimal('12.34567') "
-
-Formatted string literals cannot be used as docstrings, even if they do not
-include expressions.::
-
-   >>> def foo():
-   ...     f"Not a docstring"
-   ...
-   >>> print(foo.__doc__)
-   None
-
-A consequence of sharing the same syntax as regular string literals is
-that characters in the replacement fields must not conflict with the
-quoting used in the outer formatted string literal::
-
-   >>> a = {"Terry":"Jones", "John":"Cleese", "x":"Gilliam", "Eric":"Idle"}
-   >>> f"abc {a["x"]} def"
-     File  "<stdin>", line 1
-       f"abc {a["x"]} def"
-                 ^
-   SyntaxError: f-string: unmatched '['
-
-   >>> f"abc {a['x']} def"    # workaround: use different quoting
-   'abc Gilliam def'
-
-Backslashes are not allowed in format expressions and will raise
-an error::
+For example:
 
-   >>> f'{ord("\n")}'
-     File "<stdin>", line 1
-       f'{ord("\n")}'
-   SyntaxError: f-string expression part cannot include a backslash
+.. code-block:: pycon
+
+   >>> from fractions import Fraction
+   >>> f'{Fraction(1, 3)!s}'
+   '1/3'
+   >>> f'{Fraction(1, 3)!r}'
+   'Fraction(1, 3)'
+   >>> question = '¿Dónde está el Presidente?'
+   >>> print(f'{question!a}')
+   '\xbfD\xf3nde est\xe1 el Presidente?'
+
+While debugging it may be helpful to see both the expression and its value,
+using the equals sign (``=``) after the expression.
+This preserves spaces within the brackets, and can be used with a converter.
+By default, the debugging operator uses the :func:`repr` (``!r``) conversion.
+For example:
 
-To include a value in which a backslash escape is required, create
-a temporary variable.::
+.. code-block:: pycon
+
+   >>> from fractions import Fraction
+   >>> calculation = Fraction(1, 3)
+   >>> f'{calculation=}'
+   'calculation=Fraction(1, 3)'
+   >>> f'{calculation = }'
+   'calculation = Fraction(1, 3)'
+   >>> f'{calculation = !s}'
+   'calculation = 1/3'
+
+Once the output has been evaluated, it can be formatted using a
+:ref:`format specifier <formatstrings>` following a colon (``':'``).
+After the expression has been evaluated, and possibly converted to a string,
+the :meth:`__format__` method of the result is called with the format specifier,
+or the empty string if no format specifier is given.
+The formatted result is then used as the final value for the replacement field.
+For example:
 
-   >>> newline = ord('\n')
-   >>> f"newline: {newline}"
-   'newline: 10'
+   >>> from fractions import Fraction
+   >>> f'{Fraction(1, 7):.6f}'
+   '0.142857'
+   >>> f'{Fraction(1, 7):_^+10}'
+   '___+1/7___'
 
 
+.. index::
+   single: buffer protocol; binary sequence types
 
 .. _binaryseq: