Repository: streamlit/streamlit
File: lib/streamlit/runtime/caching/cache_resource_api.py (Python)

Code before:
            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. Defaults to None.

        show_spinner : bool or str
            Enable the spinner. Default is True to show a spinner when there is
            a "cache miss" and the cached resource is being created. If string,
            value of show_spinner param will be used for spinner text.

        show_time : bool
            Whether to show the elapsed time next to the spinner text. If this is
            ``False`` (default), no time is displayed. If this is ``True``,
            elapsed time is displayed with a precision of 0.1 seconds. The time
            format is not configurable.

        validate : callable or None
            An optional validation function for cached resources. ``validate`` is called
            each time the cached value is accessed. It receives the cached value as
            its only parameter and it must return a boolean. If ``validate`` returns
            False, the current cached value is discarded, and the decorated function
            is called to compute a new value. This is useful e.g. to check the
            health of database connections.

            This is not used as a part of the cache key - meaning changes to this
            function between script runs will not trigger a new resource being
            generated.

        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.

        on_release : callable or None
            If set, a function to call when a cache entry is removed from the cache.
            The removed item will be provided to the function as an argument.

            This is only useful for caches which will remove entries normally: Those
            with ``max_entries`` or ``ttl`` settings. Note that TTL expiration does not
            happen on all reads - so ``ttl`` should not be used to guarantee timely
            cleanup, only cleanup when expired resources are accessed. Also note that
            expiration can happen on any app render or load, so care should be taken
            to ensure that ``on_release`` functions are thread-safe and do not rely on
            session state.

            This will NOT be called when an app is shut down.

            This function is not used as a part of the cache key - meaning changes to
            this function between script runs will not trigger a new resource being

Review comment (performance):
**suggestion:** This note might be a bit misleading/inconsistent since - afaik - none of the cache configuration parameters are part of the cache key or trigger a cache regeneration. Maybe we can simplify this to just add a top-level note that changing cache configuration parameter will not invalidate the existing cached entries.

Code after:
            - A ``timedelta`` object from `Python's built-in datetime library
              <https://docs.python.org/3/library/datetime.html#timedelta-objects>`_,
              e.g. ``timedelta(days=1)``.

            Changes to this value will trigger a new cache to be created.

        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. Defaults to None.

            Changes to this value will trigger a new cache to be created.

        show_spinner : bool or str
            Enable the spinner. Default is True to show a spinner when there is
            a "cache miss" and the cached resource is being created. If string,
            value of show_spinner param will be used for spinner text.

        show_time : bool
            Whether to show the elapsed time next to the spinner text. If this is
            ``False`` (default), no time is displayed. If this is ``True``,
            elapsed time is displayed with a precision of 0.1 seconds. The time
            format is not configurable.

        validate : callable or None
            An optional validation function for cached resources. ``validate`` is called
            each time the cached value is accessed. It receives the cached value as
            its only parameter and it must return a boolean. If ``validate`` returns
            False, the current cached value is discarded, and the decorated function
            is called to compute a new value. This is useful e.g. to check the
            health of database connections.

        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.

        on_release : callable or None
            If set, a function to call when a cache entry is removed from the cache.
            The removed item will be provided to the function as an argument.

            This is only useful for caches which will remove entries normally: Those
            with ``max_entries`` or ``ttl`` settings. Note that TTL expiration does not
            happen on all reads - so ``ttl`` should not be used to guarantee timely
            cleanup, only cleanup when expired resources are accessed. Also note that
            expiration can happen on any app render or load, so care should be taken
            to ensure that ``on_release`` functions are thread-safe and do not rely on
            session state.