Three cases when the type doesn't work

ty says invalid-assignment in all three cases. See playground.

One function is decorated with functools.cache and Pylance says:

Type "list[_lru_cache_wrapper[int] | ((dd: int, /) -> int)]" is not assignable to declared type "list[CallableFunction[(int), int]]"
  "_lru_cache_wrapper[int]" is incompatible with protocol "CallableFunction[(int), int]"
    "__closure__" is not present
    "__code__" is not present
    "__defaults__" is not present
    "__globals__" is not present
    "__name__" is not present
    "__annotate__" is not present
    "__kwdefaults__" is not present

In the other two cases, the functions are not decorated, and Pylance objects to "__wrapped__" is not present

# Code
direction: CallableFunction[[int], int] = pos if 0 <=index else neg

# Diagnostic message
Type "((a: _SupportsPos[_T_co@pos], /) -> _T_co@pos) | ((a: _SupportsNeg[_T_co@neg], /) -> _T_co@neg)" is not assignable to declared type "CallableFunction[(int), int]"
  Type "((a: _SupportsPos[_T_co@pos], /) -> _T_co@pos) | ((a: _SupportsNeg[_T_co@neg], /) -> _T_co@neg)" is not assignable to type "CallableFunction[(int), int]"
    "FunctionType" is incompatible with protocol "CallableFunction[(int), int]"
      "__wrapped__" is not present
        "CallableFunction[P@CallableFunction, R@CallableFunction]" is not assignable to "FunctionType"
        "CallableFunction[P@CallableFunction, R@CallableFunction]" is not assignable to "FunctionType"
        "CallableFunction[P@CallableFunction, R@CallableFunction]" is not assignable to "FunctionType"

If I remove __wrapped__: Any from the CallableFunction class, all three Pylance errors go away, and the ty errors on the functions without @cache go away. I feel like I need to write __wrapped__: PassThroughAnnotation or something more specific than "Any," but the situation is too complex for me to understand.

Python’s static typing system cannot currently infer a generic return type from an “indirect” factory method unless the type variable is directly tied to an input parameter. That’s a limitation of how type variables are propagated in Python’s type checkers and the language’s typing design.

In particular:

Type variables (TypeVar) are only meaningful to type checkers when they are tied to a function’s signature in a way the checker can follow — usually as function arguments or bound to a class.

If you write a factory function that returns a type based on some internal logic without any connection between the return type and the signature’s type parameters, type checkers have no basis to infer the correct return type at call sites.

Python’s typing does not support “higher kinded types” or type inference from indirect logic — this is something discussed frequently but unresolved in the core typing design.

The canonical pattern that does work and is fully supported today looks like this:
from typing import Type, TypeVar

T = TypeVar("T")

def create_instance(cls: Type[T]) -> T:
# At runtime this will construct an instance of cls
return cls()

In this pattern:

The cls: Type[T] parameter connects the generic type variable T to an input parameter.

Static checkers like mypy or PyCharm can then reason that create_instance(Foo) returns a Foo.

Without this connection, no current type checker (including mypy, pyright, or the built-in stubs) can reliably infer the return type.

So although Python’s typing library has evolved significantly, there is no built-in mechanism today that allows a factory function to magically infer its generic return type from indirect logic alone. The recommended workaround is to ensure the type variable appears in the function signature in a way type checkers understand.

I think the main issue is that the protocol is trying to represent two different things: ordinary Python function objects and arbitrary callable objects.

Callable[P, R] includes callable instances, decorated functions, and built-in callables, but those don't necessarily expose the attributes of types.FunctionType.

In particular:

• __wrapped__ is not guaranteed to exist on ordinary functions. It is commonly added by decorators using functools.update_wrapper.
• functools.cache returns an _lru_cache_wrapper, which is callable but doesn't expose every attribute of an ordinary Python function.
• Requiring __code__, __closure__, and other function-specific attributes prevents the protocol from accepting many otherwise valid callables.

If your actual requirement is a callable with a __name__ attribute, I'd recommend a much smaller protocol:

from typing import Protocol

class NamedCallable[**P, R](Protocol):
    @property
    def __name__(self) -> str: ...

    def __call__(
        self,
        *args: P.args,
        **kwargs: P.kwargs,
    ) -> R: ...

This preserves the callable's parameter and return types while requiring only the additional attribute you need.

For example:

def double(value: int) -> int:
    return value * 2

fn: NamedCallable[[int], int] = double

print(fn.__name__)
print(fn(5))

However, this deliberately does not accept every Callable. Cached wrappers and callable objects may lack __name__, even though they can be called successfully.

If you need to support arbitrary callables, a fallback is more appropriate:

from collections.abc import Callable
from typing import Any

def callable_name(fn: Callable[..., Any]) -> str:
    return getattr(fn, "__name__", type(fn).__name__)

So I would avoid making CallableFunction a full replacement for Callable. Instead, define the smallest protocol that matches the attributes your application actually requires.

This avoids depending on implementation-specific function attributes and makes the intended structural contract clearer.