Improve template typing with specialized version

[JoniKauf]

This is the basic idea I had to improve typing for templates:

from collections.abc import Iterator
from types import GenericAlias
from typing import Any, Generic, Literal, TypeVar, final, overload, TypeAlias

_T = TypeVar("_T")
_T1_co = TypeVar("_T1_co", covariant=True)
_T2_co = TypeVar("_T2_co", covariant=True)


class __BaseTypingTemplate:
    @overload
    def __new__(cls, *args: str) -> __Special0.Template: ...
    @overload
    def __new__(cls, arg1: str, arg2: Interpolation[_T1_co], /, *args: str) -> __Special1.Template[_T1_co]: ...
    @overload
    def __new__(cls, arg1: str, arg2: Interpolation[_T1_co], arg3: str, arg4: Interpolation[_T2_co], /, *args: str) -> __Special2.Template[_T1_co, _T2_co]: ...

    @overload
    def __new__(cls, *args: str | Interpolation[Any]) -> Template: ...

    def __class_getitem__(cls, item: Any, /) -> GenericAlias: ...
    
    
@final
class Template(__BaseTypingTemplate):
    strings: tuple[str, ...]
    interpolations: tuple[Interpolation[Any], ...]
    
    def __iter__(self) -> Iterator[str | Interpolation[Any]]: ...
    
    def __add__(self, other: Template | __Special0.Template | __Special1.Template, /) -> Template: ...
    
    @property
    def values(self) -> tuple[Any, ...]: ...

__GeneralTemplate = Template  # Alias we need in the specialized classes to make referencing it possible

class __Special0:
    @final
    class Template(__BaseTypingTemplate):
        strings: tuple[str]
        interpolations: tuple[()]

        def __iter__(self) -> Iterator[str]: ...

        @overload
        def __add__(self, other: __GeneralTemplate, /) -> __GeneralTemplate: ...
        @overload
        def __add__(self, other: __Special0.Template, /) -> __Special0.Template: ...
        @overload
        def __add__(self, other: __Special1.Template[_T1_co], /) -> __Special1.Template[_T1_co]: ...
        @overload
        def __add__(self, other: __Special2.Template[_T1_co, _T2_co], /) -> __Special2.Template[_T1_co, _T2_co]: ...

        @property
        def values(self) -> tuple[()]: ...
        
       
class __Special1:
    @final
    class Template(__BaseTypingTemplate, Generic[_T1_co]):
        strings: tuple[str, str]
        interpolations: tuple[Interpolation[_T1_co]]

        def __iter__(self) -> Iterator[str | Interpolation[_T1_co]]: ...

        @overload
        def __add__(self, other: __GeneralTemplate, /) -> __GeneralTemplate: ...
        @overload
        def __add__(self, other: __Special0.Template, /) -> __Special1.Template[_T1_co]: ...
        @overload
        def __add__(self, other: __Special1.Template[_T2_co], /) -> __Special2.Template[_T1_co, _T2_co]: ...
        @overload
        def __add__(self, other: __Special2.Template[_T1_co, _T2_co], /) -> __GeneralTemplate: ...  # 3 but we stop at 2 for now

        @property
        def values(self) -> tuple[_T1_co]: ...

class __Special2:
    @final
    class Template(__BaseTypingTemplate, Generic[_T1_co, _T2_co]):
        strings: tuple[str, str, str]
        interpolations: tuple[Interpolation[_T1_co], Interpolation[_T2_co]]

        def __iter__(self) -> Iterator[str | Interpolation[_T1_co] | Interpolation[_T2_co]]: ...
        def __add__(self, other: Template, /) -> Template: ...
        
        @property
        def values(self) -> tuple[_T1_co, _T2_co]: ...

@final
class Interpolation(Generic[_T1_co]):
    value: _T1_co
    expression: str
    conversion: Literal["a", "r", "s"] | None
    format_spec: str

    __match_args__ = ("value", "expression", "conversion", "format_spec")

    def __new__(
        cls, value: _T1_co, expression: str = "", conversion: Literal["a", "r", "s"] | None = None, format_spec: str = ""
    ) -> Interpolation[_T1_co]: ...
    def __class_getitem__(cls, item: Any, /) -> GenericAlias: ...

@overload
def convert(obj: _T, /, conversion: None) -> _T: ...
@overload
def convert(obj: object, /, conversion: Literal["r", "s", "a"]) -> str: ...

Side note: Before, the interpolation's value was invariant instead of covariant. I'm not sure why exactly, since interpolations and templates only have readonly attributes. For now I made them covariant.

My idea is basically making specialized version of Template. Since "class overloading" is not really a thing, this was the idea I came up with. We have the __SpecialX namespaces to be able to create multiple Template classes. Everything that should not be exposed I made "private", aka double underscored. Alternatively we could del of course.

What you might also notice is that the __new__ method always switches between str and Interpolation, exactly like __iter__ returns elements. This design choice has multiple reasons:

• This matches the __iter__ output and how (I think) templates are stored internally and therefore it would make it very easy for type checkers to support literal templates (t"...") with these specialized versions. Any literal could just be interpreted as a __new__ call and it would make their typing much better as well.
• This is the minimal way fully represent any template (up to n specialized templates we would support). If we removed some str args in the middle, then we would have to do so for every combination. This would already explode the amount of overloads. If we would add more str args, this would be even worse.
• The final args of str allows for more str elements at the end for free. Having args in the middle or multiple times is not possible or logically sound.

This example only shows up to 2 interpolations. I would type it up to at least 8 interpolations.
Also, the base class is there for convenience and maybe could be factored out.

In summary I think this would be the perfect addition, especially to make it easy for type checkers to have more support the literal template syntax better.

What are your thoughts? Generally a good idea or some worries? Anything that could be simplified?

[JelleZijlstra]

Are there significant use cases for templates with exactly N interpolations? I'm worried for most users this sort of thing will just overcomplicate use of templates and not help.

Most use cases I've seen for templates (e.g. logging, SQL queries) would involve templates that can hold any number of interpolations, of somewhat restricted types.

[JoniKauf]

I know that I would use definitely it. It not only helps with the amount, but also to specify only certain allowed types.

For example I have a mini library I wanna publish that also needs a template with exactly one interpolation. In that library I would also use the type of that single interpolation as a generic return type of the function that takes in the template.