Incorrect explanation for PYI019

[henribru]

The explanation for PYI019 at https://docs.astral.sh/ruff/rules/custom-type-var-return-type/ seems incorrect to me. The rationale there applies when you use a fixed class as the return type (like what PYI034 flags), but not when you use a TypeVar. You can see that Mypy and Pyright both correctly infer return types on a subclass based on that example:

https://mypy-play.net/?mypy=latest&python=3.11&gist=523f6373f5a85dd8f78e8b7038d9d74d

https://pyright-play.net/?code=GYJw9gtgBALgngBwJYDsDmUkQWEMoAqiApgGoCGIAsAFC0D6AylALyEkUgAUAREzwEpatAMYAbcgGdJUAGJgwALlpRVUACbFgUevRTEA7rq7jJi2CQDaTALoAaKACpKaM1EkwQDx44DWBlzdUGAEoAFoAPh1GZRo1eKgAOmThOLVNbWAFLkliMWBzJgcXcwAjOBhiSVDI6NiEtWTE1PiAAXEpSQhiGAALMHUVdK0oUsoTMTd4BGJrRnsoEswUEPCopnqGpJS0htEJaSgAIXH5MAFzJtSQYgA3YnIxemniLhPuASEaG-vH55I3uMBIksmAuKUeIIvj8Hk8XoCQIkxtwAMyfIA

The PEP for Self also shows the TypeVar variant as being equivalent, but describes Self as "more intuitive and succinct". flake8-pyi doesn't really explain the rationale for the rule in their explanation, but based on this I assume it's actually just meant to be stylistic. If so Ruff's explanation should reflect this.

[charliermarsh]

\cc @AlexWaygood - only if quick / easy for you, do you know if Y019 is about clearer style / intent, or correctness?

[AlexWaygood]

@henribru is correct — Y019 is purely concerned with style, not with correctness (though it is slightly easier to be correct if you use the more modern syntax — in a .py file, you don't have to worry about binding the TypeVar to a forward reference etc :)

The "use instead" snippet ruff gives in the docs also isn't ideal — currently it's this:

from typing import Self


class Foo:
    def __new__(cls: type[Self], *args: str, **kwargs: int) -> Self:
        ...

    def foo(self: Self, arg: bytes) -> Self:
        ...

    @classmethod
    def bar(cls: type[Self], arg: int) -> Self:
        ...

But part of the point of typing.Self is that (unlike a normal TypeVar) you can skip the annotations on cls or self — so a better "use instead" snippet would be this:

from typing import Self


class Foo:
    def __new__(cls, *args: str, **kwargs: int) -> Self:
        ...

    def foo(self, arg: bytes) -> Self:
        ...

    @classmethod
    def bar(cls, arg: int) -> Self:
        ...

[charliermarsh]

Awesome, thanks @AlexWaygood for the characteristically clear + through answer! Will fix.

[AlexWaygood]

I just overhauled our flake8-pyi docs in PyCQA/flake8-pyi@504ef82, so hopefully it should be a bit clearer in the future to figure out what the motivation is for each of our rules :)