Improve template typing with specialized version

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?

Aucun fichier cible, test ou point d’entrée n’est nommé. Commencez par examiner les signatures proposées de Template, specialized Template, Interpolation et convert, puis cherchez un accord sur la conception et le nombre d’interpolations prises en charge avant de définir ce que devrait inclure la couverture de typage complète.