Improve original type stubs from typeshed.

Author: tkem

src/cachetools/__init__.pyi

@@ -1,25 +1,43 @@
-from _typeshed import IdentityFunction, Unused
+import random
 from collections.abc import Callable, Iterator, MutableMapping, Sequence
 from contextlib import AbstractContextManager
-from threading import Condition
-from typing import Any, Generic, Literal, NamedTuple, TypeVar, overload, type_check_only
-from typing_extensions import Self, deprecated
-
-from . import keys
-
-__all__ = ("Cache", "FIFOCache", "LFUCache", "LRUCache", "RRCache", "TLRUCache", "TTLCache", "cached", "cachedmethod")
+from typing import (
+    Any,
+    Final,
+    Generic,
+    Literal,
+    NamedTuple,
+    Protocol,
+    TypeVar,
+    overload,
+    type_check_only,
+)
+
+__all__: Final = (
+    "Cache",
+    "FIFOCache",
+    "LFUCache",
+    "LRUCache",
+    "RRCache",
+    "TLRUCache",
+    "TTLCache",
+    "cached",
+    "cachedmethod",
+)
 __version__: str
 
 _KT = TypeVar("_KT")
 _VT = TypeVar("_VT")
+_TT = TypeVar("_TT", default=float)
 _T = TypeVar("_T")
 _R = TypeVar("_R")
+_KT2 = TypeVar("_KT2")
+_VT2 = TypeVar("_VT2")
 
 class Cache(MutableMapping[_KT, _VT]):
-    @overload
-    def __init__(self, maxsize: float, getsizeof: Callable[[_VT], float]) -> None: ...
-    @overload
-    def __init__(self, maxsize: float, getsizeof: None = None) -> None: ...
+    def __init__(
+        self, maxsize: float, getsizeof: Callable[[_VT], float] | None = None
+    ) -> None: ...
     def __getitem__(self, key: _KT) -> _VT: ...
     def __setitem__(self, key: _KT, value: _VT) -> None: ...
     def __delitem__(self, key: _KT) -> None: ...
@@ -43,111 +61,153 @@ class LFUCache(Cache[_KT, _VT]): ...
 class LRUCache(Cache[_KT, _VT]): ...
 
 class RRCache(Cache[_KT, _VT]):
-    @overload
-    def __init__(self, maxsize: float, choice: None = None, getsizeof: None = None) -> None: ...
-    @overload
-    def __init__(self, maxsize: float, *, getsizeof: Callable[[_VT], float]) -> None: ...
-    @overload
-    def __init__(self, maxsize: float, choice: None, getsizeof: Callable[[_VT], float]) -> None: ...
-    @overload
-    def __init__(self, maxsize: float, choice: Callable[[Sequence[_KT]], _KT], getsizeof: None = None) -> None: ...
-    @overload
-    def __init__(self, maxsize: float, choice: Callable[[Sequence[_KT]], _KT], getsizeof: Callable[[_VT], float]) -> None: ...
+    def __init__(
+        self,
+        maxsize: float,
+        choice: Callable[[Sequence[_KT]], _KT] = random.choice,
+        getsizeof: Callable[[_VT], float] | None = None,
+    ) -> None: ...
     @property
     def choice(self) -> Callable[[Sequence[_KT]], _KT]: ...
-    def __setitem__(self, key: _KT, value: _VT, cache_setitem: Callable[[Self, _KT, _VT], None] = ...) -> None: ...
-    def __delitem__(self, key: _KT, cache_delitem: Callable[[Self, _KT], None] = ...) -> None: ...
 
-class _TimedCache(Cache[_KT, _VT]):
-    @overload
-    def __init__(self, maxsize: float, timer: Callable[[], float] = ..., getsizeof: None = None) -> None: ...
-    @overload
-    def __init__(self, maxsize: float, timer: Callable[[], float], getsizeof: Callable[[_VT], float]) -> None: ...
-    @overload
-    def __init__(self, maxsize: float, timer: Callable[[], float] = ..., *, getsizeof: Callable[[_VT], float]) -> None: ...
-    @property
-    def currsize(self) -> float: ...
+class _TimedCache(Cache[_KT, _VT], Generic[_KT, _VT, _TT]):
+    def __init__(
+        self,
+        maxsize: float,
+        timer: Callable[[], _TT],
+        getsizeof: Callable[[_VT], float] | None = None,
+    ) -> None: ...
 
-    class _Timer:
-        def __init__(self, timer: Callable[[], float]) -> None: ...
-        def __call__(self) -> float: ...
-        def __enter__(self) -> float: ...
-        def __exit__(self, *exc: Unused) -> None: ...
+    class _Timer(AbstractContextManager[_T]):
+        def __init__(self, timer: Callable[[], _T]) -> None: ...
+        def __call__(self) -> _T: ...
+        def __enter__(self) -> _T: ...
+        def __exit__(self, *exc: object) -> None: ...
+        def __getattr__(self, name: str) -> Any: ...
 
     @property
-    def timer(self) -> _Timer: ...
+    def timer(self) -> _Timer[_TT]: ...
 
-class TTLCache(_TimedCache[_KT, _VT]):
-    @overload
-    def __init__(self, maxsize: float, ttl: float, timer: Callable[[], float] = ..., getsizeof: None = None) -> None: ...
+class TTLCache(_TimedCache[_KT, _VT, _TT]):
     @overload
-    def __init__(self, maxsize: float, ttl: float, timer: Callable[[], float], getsizeof: Callable[[_VT], float]) -> None: ...
+    def __init__(
+        self: TTLCache[_KT2, _VT2, float],
+        maxsize: float,
+        ttl: float,
+        *,
+        getsizeof: Callable[[_VT2], float] | None = None,
+    ) -> None: ...
     @overload
     def __init__(
-        self, maxsize: float, ttl: float, timer: Callable[[], float] = ..., *, getsizeof: Callable[[_VT], float]
+        self,
+        maxsize: float,
+        ttl: Any,  # FIXME: must be "addable" to _TT
+        timer: Callable[[], _TT],
+        getsizeof: Callable[[_VT], float] | None = None,
     ) -> None: ...
     @property
-    def ttl(self) -> float: ...
-    def expire(self, time: float | None = None) -> list[tuple[_KT, _VT]]: ...
+    def ttl(self) -> Any: ...
+    def expire(self, time: _TT | None = None) -> list[tuple[_KT, _VT]]: ...
 
-class TLRUCache(_TimedCache[_KT, _VT]):
+class TLRUCache(_TimedCache[_KT, _VT, _TT]):
+    @overload
+    def __init__(
+        self: TLRUCache[_KT2, _VT2, float],
+        maxsize: float,
+        ttu: Callable[[_KT2, _VT2, float], float],
+        *,
+        getsizeof: Callable[[_VT2], float] | None = None,
+    ) -> None: ...
+    @overload
     def __init__(
         self,
         maxsize: float,
-        ttu: Callable[[_KT, _VT, float], float],
-        timer: Callable[[], float] = ...,
+        ttu: Callable[[_KT, _VT, _TT], _TT],
+        timer: Callable[[], _TT],
         getsizeof: Callable[[_VT], float] | None = None,
     ) -> None: ...
     @property
-    def ttu(self) -> Callable[[_KT, _VT, float], float]: ...
-    def expire(self, time: float | None = None) -> list[tuple[_KT, _VT]]: ...
+    def ttu(self) -> Callable[[_KT, _VT, _TT], _TT]: ...
+    def expire(self, time: _TT | None = None) -> list[tuple[_KT, _VT]]: ...
 
 class _CacheInfo(NamedTuple):
     hits: int
     misses: int
-    maxsize: int | None
-    currsize: int
+    maxsize: float | None
+    currsize: float
+
+@type_check_only
+class _AbstractCondition(AbstractContextManager[Any], Protocol):
+    # implementation and unit tests do not use plain wait() and notify()
+    def wait(self, timeout: float | None = None) -> bool: ...
+    def wait_for(
+        self, predicate: Callable[[], _T], timeout: float | None = None
+    ) -> _T: ...
+    def notify(self, n: int = 1) -> None: ...
+    def notify_all(self) -> None: ...
 
 @type_check_only
 class _cached_wrapper(Generic[_R]):
     __wrapped__: Callable[..., _R]
+    __name__: str
+    __doc__: str | None
+    cache: MutableMapping[Any, Any] | None
+    cache_key: Callable[..., Any] = ...
+    cache_lock: AbstractContextManager[Any] | None = None
+    cache_condition: _AbstractCondition | None = None
     def __call__(self, /, *args: Any, **kwargs: Any) -> _R: ...
+    def cache_clear(self) -> None: ...
 
 @type_check_only
 class _cached_wrapper_info(_cached_wrapper[_R]):
     def cache_info(self) -> _CacheInfo: ...
-    def cache_clear(self) -> None: ...
 
 @overload
 def cached(
     cache: MutableMapping[_KT, Any] | None,
     key: Callable[..., _KT] = ...,
     lock: AbstractContextManager[Any] | None = None,
-    condition: Condition | None = None,
+    condition: _AbstractCondition | None = None,
     info: Literal[True] = ...,
 ) -> Callable[[Callable[..., _R]], _cached_wrapper_info[_R]]: ...
 @overload
 def cached(
     cache: MutableMapping[_KT, Any] | None,
     key: Callable[..., _KT] = ...,
     lock: AbstractContextManager[Any] | None = None,
-    condition: Condition | None = None,
+    condition: _AbstractCondition | None = None,
     info: Literal[False] = ...,
 ) -> Callable[[Callable[..., _R]], _cached_wrapper[_R]]: ...
 
+@type_check_only
+class _cachedmethod_wrapper(Generic[_R]):
+    __wrapped__: Callable[..., _R]
+    __name__: str
+    __doc__: str | None
+    cache: MutableMapping[Any, Any] | None
+    cache_key: Callable[..., Any] = ...
+    cache_lock: AbstractContextManager[Any] | None = None
+    cache_condition: _AbstractCondition | None = None
+    def __call__(self, /, *args: Any, **kwargs: Any) -> _R: ...
+    def cache_clear(self) -> None: ...
+
+@type_check_only
+class _cachedmethod_wrapper_info(_cachedmethod_wrapper[_R]):
+    def cache_info(self) -> _CacheInfo: ...
+
 @overload
 def cachedmethod(
     cache: Callable[[Any], MutableMapping[_KT, Any]],
     key: Callable[..., _KT] = ...,
     lock: Callable[[Any], AbstractContextManager[Any]] | None = None,
-    condition: Callable[[Any], Condition] | None = None,
+    condition: Callable[[Any], _AbstractCondition] | None = None,
     info: Literal[True] = ...,
-) -> IdentityFunction: ...
+) -> Callable[[Callable[..., _R]], _cachedmethod_wrapper_info[_R]]: ...
 @overload
 def cachedmethod(
     cache: Callable[[Any], MutableMapping[_KT, Any]],
     key: Callable[..., _KT] = ...,
     lock: Callable[[Any], AbstractContextManager[Any]] | None = None,
-    condition: Callable[[Any], Condition] | None = None,
+    condition: Callable[[Any], _AbstractCondition] | None = None,
     info: Literal[False] = ...,
-) -> IdentityFunction: ...
+) -> Callable[[Callable[..., _R]], _cachedmethod_wrapper[_R]]: ...

src/cachetools/func.pyi

@@ -11,6 +11,8 @@ _R = TypeVar("_R")
 @type_check_only
 class _cachetools_cache_wrapper(Generic[_R]):
     __wrapped__: Callable[..., _R]
+    __name__: str
+    __doc__: str | None
     def __call__(self, /, *args: Any, **kwargs: Any) -> _R: ...
     def cache_info(self) -> _CacheInfo: ...
     def cache_clear(self) -> None: ...
@@ -21,28 +23,48 @@ 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]: ...
+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]]: ...
+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]: ...
+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]]: ...
+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]: ...
+def lru_cache(
+    maxsize: Callable[..., _R], typed: bool = False
+) -> _cachetools_cache_wrapper[_R]: ...
 @overload
 def rr_cache(
-    maxsize: int | None = 128, choice: Callable[[Sequence[_T]], _T] | None = ..., typed: bool = False
+    maxsize: int | None = 128,
+    choice: Callable[[Sequence[_T]], _T] = ...,
+    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
+    maxsize: Callable[..., _R],
+    choice: Callable[[Sequence[_T]], _T] = ...,
+    typed: bool = False,
 ) -> _cachetools_cache_wrapper[_R]: ...
 @overload
 def ttl_cache(
-    maxsize: int | None = 128, ttl: float = 600, timer: Callable[[], float] = ..., typed: bool = False
+    maxsize: int | None = 128,
+    ttl: Any = 600,
+    timer: Callable[[], _T] = ...,
+    typed: bool = False,
 ) -> Callable[[Callable[..., _R]], _cachetools_cache_wrapper[_R]]: ...
 @overload
 def ttl_cache(
-    maxsize: Callable[..., _R], ttl: float = 600, timer: Callable[[], float] = ..., typed: bool = False
+    maxsize: Callable[..., _R],
+    ttl: Any = 600,
+    timer: Callable[[], _T] = ...,
+    typed: bool = False,
 ) -> _cachetools_cache_wrapper[_R]: ...

src/cachetools/keys.pyi

@@ -1,9 +1,14 @@
 from _typeshed import Unused
 from collections.abc import Hashable
+from typing import Final
 
-__all__ = ("hashkey", "methodkey", "typedkey", "typedmethodkey")
+__all__: Final = ("hashkey", "methodkey", "typedkey", "typedmethodkey")
 
 def hashkey(*args: Hashable, **kwargs: Hashable) -> tuple[Hashable, ...]: ...
-def methodkey(self: Unused, /, *args: Hashable, **kwargs: Hashable) -> tuple[Hashable, ...]: ...
+def methodkey(
+    self: Unused, /, *args: Hashable, **kwargs: Hashable
+) -> tuple[Hashable, ...]: ...
 def typedkey(*args: Hashable, **kwargs: Hashable) -> tuple[Hashable, ...]: ...
-def typedmethodkey(self: Unused, /, *args: Hashable, **kwargs: Hashable) -> tuple[Hashable, ...]: ...
+def typedmethodkey(
+    self: Unused, /, *args: Hashable, **kwargs: Hashable
+) -> tuple[Hashable, ...]: ...