有效的标签名称

标签名称可以是任何未带点的名称，该名称不是现有有效的字符串或字节前缀，如 词法分析规范 中所示。因此，这些前缀不能用作标签

stringprefix: "r" | "u" | "R" | "U" | "f" | "F"
            : | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | "Rf" | "RF"

bytesprefix: "b" | "B" | "br" | "Br" | "bR" | "BR" | "rb" | "rB" | "Rb" | "RB"

Python 限制某些关键字 用作标识符。此限制也适用于标签名称。关键字的使用应触发有用的错误，就像最近的 CPython 版本中所做的那样。

标签必须紧接在引号之前

与其他字符串字面量前缀一样，标签和引号之间不能有空格。

PEP 701

标签字符串支持 PEP 701 的完整语法，因为任何字符串字面量，使用任何引号，都可以嵌套在插值中。当然，此嵌套包括标签字符串。

评估标签字符串

当标签字符串被求值时，标签必须有一个绑定，否则会引发 NameError；并且它必须是一个可调用对象，否则会引发 TypeError。可调用对象必须接受一系列位置参数。此行为遵循以下内容的去糖化：

trade = 'shrubberies'
mytag'Did you say "{trade}"?'

至

mytag(DecodedConcrete(r'Did you say "'), InterpolationConcrete(lambda: trade, 'trade', None, None), DecodedConcrete(r'"?'))

解码后的字符串

在 mytag'Did you say "{trade}"?' 示例中，有两个字符串：r'Did you say "' 和 r'"?'。

字符串在内部存储为具有 Decoded 结构的对象，这意味着：符合协议 Decoded

@runtime_checkable
class Decoded(Protocol):
    def __str__(self) -> str:
        ...

    raw: str

这些 Decoded 对象可以访问原始字符串。使用原始字符串是因为标签字符串旨在针对各种 DSL，例如 shell 和正则表达式。此类 DSL 对元字符（即反斜杠）有其自己的特定处理方式。

但是，通常需要“已处理”字符串，方法是像标准 Python 字符串一样解码字符串。在提议的实现中，解码对象的 __new__ 将 *存储* 原始字符串并 *存储和返回* “已处理”字符串。

该协议被标记为 @runtime_checkable 以允许结构化模式匹配测试协议而不是类型。这可能会产生很小的性能损失。由于 case 测试位于用户代码标签函数中，因此作者可以选择通过测试接下来讨论的实现类型来进行优化。

Decoded 协议将可从 typing 获取。在 CPython 中，Decoded 将在 C 中实现，但对于本 PEP 的讨论，以下是一个兼容的实现

class DecodedConcrete(str):
    _raw: str

    def __new__(cls, raw: str):
        decoded = raw.encode("utf-8").decode("unicode-escape")
        if decoded == raw:
            decoded = raw
        chunk = super().__new__(cls, decoded)
        chunk._raw = raw
        return chunk

    @property
    def raw(self):
        return self._raw

插值

Interpolation 是表示标签字符串内表达式的的数据结构。插值支持延迟求值模型，其中插值表达式被计算、转换、记忆化或以任何方式处理。

此外，插值表达式的原始文本可供标签函数使用。这对于调试或元编程很有用。

Interpolation 是一个将从 typing 中提供的 Protocol。其定义如下：

@runtime_checkable
class Interpolation(Protocol):
    def __len__(self):
        ...

    def __getitem__(self, index: int):
        ...

    def getvalue(self) -> Callable[[], Any]:
        ...

    expr: str
    conv: Literal["a", "r", "s"] | None
    format_spec: str | None

给定此插值示例

mytag'{trade!r:some-formatspec}'

这些属性如下：

• getvalue 是插值的一个零参数闭包。在本例中，lambda: trade。
• expr 是插值的表达式文本。例如：'trade'。
• conv 是标签函数将使用的可选转换，可以是 r、s 和 a 之一，分别对应 repr、str 和 ascii 转换。请注意，与 f 字符串一样，不支持其他转换。例如：'r'。
• format_spec 是可选的format_spec 字符串。如果 format_spec 包含任何表达式，则会在传递给标签函数之前对其进行急切求值。例如：'some-formatspec'。

在所有情况下，标签函数都决定如何处理有效的 Interpolation 属性。

在 CPython 参考实现中，使用 C 实现 Interpolation 将使用等效的结构序列对象（参见诸如 os.stat_result 之类的代码）。出于本 PEP 的目的，以下是一个纯 Python 实现的示例

class InterpolationConcrete(NamedTuple):
    getvalue: Callable[[], Any]
    expr: str
    conv: Literal['a', 'r', 's'] | None = None
    format_spec: str | None = None

插值表达式求值

插值的表达式求值与PEP 498 中相同，只是所有表达式始终隐式地用 lambda 包装。

从字符串中提取的表达式在标签字符串出现的上下文中进行求值。这意味着表达式可以完全访问其词法作用域，包括局部和全局变量。可以使用任何有效的 Python 表达式，包括函数和方法调用。

但是，还需要考虑一个额外的细微差别，即函数作用域 与注释作用域。考虑以下配置标题的稍微做作的示例

class CaptionConfig:
    tag = 'b'
    figure = f'<{tag}>Figure</{tag}>'

现在让我们尝试重写以上示例以使用标签字符串

class CaptionConfig:
    tag = 'b'
    figure = html'<{tag}>Figure</{tag}>'

不幸的是，如果使用通常的 lambda 包装来实现插值（即 lambda: tag），则此重写不起作用。当标签函数对插值进行求值时，将导致 NameError: name 'tag' is not defined。此名称错误的根本原因是 lambda: tag 使用函数作用域，因此无法使用定义 tag 的类定义。

即使使用 f 字符串，对标签字符串如何求值进行反糖化也会导致相同的 NameError；此处的 lambda 包装也使用函数作用域

class CaptionConfig:
    tag = 'b'
    figure = f'<{(lambda: tag)()}>Figure</{(lambda: tag)()}>'

对于标签字符串，出现此类 NameError 将令人惊讶。在使用标签字符串处理类变量的这种特定情况下，它也将是一个粗糙的边缘。毕竟，标签字符串应该支持 f 字符串功能的超集。

解决方案是为标签字符串插值使用注释作用域。虽然名称“注释作用域”暗示它仅与注释有关，但它通过在类定义（例如 tag）中词法解析名称来解决此问题，这与函数作用域不同。

因此，本 PEP 及其参考实现使用对注释作用域的支持。请注意，此用法与PEP 649 和PEP 695 的实现是可分离的部分，后者为注释提供了某种类似的延迟执行模型。相反，由标签函数评估任何插值。

有了注释作用域，插值中的 lambda 包装表达式就可以提供与 f 字符串相同的常用词法作用域。因此，无需使用 locals()、globals() 或使用 sys._getframe 进行框架内省来评估插值。此外，每个表达式的代码都可用，无需使用 inspect.getsource 或其他方法查找。

格式规范

如果未在标签字符串的对应插值中指定 format_spec，则默认为 None。

由于标签函数完全负责处理 Decoded 和 Interpolation 值，因此插值中的格式规范和转换没有所需的解释。例如，这是一个有效的用法

html'<div id={id:int}>{content:HTML|str}</div>'

在本例中，第二个插值的 format_spec 是字符串 'HTML|str'；由 html 标签决定在此处对“格式规范”执行什么操作（如果有的话）。

f-string 样式 = 求值

mytag'{expr=}' 的解析结果与 mytag'expr={expr}’ 相同，如问题 Add = to f-strings for easier debugging 中所实现。

标签函数参数

标签函数具有以下签名

def mytag(*args: Decoded | Interpolation) -> Any:
    ...

这对应于以下协议

class TagFunction(Protocol):
    def __call__(self, *args: Decoded | Interpolation) -> Any:
        ...

由于子类化，mytag 的签名当然可以扩展到以下内容，但代价是会损失一些类型特异性

def mytag(*args: str | tuple) -> Any:
    ...

用户可能会这样编写标签字符串：

def tag(*args):
    return args

tag"\N{{GRINNING FACE}}"

标签字符串会将其表示为正好一个 Decoded 参数。在本例中，Decoded.raw 将为 '\\N{GRINNING FACE}'。“已处理”的表示形式（通过编码和解码）将为

'\\N{GRINNING FACE}'.encode('utf-8').decode('unicode-escape')
'😀'

紧跟更多文本的命名 Unicode 字符仍将产生一个 Decoded 参数

def tag(*args):
    return args

assert tag"\N{{GRINNING FACE}}sometext" == (DecodedConcrete("😀sometext"),)

返回值

标签函数可以返回任何类型。通常它们会返回一个字符串，但可以通过返回更丰富的对象来构建更丰富的系统。请参见下面的示例。

函数应用

标签字符串的反糖化如下：

mytag'Hi, {name!s:format_spec}!'

这等效于

mytag(DecodedConcrete(r'Hi, '), InterpolationConcrete(lambda: name, 'name',
's', 'format_spec'), DecodedConcrete(r'!'))

不允许空解码字符串

解码和插值之间的交替很常见，但这取决于标签字符串。解码字符串的值永远不会为空字符串

mytag'{a}{b}{c}'

…这会导致以下反糖化

mytag(InterpolationConcrete(lambda: a, 'a', None, None), InterpolationConcrete(lambda: b, 'b', None, None), InterpolationConcrete(lambda: c, 'c', None, None))

同样

mytag''

…这会导致以下反糖化

mytag()

标签字符串中的 Python 语义

Python 模板语言和其他 DSL 具有与 Python 完全不同的语义。不同的作用域规则、不同的调用语义（例如宏）、它们自己的循环语法等等。

这意味着所有工具都需要为每种语言编写特殊支持。即使这样，通常也很难找到所有可能的作用域，例如自动完成值。

但是，f 字符串没有此问题。f 字符串被视为 Python 的一部分。花括号中的表达式按预期行为，并且值应根据常规作用域规则解析。像 mypy 这样的工具可以查看 f 字符串表达式内部，但可能永远不会查看 Jinja2 模板内部。

使用标签字符串编写的 DSL 将继承许多此值。虽然我们不能期望标准工具理解 DSL 中的“域”，但它们仍然可以检查 f 字符串中可表达的任何内容。

结构化模式匹配

使用结构化模式匹配迭代参数是许多标签函数实现的预期最佳实践。

def tag(*args: Decoded | Interpolation) -> Any:
    for arg in args:
        match arg:
            case Decoded() as decoded:
                ... # handle each decoded string
            case Interpolation() as interpolation:
                ... # handle each interpolation

惰性求值

上面示例标签函数中的每个函数都立即调用插值的 getvalue lambda。Python 开发人员经常希望 f-字符串可以被延迟或延迟求值。编写一个包装器将非常简单，例如，在调用 __str__ 时延迟调用 lambda。

记忆化

标签函数作者可以控制处理静态字符串部分和动态插值部分。为了提高性能，他们可以部署记忆处理方法，例如通过生成键。

求值顺序

假设一个标签生成 HTML 中的多个部分。该标签需要每个部分的输入。但是如果最后一个输入参数需要一段时间呢？在所有参数都可用之前，您无法返回第一部分的 HTML。

您希望在输入可用时发出标记。一些模板工具支持这种方法，标签字符串也支持。

启用 conv 和 format_spec 的精确往返

关于精确往返到原始源文本，有两个限制。

首先，format_spec 可以任意嵌套。

mytag'{x:{a{b{c}}}}'

在此 PEP 和相应的参考实现中，format_spec 被急切地求值以设置插值中的 format_spec，从而丢失原始表达式。

虽然在每个用法中保留往返是可行的，但这将需要一个额外的标志 equals 来支持，例如 {x=}，以及用于 format_spec 的递归 Interpolation 定义。以下是此类型的纯 Python 等效项，包括保留序列解包（如在 case 语句中使用）

class InterpolationConcrete(NamedTuple):
    getvalue: Callable[[], Any]
    raw: str
    conv: str | None = None
    format_spec: str | None | tuple[Decoded | Interpolation, ...] = None
    equals: bool = False

    def __len__(self):
        return 4

    def __iter__(self):
        return iter((self.getvalue, self.raw, self.conv, self.format_spec))

但是，支持精确往返的额外复杂性似乎没有必要，因此被拒绝。

不允许隐式字符串连接

不支持隐式标签字符串连接，这与其他字符串文字不同。

预期三引号就足够了。如果支持隐式字符串连接，标签评估的结果将需要支持使用 __add__ 和 __radd__ 的 + 运算符。

由于标签字符串针对嵌入式 DSL，因此这种复杂性会引入其他问题，例如确定合适的分隔符。这似乎不必要地复杂，因此被拒绝。

任意转换值

Python 仅允许 r、s 或 a 作为可能的转换类型值。尝试分配不同的值会导致 SyntaxError。

理论上，标签函数可以选择处理其他转换类型。但是此 PEP 严格遵循PEP 701。对允许值的任何更改都应在单独的 PEP 中进行。