Add string.templatelib in 3.14 (#14044)

stdlib/string/__init__.pyi

@@ -0,0 +1,76 @@
+import sys
+from _typeshed import StrOrLiteralStr
+from collections.abc import Iterable, Mapping, Sequence
+from re import Pattern, RegexFlag
+from typing import Any, ClassVar, overload
+from typing_extensions import LiteralString
+
+__all__ = [
+    "ascii_letters",
+    "ascii_lowercase",
+    "ascii_uppercase",
+    "capwords",
+    "digits",
+    "hexdigits",
+    "octdigits",
+    "printable",
+    "punctuation",
+    "whitespace",
+    "Formatter",
+    "Template",
+]
+
+ascii_letters: LiteralString
+ascii_lowercase: LiteralString
+ascii_uppercase: LiteralString
+digits: LiteralString
+hexdigits: LiteralString
+octdigits: LiteralString
+punctuation: LiteralString
+printable: LiteralString
+whitespace: LiteralString
+
+def capwords(s: StrOrLiteralStr, sep: StrOrLiteralStr | None = None) -> StrOrLiteralStr: ...
+
+class Template(metaclass=type):
+    template: str
+    delimiter: ClassVar[str]
+    idpattern: ClassVar[str]
+    braceidpattern: ClassVar[str | None]
+    flags: ClassVar[RegexFlag]
+    pattern: ClassVar[Pattern[str]]
+    def __init__(self, template: str) -> None: ...
+    def substitute(self, mapping: Mapping[str, object] = {}, /, **kwds: object) -> str: ...
+    def safe_substitute(self, mapping: Mapping[str, object] = {}, /, **kwds: object) -> str: ...
+    if sys.version_info >= (3, 11):
+        def get_identifiers(self) -> list[str]: ...
+        def is_valid(self) -> bool: ...
+
+class Formatter:
+    @overload
+    def format(self, format_string: LiteralString, /, *args: LiteralString, **kwargs: LiteralString) -> LiteralString: ...
+    @overload
+    def format(self, format_string: str, /, *args: Any, **kwargs: Any) -> str: ...
+    @overload
+    def vformat(
+        self, format_string: LiteralString, args: Sequence[LiteralString], kwargs: Mapping[LiteralString, LiteralString]
+    ) -> LiteralString: ...
+    @overload
+    def vformat(self, format_string: str, args: Sequence[Any], kwargs: Mapping[str, Any]) -> str: ...
+    def _vformat(  # undocumented
+        self,
+        format_string: str,
+        args: Sequence[Any],
+        kwargs: Mapping[str, Any],
+        used_args: set[int | str],
+        recursion_depth: int,
+        auto_arg_index: int = 0,
+    ) -> tuple[str, int]: ...
+    def parse(
+        self, format_string: StrOrLiteralStr
+    ) -> Iterable[tuple[StrOrLiteralStr, StrOrLiteralStr | None, StrOrLiteralStr | None, StrOrLiteralStr | None]]: ...
+    def get_field(self, field_name: str, args: Sequence[Any], kwargs: Mapping[str, Any]) -> Any: ...
+    def get_value(self, key: int | str, args: Sequence[Any], kwargs: Mapping[str, Any]) -> Any: ...
+    def check_unused_args(self, used_args: set[int | str], args: Sequence[Any], kwargs: Mapping[str, Any]) -> None: ...
+    def format_field(self, value: Any, format_spec: str) -> Any: ...
+    def convert_field(self, value: Any, conversion: str | None) -> Any: ...

stdlib/string/templatelib.pyi

@@ -0,0 +1,28 @@
+from collections.abc import Iterator
+from typing import Any, Literal, final
+
+__all__ = ["Interpolation", "Template"]
+
+@final
+class Template:  # TODO: consider making `Template` generic on `TypeVarTuple`
+    strings: tuple[str, ...]
+    interpolations: tuple[Interpolation, ...]
+
+    def __new__(cls, *args: str | Interpolation) -> Template: ...
+    def __iter__(self) -> Iterator[str | Interpolation]: ...
+    def __add__(self, other: Template | str) -> Template: ...
+    @property
+    def values(self) -> tuple[Any, ...]: ...  # Tuple of interpolation values, which can have any type
+
+@final
+class Interpolation:
+    value: Any  # TODO: consider making `Interpolation` generic in runtime
+    expression: str
+    conversion: Literal["a", "r", "s"] | None
+    format_spec: str
+
+    __match_args__ = ("value", "expression", "conversion", "format_spec")
+
+    def __new__(
+        cls, value: Any, expression: str, conversion: Literal["a", "r", "s"] | None = None, format_spec: str = ""
+    ) -> Interpolation: ...