streamlit-nightly 1.46.2.dev20250701__py3-none-any.whl → 1.46.2.dev20250704__py3-none-any.whl

streamlit/runtime/caching/cache_data_api.py

@@ -24,10 +24,8 @@ from typing import (
     Callable,
     Final,
     Literal,
-    Protocol,
     TypeVar,
     Union,
-    cast,
     overload,
 )
 
@@ -41,6 +39,7 @@ from streamlit.runtime.caching.cache_errors import CacheError, CacheKeyNotFoundE
 from streamlit.runtime.caching.cache_type import CacheType
 from streamlit.runtime.caching.cache_utils import (
     Cache,
+    CachedFunc,
     CachedFuncInfo,
     make_cached_func_wrapper,
 )
@@ -68,7 +67,6 @@ from streamlit.runtime.stats import CacheStat, CacheStatsProvider, group_stats
 from streamlit.time_util import time_to_seconds
 
 if TYPE_CHECKING:
-    import types
     from datetime import timedelta
 
     from streamlit.runtime.caching.hashing import HashFuncsDict
@@ -81,7 +79,11 @@ CACHE_DATA_MESSAGE_REPLAY_CTX = CachedMessageReplayContext(CacheType.DATA)
 CachePersistType: TypeAlias = Union[Literal["disk"], None]
 
 
-class CachedDataFuncInfo(CachedFuncInfo):
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class CachedDataFuncInfo(CachedFuncInfo[P, R]):
     """Implements the CachedFuncInfo interface for @st.cache_data."""
 
     persist: CachePersistType
@@ -90,7 +92,7 @@ class CachedDataFuncInfo(CachedFuncInfo):
 
     def __init__(
         self,
-        func: types.FunctionType,
+        func: Callable[P, R],
         persist: CachePersistType,
         max_entries: int | None,
         ttl: float | timedelta | str | None,
@@ -123,7 +125,7 @@ class CachedDataFuncInfo(CachedFuncInfo):
         """A human-readable name for the cached function."""
         return f"{self.func.__module__}.{self.func.__qualname__}"
 
-    def get_function_cache(self, function_key: str) -> Cache:
+    def get_function_cache(self, function_key: str) -> Cache[R]:
         return _data_caches.get_cache(
             key=function_key,
             persist=self.persist,
@@ -152,7 +154,7 @@ class DataCaches(CacheStatsProvider):
 
     def __init__(self) -> None:
         self._caches_lock = threading.Lock()
-        self._function_caches: dict[str, DataCache] = {}
+        self._function_caches: dict[str, DataCache[Any]] = {}
 
     def get_cache(
         self,
@@ -161,7 +163,7 @@ class DataCaches(CacheStatsProvider):
         max_entries: int | None,
         ttl: int | float | timedelta | str | None,
         display_name: str,
-    ) -> DataCache:
+    ) -> DataCache[Any]:
         """Return the mem cache for the given key.
 
         If it doesn't exist, create a new one with the given params.
@@ -319,29 +321,6 @@ def get_data_cache_stats_provider() -> CacheStatsProvider:
     return _data_caches
 
 
-# Type-annotate the decorator function.
-# (See https://mypy.readthedocs.io/en/stable/generics.html#decorator-factories)
-P = ParamSpec("P")
-T_co = TypeVar("T_co", covariant=True)
-
-
-class CachedFunc(Protocol[P, T_co]):
-    """Protocol for cached functions that preserve the original function's signature and add a clear method."""
-
-    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T_co: ...
-
-    @overload
-    def clear(self) -> None: ...
-
-    @overload
-    def clear(self, *args: P.args, **kwargs: P.kwargs) -> None: ...
-
-    # Currently we can't define the "all-optional" argument overload with `P.args` and `P.kwargs` in Python.
-    # So we use `Any` as a fallback.
-    @overload
-    def clear(self, *args: Any, **kwargs: Any) -> None: ...
-
-
 class CacheDataAPI:
     """Implements the public st.cache_data API: the @st.cache_data decorator, and
     st.cache_data.clear().
@@ -362,9 +341,12 @@ class CacheDataAPI:
             decorator_metric_name, self._decorator
         )
 
+    # Type-annotate the decorator function.
+    # (See https://mypy.readthedocs.io/en/stable/generics.html#decorator-factories)
+
     # Bare decorator usage
     @overload
-    def __call__(self, func: Callable[P, T_co]) -> CachedFunc[P, T_co]: ...
+    def __call__(self, func: Callable[P, R]) -> CachedFunc[P, R]: ...
 
     # Decorator with arguments
     @overload
@@ -378,11 +360,11 @@ class CacheDataAPI:
         persist: CachePersistType | bool = None,
         experimental_allow_widgets: bool = False,
         hash_funcs: HashFuncsDict | None = None,
-    ) -> Callable[[Callable[P, T_co]], CachedFunc[P, T_co]]: ...
+    ) -> Callable[[Callable[P, R]], CachedFunc[P, R]]: ...
 
     def __call__(
         self,
-        func: Callable[P, T_co] | None = None,
+        func: Callable[P, R] | None = None,
         *,
         ttl: float | timedelta | str | None = None,
         max_entries: int | None = None,
@@ -391,7 +373,7 @@ class CacheDataAPI:
         persist: CachePersistType | bool = None,
         experimental_allow_widgets: bool = False,
         hash_funcs: HashFuncsDict | None = None,
-    ) -> CachedFunc[P, T_co] | Callable[[Callable[P, T_co]], CachedFunc[P, T_co]]:
+    ) -> CachedFunc[P, R] | Callable[[Callable[P, R]], CachedFunc[P, R]]:
         return self._decorator(
             func,
             ttl=ttl,
@@ -405,7 +387,7 @@ class CacheDataAPI:
 
     def _decorator(
         self,
-        func: Callable[P, T_co] | None = None,
+        func: Callable[P, R] | None = None,
         *,
         ttl: float | timedelta | str | None,
         max_entries: int | None,
@@ -414,7 +396,7 @@ class CacheDataAPI:
         persist: CachePersistType | bool,
         experimental_allow_widgets: bool,
         hash_funcs: HashFuncsDict | None = None,
-    ) -> CachedFunc[P, T_co] | Callable[[Callable[P, T_co]], CachedFunc[P, T_co]]:
+    ) -> CachedFunc[P, R] | Callable[[Callable[P, R]], CachedFunc[P, R]]:
         """Decorator to cache functions that return data (e.g. dataframe transforms, database queries, ML inference).
 
         Cached objects are stored in "pickled" form, which means that the return
@@ -598,20 +580,17 @@ class CacheDataAPI:
         if experimental_allow_widgets:
             show_widget_replay_deprecation("cache_data")
 
-        def wrapper(f: Callable[P, T_co]) -> CachedFunc[P, T_co]:
-            return cast(
-                "CachedFunc[P, T_co]",
-                make_cached_func_wrapper(
-                    CachedDataFuncInfo(
-                        func=f,  # type: ignore
-                        persist=persist_string,
-                        show_spinner=show_spinner,
-                        show_time=show_time,
-                        max_entries=max_entries,
-                        ttl=ttl,
-                        hash_funcs=hash_funcs,
-                    )
-                ),
+        def wrapper(f: Callable[P, R]) -> CachedFunc[P, R]:
+            return make_cached_func_wrapper(
+                CachedDataFuncInfo(
+                    func=f,
+                    persist=persist_string,
+                    show_spinner=show_spinner,
+                    show_time=show_time,
+                    max_entries=max_entries,
+                    ttl=ttl,
+                    hash_funcs=hash_funcs,
+                )
             )
 
         if func is None:
@@ -619,7 +598,7 @@ class CacheDataAPI:
 
         return make_cached_func_wrapper(
             CachedDataFuncInfo(
-                func=cast("types.FunctionType", func),
+                func=func,
                 persist=persist_string,
                 show_spinner=show_spinner,
                 show_time=show_time,
@@ -635,7 +614,7 @@ class CacheDataAPI:
         _data_caches.clear_all()
 
 
-class DataCache(Cache):
+class DataCache(Cache[R]):
     """Manages cached values for a single st.cache_data function."""
 
     def __init__(
@@ -660,7 +639,7 @@ class DataCache(Cache):
             return self.storage.get_stats()
         return []
 
-    def read_result(self, key: str) -> CachedResult:
+    def read_result(self, key: str) -> CachedResult[R]:
         """Read a value and messages from the cache. Raise `CacheKeyNotFoundError`
         if the value doesn't exist, and `CacheError` if the value exists but can't
         be unpickled.
@@ -684,7 +663,7 @@ class DataCache(Cache):
             raise CacheError(f"Failed to unpickle {key}") from exc
 
     @gather_metrics("_cache_data_object")
-    def write_result(self, key: str, value: Any, messages: list[MsgData]) -> None:
+    def write_result(self, key: str, value: R, messages: list[MsgData]) -> None:
         """Write a value and associated messages to the cache.
         The value must be pickleable.
         """

streamlit/runtime/caching/cache_errors.py

@@ -14,15 +14,12 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import Any, Callable, Generic, TypeVar
 
 from streamlit import type_util
 from streamlit.errors import MarkdownFormattedException, StreamlitAPIException
 from streamlit.runtime.caching.cache_type import CacheType, get_decorator_api_name
 
-if TYPE_CHECKING:
-    from types import FunctionType
-
 CACHE_DOCS_URL = "https://docs.streamlit.io/develop/concepts/architecture/caching"
 
 
@@ -49,7 +46,7 @@ class UnhashableParamError(StreamlitAPIException):
     def __init__(
         self,
         cache_type: CacheType,
-        func: FunctionType,
+        func: Callable[..., Any],
         arg_name: str | None,
         arg_value: Any,
         orig_exc: BaseException,
@@ -61,7 +58,7 @@ class UnhashableParamError(StreamlitAPIException):
     @staticmethod
     def _create_message(
         cache_type: CacheType,
-        func: FunctionType,
+        func: Callable[..., Any],
         arg_name: str | None,
         arg_value: Any,
     ) -> str:
@@ -98,7 +95,7 @@ class CacheReplayClosureError(StreamlitAPIException):
     def __init__(
         self,
         cache_type: CacheType,
-        cached_func: FunctionType,
+        cached_func: Callable[..., Any],
     ) -> None:
         func_name = get_cached_func_name_md(cached_func)
         decorator_name = get_decorator_api_name(cache_type)
@@ -120,8 +117,11 @@ How to fix this:
         super().__init__(msg)
 
 
-class UnserializableReturnValueError(MarkdownFormattedException):
-    def __init__(self, func: FunctionType, return_value: FunctionType) -> None:
+R = TypeVar("R")
+
+
+class UnserializableReturnValueError(MarkdownFormattedException, Generic[R]):
+    def __init__(self, func: Callable[..., R], return_value: R) -> None:
         MarkdownFormattedException.__init__(
             self,
             f"""

streamlit/runtime/caching/cache_resource_api.py

@@ -23,9 +23,7 @@ from typing import (
     Any,
     Callable,
     Final,
-    Protocol,
     TypeVar,
-    cast,
     overload,
 )
 
@@ -39,6 +37,7 @@ from streamlit.runtime.caching.cache_errors import CacheKeyNotFoundError
 from streamlit.runtime.caching.cache_type import CacheType
 from streamlit.runtime.caching.cache_utils import (
     Cache,
+    CachedFunc,
     CachedFuncInfo,
     make_cached_func_wrapper,
 )
@@ -53,7 +52,6 @@ from streamlit.runtime.stats import CacheStat, CacheStatsProvider, group_stats
 from streamlit.time_util import time_to_seconds
 
 if TYPE_CHECKING:
-    import types
     from datetime import timedelta
 
     from streamlit.runtime.caching.hashing import HashFuncsDict
@@ -80,7 +78,7 @@ class ResourceCaches(CacheStatsProvider):
 
     def __init__(self) -> None:
         self._caches_lock = threading.Lock()
-        self._function_caches: dict[str, ResourceCache] = {}
+        self._function_caches: dict[str, ResourceCache[Any]] = {}
 
     def get_cache(
         self,
@@ -89,7 +87,7 @@ class ResourceCaches(CacheStatsProvider):
         max_entries: int | float | None,
         ttl: float | timedelta | str | None,
         validate: ValidateFunc | None,
-    ) -> ResourceCache:
+    ) -> ResourceCache[Any]:
         """Return the mem cache for the given key.
 
         If it doesn't exist, create a new one with the given params.
@@ -149,12 +147,16 @@ def get_resource_cache_stats_provider() -> CacheStatsProvider:
     return _resource_caches
 
 
-class CachedResourceFuncInfo(CachedFuncInfo):
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class CachedResourceFuncInfo(CachedFuncInfo[P, R]):
     """Implements the CachedFuncInfo interface for @st.cache_resource."""
 
     def __init__(
         self,
-        func: types.FunctionType,
+        func: Callable[P, R],
         show_spinner: bool | str,
         max_entries: int | None,
         ttl: float | timedelta | str | None,
@@ -185,7 +187,7 @@ class CachedResourceFuncInfo(CachedFuncInfo):
         """A human-readable name for the cached function."""
         return f"{self.func.__module__}.{self.func.__qualname__}"
 
-    def get_function_cache(self, function_key: str) -> Cache:
+    def get_function_cache(self, function_key: str) -> Cache[R]:
         return _resource_caches.get_cache(
             key=function_key,
             display_name=self.display_name,
@@ -195,29 +197,6 @@ class CachedResourceFuncInfo(CachedFuncInfo):
         )
 
 
-# Type-annotate the decorator function.
-# (See https://mypy.readthedocs.io/en/stable/generics.html#decorator-factories)
-P = ParamSpec("P")
-T_co = TypeVar("T_co", covariant=True)
-
-
-class CachedFunc(Protocol[P, T_co]):
-    """Protocol for cached functions that preserve the original function's signature and add a clear method."""
-
-    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> T_co: ...
-
-    @overload
-    def clear(self) -> None: ...
-
-    @overload
-    def clear(self, *args: P.args, **kwargs: P.kwargs) -> None: ...
-
-    # Currently we can't define the "all-optional" argument overload with `P.args` and `P.kwargs` in Python.
-    # So we use `Any` as a fallback.
-    @overload
-    def clear(self, *args: Any, **kwargs: Any) -> None: ...
-
-
 class CacheResourceAPI:
     """Implements the public st.cache_resource API: the @st.cache_resource decorator,
     and st.cache_resource.clear().
@@ -236,9 +215,12 @@ class CacheResourceAPI:
         # (Ignore spurious mypy complaints - https://github.com/python/mypy/issues/2427)
         self._decorator = gather_metrics(decorator_metric_name, self._decorator)  # type: ignore
 
+    # Type-annotate the decorator function.
+    # (See https://mypy.readthedocs.io/en/stable/generics.html#decorator-factories)
+
     # Bare decorator usage
     @overload
-    def __call__(self, func: Callable[P, T_co]) -> CachedFunc[P, T_co]: ...
+    def __call__(self, func: Callable[P, R]) -> CachedFunc[P, R]: ...
 
     # Decorator with arguments
     @overload
@@ -252,11 +234,11 @@ class CacheResourceAPI:
         validate: ValidateFunc | None = None,
         experimental_allow_widgets: bool = False,
         hash_funcs: HashFuncsDict | None = None,
-    ) -> Callable[[Callable[P, T_co]], CachedFunc[P, T_co]]: ...
+    ) -> Callable[[Callable[P, R]], CachedFunc[P, R]]: ...
 
     def __call__(
         self,
-        func: Callable[P, T_co] | None = None,
+        func: Callable[P, R] | None = None,
         *,
         ttl: float | timedelta | str | None = None,
         max_entries: int | None = None,
@@ -265,7 +247,7 @@ class CacheResourceAPI:
         validate: ValidateFunc | None = None,
         experimental_allow_widgets: bool = False,
         hash_funcs: HashFuncsDict | None = None,
-    ) -> CachedFunc[P, T_co] | Callable[[Callable[P, T_co]], CachedFunc[P, T_co]]:
+    ) -> CachedFunc[P, R] | Callable[[Callable[P, R]], CachedFunc[P, R]]:
         return self._decorator(
             func,
             ttl=ttl,
@@ -279,7 +261,7 @@ class CacheResourceAPI:
 
     def _decorator(
         self,
-        func: Callable[P, T_co] | None,
+        func: Callable[P, R] | None,
         *,
         ttl: float | timedelta | str | None,
         max_entries: int | None,
@@ -288,7 +270,7 @@ class CacheResourceAPI:
         validate: ValidateFunc | None,
         experimental_allow_widgets: bool,
         hash_funcs: HashFuncsDict | None = None,
-    ) -> CachedFunc[P, T_co] | Callable[[Callable[P, T_co]], CachedFunc[P, T_co]]:
+    ) -> CachedFunc[P, R] | Callable[[Callable[P, R]], CachedFunc[P, R]]:
         """Decorator to cache functions that return global resources (e.g. database connections, ML models).
 
         Cached objects are shared across all users, sessions, and reruns. They
@@ -456,9 +438,9 @@ class CacheResourceAPI:
         # Support passing the params via function decorator, e.g.
         # @st.cache_resource(show_spinner=False)
         if func is None:
-            return lambda f: make_cached_func_wrapper(  # type: ignore
+            return lambda f: make_cached_func_wrapper(
                 CachedResourceFuncInfo(
-                    func=f,  # type: ignore
+                    func=f,
                     show_spinner=show_spinner,
                     show_time=show_time,
                     max_entries=max_entries,
@@ -470,7 +452,7 @@ class CacheResourceAPI:
 
         return make_cached_func_wrapper(
             CachedResourceFuncInfo(
-                func=cast("types.FunctionType", func),
+                func=func,
                 show_spinner=show_spinner,
                 show_time=show_time,
                 max_entries=max_entries,
@@ -486,7 +468,7 @@ class CacheResourceAPI:
         _resource_caches.clear_all()
 
 
-class ResourceCache(Cache):
+class ResourceCache(Cache[R]):
     """Manages cached values for a single st.cache_resource function."""
 
     def __init__(
@@ -500,7 +482,7 @@ class ResourceCache(Cache):
         super().__init__()
         self.key = key
         self.display_name = display_name
-        self._mem_cache: TTLCache[str, CachedResult] = TTLCache(
+        self._mem_cache: TTLCache[str, CachedResult[R]] = TTLCache(
             maxsize=max_entries, ttl=ttl_seconds, timer=cache_utils.TTLCACHE_TIMER
         )
         self._mem_cache_lock = threading.Lock()
@@ -514,7 +496,7 @@ class ResourceCache(Cache):
     def ttl_seconds(self) -> float:
         return self._mem_cache.ttl
 
-    def read_result(self, key: str) -> CachedResult:
+    def read_result(self, key: str) -> CachedResult[R]:
         """Read a value and associated messages from the cache.
         Raise `CacheKeyNotFoundError` if the value doesn't exist.
         """
@@ -533,7 +515,7 @@ class ResourceCache(Cache):
             return result
 
     @gather_metrics("_cache_resource_object")
-    def write_result(self, key: str, value: Any, messages: list[MsgData]) -> None:
+    def write_result(self, key: str, value: R, messages: list[MsgData]) -> None:
         """Write a value and associated messages to the cache."""
         main_id = st._main.id
         sidebar_id = st.sidebar.id

streamlit/runtime/caching/cache_utils.py

@@ -24,7 +24,9 @@ import threading
 import time
 from abc import abstractmethod
 from collections import defaultdict
-from typing import TYPE_CHECKING, Any, Callable, Final
+from typing import TYPE_CHECKING, Any, Callable, Final, Generic, TypeVar, cast, overload
+
+from typing_extensions import ParamSpec
 
 from streamlit import type_util
 from streamlit.dataframe_util import is_unevaluated_data_object
@@ -51,8 +53,6 @@ from streamlit.runtime.scriptrunner_utils.script_run_context import (
 )
 
 if TYPE_CHECKING:
-    from types import FunctionType
-
     from streamlit.runtime.caching.cache_type import CacheType
 
 _LOGGER: Final = get_logger(__name__)
@@ -61,8 +61,12 @@ _LOGGER: Final = get_logger(__name__)
 # is exposed here as a constant so that it can be patched in unit tests.
 TTLCACHE_TIMER = time.monotonic
 
+# Type-annotate the cached function.
+P = ParamSpec("P")
+R = TypeVar("R")
+
 
-class Cache:
+class Cache(Generic[R]):
     """Function cache interface. Caches persist across script runs."""
 
     def __init__(self) -> None:
@@ -70,7 +74,7 @@ class Cache:
         self._value_locks_lock = threading.Lock()
 
     @abstractmethod
-    def read_result(self, value_key: str) -> CachedResult:
+    def read_result(self, value_key: str) -> CachedResult[R]:
         """Read a value and associated messages from the cache.
 
         Raises
@@ -82,7 +86,7 @@ class Cache:
         raise NotImplementedError
 
     @abstractmethod
-    def write_result(self, value_key: str, value: Any, messages: list[MsgData]) -> None:
+    def write_result(self, value_key: str, value: R, messages: list[MsgData]) -> None:
         """Write a value and associated messages to the cache, overwriting any existing
         result that uses the value_key.
         """
@@ -118,7 +122,7 @@ class Cache:
         raise NotImplementedError
 
 
-class CachedFuncInfo:
+class CachedFuncInfo(Generic[P, R]):
     """Encapsulates data for a cached function instance.
 
     CachedFuncInfo instances are scoped to a single script run - they're not
@@ -127,7 +131,7 @@ class CachedFuncInfo:
 
     def __init__(
         self,
-        func: FunctionType,
+        func: Callable[P, R],
         hash_funcs: HashFuncsDict | None,
         show_spinner: bool | str,
         show_time: bool = False,
@@ -145,12 +149,12 @@ class CachedFuncInfo:
     def cached_message_replay_ctx(self) -> CachedMessageReplayContext:
         raise NotImplementedError
 
-    def get_function_cache(self, function_key: str) -> Cache:
+    def get_function_cache(self, function_key: str) -> Cache[R]:
         """Get or create the function cache for the given key."""
         raise NotImplementedError
 
 
-def make_cached_func_wrapper(info: CachedFuncInfo) -> Callable[..., Any]:
+def make_cached_func_wrapper(info: CachedFuncInfo[P, R]) -> CachedFunc[P, R]:
     """Create a callable wrapper around a CachedFunctionInfo.
 
     Calling the wrapper will return the cached value if it's already been
@@ -161,19 +165,19 @@ def make_cached_func_wrapper(info: CachedFuncInfo) -> Callable[..., Any]:
     some or all of the wrapper's cached values.
     """
     cached_func = CachedFunc(info)
-    return functools.update_wrapper(cached_func, info.func)
+    return cast("CachedFunc[P, R]", functools.update_wrapper(cached_func, info.func))
 
 
-class BoundCachedFunc:
+class BoundCachedFunc(Generic[P, R]):
     """A wrapper around a CachedFunc that binds it to a specific instance in case of
     decorated function is a class method.
     """
 
-    def __init__(self, cached_func: CachedFunc, instance: Any) -> None:
+    def __init__(self, cached_func: CachedFunc[P, R], instance: Any) -> None:
         self._cached_func = cached_func
         self._instance = instance
 
-    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
         return self._cached_func(self._instance, *args, **kwargs)
 
     def __repr__(self) -> str:
@@ -190,8 +194,8 @@ class BoundCachedFunc:
             self._cached_func.clear()
 
 
-class CachedFunc:
-    def __init__(self, info: CachedFuncInfo) -> None:
+class CachedFunc(Generic[P, R]):
+    def __init__(self, info: CachedFuncInfo[P, R]) -> None:
         self._info = info
         self._function_key = _make_function_key(info.cache_type, info.func)
 
@@ -205,7 +209,7 @@ class CachedFunc:
 
         return functools.update_wrapper(BoundCachedFunc(self, instance), self)
 
-    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
         """The wrapper. We'll only call our underlying function on a cache miss."""
 
         spinner_message: str | None = None
@@ -225,7 +229,7 @@ class CachedFunc:
         func_args: tuple[Any, ...],
         func_kwargs: dict[str, Any],
         spinner_message: str | None = None,
-    ) -> Any:
+    ) -> R:
         # Retrieve the function's cache object. We must do this "just-in-time"
         # (as opposed to in the constructor), because caches can be invalidated
         # at any time.
@@ -262,7 +266,7 @@ class CachedFunc:
         with spinner_or_no_context:
             return self._handle_cache_miss(cache, value_key, func_args, func_kwargs)
 
-    def _handle_cache_hit(self, result: CachedResult) -> Any:
+    def _handle_cache_hit(self, result: CachedResult[R]) -> R:
         """Handle a cache hit: replay the result's cached messages, and return its
         value.
         """
@@ -275,11 +279,11 @@ class CachedFunc:
 
     def _handle_cache_miss(
         self,
-        cache: Cache,
+        cache: Cache[R],
         value_key: str,
         func_args: tuple[Any, ...],
         func_kwargs: dict[str, Any],
-    ) -> Any:
+    ) -> R:
         """Handle a cache miss: compute a new cached value, write it back to the cache,
         and return that newly-computed value.
         """
@@ -348,6 +352,15 @@ class CachedFunc:
                     return_value=computed_value, func=self._info.func
                 )
 
+    @overload
+    def clear(self) -> None: ...
+
+    @overload
+    def clear(self, *args: P.args, **kwargs: P.kwargs) -> None: ...
+
+    @overload
+    def clear(self, *args: Any, **kwargs: Any) -> None: ...
+
     def clear(self, *args: Any, **kwargs: Any) -> None:
         """Clear the cached function's associated cache.
 
@@ -400,7 +413,7 @@ class CachedFunc:
 
 def _make_value_key(
     cache_type: CacheType,
-    func: FunctionType,
+    func: Callable[..., Any],
     func_args: tuple[Any, ...],
     func_kwargs: dict[str, Any],
     hash_funcs: HashFuncsDict | None,
@@ -465,7 +478,7 @@ def _make_value_key(
     return value_key
 
 
-def _make_function_key(cache_type: CacheType, func: FunctionType) -> str:
+def _make_function_key(cache_type: CacheType, func: Callable[..., Any]) -> str:
     """Create the unique key for a function's cache.
 
     A function's key is stable across reruns of the app, and changes when
@@ -505,7 +518,7 @@ def _make_function_key(cache_type: CacheType, func: FunctionType) -> str:
     return func_hasher.hexdigest()
 
 
-def _get_positional_arg_name(func: FunctionType, arg_index: int) -> str | None:
+def _get_positional_arg_name(func: Callable[..., Any], arg_index: int) -> str | None:
     """Return the name of a function's positional argument.
 
     If arg_index is out of range, or refers to a parameter that is not a