(🎁) Add a StubOnlyBase decorator for types that don't actually extend things, but do in the stubs (like Generic)

[KotlinIsland]

There are existing classes that extend things in an abstract way, like ABCs, and things that are Generic in theory but not in reality, for example all the collections (the collection classes are not Generics, they define __class_getitem__) and some are still not subscribe-able but state they are in the stubs, for instance _collections_abc.dict_keys or any of the collections pre 3.9.

It could be used something like:

# _collections_abc.pyi
@StubOnlyBase(KeysView[_KT_co], Generic[_KT_co, _VT_co])
class dict_keys:
    ...

# typing.pyi

@StubOnlyBase(Generic[_T])
class Container:
    if sys.version_info >= (3, 9):
        def __class_getitem__(???) -> ???:

@StubOnlyBase(Collection[_KT], Generic[_KT, _VT_co])
class Mapping(Collection):
    ...

Mapping doesn't actually extend Generic, but Container defines __class_getitem__, so that would also need to be updated in the stubs.

This might help resolve python/mypy#3186, but still indicate that it's not actually one of the bases.

# builtins.pyi
@StubOnlyBase(numbers.Integral)
class int:
    ...

I think a change like this would make the stubs much more understandable and closer to the actual implementation, also fixing issues about older python versions not working properly with the current stubs(python/mypy#11529).

I personally find it very confusing when referencing the stubs that the bases are often false.

No idea how this would be used in a real life annotation, but a workaround that works is:

from typing import _alias  # type: ignore[attr-defined]
from typing import TYPE_CHECKING
from _collections_abc import dict_keys

if not TYPE_CHECKING:
    dict_keys = _alias(dict_keys, 2)

def foo(dk: dict_keys[str, int]) -> None: ...

python/typeshed#6312 (comment)
python/typeshed#6257

Obligatory shill to #953, which I think would render this moot.

[AlexWaygood]

I like this idea! It would reduce the need for PRs like python/cpython#29355, which corrects an annoying inconsistency between the stub file and the runtime code, but is unlikely to get merged (no real use case, if we're honest).

[KotlinIsland]

Isn't the use case making the stubs more accurate mainly around type parameters?

[AlexWaygood]

That's the use case for making singledispatchmethod generic in the stubs, of course. But I, for one, have no real use case for being able to parameterize singledispatchmethod at runtime, other than wanting consistency with the stubs. Can you think of a situation when you'd want to use singledispatchmethod in a type annotation, and therefore need to parameterize it?

[KotlinIsland]

As per the OP, my use case is mainly around dict_keys and the rest of the collections pre 1.9, also registered abcs

[AlexWaygood]

I think we might be talking at cross purposes 🙂

As I said in my first message in this thread, I agree with your case — I like your idea! I was saying that there wasn't much of a use case for my previous PR to cpython that I linked to here, and that I liked your idea because it would reduce the need for PRs to cpython such as the one I linked to. My "no real use case, if we're honest" comment was referring to my PR to cpython, not your idea here 🙂

[not-my-profile]

I think python/typeshed#7436 would be a really nice use case for this.

The existing typing decorators all use snake_case, so I think this new decorator should also use snake case (in accordance with PEP 8). I don't think stub-only should be in the name, because afaik everything currently in typing can also be used in regular .py files, so I think we should keep it that way.

There already is @typing.type_check_only, so @typing.type_check_only_base_classes would be analogous ... it is however a bit too verbose for my liking. I think simply @typing.base_classes should be fine, what do you think?

I guess getting this into Python would require a PEP?

CC: @srittau, @JelleZijlstra