| :mod:`!string.templatelib` --- Support for template string literals |
| =================================================================== |
| |
| .. module:: string.templatelib |
| :synopsis: Support for template string literals. |
| |
| **Source code:** :source:`Lib/string/templatelib.py` |
| |
| -------------- |
| |
| .. seealso:: |
| |
| * :ref:`Format strings <f-strings>` |
| * :ref:`Template string literal (t-string) syntax <t-strings>` |
| * :pep:`750` |
| |
| .. _template-strings: |
| |
| Template strings |
| ---------------- |
| |
| .. versionadded:: 3.14 |
| |
| Template strings are a mechanism for custom string processing. |
| They have the full flexibility of Python's :ref:`f-strings`, |
| but return a :class:`Template` instance that gives access |
| to the static and interpolated (in curly brackets) parts of a string |
| *before* they are combined. |
| |
| To write a t-string, use a ``'t'`` prefix instead of an ``'f'``, like so: |
| |
| .. code-block:: pycon |
| |
| >>> pi = 3.14 |
| >>> t't-strings are new in Python {pi!s}!' |
| Template( |
| strings=('t-strings are new in Python ', '!'), |
| interpolations=(Interpolation(3.14, 'pi', 's', ''),) |
| ) |
| |
| Types |
| ----- |
| |
| .. class:: Template |
| |
| The :class:`!Template` class describes the contents of a template string. |
| It is immutable, meaning that attributes of a template cannot be reassigned. |
| |
| The most common way to create a :class:`!Template` instance is to use the |
| :ref:`template string literal syntax <t-strings>`. |
| This syntax is identical to that of :ref:`f-strings <f-strings>`, |
| except that it uses a ``t`` prefix in place of an ``f``: |
| |
| >>> 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: |
| |
| >>> cheese = 'Camembert' |
| >>> template = t'Ah! We do have {cheese}.' |
| >>> template.strings |
| ('Ah! We do have ', '.') |
| >>> template.interpolations |
| (Interpolation('Camembert', ...),) |
| >>> template.values |
| ('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: ('Ah! We do have ', '.') |
| template.values: ( 'Camembert', ) |
| |
| .. rubric:: Attributes |
| |
| .. attribute:: strings |
| :type: tuple[str, ...] |
| |
| A :class:`tuple` of the static strings in the template. |
| |
| >>> cheese = 'Camembert' |
| >>> template = t'Ah! We do have {cheese}.' |
| >>> template.strings |
| ('Ah! We do have ', '.') |
| |
| Empty strings *are* included in the tuple: |
| |
| >>> response = 'We do have ' |
| >>> cheese = 'Camembert' |
| >>> template = t'Ah! {response}{cheese}.' |
| >>> template.strings |
| ('Ah! ', '', '.') |
| |
| The ``strings`` tuple is never empty, and always contains one more |
| string than the ``interpolations`` and ``values`` tuples: |
| |
| >>> t''.strings |
| ('',) |
| >>> t''.values |
| () |
| >>> t'{'cheese'}'.strings |
| ('', '') |
| >>> t'{'cheese'}'.values |
| ('cheese',) |
| |
| .. attribute:: interpolations |
| :type: tuple[Interpolation, ...] |
| |
| A :class:`tuple` of the interpolations in the template. |
| |
| >>> cheese = 'Camembert' |
| >>> template = t'Ah! We do have {cheese}.' |
| >>> template.interpolations |
| (Interpolation('Camembert', 'cheese', None, ''),) |
| |
| The ``interpolations`` tuple may be empty and always contains one fewer |
| values than the ``strings`` tuple: |
| |
| >>> t'Red Leicester'.interpolations |
| () |
| |
| .. attribute:: values |
| :type: tuple[object, ...] |
| |
| A tuple of all interpolated values in the template. |
| |
| >>> cheese = 'Camembert' |
| >>> template = t'Ah! We do have {cheese}.' |
| >>> template.values |
| ('Camembert',) |
| |
| The ``values`` tuple always has the same length as the |
| ``interpolations`` tuple. It is always equivalent to |
| ``tuple(i.value for i in template.interpolations)``. |
| |
| .. rubric:: Methods |
| |
| .. method:: __new__(*args: str | Interpolation) |
| |
| While literal syntax is the most common way to create a :class:`!Template`, |
| it is also possible to create them directly using the constructor: |
| |
| >>> from string.templatelib import Interpolation, Template |
| >>> cheese = 'Camembert' |
| >>> template = Template( |
| ... 'Ah! We do have ', Interpolation(cheese, 'cheese'), '.' |
| ... ) |
| >>> list(template) |
| ['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('Ah! We do have ', 'Camembert', '.') |
| >>> template.strings |
| ('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. |
| For example, the following code creates a template with empty placeholders |
| in the :attr:`~Template.strings` attribute: |
| |
| >>> from string.templatelib import Interpolation, Template |
| >>> template = Template( |
| ... Interpolation('Camembert', 'cheese'), |
| ... Interpolation('.', 'punctuation'), |
| ... ) |
| >>> template.strings |
| ('', '', '') |
| |
| .. describe:: iter(template) |
| |
| Iterate over the template, yielding each non-empty string and |
| :class:`Interpolation` in the correct order: |
| |
| >>> 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: |
| |
| >>> 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: |
| |
| >>> 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 |
| a static string or an interpolation. |
| If you want to concatenate a :class:`!Template` with a string, |
| you should either wrap the string directly in a :class:`!Template` |
| (to treat it as a static string) |
| or use an :class:`!Interpolation` (to treat it as dynamic): |
| |
| >>> 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) |
| ['Ah! We do have ', Interpolation('Camembert', 'cheese', None, '')] |
| |
| |
| .. class:: Interpolation |
| |
| The :class:`!Interpolation` type represents an expression inside a template string. |
| It is immutable, meaning that attributes of an interpolation cannot be reassigned. |
| |
| Interpolations support pattern matching, allowing you to match against |
| their attributes with the :ref:`match statement <match>`: |
| |
| >>> from string.templatelib import Interpolation |
| >>> interpolation = t'{1. + 2.:.2f}'.interpolations[0] |
| >>> interpolation |
| Interpolation(3.0, '1. + 2.', None, '.2f') |
| >>> match interpolation: |
| ... case Interpolation(value, expression, conversion, format_spec): |
| ... print(value, expression, conversion, format_spec, sep=' | ') |
| ... |
| 3.0 | 1. + 2. | None | .2f |
| |
| .. rubric:: Attributes |
| |
| .. attribute:: value |
| :type: object |
| |
| The evaluated value of the interpolation. |
| |
| >>> t'{1 + 2}'.interpolations[0].value |
| 3 |
| |
| .. attribute:: expression |
| :type: str |
| |
| For interpolations created by t-string literals, :attr:`!expression` |
| is the expression text found inside the curly brackets (``{`` & ``}``), |
| including any whitespace, excluding the curly brackets themselves, |
| and ending before the first ``!``, ``:``, or ``=`` if any is present. |
| For manually created interpolations, :attr:`!expression` is the arbitrary |
| string provided when constructing the interpolation instance. |
| |
| We recommend using valid Python expressions or the empty string for the |
| ``expression`` field of manually created :class:`!Interpolation` |
| instances, although this is not enforced at runtime. |
| |
| >>> t'{1 + 2}'.interpolations[0].expression |
| '1 + 2' |
| |
| .. attribute:: conversion |
| :type: typing.Literal['a', 'r', 's'] | None |
| |
| The conversion to apply to the value, or ``None``. |
| |
| The :attr:`!conversion` is the optional conversion to apply |
| to the value: |
| |
| >>> t'{1 + 2!a}'.interpolations[0].conversion |
| 'a' |
| |
| .. note:: |
| |
| Unlike f-strings, where conversions are applied automatically, |
| the expected behavior with t-strings is that code that *processes* the |
| :class:`!Template` will decide how to interpret and whether to apply |
| the :attr:`!conversion`. |
| For convenience, the :func:`convert` function can be used to mimic |
| f-string conversion semantics. |
| |
| .. attribute:: format_spec |
| :type: str |
| |
| The format specification to apply to the value. |
| |
| The :attr:`!format_spec` is an optional, arbitrary string |
| used as the format specification to present the value: |
| |
| >>> t'{1 + 2:.2f}'.interpolations[0].format_spec |
| '.2f' |
| |
| .. note:: |
| |
| Unlike f-strings, where format specifications are applied automatically |
| via the :func:`format` protocol, the expected behavior with |
| t-strings is that code that *processes* the interpolation will |
| decide how to interpret and whether to apply the format specification. |
| As a result, :attr:`!format_spec` values in interpolations |
| can be arbitrary strings, |
| including those that do not conform to the :func:`format` protocol. |
| |
| .. rubric:: Methods |
| |
| .. method:: __new__(value: object, \ |
| expression: str, \ |
| conversion: typing.Literal['a', 'r', 's'] | None = None, \ |
| format_spec: str = '') |
| |
| Create a new :class:`!Interpolation` object from component parts. |
| |
| :param value: The evaluated, in-scope result of the interpolation. |
| :param expression: The text of a valid Python expression, |
| or an empty string. |
| :param conversion: The :ref:`conversion <formatstrings>` to be used, |
| one of ``None``, ``'a'``, ``'r'``, or ``'s'``. |
| :param format_spec: An optional, arbitrary string used as the |
| :ref:`format specification <formatspec>` to present the value. |
| |
| |
| Helper functions |
| ---------------- |
| |
| .. function:: convert(obj, /, conversion) |
| |
| Applies formatted string literal :ref:`conversion <formatstrings-conversion>` |
| semantics to the given object *obj*. |
| This is frequently useful for custom template string processing logic. |
| |
| Three conversion flags are currently supported: |
| |
| * ``'s'`` which calls :func:`str` on the value (like ``!s``), |
| * ``'r'`` which calls :func:`repr` (like ``!r``), and |
| * ``'a'`` which calls :func:`ascii` (like ``!a``). |
| |
| If the conversion flag is ``None``, *obj* is returned unchanged. |
