Update func.pyi with precise cache decorator type hints

Author: ashm-dev

stubs/cachetools/cachetools/func.pyi

@@ -1,16 +1,51 @@
-from _typeshed import IdentityFunction
 from collections.abc import Callable, Sequence
-from typing import TypeVar
+from typing import Any, Final, Generic, NamedTuple, TypeVar, overload
+
+__all__: Final = ("fifo_cache", "lfu_cache", "lru_cache", "rr_cache", "ttl_cache")
 
-__all__ = ("fifo_cache", "lfu_cache", "lru_cache", "rr_cache", "ttl_cache")
 _T = TypeVar("_T")
+_R = TypeVar("_R")
+
+class _CacheInfo(NamedTuple):
+    hits: int
+    misses: int
+    maxsize: int | None
+    currsize: int
+
+class _cachetools_cache_wrapper(Generic[_R]):
+    __wrapped__: Callable[..., _R]
+    def __call__(self, /, *args: Any, **kwargs: Any) -> _R: ...
+    def cache_info(self) -> _CacheInfo: ...
+    def cache_clear(self) -> None: ...
+    def cache_parameters(self) -> dict[str, Any]: ...
 
-def fifo_cache(maxsize: float | None = 128, typed: bool = False) -> IdentityFunction: ...
-def lfu_cache(maxsize: float | None = 128, typed: bool = False) -> IdentityFunction: ...
-def lru_cache(maxsize: float | None = 128, typed: bool = False) -> IdentityFunction: ...
+@overload
+def fifo_cache(
+    maxsize: int | None = 128, typed: bool = False
+) -> Callable[[Callable[..., _R]], _cachetools_cache_wrapper[_R]]: ...
+@overload
+def fifo_cache(maxsize: Callable[..., _R], typed: bool = False) -> _cachetools_cache_wrapper[_R]: ...
+@overload
+def lfu_cache(maxsize: int | None = 128, typed: bool = False) -> Callable[[Callable[..., _R]], _cachetools_cache_wrapper[_R]]: ...
+@overload
+def lfu_cache(maxsize: Callable[..., _R], typed: bool = False) -> _cachetools_cache_wrapper[_R]: ...
+@overload
+def lru_cache(maxsize: int | None = 128, typed: bool = False) -> Callable[[Callable[..., _R]], _cachetools_cache_wrapper[_R]]: ...
+@overload
+def lru_cache(maxsize: Callable[..., _R], typed: bool = False) -> _cachetools_cache_wrapper[_R]: ...
+@overload
 def rr_cache(
-    maxsize: float | None = 128, choice: Callable[[Sequence[_T]], _T] | None = ..., typed: bool = False
-) -> IdentityFunction: ...
+    maxsize: int | None = 128, choice: Callable[[Sequence[_T]], _T] | None = ..., typed: bool = False
+) -> Callable[[Callable[..., _R]], _cachetools_cache_wrapper[_R]]: ...
+@overload
+def rr_cache(
+    maxsize: Callable[..., _R], choice: Callable[[Sequence[_T]], _T] | None = ..., typed: bool = False
+) -> _cachetools_cache_wrapper[_R]: ...
+@overload
+def ttl_cache(
+    maxsize: int | None = 128, ttl: float = 600, timer: Callable[[], float] = ..., typed: bool = False
+) -> Callable[[Callable[..., _R]], _cachetools_cache_wrapper[_R]]: ...
+@overload
 def ttl_cache(
-    maxsize: float | None = 128, ttl: float = 600, timer: Callable[[], float] = ..., typed: bool = False
-) -> IdentityFunction: ...
+    maxsize: Callable[..., _R], ttl: float = 600, timer: Callable[[], float] = ..., typed: bool = False
+) -> _cachetools_cache_wrapper[_R]: ...