CallableFunction as a drop-in replacement for Callable

[hunterhogan]

Not all Callable have the __name__ attribute. See, for example, "Why does ty say Callable has no attribute __name__?". That looks like a difficult problem to solve, so I've attempted to create a type I can use temporarily while the experienced programmers work on a permanent solution.

I learned about this issue because of a function in my tests. The type below works as a replacement for my one function. See ty playground. But that doesn't mean much.

I've mashed-up annotations from typeshed, then "refined" the code by running it through different LLMs and trying to separate the good advice from the bad advice.

Frankly, this is beyond my ability to evaluate. The type below may be so flawed that I should start over. If this is a decent start, I don't know how to find the parts that need improvement. Therefore, I would love some feedback.

"""Protocol for callable functions with full type safety."""
from collections.abc import Callable
from types import CellType, CodeType, MethodType
from typing import Any, overload, ParamSpec, Protocol, runtime_checkable, Self, TypeVar, TypeVarTuple
import sys

#======== Stolen, uh, I mean copied from typeshed:stdlib\_typeshed\__init__.pyi ========
type AnnotationForm = Any

if sys.version_info >= (3, 14):
	from annotationlib import Format

# NOTE These return annotations, which can be arbitrary objects
	type AnnotateFunc = Callable[[Format], dict[str, AnnotationForm]]
	type EvaluateFunc = Callable[[Format], AnnotationForm]
#======== End stolen, uh, I mean copied from typeshed:stdlib\_typeshed\__init__.pyi ========

@runtime_checkable
class CallableFunction[**P, R](Protocol):
	"""A Protocol representing callable functions with descriptor support.

	Mimics types.FunctionType while being a drop-in replacement for `collections.abc.Callable`. Includes all standard function
	attributes and the descriptor protocol for proper method binding.

	Note: @runtime_checkable only validates attribute presence, not signatures.
	"""

# NOTE: The eehhhh, IDK... section
	__doc__: str | None
	__wrapped__: Any  # Allegedly, for functools.wraps support
# NOTE: End eehhhh, IDK... section

	@property
	def __closure__(self) -> tuple[CellType, ...] | None:
		"""Tuple of cells that contain bindings for the function's free variables."""
		...
	__code__: CodeType
	__defaults__: tuple[Any, ...] | None
	__dict__: dict[str, Any]
	@property
	def __globals__(self) -> dict[str, Any]:
		"""The global namespace in which the function was defined."""
		...
	__name__: str
	__qualname__: str
	__annotations__: dict[str, AnnotationForm]
	if sys.version_info >= (3, 14):
		__annotate__: AnnotateFunc | None
	__kwdefaults__: dict[str, Any] | None
	@property
	def __builtins__(self) -> dict[str, Any]:
		"""The built-in namespace in which the function was defined."""
		...
	__type_params__: tuple[TypeVar | ParamSpec | TypeVarTuple, ...]
	__module__: str

	def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
		"""Execute the callable with the given arguments."""
		...

	@overload
	def __get__(self, instance: None, owner: type, /) -> Self: ...
	@overload
	def __get__(self, instance: object, owner: type | None = None, /) -> MethodType: ...
	def __get__(self, instance: object | None, owner: type | None = None) -> Self | MethodType:
		"""Descriptor protocol for method binding.

		Returns self when accessed on the class, or a bound MethodType when accessed on an instance.
		"""
		...

[hunterhogan]

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.