streamlit-nightly 1.43.2.dev20250307__py3-none-any.whl

streamlit/runtime/caching/legacy_cache_api.py

@@ -0,0 +1,169 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2025)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""A library of caching utilities."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, TypeVar
+
+from streamlit import deprecation_util
+from streamlit.runtime.caching import CACHE_DOCS_URL
+from streamlit.runtime.metrics_util import gather_metrics
+
+if TYPE_CHECKING:
+    from streamlit.runtime.caching.hashing import HashFuncsDict
+
+# Type-annotate the decorator function.
+# (See https://mypy.readthedocs.io/en/stable/generics.html#decorator-factories)
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@gather_metrics("cache")
+def cache(
+    func: F | None = None,
+    persist: bool = False,
+    allow_output_mutation: bool = False,
+    show_spinner: bool = True,
+    suppress_st_warning: bool = False,
+    hash_funcs: HashFuncsDict | None = None,
+    max_entries: int | None = None,
+    ttl: float | None = None,
+):
+    """Legacy caching decorator (deprecated).
+
+    Legacy caching with ``st.cache`` has been removed from Streamlit. This is
+    now an alias for ``st.cache_data`` and ``st.cache_resource``.
+
+    Parameters
+    ----------
+    func : callable
+        The function to cache. Streamlit hashes the function's source code.
+
+    persist : bool
+        Whether to persist the cache on disk.
+
+    allow_output_mutation : bool
+        Whether to use ``st.cache_data`` or ``st.cache_resource``. If this is
+        ``False`` (default), the arguments are passed to ``st.cache_data``. If
+        this is ``True``, the arguments are passed to ``st.cache_resource``.
+
+    show_spinner : bool
+        Enable the spinner. Default is ``True`` to show a spinner when there is
+        a "cache miss" and the cached data is being created.
+
+    suppress_st_warning : bool
+        This is not used.
+
+    hash_funcs : dict or None
+        Mapping of types or fully qualified names to hash functions. This is used to
+        override the behavior of the hasher inside Streamlit's caching mechanism: when
+        the hasher encounters an object, it will first check to see if its type matches
+        a key in this dict and, if so, will use the provided function to generate a hash
+        for it. See below for an example of how this can be used.
+
+    max_entries : int or None
+        The maximum number of entries to keep in the cache, or ``None``
+        for an unbounded cache. (When a new entry is added to a full cache,
+        the oldest cached entry will be removed.) The default is ``None``.
+
+    ttl : float or None
+        The maximum number of seconds to keep an entry in the cache, or
+        None if cache entries should not expire. The default is None.
+
+    Example
+    -------
+    >>> import streamlit as st
+    >>>
+    >>> @st.cache
+    ... def fetch_and_clean_data(url):
+    ...     # Fetch data from URL here, and then clean it up.
+    ...     return data
+    >>>
+    >>> d1 = fetch_and_clean_data(DATA_URL_1)
+    >>> # Actually executes the function, since this is the first time it was
+    >>> # encountered.
+    >>>
+    >>> d2 = fetch_and_clean_data(DATA_URL_1)
+    >>> # Does not execute the function. Instead, returns its previously computed
+    >>> # value. This means that now the data in d1 is the same as in d2.
+    >>>
+    >>> d3 = fetch_and_clean_data(DATA_URL_2)
+    >>> # This is a different URL, so the function executes.
+
+    To set the ``persist`` parameter, use this command as follows:
+
+    >>> @st.cache(persist=True)
+    ... def fetch_and_clean_data(url):
+    ...     # Fetch data from URL here, and then clean it up.
+    ...     return data
+
+    To disable hashing return values, set the ``allow_output_mutation`` parameter to
+    ``True``:
+
+    >>> @st.cache(allow_output_mutation=True)
+    ... def fetch_and_clean_data(url):
+    ...     # Fetch data from URL here, and then clean it up.
+    ...     return data
+
+
+    To override the default hashing behavior, pass a custom hash function.
+    You can do that by mapping a type (e.g. ``MongoClient``) to a hash function (``id``)
+    like this:
+
+    >>> @st.cache(hash_funcs={MongoClient: id})
+    ... def connect_to_database(url):
+    ...     return MongoClient(url)
+
+    Alternatively, you can map the type's fully-qualified name
+    (e.g. ``"pymongo.mongo_client.MongoClient"``) to the hash function instead:
+
+    >>> @st.cache(hash_funcs={"pymongo.mongo_client.MongoClient": id})
+    ... def connect_to_database(url):
+    ...     return MongoClient(url)
+
+    """
+    import streamlit as st
+
+    deprecation_util.show_deprecation_warning(
+        f"""
+`st.cache` is deprecated and will be removed soon. Please use one of Streamlit's new
+caching commands, `st.cache_data` or `st.cache_resource`. More information
+[in our docs]({CACHE_DOCS_URL}).
+
+**Note**: The behavior of `st.cache` was updated in Streamlit 1.36 to the new caching
+logic used by `st.cache_data` and `st.cache_resource`. This might lead to some problems
+or unexpected behavior in certain edge cases.
+"""
+    )
+
+    # suppress_st_warning is unused since its not supported by the new caching commands
+
+    if allow_output_mutation:
+        return st.cache_resource(  # type: ignore
+            func,
+            show_spinner=show_spinner,
+            hash_funcs=hash_funcs,
+            max_entries=max_entries,
+            ttl=ttl,
+        )
+
+    return st.cache_data(  # type: ignore
+        func,
+        persist=persist,
+        show_spinner=show_spinner,
+        hash_funcs=hash_funcs,
+        max_entries=max_entries,
+        ttl=ttl,
+    )

streamlit/runtime/caching/storage/__init__.py

@@ -0,0 +1,29 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2025)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from streamlit.runtime.caching.storage.cache_storage_protocol import (
+    CacheStorage,
+    CacheStorageContext,
+    CacheStorageError,
+    CacheStorageKeyNotFoundError,
+    CacheStorageManager,
+)
+
+__all__ = [
+    "CacheStorage",
+    "CacheStorageContext",
+    "CacheStorageError",
+    "CacheStorageKeyNotFoundError",
+    "CacheStorageManager",
+]

streamlit/runtime/caching/storage/cache_storage_protocol.py

@@ -0,0 +1,239 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2025)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Declares the CacheStorageContext dataclass, which contains parameter information for
+each function decorated by `@st.cache_data` (for example: ttl, max_entries etc.)
+
+Declares the CacheStorageManager protocol, which implementations are used
+to create CacheStorage instances and to optionally clear all cache storages,
+that were created by this manager, and to check if the context is valid for the storage.
+
+Declares the CacheStorage protocol, which implementations are used to store cached
+values for a single `@st.cache_data` decorated function serialized as bytes.
+
+How these classes work together
+-------------------------------
+- CacheStorageContext : this is a dataclass that contains the parameters from
+`@st.cache_data` that are passed to the CacheStorageManager.create() method.
+
+- CacheStorageManager : each instance of this is able to create CacheStorage
+instances, and optionally to clear data of all cache storages.
+
+- CacheStorage : each instance of this is able to get, set, delete, and clear
+entries for a single `@st.cache_data` decorated function.
+
+  ┌───────────────────────────────┐
+  │                               │
+  │    CacheStorageManager        │
+  │                               │
+  │     - clear_all(optional)     │
+  │     - check_context           │
+  │                               │
+  └──┬────────────────────────────┘
+     │
+     │                ┌──────────────────────┐
+     │                │  CacheStorage        │
+     │ create(context)│                      │
+     └────────────────►    - get             │
+                      │    - set             │
+                      │    - delete          │
+                      │    - close (optional)│
+                      │    - clear           │
+                      └──────────────────────┘
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+
+class CacheStorageError(Exception):
+    """Base exception raised by the cache storage"""
+
+
+class CacheStorageKeyNotFoundError(CacheStorageError):
+    """Raised when the key is not found in the cache storage"""
+
+
+class InvalidCacheStorageContext(CacheStorageError):
+    """Raised if the cache storage manager is not able to work with
+    provided CacheStorageContext.
+    """
+
+
+@dataclass(frozen=True)
+class CacheStorageContext:
+    """Context passed to the cache storage during initialization
+    This is the normalized parameters that are passed to CacheStorageManager.create()
+    method.
+
+    Parameters
+    ----------
+    function_key: str
+        A hash computed based on function name and source code decorated
+        by `@st.cache_data`
+
+    function_display_name: str
+        The display name of the function that is decorated by `@st.cache_data`
+
+    ttl_seconds : float or None
+        The time-to-live for the keys in storage, in seconds. If None, the entry
+        will never expire.
+
+    max_entries : int or None
+        The maximum number of entries to store in the cache storage.
+        If None, the cache storage will not limit the number of entries.
+
+    persist : Literal["disk"] or None
+        The persistence mode for the cache storage.
+        Legacy parameter, that used in Streamlit current cache storage implementation.
+        Could be ignored by cache storage implementation, if storage does not support
+        persistence or it persistent by default.
+    """
+
+    function_key: str
+    function_display_name: str
+    ttl_seconds: float | None = None
+    max_entries: int | None = None
+    persist: Literal["disk"] | None = None
+
+
+class CacheStorage(Protocol):
+    """Cache storage protocol, that should be implemented by the concrete cache storages.
+    Used to store cached values for a single `@st.cache_data` decorated function
+    serialized as bytes.
+
+    CacheStorage instances should be created by `CacheStorageManager.create()` method.
+
+    Notes
+    -----
+    Threading: The methods of this protocol could be called from multiple threads.
+    This is a responsibility of the concrete implementation to ensure thread safety
+    guarantees.
+    """
+
+    @abstractmethod
+    def get(self, key: str) -> bytes:
+        """Returns the stored value for the key.
+
+        Raises
+        ------
+        CacheStorageKeyNotFoundError
+            Raised if the key is not in the storage.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def set(self, key: str, value: bytes) -> None:
+        """Sets the value for a given key"""
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Delete a given key"""
+        raise NotImplementedError
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all keys for the storage"""
+        raise NotImplementedError
+
+    def close(self) -> None:
+        """Closes the cache storage, it is optional to implement, and should be used
+        to close open resources, before we delete the storage instance.
+        e.g. close the database connection etc.
+        """
+        pass
+
+
+class CacheStorageManager(Protocol):
+    """Cache storage manager protocol, that should be implemented by the concrete
+    cache storage managers.
+
+    It is responsible for:
+        - Creating cache storage instances for the specific
+        decorated functions,
+        - Validating the context for the cache storages.
+        - Optionally clearing all cache storages in optimal way.
+
+    It should be created during Runtime initialization.
+    """
+
+    @abstractmethod
+    def create(self, context: CacheStorageContext) -> CacheStorage:
+        """Creates a new cache storage instance
+        Please note that the ttl, max_entries and other context fields are specific
+        for whole storage, not for individual key.
+
+        Notes
+        -----
+        Threading: Should be safe to call from any thread.
+        """
+        raise NotImplementedError
+
+    def clear_all(self) -> None:
+        """Remove everything what possible from the cache storages in optimal way.
+        meaningful default behaviour is to raise NotImplementedError, so this is not
+        abstractmethod.
+
+        The method is optional to implement: cache data API will fall back to remove
+        all available storages one by one via storage.clear() method
+        if clear_all raises NotImplementedError.
+
+        Raises
+        ------
+        NotImplementedError
+            Raised if the storage manager does not provide an ability to clear
+            all storages at once in optimal way.
+
+        Notes
+        -----
+        Threading: This method could be called from multiple threads.
+        This is a responsibility of the concrete implementation to ensure
+        thread safety guarantees.
+        """
+        raise NotImplementedError
+
+    def check_context(self, context: CacheStorageContext) -> None:
+        """Checks if the context is valid for the storage manager.
+        This method should not return anything, but log message or raise an exception
+        if the context is invalid.
+
+        In case of raising an exception, we not handle it and let the exception to be
+        propagated.
+
+        check_context is called only once at the moment of creating `@st.cache_data`
+        decorator for specific function, so it is not called for every cache hit.
+
+        Parameters
+        ----------
+        context: CacheStorageContext
+            The context to check for the storage manager, dummy function_key in context
+            will be used, since it is not computed at the point of calling this method.
+
+        Raises
+        ------
+        InvalidCacheStorageContext
+            Raised if the cache storage manager is not able to work with provided
+            CacheStorageContext. When possible we should log message instead, since
+            this exception will be propagated to the user.
+
+        Notes
+        -----
+        Threading: Should be safe to call from any thread.
+        """
+
+        pass

streamlit/runtime/caching/storage/dummy_cache_storage.py

@@ -0,0 +1,60 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2025)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from streamlit.runtime.caching.storage.cache_storage_protocol import (
+    CacheStorage,
+    CacheStorageContext,
+    CacheStorageKeyNotFoundError,
+    CacheStorageManager,
+)
+from streamlit.runtime.caching.storage.in_memory_cache_storage_wrapper import (
+    InMemoryCacheStorageWrapper,
+)
+
+
+class MemoryCacheStorageManager(CacheStorageManager):
+    def create(self, context: CacheStorageContext) -> CacheStorage:
+        """Creates a new cache storage instance wrapped with in-memory cache layer"""
+        persist_storage = DummyCacheStorage()
+        return InMemoryCacheStorageWrapper(
+            persist_storage=persist_storage, context=context
+        )
+
+    def clear_all(self) -> None:
+        raise NotImplementedError
+
+    def check_context(self, context: CacheStorageContext) -> None:
+        pass
+
+
+class DummyCacheStorage(CacheStorage):
+    def get(self, key: str) -> bytes:
+        """
+        Dummy gets the value for a given key,
+        always raises an CacheStorageKeyNotFoundError
+        """
+        raise CacheStorageKeyNotFoundError("Key not found in dummy cache")
+
+    def set(self, key: str, value: bytes) -> None:
+        pass
+
+    def delete(self, key: str) -> None:
+        pass
+
+    def clear(self) -> None:
+        pass
+
+    def close(self) -> None:
+        pass

streamlit/runtime/caching/storage/in_memory_cache_storage_wrapper.py

@@ -0,0 +1,145 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2025)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+import math
+import threading
+
+from cachetools import TTLCache
+
+from streamlit.logger import get_logger
+from streamlit.runtime.caching import cache_utils
+from streamlit.runtime.caching.storage.cache_storage_protocol import (
+    CacheStorage,
+    CacheStorageContext,
+    CacheStorageKeyNotFoundError,
+)
+from streamlit.runtime.stats import CacheStat
+
+_LOGGER = get_logger(__name__)
+
+
+class InMemoryCacheStorageWrapper(CacheStorage):
+    """
+    In-memory cache storage wrapper.
+
+    This class wraps a cache storage and adds an in-memory cache front layer,
+    which is used to reduce the number of calls to the storage.
+
+    The in-memory cache is a TTL cache, which means that the entries are
+    automatically removed if a given time to live (TTL) has passed.
+
+    The in-memory cache is also an LRU cache, which means that the entries
+    are automatically removed if the cache size exceeds a given maxsize.
+
+    If the storage implements its strategy for maxsize, it is recommended
+    (but not necessary) that the storage implement the same LRU strategy,
+    otherwise a situation may arise when different items are deleted from
+    the memory cache and from the storage.
+
+    Notes
+    -----
+    Threading: in-memory caching layer is thread safe: we hold self._mem_cache_lock for
+    working with this self._mem_cache object.
+    However, we do not hold this lock when calling into the underlying storage,
+    so it is the responsibility of the that storage to ensure that it is safe to use
+    it from multiple threads.
+    """
+
+    def __init__(self, persist_storage: CacheStorage, context: CacheStorageContext):
+        self.function_key = context.function_key
+        self.function_display_name = context.function_display_name
+        self._ttl_seconds = context.ttl_seconds
+        self._max_entries = context.max_entries
+        self._mem_cache: TTLCache[str, bytes] = TTLCache(
+            maxsize=self.max_entries,
+            ttl=self.ttl_seconds,
+            timer=cache_utils.TTLCACHE_TIMER,
+        )
+        self._mem_cache_lock = threading.Lock()
+        self._persist_storage = persist_storage
+
+    @property
+    def ttl_seconds(self) -> float:
+        return self._ttl_seconds if self._ttl_seconds is not None else math.inf
+
+    @property
+    def max_entries(self) -> float:
+        return float(self._max_entries) if self._max_entries is not None else math.inf
+
+    def get(self, key: str) -> bytes:
+        """
+        Returns the stored value for the key or raise CacheStorageKeyNotFoundError if
+        the key is not found
+        """
+        try:
+            entry_bytes = self._read_from_mem_cache(key)
+        except CacheStorageKeyNotFoundError:
+            entry_bytes = self._persist_storage.get(key)
+            self._write_to_mem_cache(key, entry_bytes)
+        return entry_bytes
+
+    def set(self, key: str, value: bytes) -> None:
+        """Sets the value for a given key"""
+        self._write_to_mem_cache(key, value)
+        self._persist_storage.set(key, value)
+
+    def delete(self, key: str) -> None:
+        """Delete a given key"""
+        self._remove_from_mem_cache(key)
+        self._persist_storage.delete(key)
+
+    def clear(self) -> None:
+        """Delete all keys for the in memory cache, and also the persistent storage"""
+        with self._mem_cache_lock:
+            self._mem_cache.clear()
+        self._persist_storage.clear()
+
+    def get_stats(self) -> list[CacheStat]:
+        """Returns a list of stats in bytes for the cache memory storage per item"""
+        stats = []
+
+        with self._mem_cache_lock:
+            for item in self._mem_cache.values():
+                stats.append(
+                    CacheStat(
+                        category_name="st_cache_data",
+                        cache_name=self.function_display_name,
+                        byte_length=len(item),
+                    )
+                )
+        return stats
+
+    def close(self) -> None:
+        """Closes the cache storage"""
+        self._persist_storage.close()
+
+    def _read_from_mem_cache(self, key: str) -> bytes:
+        with self._mem_cache_lock:
+            if key in self._mem_cache:
+                entry = bytes(self._mem_cache[key])
+                _LOGGER.debug("Memory cache HIT: %s", key)
+                return entry
+
+            else:
+                _LOGGER.debug("Memory cache MISS: %s", key)
+                raise CacheStorageKeyNotFoundError("Key not found in mem cache")
+
+    def _write_to_mem_cache(self, key: str, entry_bytes: bytes) -> None:
+        with self._mem_cache_lock:
+            self._mem_cache[key] = entry_bytes
+
+    def _remove_from_mem_cache(self, key: str) -> None:
+        with self._mem_cache_lock:
+            self._mem_cache.pop(key, None)