diff --git a/peps/pep-0750.rst b/peps/pep-0750.rst index 92ec3c34cea..b06cbbce2be 100644 --- a/peps/pep-0750.rst +++ b/peps/pep-0750.rst @@ -209,7 +209,7 @@ Like ``Template``, it is a new class found in the :mod:`!string.templatelib` mod def __new__( cls, value: object, - expression: str, + expression: str = "", conversion: Literal["a", "r", "s"] | None = None, format_spec: str = "", ): @@ -226,7 +226,8 @@ The ``value`` attribute is the evaluated result of the interpolation: template = t"Hello {name}" assert template.interpolations[0].value == "World" -The ``expression`` attribute is the *original text* of the interpolation: +When interpolations are created from a template string literal, the +``expression`` attribute contains the *original text* of the interpolation: .. code-block:: python @@ -234,6 +235,11 @@ The ``expression`` attribute is the *original text* of the interpolation: template = t"Hello {name}" assert template.interpolations[0].expression == "name" +When developers explicitly construct an ``Interpolation``, they may optionally +provide a value for the ``expression`` attribute. Even though it is stored as +a string, this *should* be a valid Python expression. If no value is provided, +the ``expression`` attribute defaults to the empty string (``""``). + We expect that the ``expression`` attribute will not be used in most template processing code. It is provided for completeness and for use in debugging and introspection. See both the `Common Patterns Seen in Processing Templates`_ @@ -455,7 +461,9 @@ The debug specifier, ``=``, is supported in template strings and behaves similar to how it behaves in f-strings, though due to limitations of the implementation there is a slight difference. -In particular, ``t'{value=}'`` is treated as ``t'value={value!r}'``: +In particular, ``t'{value=}'`` is treated as ``t'value={value!r}'``. The first +static string is rewritten from ``""`` to ``"value="`` and the ``conversion`` +defaults to ``r``: .. code-block:: python @@ -465,8 +473,11 @@ In particular, ``t'{value=}'`` is treated as ``t'value={value!r}'``: assert template.interpolations[0].value == "World" assert template.interpolations[0].conversion == "r" -If a separate format string is also provided, ``t'{value=:fmt}`` is treated -instead as ``t'value={value!s:fmt}'``. +If a conversion is explicitly provided, it is kept: ``t'{value=!s}'`` +is treated as ``t'value={value!s}'``. + +If a format string is provided without a conversion, the ``conversion`` +is set to ``None``: ``t'{value=:fmt}'`` is treated as ``t'value={value:fmt}'``. Whitespace is preserved in the debug specifier, so ``t'{value = }'`` is treated as ``t'value = {value!r}'``.