Callable type aliases are counterintuitive and very far from callback Protocols

[Drino]

The context

I wanted to type hint a lot of decorator factories. So, I've started with writing a type for a decorator.

There are two approaches to do so - one is via typing.Callable and another is via typing.Protocol. According to PEP-544:

Callback protocols and Callable[...] types can be used interchangeably.

There are two ways of writing Protocol for a decorator:

1. PDecorator which has type variables in its __call__ method
2. PGenericDecorator[TCallable] which has a class-scope type variable

There is a code snippet with all the approaches (in mypy 0.971 and pyright running via Pylance v2022.8.10):

from typing import Any, Callable, Protocol, TypeAlias, TypeVar
from typing_extensions import reveal_type

TCallable = TypeVar('TCallable', bound=Callable[..., Any])

TDecorator: TypeAlias = Callable[[TCallable], TCallable]

class PDecorator(Protocol):
    def __call__(self, _: TCallable) -> TCallable:
        ...

class PGenericDecorator(Protocol[TCallable]):
    def __call__(self, _: TCallable) -> TCallable:
        ...

def factory_with_unbound_type_alias() -> TDecorator:
    ...

def factory_with_bound_type_alias() -> TDecorator[TCallable]:
    ...

def factory_with_protocol() -> PDecorator:
    ...

def factory_with_unbound_generic_protocol() -> PGenericDecorator:
    ...

def factory_with_bound_generic_protocol() -> PGenericDecorator[TCallable]:
    ...
# pyright: TypeVar "TCallable" appears only once in generic function signature

def some_function(request: Any) -> str:
    return 'Hello world'

reveal_type(factory_with_unbound_type_alias()(some_function)) 
# mypy: Revealed type is "Any"
# pyright: Type of "factory_with_unbound_type_alias()(some_function)" is "Unknown"
reveal_type(factory_with_bound_type_alias()(some_function))
# mypy: error: Argument 1 has incompatible type "Callable[[Any], str]"; expected <nothing>
# mypy: Revealed type is "<nothing>"
# pyright: Type of "factory_with_bound_type_alias()(some_function)" is "(request: Any) -> str"
reveal_type(factory_with_protocol()(some_function)) 
# mypy: Revealed type is "def (request: Any) -> builtins.str"
# pyright: Type of "factory_with_protocol()(some_function)" is "(request: Any) -> str"
reveal_type(factory_with_unbound_generic_protocol()(some_function)) 
# mypy: Revealed type is "Any"
# pyright: Type of "factory_with_unbound_generic_protocol()(some_function)" is "Unknown"
reveal_type(factory_with_bound_generic_protocol()(some_function))
# mypy: error: Argument 1 to "__call__" of "PGenericDecorator" has incompatible type "Callable[[Any], str]"; expected <nothing>
# mypy: Revealed type is "<nothing>"
# pyright: Type of "factory_with_bound_generic_protocol()(some_function)" is "Unknown"

So it seems that the only working both in mypy and pyright solution is non-generic protocol.

I'd also like to note that Callable itself is already very different from any other generic type, say:

from typing import TypeVar, Dict, Callable

T = TypeVar('T')

def callable_factory() -> Callable[[T], T]:
    ...

c = callable_factory()

reveal_type(c)
# mypy: Revealed type is "def [T] (T`-1) -> T`-1"
# pyright: Type of "c" is "(T@callable_factory) -> T@callable_factory"

def dict_factory() -> Dict[T, T]:
    ...
# mypy: error: Need type annotation for "d" (hint: "d: Dict[<type>, <type>] = ...")

d = dict_factory()

reveal_type(d) 
# mypy: Revealed type is "builtins.dict[Any, Any]"
# pyright: Type of "d" is "Dict[Unknown, Unknown]"

Related question
It seems pretty counterintuitive that Callable type alias is handled like any other generic type alias, having their type vars replaced with Unknown/Any. This behavior is not applied to Callable itself (as in snippet with -> Callable[[T], T]) and seem to be almost never desired.

Is this a bug or this behavior is actually intended?

One possible solution
If Callable or Callable-based type alias used in type annotation has an unbound type variable (maybe it should be used only in this Callable or alias) - assume that this type variable is call-scoped instead of being Unknown/Any.

This will make TDecorator equivalent to PDecorator.

Related discussions:
#1134
microsoft/pyright#3803

[Akuli]

Sorry about having to wait for an answer so long :)

You seem to be confused about what TDecorator: TypeAlias = Callable[[TCallable], TCallable] does. It makes a generic type alias. This means that TDecorator[str] is same as Callable[[str], str] for example. It's not typically used with Callable, but it has some uses: for example, typeshed's tkinter stubs originally used _TkinterSequence = list[T] | tuple[T, ...].

This means that factory_with_unbound_type_alias() -> TDecorator doesn't supply a generic argument like it should. factory_with_bound_type_alias() -> TDecorator[TCallable] is an attempt to fix it, but as you noticed, it has a problem: when pyright sees a function call like factory_with_bound_type_alias(), it immediately tries to solve the type variables used in the call. In this case, TCallable is only used once, in the return type, so pyright doesn't know what it should be. Mypy does this differently and uses the surrounding context (it is called type context in mypy) to figure out how to solve the TypeVar, and does what you expected it to do.

PDecorator fixes this by returning an object with a method that will use the TypeVar afterwards. Pyright then treats that usage as a whole new call, as you expected it to do. PGenericDecorator defeats the purpose by moving the TypeVar to the class: now the call to factory_with_bound_generic_protocol() again involves a TypeVar that is only used in the return type, and if you don't specify it as in factory_with_unbound_generic_protocol(), type checkers will assume Any/Unknown.

The tl;dr of this is:

• Mypy has type context. Pyright does not. To get consistent results, you indeed have to design things in a way where TypeVars are resolved within each function call as pyright does it, without having to know a broader context (type context) about what else happens in the surrounding code.
• Mypy and pyright treat unbounded generics differently: mypy uses its type context, pyright falls back to Unknown.

I would argue that this is not a bug in either type checker. They both have a well-defined approach and they work consistently in their own ways. Both approaches usually solve TypeVars as people expect them to be solved. I personally think pyright's behavior is better, as type context tends to cause all kinds of weird bugs (e.g. python/mypy#13351).

[Drino]

Thank you very much for the broad explanation! :)

I would argue that this is not a bug in either type checker.

It's definitely not a bug nor a major issue. From use-case perspective it seems that the only actual use for Callable shortcut is some kind of decorator (or, probably, comparator), so it can be achieved with Protocol and there is no trouble here.

Though, from my experience nobody manages to write working decorator shortcut on their first attempt (see this thread for example).

It will be really nice to have this behavior at least specifically documented somewhere.

P.S. It's great to hear that I'm not the only one introducing my own Sequence alias out there :D Was it intended to avoid accepting str as Sequence[str]?

[Akuli]

Typing decorators is tricky :) A good place to document it might be https://typing.readthedocs.io/en/latest/, probably under the "Guides" section. This documentation is generated from files in https://github.com/python/typing/tree/master/docs.

The intent with _TkinterSequence was to prevent people from using Sequence in tkinter stubs. Because tkinter is hard-coded to check for only lists and tuples, Sequene[str] is just wrong, because if you pass e.g. a deque object it won't work as expected. I later deleted _TkinterSequence because it showed up as _TkinterSequence[str] in autocompletions instead of the more meaningful list[str] | tuple[str, ...].