streamlit-nightly 1.52.3.dev20260104__py3-none-any.whl → 1.52.3.dev20260105__py3-none-any.whl

streamlit/runtime/app_session.py

@@ -221,6 +221,15 @@ class AppSession:
         self._stop_config_listener = None
         self._stop_pages_listener = None
 
+    def clear_session_caches(self) -> None:
+        """Clears session-level caches for this session.
+
+        This should be called when a session is disconnected or shut down, since this
+        ensures memory is freed up and resource release hooks are called.
+        """
+        caching.clear_session_data_cache(self.id)
+        caching.clear_session_resource_cache(self.id)
+
     def flush_browser_queue(self) -> list[ForwardMsg]:
         """Clear the forward message queue and return the messages it contained.
 
@@ -264,6 +273,9 @@ class AppSession:
             # generally already done so by the time we get here.
             self.disconnect_file_watchers()
 
+            # Clear any session caches. This ensures shutdown hooks are called.
+            self.clear_session_caches()
+
     def _enqueue_forward_msg(self, msg: ForwardMsg) -> None:
         """Enqueue a new ForwardMsg to our browser queue.
 
@@ -691,9 +703,10 @@ class AppSession:
                 )
 
             if self._state == AppSessionState.SHUTDOWN_REQUESTED:
-                # Only clear media files if the script is done running AND the
-                # session is actually shutting down.
+                # Only clear media files and session caches if the script is done
+                # running AND the session is actually shutting down.
                 runtime.get_instance().media_file_mgr.clear_session_refs(self.id)
+                self.clear_session_caches()
 
             self._client_state = client_state
             self._scriptrunner = None

streamlit/runtime/caching/__init__.py

@@ -21,12 +21,18 @@ from streamlit.runtime.caching.cache_data_api import (
     CacheDataAPI,
     get_data_cache_stats_provider,
 )
+from streamlit.runtime.caching.cache_data_api import (
+    clear_session_cache as clear_session_data_cache,
+)
 from streamlit.runtime.caching.cache_errors import CACHE_DOCS_URL
 from streamlit.runtime.caching.cache_resource_api import (
     CACHE_RESOURCE_MESSAGE_REPLAY_CTX,
     CacheResourceAPI,
     get_resource_cache_stats_provider,
 )
+from streamlit.runtime.caching.cache_resource_api import (
+    clear_session_cache as clear_session_resource_cache,
+)
 from streamlit.runtime.caching.legacy_cache_api import cache as _cache
 
 if TYPE_CHECKING:
@@ -102,6 +108,8 @@ __all__ = [
     "cache",
     "cache_data",
     "cache_resource",
+    "clear_session_data_cache",
+    "clear_session_resource_cache",
     "get_data_cache_stats_provider",
     "get_resource_cache_stats_provider",
     "save_block_message",

streamlit/runtime/caching/cache_data_api.py

@@ -41,6 +41,8 @@ from streamlit.runtime.caching.cache_utils import (
     Cache,
     CachedFunc,
     CachedFuncInfo,
+    CacheScope,
+    get_session_id_or_throw,
     make_cached_func_wrapper,
 )
 from streamlit.runtime.caching.cached_message_replay import (
@@ -104,12 +106,14 @@ class CachedDataFuncInfo(CachedFuncInfo[P, R]):
         show_spinner: bool | str,
         show_time: bool = False,
         hash_funcs: HashFuncsDict | None = None,
+        scope: CacheScope = "global",
     ) -> None:
         super().__init__(
             func,
             hash_funcs=hash_funcs,
             show_spinner=show_spinner,
             show_time=show_time,
+            scope=scope,
         )
         self.persist = persist
         self.max_entries = max_entries
@@ -137,6 +141,7 @@ class CachedDataFuncInfo(CachedFuncInfo[P, R]):
             max_entries=self.max_entries,
             ttl=self.ttl,
             display_name=self.display_name,
+            scope=self.scope,
         )
 
     def validate_params(self) -> None:
@@ -159,7 +164,8 @@ class DataCaches(StatsProvider):
 
     def __init__(self) -> None:
         self._caches_lock = threading.Lock()
-        self._function_caches: dict[str, DataCache[Any]] = {}
+        # Map of session IDs to map of function keys to caches.
+        self._function_caches: dict[str | None, dict[str, DataCache[Any]]] = {}
 
     @property
     def stats_families(self) -> Sequence[str]:
@@ -172,18 +178,37 @@ class DataCaches(StatsProvider):
         max_entries: int | None,
         ttl: int | float | timedelta | str | None,
         display_name: str,
+        scope: CacheScope = "global",
     ) -> DataCache[Any]:
         """Return the mem cache for the given key.
 
         If it doesn't exist, create a new one with the given params.
+
+        Raises
+        ------
+        StreamlitAPIException
+            Raised when ``scope`` is ``"session"`` and there is no thread-local run
+            context.
         """
 
         ttl_seconds = time_to_seconds(ttl, coerce_none_to_inf=False)
 
+        # Fetch the session ID. Note that this will throw an exception if there is no
+        # session associated with the current thread.
+        session_id: str | None
+        if scope == "global":
+            session_id = None
+        else:
+            session_id = get_session_id_or_throw()
+
         # Get the existing cache, if it exists, and validate that its params
         # haven't changed.
         with self._caches_lock:
-            cache = self._function_caches.get(key)
+            session_caches = self._function_caches.get(session_id)
+            if session_caches is None:
+                session_caches = self._function_caches[session_id] = {}
+
+            cache = session_caches.get(key)
             if (
                 cache is not None
                 and cache.ttl_seconds == ttl_seconds
@@ -232,9 +257,22 @@ class DataCaches(StatsProvider):
                 ttl_seconds=ttl_seconds,
                 display_name=display_name,
             )
-            self._function_caches[key] = cache
+            self._function_caches[session_id][key] = cache
             return cache
 
+    def clear_session(self, session_id: str) -> None:
+        """Clears all caches for the given session ID."""
+        # Hold the lock while removing the cache, but release it while clearing.
+        with self._caches_lock:
+            session_caches = self._function_caches.get(session_id)
+            if session_caches is not None:
+                del self._function_caches[session_id]
+
+        if session_caches is not None:
+            for cache in session_caches.values():
+                cache.clear()
+                cache.storage.close()
+
     def clear_all(self) -> None:
         """Clear all in-memory and on-disk caches."""
         with self._caches_lock:
@@ -245,9 +283,10 @@ class DataCaches(StatsProvider):
                 # available storages one by one
                 self.get_storage_manager().clear_all()
             except NotImplementedError:
-                for data_cache in self._function_caches.values():
-                    data_cache.clear()
-                    data_cache.storage.close()
+                for data_caches in self._function_caches.values():
+                    for data_cache in data_caches.values():
+                        data_cache.clear()
+                        data_cache.storage.close()
             self._function_caches = {}
 
     def get_stats(
@@ -256,10 +295,14 @@ class DataCaches(StatsProvider):
         with self._caches_lock:
             # Shallow-clone our caches. We don't want to hold the global
             # lock during stats-gathering.
-            function_caches = self._function_caches.copy()
+            function_caches = [
+                cache
+                for caches in self._function_caches.values()
+                for cache in caches.values()
+            ]
 
         stats: list[CacheStat] = []
-        for cache in function_caches.values():
+        for cache in function_caches:
             cache_stats = cache.get_stats()
             for family_stats in cache_stats.values():
                 stats.extend(family_stats)
@@ -334,6 +377,11 @@ class DataCaches(StatsProvider):
 _data_caches = DataCaches()
 
 
+def clear_session_cache(session_id: str) -> None:
+    """Clears all caches for the given session ID."""
+    _data_caches.clear_session(session_id)
+
+
 def get_data_cache_stats_provider() -> StatsProvider:
     """Return the StatsProvider for all @st.cache_data functions."""
     return _data_caches
@@ -377,6 +425,7 @@ class CacheDataAPI:
         show_time: bool = False,
         persist: CachePersistType | bool = None,
         hash_funcs: HashFuncsDict | None = None,
+        scope: CacheScope = "global",
     ) -> Callable[[Callable[P, R]], CachedFunc[P, R]]: ...
 
     def __call__(
@@ -389,6 +438,7 @@ class CacheDataAPI:
         show_time: bool = False,
         persist: CachePersistType | bool = None,
         hash_funcs: HashFuncsDict | None = None,
+        scope: CacheScope = "global",
     ) -> CachedFunc[P, R] | Callable[[Callable[P, R]], CachedFunc[P, R]]:
         return self._decorator(
             func,  # ty: ignore[invalid-argument-type]
@@ -398,6 +448,7 @@ class CacheDataAPI:
             show_spinner=show_spinner,
             show_time=show_time,
             hash_funcs=hash_funcs,
+            scope=scope,
         )
 
     def _decorator(
@@ -410,6 +461,7 @@ class CacheDataAPI:
         show_time: bool = False,
         persist: CachePersistType | bool,
         hash_funcs: HashFuncsDict | None = None,
+        scope: CacheScope = "global",
     ) -> 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).
 
@@ -491,6 +543,15 @@ class CacheDataAPI:
             the provided function to generate a hash for it. See below for an example
             of how this can be used.
 
+        scope : "global" or "session"
+            The scope for the resource. If "global", cache globally. If "session",
+            cache in the session.
+
+            Session-scoped cache entries will be expired when a user's session is
+            disconnected. Note that disconnected sessions can reconnect - so it is
+            possible for the cache to populate multiple times in a single session for
+            the same key.
+
         Example
         -------
         >>> import streamlit as st
@@ -595,6 +656,11 @@ class CacheDataAPI:
                 f"Unsupported persist option '{persist}'. Valid values are 'disk' or None."
             )
 
+        if scope not in ("global", "session"):
+            raise StreamlitAPIException(
+                f"Unsupported scope option '{scope}'. Valid values are 'global' or 'session'."
+            )
+
         def wrapper(f: Callable[P, R]) -> CachedFunc[P, R]:
             return make_cached_func_wrapper(
                 CachedDataFuncInfo(
@@ -605,6 +671,7 @@ class CacheDataAPI:
                     max_entries=max_entries,
                     ttl=ttl,
                     hash_funcs=hash_funcs,
+                    scope=scope,
                 )
             )
 
@@ -620,6 +687,7 @@ class CacheDataAPI:
                 max_entries=max_entries,
                 ttl=ttl,
                 hash_funcs=hash_funcs,
+                scope=scope,
             )
         )
 

streamlit/runtime/caching/cache_resource_api.py

@@ -32,6 +32,7 @@ from typing import (
 from typing_extensions import ParamSpec
 
 import streamlit as st
+from streamlit.errors import StreamlitAPIException
 from streamlit.logger import get_logger
 from streamlit.runtime.caching import cache_utils
 from streamlit.runtime.caching.cache_errors import CacheKeyNotFoundError
@@ -40,7 +41,9 @@ from streamlit.runtime.caching.cache_utils import (
     Cache,
     CachedFunc,
     CachedFuncInfo,
+    CacheScope,
     OnRelease,
+    get_session_id_or_throw,
     make_cached_func_wrapper,
 )
 from streamlit.runtime.caching.cached_message_replay import (
@@ -89,7 +92,8 @@ class ResourceCaches(StatsProvider):
 
     def __init__(self) -> None:
         self._caches_lock = threading.Lock()
-        self._function_caches: dict[str, ResourceCache[Any]] = {}
+        # Map of session IDs to map of function keys to caches.
+        self._function_caches: dict[str | None, dict[str, ResourceCache[Any]]] = {}
 
     @property
     def stats_families(self) -> Sequence[str]:
@@ -103,20 +107,39 @@ class ResourceCaches(StatsProvider):
         ttl: float | timedelta | str | None,
         validate: ValidateFunc | None,
         on_release: OnRelease,
+        scope: CacheScope = "global",
     ) -> ResourceCache[Any]:
         """Return the mem cache for the given key.
 
         If it doesn't exist, create a new one with the given params.
+
+        Raises
+        ------
+        StreamlitAPIException
+            Raised when ``scope`` is ``"session"`` and there is no thread-local run
+            context.
         """
         if max_entries is None:
             max_entries = math.inf
 
         ttl_seconds = time_to_seconds(ttl)
 
+        # Fetch the session ID. Note that this will throw an exception if there is no
+        # session associated with the current thread.
+        session_id: str | None
+        if scope == "global":
+            session_id = None
+        else:
+            session_id = get_session_id_or_throw()
+
         # Get the existing cache, if it exists, and validate that its params
         # haven't changed.
         with self._caches_lock:
-            cache = self._function_caches.get(key)
+            session_caches = self._function_caches.get(session_id)
+            if session_caches is None:
+                session_caches = self._function_caches[session_id] = {}
+
+            cache = session_caches.get(key)
             if (
                 cache is not None
                 and cache.ttl_seconds == ttl_seconds
@@ -135,14 +158,30 @@ class ResourceCaches(StatsProvider):
                 validate=validate,
                 on_release=on_release,
             )
-            self._function_caches[key] = cache
+            self._function_caches[session_id][key] = cache
             return cache
 
+    def clear_session(self, session_id: str) -> None:
+        """Clears all caches for the given session ID."""
+        # Hold the lock while removing the cache, but release it while clearing.
+        with self._caches_lock:
+            session_caches = self._function_caches.get(session_id)
+            if session_caches is not None:
+                del self._function_caches[session_id]
+
+        if session_caches is not None:
+            for cache in session_caches.values():
+                cache.clear()
+
     def clear_all(self) -> None:
         """Clear all resource caches."""
         # Hold the lock long enough to copy the caches.
         with self._caches_lock:
-            caches = list(self._function_caches.values())
+            caches = [
+                cache
+                for caches in self._function_caches.values()
+                for cache in caches.values()
+            ]
             self._function_caches = {}
 
         # Clear each cache to ensure any on_release functions are called.
@@ -152,13 +191,18 @@ class ResourceCaches(StatsProvider):
     def get_stats(
         self, _family_names: Sequence[str] | None = None
     ) -> dict[str, list[CacheStat]]:
+        function_caches: list[ResourceCache[Any]]
         with self._caches_lock:
             # Shallow-clone our caches. We don't want to hold the global
             # lock during stats-gathering.
-            function_caches = self._function_caches.copy()
+            function_caches = [
+                cache
+                for caches in self._function_caches.values()
+                for cache in caches.values()
+            ]
 
         stats: list[CacheStat] = []
-        for cache in function_caches.values():
+        for cache in function_caches:
             cache_stats = cache.get_stats()
             for family_stats in cache_stats.values():
                 stats.extend(family_stats)
@@ -174,6 +218,11 @@ class ResourceCaches(StatsProvider):
 _resource_caches = ResourceCaches()
 
 
+def clear_session_cache(session_id: str) -> None:
+    """Clears all caches for the given session ID."""
+    _resource_caches.clear_session(session_id)
+
+
 def get_resource_cache_stats_provider() -> StatsProvider:
     """Return the StatsProvider for all @st.cache_resource functions."""
     return _resource_caches
@@ -196,12 +245,14 @@ class CachedResourceFuncInfo(CachedFuncInfo[P, R]):
         hash_funcs: HashFuncsDict | None = None,
         show_time: bool = False,
         on_release: OnRelease | None = None,
+        scope: CacheScope = "global",
     ) -> None:
         super().__init__(
             func,
             hash_funcs=hash_funcs,
             show_spinner=show_spinner,
             show_time=show_time,
+            scope=scope,
         )
         self.max_entries = max_entries
         self.ttl = ttl
@@ -229,6 +280,7 @@ class CachedResourceFuncInfo(CachedFuncInfo[P, R]):
             ttl=self.ttl,
             validate=self.validate,
             on_release=self.on_release,
+            scope=self.scope,
         )
 
 
@@ -268,6 +320,8 @@ class CacheResourceAPI:
         show_time: bool = False,
         validate: ValidateFunc | None = None,
         hash_funcs: HashFuncsDict | None = None,
+        on_release: OnRelease | None = None,
+        scope: CacheScope = "global",
     ) -> Callable[[Callable[P, R]], CachedFunc[P, R]]: ...
 
     def __call__(
@@ -281,6 +335,7 @@ class CacheResourceAPI:
         validate: ValidateFunc | None = None,
         hash_funcs: HashFuncsDict | None = None,
         on_release: OnRelease | None = None,
+        scope: CacheScope = "global",
     ) -> CachedFunc[P, R] | Callable[[Callable[P, R]], CachedFunc[P, R]]:
         return self._decorator(  # ty: ignore[missing-argument]
             func,  # ty: ignore[invalid-argument-type]
@@ -291,6 +346,7 @@ class CacheResourceAPI:
             validate=validate,
             hash_funcs=hash_funcs,
             on_release=on_release,
+            scope=scope,
         )
 
     def _decorator(
@@ -304,6 +360,7 @@ class CacheResourceAPI:
         validate: ValidateFunc | None,
         hash_funcs: HashFuncsDict | None = None,
         on_release: OnRelease | None = None,
+        scope: CacheScope = "global",
     ) -> CachedFunc[P, R] | Callable[[Callable[P, R]], CachedFunc[P, R]]:
         """Decorator to cache functions that return global resources (e.g. database connections, ML models).
 
@@ -415,6 +472,15 @@ class CacheResourceAPI:
 
             This will NOT be called when an app is shut down.
 
+        scope : "global" or "session"
+            The scope for the resource. If "global", cache globally. If "session",
+            cache in the session.
+
+            Session-scoped cache entries will be expired when a user's session is
+            disconnected. Note that disconnected sessions can reconnect - so it is
+            possible for the cache to populate multiple times in a single session for
+            the same key.
+
         Example
         -------
         >>> import streamlit as st
@@ -498,6 +564,11 @@ class CacheResourceAPI:
         ...     return person.name
         """
 
+        if scope not in ("global", "session"):
+            raise StreamlitAPIException(
+                f"Unsupported scope option '{scope}'. Valid values are 'global' or 'session'."
+            )
+
         # Support passing the params via function decorator, e.g.
         # @st.cache_resource(show_spinner=False)
         if func is None:
@@ -511,6 +582,7 @@ class CacheResourceAPI:
                     validate=validate,
                     hash_funcs=hash_funcs,
                     on_release=on_release,
+                    scope=scope,
                 )
             )
 
@@ -524,6 +596,7 @@ class CacheResourceAPI:
                 validate=validate,
                 hash_funcs=hash_funcs,
                 on_release=on_release,
+                scope=scope,
             )
         )
 

streamlit/runtime/caching/cache_utils.py

@@ -30,6 +30,7 @@ from typing import (
     Any,
     Final,
     Generic,
+    Literal,
     TypeAlias,
     TypeVar,
     cast,
@@ -41,6 +42,7 @@ from typing_extensions import ParamSpec
 from streamlit import type_util
 from streamlit.dataframe_util import is_unevaluated_data_object
 from streamlit.delta_generator_singletons import get_dg_singleton_instance
+from streamlit.errors import StreamlitAPIException
 from streamlit.logger import get_logger
 from streamlit.runtime.caching.cache_errors import (
     CacheError,
@@ -81,6 +83,32 @@ R = TypeVar("R")
 OnRelease: TypeAlias = Callable[[Any], None]
 
 
+# The scope of a cache.
+CacheScope: TypeAlias = Literal["global", "session"]
+
+
+def get_session_id_or_throw() -> str:
+    """Returns the active session ID from the thread-local run context.
+
+    Raises
+    ------
+    StreamlitAPIException
+        Raised if there is no thread-local run context.
+    """
+    from streamlit.runtime.scriptrunner_utils.script_run_context import (
+        get_script_run_ctx,
+    )
+
+    ctx = get_script_run_ctx()
+    if ctx is None:
+        raise StreamlitAPIException(
+            "A session-scoped cache was accessed outside of the app execution thread. "
+            "Make sure all session-scoped caches are read during rendering and not "
+            "read in background threads."
+        )
+    return ctx.session_id
+
+
 class Cache(Generic[R]):
     """Function cache interface. Caches persist across script runs."""
 
@@ -96,7 +124,9 @@ class Cache(Generic[R]):
         ------
         CacheKeyNotFoundError
             Raised if value_key is not in the cache.
-
+        StreamlitAPIException
+            Raised when a thread attempts to read from a session-scoped cache but that
+            thread does not have a session associated with it.
         """
         raise NotImplementedError
 
@@ -104,6 +134,12 @@ class Cache(Generic[R]):
     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.
+
+        Raises
+        ------
+        StreamlitAPIException
+            Raised when a thread attempts to write to a session-scoped cache but that
+            thread does not have a session associated with it.
         """
         # We *could* `del self._value_locks[value_key]` here, since nobody will be taking
         # a compute_value_lock for this value_key after the result is written.
@@ -150,11 +186,13 @@ class CachedFuncInfo(Generic[P, R]):
         hash_funcs: HashFuncsDict | None,
         show_spinner: bool | str,
         show_time: bool = False,
+        scope: CacheScope = "global",
     ) -> None:
         self.func = func
         self.hash_funcs = hash_funcs
         self.show_spinner = show_spinner
         self.show_time = show_time
+        self.scope = scope
 
     @property
     def cache_type(self) -> CacheType:
@@ -165,7 +203,10 @@ class CachedFuncInfo(Generic[P, R]):
         raise NotImplementedError
 
     def get_function_cache(self, function_key: str) -> Cache[R]:
-        """Get or create the function cache for the given key."""
+        """Get or create the function cache for the given key.
+
+        This is responsible for handling cache scope correctly.
+        """
         raise NotImplementedError
 
 

streamlit/runtime/stats.py

@@ -19,6 +19,7 @@ from typing import TYPE_CHECKING, Final, NamedTuple, Protocol, runtime_checkable
 
 CACHE_MEMORY_FAMILY: Final = "cache_memory_bytes"
 SESSION_EVENTS_FAMILY: Final = "session_events_total"
+SESSION_DURATION_FAMILY: Final = "session_duration_seconds_total"
 ACTIVE_SESSIONS_FAMILY: Final = "active_sessions"
 
 if TYPE_CHECKING: