improve lru_cache by using ParamSpec

stdlib/functools.pyi

@@ -2,8 +2,8 @@ import sys
 import types
 from _typeshed import Self, SupportsAllComparisons, SupportsItems
 from collections.abc import Callable, Hashable, Iterable, Sequence, Sized
-from typing import Any, Generic, NamedTuple, TypeVar, overload
-from typing_extensions import Literal, TypeAlias, final
+from typing import Any, Generic, NamedTuple, Protocol, TypeVar, overload
+from typing_extensions import Concatenate, Literal, ParamSpec, TypeAlias, final
 
 if sys.version_info >= (3, 9):
     from types import GenericAlias
@@ -57,8 +57,10 @@ else:
 
 _AnyCallable: TypeAlias = Callable[..., Any]
 
+_P = ParamSpec("_P")
 _T = TypeVar("_T")
 _S = TypeVar("_S")
+_R = TypeVar("_R")
 
 @overload
 def reduce(function: Callable[[_T, _S], _T], sequence: Iterable[_S], initial: _T) -> _T: ...
@@ -72,22 +74,48 @@ class _CacheInfo(NamedTuple):
     currsize: int
 
 @final
-class _lru_cache_wrapper(Generic[_T]):
-    __wrapped__: Callable[..., _T]
-    def __call__(self, *args: Hashable, **kwargs: Hashable) -> _T: ...
+class _lru_cache_wrapper_0(Generic[_P, _R]):
+    @property
+    def __wrapped__(self) -> Callable[_P, _R]: ...
+    def __call__(self, *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
+    def cache_info(self) -> _CacheInfo: ...
+    def cache_clear(self) -> None: ...
+    def __copy__(self) -> _lru_cache_wrapper_0[_P, _R]: ...
+    def __deepcopy__(self, __memo: Any) -> _lru_cache_wrapper_0[_P, _R]: ...
+
+@final
+class _lru_cache_wrapper(Generic[_S, _P, _R]):
+    @property
+    def __wrapped__(self) -> Callable[Concatenate[_S, _P], _R]: ...
+    def __call__(self, arg0: _S, *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
     def cache_info(self) -> _CacheInfo: ...
     def cache_clear(self) -> None: ...
-    def __copy__(self) -> _lru_cache_wrapper[_T]: ...
-    def __deepcopy__(self, __memo: Any) -> _lru_cache_wrapper[_T]: ...
+    def __copy__(self) -> _lru_cache_wrapper[_S, _P, _R]: ...
+    def __deepcopy__(self, __memo: Any) -> _lru_cache_wrapper[_S, _P, _R]: ...
+    def __get__(self, inst: object, owner: type) -> _lru_cache_wrapper_0[_P, _R]: ...
+
+class _LRUCacheDecorator(Protocol):
+    @overload
+    def __call__(self, func: Callable[Concatenate[_S, _P], _R]) -> _lru_cache_wrapper[_S, _P, _R]: ...
+    @overload
+    def __call__(self, func: Callable[_P, _R]) -> _lru_cache_wrapper_0[_P, _R]: ...
 
 if sys.version_info >= (3, 8):
     @overload
-    def lru_cache(maxsize: int | None = ..., typed: bool = ...) -> Callable[[Callable[..., _T]], _lru_cache_wrapper[_T]]: ...
+    def lru_cache(maxsize: int | None = ..., typed: bool = ...) -> _LRUCacheDecorator: ...
+    @overload
+    def lru_cache(maxsize: Callable[Concatenate[_S, _P], _R], typed: bool = ...) -> _lru_cache_wrapper[_S, _P, _R]: ...
     @overload
-    def lru_cache(maxsize: Callable[..., _T], typed: bool = ...) -> _lru_cache_wrapper[_T]: ...
+    def lru_cache(maxsize: Callable[_P, _R], typed: bool = ...) -> _lru_cache_wrapper_0[_P, _R]: ...
 
 else:
-    def lru_cache(maxsize: int | None = ..., typed: bool = ...) -> Callable[[Callable[..., _T]], _lru_cache_wrapper[_T]]: ...
+    def lru_cache(maxsize: int | None = ..., typed: bool = ...) -> _LRUCacheDecorator: ...
+
+if sys.version_info >= (3, 9):
+    @overload
+    def cache(__user_function: Callable[Concatenate[_S, _P], _R]) -> _lru_cache_wrapper[_S, _P, _R]: ...
+    @overload
+    def cache(__user_function: Callable[_P, _R]) -> _lru_cache_wrapper_0[_P, _R]: ...
 
 WRAPPER_ASSIGNMENTS: tuple[
     Literal["__module__"], Literal["__name__"], Literal["__qualname__"], Literal["__doc__"], Literal["__annotations__"],
@@ -178,9 +206,6 @@ if sys.version_info >= (3, 8):
         if sys.version_info >= (3, 9):
             def __class_getitem__(cls, item: Any) -> GenericAlias: ...
 
-if sys.version_info >= (3, 9):
-    def cache(__user_function: Callable[..., _T]) -> _lru_cache_wrapper[_T]: ...
-
 def _make_key(
     args: tuple[Hashable, ...],
     kwds: SupportsItems[Any, Any],