streamlit-nightly 1.32.3.dev20240325__py2.py3-none-any.whl → 1.32.3.dev20240328__py2.py3-none-any.whl

streamlit/runtime/fragment.py

@@ -0,0 +1,239 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2024)
+#
+# 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 contextlib
+import hashlib
+import inspect
+from abc import abstractmethod
+from copy import deepcopy
+from datetime import timedelta
+from functools import wraps
+from typing import Any, Callable, Protocol, TypeVar, overload
+
+from streamlit.proto.ForwardMsg_pb2 import ForwardMsg
+from streamlit.runtime.metrics_util import gather_metrics
+from streamlit.runtime.scriptrunner import get_script_run_ctx
+from streamlit.time_util import time_to_seconds
+
+F = TypeVar("F", bound=Callable[..., Any])
+Fragment = Callable[[], Any]
+
+
+class FragmentStorage(Protocol):
+    """A key-value store for Fragments. Used to implement the @st.experimental_fragment
+    decorator.
+
+    We intentionally define this as its own protocol despite how generic it appears to
+    be at first glance. The reason why is that, in any case where fragments aren't just
+    stored as Python closures in memory, storing and retrieving Fragments will generally
+    involve serializing and deserializing function bytecode, which is a tricky aspect
+    to implementing FragmentStorages that won't generally appear with our other *Storage
+    protocols.
+    """
+
+    @abstractmethod
+    def get(self, key: str) -> Fragment:
+        """Returns the stored fragment for the given key."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def set(self, key: str, value: Fragment) -> None:
+        """Saves a fragment under the given key."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Delete the fragment corresponding to the given key."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all fragments saved in this FragmentStorage."""
+        raise NotImplementedError
+
+
+# NOTE: Ideally, we'd like to add a MemoryFragmentStorageStatProvider implementation to
+# keep track of memory usage due to fragments, but doing something like this ends up
+# being difficult in practice as the memory usage of a closure is hard to measure (the
+# vendored implementation of pympler.asizeof that we use elsewhere is unable to measure
+# the size of a function).
+class MemoryFragmentStorage(FragmentStorage):
+    """A simple, memory-backed implementation of FragmentStorage.
+
+    MemoryFragmentStorage is just a wrapper around a plain Python dict that complies with
+    the FragmentStorage protocol.
+    """
+
+    def __init__(self):
+        self._fragments: dict[str, Fragment] = {}
+
+    def get(self, key: str) -> Fragment:
+        return self._fragments[key]
+
+    def set(self, key: str, value: Fragment) -> None:
+        self._fragments[key] = value
+
+    def delete(self, key: str) -> None:
+        del self._fragments[key]
+
+    def clear(self) -> None:
+        self._fragments.clear()
+
+
+@overload
+def fragment(
+    func: F,
+    *,
+    run_every: int | float | timedelta | str | None = None,
+) -> F:
+    ...
+
+
+# Support being able to pass parameters to this decorator (that is, being able to write
+# `@fragment(run_every=5.0)`).
+@overload
+def fragment(
+    func: None = None,
+    *,
+    run_every: int | float | timedelta | str | None = None,
+) -> Callable[[F], F]:
+    ...
+
+
+@gather_metrics("experimental_fragment")
+def fragment(
+    func: F | None = None,
+    *,
+    run_every: int | float | timedelta | str | None = None,
+) -> Callable[[F], F] | F:
+    """Allow a function to be run independently of the full script.
+
+    Functions decorated with ``@st.experimental_fragment`` are handled specially within
+    an app: when a widget created within an invocation of the function (a fragment) is
+    interacted with, then only that fragment is rerun rather than the full streamlit app.
+
+    Parameters
+    ----------
+    run_every: int, float, timedelta, str, or None
+        If set, fragments created from this function rerun periodically at the specified
+        time interval.
+
+    Example
+    -------
+    The following example demonstrates basic usage of ``@st.experimental_fragment``. In
+    this app, clicking on the "rerun full script" button will increment both counters,
+    but the "rerun fragment" button will only increment the counter within the fragment.
+
+    ```python3
+    import streamlit as st
+
+    if "script_runs" not in st.session_state:
+        st.session_state.script_runs = 0
+        st.session_state.fragment_runs = 0
+
+    @st.experimental_fragment
+    def fragment():
+        st.button("rerun fragment")
+        st.write(f"fragment runs: {st.session_state.fragment_runs}")
+        st.session_state.fragment_runs += 1
+
+    fragment()
+
+    st.button("rerun full script")
+    st.write(f"full script runs: {st.session_state.script_runs}")
+    st.session_state.script_runs += 1
+    ```
+    """
+
+    if func is None:
+        # Support passing the params via function decorator
+        def wrapper(f: F) -> F:
+            return fragment(
+                func=f,
+                run_every=run_every,
+            )
+
+        return wrapper
+    else:
+        non_optional_func = func
+
+    @wraps(non_optional_func)
+    def wrap(*args, **kwargs):
+        from streamlit.delta_generator import dg_stack
+
+        ctx = get_script_run_ctx()
+        if ctx is None:
+            return
+
+        cursors_snapshot = deepcopy(ctx.cursors)
+        dg_stack_snapshot = deepcopy(dg_stack.get())
+        active_dg = dg_stack_snapshot[-1]
+        h = hashlib.new("md5")
+        h.update(
+            f"{non_optional_func.__module__}.{non_optional_func.__qualname__}{active_dg._get_delta_path_str()}".encode(
+                "utf-8"
+            )
+        )
+        fragment_id = h.hexdigest()
+
+        def wrapped_fragment():
+            import streamlit as st
+
+            # NOTE: We need to call get_script_run_ctx here again and can't just use the
+            # value of ctx from above captured by the closure because subsequent
+            # fragment runs will generally run in a new script run, thus we'll have a
+            # new ctx.
+            ctx = get_script_run_ctx(suppress_warning=True)
+            assert ctx is not None
+
+            if ctx.fragment_ids_this_run:
+                # This script run is a run of one or more fragments. We restore the
+                # state of ctx.cursors and dg_stack to the snapshots we took when this
+                # fragment was declared.
+                ctx.cursors = deepcopy(cursors_snapshot)
+                dg_stack.set(deepcopy(dg_stack_snapshot))
+            else:
+                # Otherwise, we must be in a full script run. We need to temporarily set
+                # ctx.current_fragment_id so that elements corresponding to this
+                # fragment get tagged with the appropriate ID. ctx.current_fragment_id
+                # gets reset after the fragment function finishes running.
+                ctx.current_fragment_id = fragment_id
+
+            try:
+                with st.container():
+                    result = non_optional_func(*args, **kwargs)
+            finally:
+                ctx.current_fragment_id = None
+
+            return result
+
+        ctx.fragment_storage.set(fragment_id, wrapped_fragment)
+
+        if run_every:
+            msg = ForwardMsg()
+            msg.auto_rerun.interval = time_to_seconds(run_every)
+            msg.auto_rerun.fragment_id = fragment_id
+            ctx.enqueue(msg)
+
+        return wrapped_fragment()
+
+    with contextlib.suppress(AttributeError):
+        # Make this a well-behaved decorator by preserving important function
+        # attributes.
+        wrap.__dict__.update(non_optional_func.__dict__)
+        wrap.__signature__ = inspect.signature(non_optional_func)  # type: ignore
+
+    return wrap

streamlit/runtime/metrics_util.py

@@ -427,12 +427,17 @@ def create_page_profile_message(
     uncaught_exception: str | None = None,
 ) -> ForwardMsg:
     """Create and return the full PageProfile ForwardMsg."""
+    # Local import to prevent circular dependencies
+    from streamlit.runtime.scriptrunner import get_script_run_ctx
+
     msg = ForwardMsg()
-    msg.page_profile.commands.extend(commands)
-    msg.page_profile.exec_time = exec_time
-    msg.page_profile.prep_time = prep_time
+    page_profile = msg.page_profile
+
+    page_profile.commands.extend(commands)
+    page_profile.exec_time = exec_time
+    page_profile.prep_time = prep_time
 
-    msg.page_profile.headless = config.get_option("server.headless")
+    page_profile.headless = config.get_option("server.headless")
 
     # Collect all config options that have been manually set
     config_options: set[str] = set()
@@ -447,7 +452,7 @@ def create_page_profile_message(
                 option_name = f"{option_name}:default"
             config_options.add(option_name)
 
-    msg.page_profile.config.extend(config_options)
+    page_profile.config.extend(config_options)
 
     # Check the predefined set of modules for attribution
     attributions: set[str] = {
@@ -456,11 +461,14 @@ def create_page_profile_message(
         if attribution in sys.modules
     }
 
-    msg.page_profile.os = str(sys.platform)
-    msg.page_profile.timezone = str(time.tzname)
-    msg.page_profile.attributions.extend(attributions)
+    page_profile.os = str(sys.platform)
+    page_profile.timezone = str(time.tzname)
+    page_profile.attributions.extend(attributions)
 
     if uncaught_exception:
-        msg.page_profile.uncaught_exception = uncaught_exception
+        page_profile.uncaught_exception = uncaught_exception
+
+    if ctx := get_script_run_ctx():
+        page_profile.is_fragment_run = bool(ctx.current_fragment_id)
 
     return msg

streamlit/runtime/runtime.py

@@ -22,8 +22,6 @@ from enum import Enum
 from typing import TYPE_CHECKING, Awaitable, Final, NamedTuple
 
 from streamlit import config
-from streamlit.components.lib.local_component_registry import LocalComponentRegistry
-from streamlit.components.types.base_component_registry import BaseComponentRegistry
 from streamlit.logger import get_logger
 from streamlit.proto.BackMsg_pb2 import BackMsg
 from streamlit.proto.ForwardMsg_pb2 import ForwardMsg
@@ -98,11 +96,6 @@ class RuntimeConfig:
         default_factory=LocalDiskCacheStorageManager
     )
 
-    # The ComponentRegistry instance to use.
-    component_registry: BaseComponentRegistry = field(
-        default_factory=LocalComponentRegistry
-    )
-
     # The SessionManager class to be used.
     session_manager_class: type[SessionManager] = WebsocketSessionManager
 
@@ -112,6 +105,12 @@ class RuntimeConfig:
     # True if the command used to start Streamlit was `streamlit hello`.
     is_hello: bool = False
 
+    # TODO(vdonato): Eventually add a new fragment_storage_class field enabling the code
+    # creating a new Streamlit Runtime to configure the FragmentStorage instances
+    # created by each new AppSession. We choose not to do this for now to avoid adding
+    # additional complexity to RuntimeConfig/SessionManager/etc when it's unlikely
+    # we'll have a custom implementation of this class anytime soon.
+
 
 class RuntimeState(Enum):
     INITIAL = "INITIAL"
@@ -196,7 +195,6 @@ class Runtime:
         self._state = RuntimeState.INITIAL
 
         # Initialize managers
-        self._component_registry = config.component_registry
         self._message_cache = ForwardMsgCache()
         self._uploaded_file_mgr = config.uploaded_file_manager
         self._media_file_mgr = MediaFileManager(storage=config.media_file_storage)
@@ -222,10 +220,6 @@ class Runtime:
     def state(self) -> RuntimeState:
         return self._state
 
-    @property
-    def component_registry(self) -> BaseComponentRegistry:
-        return self._component_registry
-
     @property
     def message_cache(self) -> ForwardMsgCache:
         return self._message_cache

streamlit/runtime/runtime_util.py

@@ -16,10 +16,12 @@
 
 from __future__ import annotations
 
-from typing import Any
+import math
+from datetime import timedelta
+from typing import Any, Literal, overload
 
 from streamlit import config
-from streamlit.errors import MarkdownFormattedException
+from streamlit.errors import MarkdownFormattedException, StreamlitAPIException
 from streamlit.proto.ForwardMsg_pb2 import ForwardMsg
 from streamlit.runtime.forward_msg_cache import populate_hash_if_needed
 
@@ -54,6 +56,17 @@ of the client's browser and the Streamlit server._
         )
 
 
+class BadDurationStringError(StreamlitAPIException):
+    """Raised when a bad duration argument string is passed."""
+
+    def __init__(self, duration: str):
+        MarkdownFormattedException.__init__(
+            self,
+            "TTL string doesn't look right. It should be formatted as"
+            f"`'1d2h34m'` or `2 days`, for example. Got: {duration}",
+        )
+
+
 def is_cacheable_msg(msg: ForwardMsg) -> bool:
     """True if the given message qualifies for caching."""
     if msg.WhichOneof("type") in {"ref_hash", "initialize"}:
@@ -62,6 +75,45 @@ def is_cacheable_msg(msg: ForwardMsg) -> bool:
     return msg.ByteSize() >= int(config.get_option("global.minCachedMessageSize"))
 
 
+@overload
+def duration_to_seconds(
+    ttl: float | timedelta | str | None, *, coerce_none_to_inf: Literal[False]
+) -> float | None:
+    ...
+
+
+@overload
+def duration_to_seconds(ttl: float | timedelta | str | None) -> float:
+    ...
+
+
+def duration_to_seconds(
+    ttl: float | timedelta | str | None, *, coerce_none_to_inf: bool = True
+) -> float | None:
+    """
+    Convert a ttl value to a float representing "number of seconds".
+    """
+    if coerce_none_to_inf and ttl is None:
+        return math.inf
+    if isinstance(ttl, timedelta):
+        return ttl.total_seconds()
+    if isinstance(ttl, str):
+        import numpy as np
+        import pandas as pd
+
+        try:
+            out: float = pd.Timedelta(ttl).total_seconds()
+        except ValueError as ex:
+            raise BadDurationStringError(ttl) from ex
+
+        if np.isnan(out):
+            raise BadDurationStringError(ttl)
+
+        return out
+
+    return ttl
+
+
 def serialize_forward_msg(msg: ForwardMsg) -> bytes:
     """Serialize a ForwardMsg to send to a client.
 

streamlit/runtime/scriptrunner/script_requests.py

@@ -15,7 +15,7 @@
 from __future__ import annotations
 
 import threading
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from enum import Enum
 from typing import cast
 
@@ -46,6 +46,7 @@ class RerunData:
     widget_states: WidgetStates | None = None
     page_script_hash: str = ""
     page_name: str = ""
+    fragment_id_queue: list[str] = field(default_factory=list)
 
     def __repr__(self) -> str:
         return util.repr_(self)
@@ -103,41 +104,46 @@ class ScriptRequests:
                 return False
 
             if self._state == ScriptRequestType.CONTINUE:
-                # If we're running, we can handle a rerun request
-                # unconditionally.
+                # The script is currently running, and we haven't received a request to
+                # rerun it as of yet. We can handle a rerun request unconditionally so
+                # just change self._state and set self._rerun_data.
                 self._state = ScriptRequestType.RERUN
                 self._rerun_data = new_data
                 return True
 
             if self._state == ScriptRequestType.RERUN:
-                # If we have an existing Rerun request, we coalesce this
-                # new request into it.
-                if self._rerun_data.widget_states is None:
-                    # The existing request's widget_states is None, which
-                    # means it wants to rerun with whatever the most
-                    # recent script execution's widget state was.
-                    # We have no meaningful state to merge with, and
-                    # so we simply overwrite the existing request.
-                    self._rerun_data = new_data
-                    return True
-
-                if new_data.widget_states is not None:
-                    # Both the existing and the new request have
-                    # non-null widget_states. Merge them together.
-                    coalesced_states = coalesce_widget_states(
-                        self._rerun_data.widget_states, new_data.widget_states
-                    )
-                    self._rerun_data = RerunData(
-                        query_string=new_data.query_string,
-                        widget_states=coalesced_states,
-                        page_script_hash=new_data.page_script_hash,
-                        page_name=new_data.page_name,
-                    )
-                    return True
-
-                # If old widget_states is NOT None, and new widget_states IS
-                # None, then this new request is entirely redundant. Leave
-                # our existing rerun_data as is.
+                # We already have an existing Rerun request, so we can coalesce the new
+                # rerun request into the existing one.
+
+                coalesced_states = coalesce_widget_states(
+                    self._rerun_data.widget_states, new_data.widget_states
+                )
+
+                if new_data.fragment_id_queue:
+                    # This RERUN request corresponds to a fragment run. We append the
+                    # new fragment ID to the end of the current fragment_id_queue if it
+                    # isn't already contained in it.
+                    fragment_id_queue = [*self._rerun_data.fragment_id_queue]
+                    if (
+                        # new_data.fragment_id_queue is always a singleton
+                        (new_fragment_id := new_data.fragment_id_queue[0])
+                        not in fragment_id_queue
+                    ):
+                        fragment_id_queue.append(new_fragment_id)
+                else:
+                    # Otherwise, this is a request to rerun the full script, so we want
+                    # to clear out any fragments we have queued to run since they'll all
+                    # be run with the full script anyway.
+                    fragment_id_queue = []
+
+                self._rerun_data = RerunData(
+                    query_string=new_data.query_string,
+                    widget_states=coalesced_states,
+                    page_script_hash=new_data.page_script_hash,
+                    page_name=new_data.page_name,
+                    fragment_id_queue=fragment_id_queue,
+                )
+
                 return True
 
             # We'll never get here
@@ -146,22 +152,32 @@ class ScriptRequests:
     def on_scriptrunner_yield(self) -> ScriptRequest | None:
         """Called by the ScriptRunner when it's at a yield point.
 
-        If we have no request, return None.
+        If we have no request or a RERUN request corresponding to one or more fragments,
+        return None.
 
-        If we have a RERUN request, return the request and set our internal
+        If we have a (full script) RERUN request, return the request and set our internal
         state to CONTINUE.
 
         If we have a STOP request, return the request and remain stopped.
         """
-        if self._state == ScriptRequestType.CONTINUE:
-            # We avoid taking a lock in the common case. If a STOP or RERUN
-            # request is received between the `if` and `return`, it will be
-            # handled at the next `on_scriptrunner_yield`, or when
+        if self._state == ScriptRequestType.CONTINUE or (
+            # Reruns corresponding to fragments should *not* cancel the current script
+            # run as doing so will affect elements outside of the fragment.
+            self._state == ScriptRequestType.RERUN
+            and self._rerun_data.fragment_id_queue
+        ):
+            # We avoid taking the lock in the common cases of having no request and
+            # having a RERUN request corresponding to >=1 fragments. If a STOP or
+            # (full script) RERUN request is received between the `if` and `return`, it
+            # will be handled at the next `on_scriptrunner_yield`, or when
             # `on_scriptrunner_ready` is called.
             return None
 
         with self._lock:
             if self._state == ScriptRequestType.RERUN:
+                if self._rerun_data.fragment_id_queue:
+                    return None
+
                 self._state = ScriptRequestType.CONTINUE
                 return ScriptRequest(ScriptRequestType.RERUN, self._rerun_data)
 

streamlit/runtime/scriptrunner/script_run_context.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 import collections
 import threading
 from dataclasses import dataclass, field
-from typing import Callable, Counter, Dict, Final, Union
+from typing import TYPE_CHECKING, Callable, Counter, Dict, Final, Union
 from urllib import parse
 
 from typing_extensions import TypeAlias
@@ -31,6 +31,9 @@ from streamlit.runtime.scriptrunner.script_requests import ScriptRequests
 from streamlit.runtime.state import SafeSessionState
 from streamlit.runtime.uploaded_file_manager import UploadedFileManager
 
+if TYPE_CHECKING:
+    from streamlit.runtime.fragment import FragmentStorage
+
 _LOGGER: Final = get_logger(__name__)
 
 UserInfo: TypeAlias = Dict[str, Union[str, None]]
@@ -59,6 +62,7 @@ class ScriptRunContext:
     main_script_path: str
     page_script_hash: str
     user_info: UserInfo
+    fragment_storage: "FragmentStorage"
 
     gather_usage_stats: bool = False
     command_tracking_deactivated: bool = False
@@ -71,12 +75,19 @@ class ScriptRunContext:
     form_ids_this_run: set[str] = field(default_factory=set)
     cursors: dict[int, "streamlit.cursor.RunningCursor"] = field(default_factory=dict)
     script_requests: ScriptRequests | None = None
+    current_fragment_id: str | None = None
+    fragment_ids_this_run: set[str] | None = None
 
     # TODO(willhuang1997): Remove this variable when experimental query params are removed
     _experimental_query_params_used = False
     _production_query_params_used = False
 
-    def reset(self, query_string: str = "", page_script_hash: str = "") -> None:
+    def reset(
+        self,
+        query_string: str = "",
+        page_script_hash: str = "",
+        fragment_ids_this_run: set[str] | None = None,
+    ) -> None:
         self.cursors = {}
         self.widget_ids_this_run = set()
         self.widget_user_keys_this_run = set()
@@ -89,6 +100,8 @@ class ScriptRunContext:
         self.command_tracking_deactivated: bool = False
         self.tracked_commands = []
         self.tracked_commands_counter = collections.Counter()
+        self.current_fragment_id = None
+        self.fragment_ids_this_run = fragment_ids_this_run
 
         parsed_query_params = parse.parse_qs(query_string, keep_blank_values=True)
         with self.session_state.query_params() as qp: