streamlit 1.49.1__py3-none-any.whl → 1.51.0__py3-none-any.whl

streamlit/runtime/state/common.py

@@ -16,26 +16,29 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import (
+    TYPE_CHECKING,
     Any,
-    Callable,
     Final,
     Generic,
     Literal,
+    TypeAlias,
+    TypeGuard,
     TypeVar,
-    Union,
     cast,
     get_args,
 )
 
-from typing_extensions import TypeAlias, TypeGuard
-
 from streamlit import util
 from streamlit.errors import (
     StreamlitAPIException,
 )
 
+if TYPE_CHECKING:
+    from streamlit.runtime.state.session_state import SessionState
+
 GENERATED_ELEMENT_ID_PREFIX: Final = "$$ID"
 TESTING_KEY = "$$STREAMLIT_INTERNAL_KEY_TESTING"
 
@@ -44,7 +47,7 @@ T = TypeVar("T")
 T_co = TypeVar("T_co", covariant=True)
 
 
-WidgetArgs: TypeAlias = Union[tuple[Any, ...], list[Any]]
+WidgetArgs: TypeAlias = tuple[Any, ...] | list[Any]
 WidgetKwargs: TypeAlias = dict[str, Any]
 WidgetCallback: TypeAlias = Callable[..., None]
 
@@ -93,6 +96,7 @@ ValueFieldName: TypeAlias = Literal[
     "file_uploader_state_value",
     "int_value",
     "json_value",
+    "json_trigger_value",
     "string_value",
     "trigger_value",
     "string_trigger_value",
@@ -104,6 +108,13 @@ def is_array_value_field_name(obj: object) -> TypeGuard[ArrayValueFieldName]:
     return obj in _ARRAY_VALUE_FIELD_NAMES
 
 
+# Optional hook that allows a widget to customize how its value should be
+# presented in `st.session_state` without altering the underlying stored value
+# or callback semantics. The presenter receives the widget's base value and the
+# SessionState instance in case it needs to access additional widget state.
+WidgetValuePresenter: TypeAlias = Callable[[Any, "SessionState"], Any]
+
+
 @dataclass(frozen=True)
 class WidgetMetadata(Generic[T]):
     """Metadata associated with a single widget. Immutable."""
@@ -117,11 +128,25 @@ class WidgetMetadata(Generic[T]):
     # Widget callbacks are called at the start of a script run, before the
     # body of the script is executed.
     callback: WidgetCallback | None = None
+
+    # An optional dictionary of event names to user-code callbacks. These are
+    # invoked when the corresponding widget event occurs. Callbacks are called
+    # at the start of a script run, before the body of the script is executed.
+    # Right now, multiple callbacks are only supported for widgets with a
+    # `value_type` of `json_value` or `json_trigger_value`. The keys in this
+    # dictionary should correspond to keys in the widget's JSON state.
+    callbacks: dict[str, WidgetCallback] | None = None
     callback_args: WidgetArgs | None = None
     callback_kwargs: WidgetKwargs | None = None
 
     fragment_id: str | None = None
 
+    # Optional presenter hook used for customizing the user-visible value in
+    # st.session_state. This is intended for advanced widgets (e.g. Custom
+    # Components v2) that need to synthesize a presentation-only value from
+    # multiple internal widget states.
+    presenter: WidgetValuePresenter | None = None
+
     def __repr__(self) -> str:
         return util.repr_(self)
 

streamlit/runtime/state/presentation.py

@@ -0,0 +1,85 @@
+# 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 typing import TYPE_CHECKING, Any, Final
+
+from streamlit.logger import get_logger
+
+_LOGGER: Final = get_logger(__name__)
+
+if TYPE_CHECKING:
+    from streamlit.runtime.state.session_state import SessionState
+
+
+def apply_presenter(
+    session_state: SessionState, widget_id: str, base_value: Any
+) -> Any:
+    """Return the user-visible value for a widget if it has a ``presenter``.
+
+    If the widget's metadata defines a ``presenter`` callable, it is used to
+    transform the stored value into its presentation form. Any exception raised
+    while resolving metadata or invoking the presenter is swallowed and
+    ``base_value`` is returned, so presentation never interferes with core
+    behavior.
+
+    Notes
+    -----
+    Presentation is applied exclusively for user-facing access paths such as:
+    - `st.session_state[... ]` via `SessionState.__getitem__`
+    - `SessionState.filtered_state`
+
+    Internal serialization paths (for example `WStates.as_widget_states()` and
+    `SessionState.get_widget_states()`) must operate on base (unpresented)
+    values to ensure stable and lossless serialization. Do not use
+    `apply_presenter` in serialization code paths.
+
+    Parameters
+    ----------
+    session_state : SessionState
+        The current session state object that holds widget state and metadata.
+    widget_id : str
+        The identifier of the widget whose value is being presented.
+    base_value : Any
+        The raw value stored for the widget.
+
+    Returns
+    -------
+    Any
+        The value that should be shown to the user.
+    """
+
+    try:
+        meta = session_state._get_widget_metadata(widget_id)
+        presenter = getattr(meta, "presenter", None) if meta is not None else None
+        if presenter is None:
+            return base_value
+
+        # Ensure the presenter is callable to avoid silently failing on a
+        # TypeError when attempting to invoke a non-callable value.
+        if not callable(presenter):
+            _LOGGER.warning(
+                "Widget '%s' has a non-callable presenter (%r); returning base value.",
+                widget_id,
+                presenter,
+            )
+            return base_value
+        try:
+            return presenter(base_value, session_state)
+        except Exception:
+            return base_value
+    except Exception:
+        # If metadata is unavailable or any other error occurs, degrade gracefully.
+        return base_value

streamlit/runtime/state/safe_session_state.py

@@ -16,10 +16,10 @@ from __future__ import annotations
 
 import threading
 from contextlib import contextmanager
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator
 
     from streamlit.proto.WidgetStates_pb2 import WidgetState as WidgetStateProto
     from streamlit.proto.WidgetStates_pb2 import WidgetStates as WidgetStatesProto

streamlit/runtime/state/session_state.py

@@ -23,14 +23,12 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Final,
-    Union,
+    TypeAlias,
     cast,
 )
 
-from typing_extensions import TypeAlias
-
-import streamlit as st
 from streamlit import config, util
+from streamlit.delta_generator_singletons import get_dg_singleton_instance
 from streamlit.errors import StreamlitAPIException, UnserializableSessionStateError
 from streamlit.proto.WidgetStates_pb2 import WidgetState as WidgetStateProto
 from streamlit.proto.WidgetStates_pb2 import WidgetStates as WidgetStatesProto
@@ -39,11 +37,14 @@ from streamlit.runtime.state.common import (
     RegisterWidgetResult,
     T,
     ValueFieldName,
+    WidgetArgs,
+    WidgetCallback,
     WidgetMetadata,
     is_array_value_field_name,
     is_element_id,
     is_keyed_element_id,
 )
+from streamlit.runtime.state.presentation import apply_presenter
 from streamlit.runtime.state.query_params import QueryParams
 from streamlit.runtime.stats import CacheStat, CacheStatsProvider, group_stats
 
@@ -71,7 +72,7 @@ class Value:
     value: Any
 
 
-WState: TypeAlias = Union[Value, Serialized]
+WState: TypeAlias = Value | Serialized
 
 
 @dataclass
@@ -228,7 +229,7 @@ class WStates(MutableMapping[str, Any]):
         if is_array_value_field_name(field):
             arr = getattr(widget, field)
             arr.data.extend(serialized)
-        elif field == "json_value":
+        elif field in {"json_value", "json_trigger_value"}:
             setattr(widget, field, json.dumps(serialized))
         elif field == "file_uploader_state_value":
             widget.file_uploader_state_value.CopyFrom(serialized)
@@ -401,7 +402,7 @@ class SessionState:
 
     @property
     def filtered_state(self) -> dict[str, Any]:
-        """The combined session and widget state, excluding keyless widgets."""
+        """The combined session and widget state, excluding keyless widgets and internal widgets."""
 
         wid_key_map = self._key_id_mapper.id_key_mapping
 
@@ -414,9 +415,10 @@ class SessionState:
         for k in self._keys():
             if not is_element_id(k) and not _is_internal_key(k):
                 state[k] = self[k]
-            elif is_keyed_element_id(k):
+            elif is_keyed_element_id(k) and not _is_internal_key(k):
                 try:
                     key = wid_key_map[k]
+                    # Value returned by __getitem__ is already presented.
                     state[key] = self[k]
                 except KeyError:
                     # Widget id no longer maps to a key, it is a not yet
@@ -466,7 +468,12 @@ class SessionState:
             # the "key" is a raw widget id, so get its associated user key for lookup
             key = wid_key_map[widget_id]
         try:
-            return self._getitem(widget_id, key)
+            base_value = self._getitem(widget_id, key)
+            return (
+                apply_presenter(self, widget_id, base_value)
+                if widget_id is not None
+                else base_value
+            )
         except KeyError:
             raise KeyError(_missing_key_error_message(key))
 
@@ -576,19 +583,210 @@ class SessionState:
         self._call_callbacks()
 
     def _call_callbacks(self) -> None:
-        """Call any callback associated with each widget whose value
-        changed between the previous and current script runs.
-        """
+        """Call callbacks for widgets whose value changed or whose trigger fired."""
         from streamlit.runtime.scriptrunner import RerunException
 
-        changed_widget_ids = [
-            wid for wid in self._new_widget_state if self._widget_changed(wid)
+        # Path 1: single callback.
+        changed_widget_ids_for_single_callback = [
+            wid
+            for wid in self._new_widget_state
+            if self._widget_changed(wid)
+            and (metadata := self._new_widget_state.widget_metadata.get(wid))
+            is not None
+            and metadata.callback is not None
         ]
-        for wid in changed_widget_ids:
+
+        for wid in changed_widget_ids_for_single_callback:
             try:
                 self._new_widget_state.call_callback(wid)
             except RerunException:  # noqa: PERF203
-                st.warning("Calling st.rerun() within a callback is a no-op.")
+                get_dg_singleton_instance().main_dg.warning(
+                    "Calling st.rerun() within a callback is a no-op."
+                )
+
+        # Path 2: multiple callbacks.
+        widget_ids_to_process = list(self._new_widget_state.states.keys())
+
+        for wid in widget_ids_to_process:
+            metadata = self._new_widget_state.widget_metadata.get(wid)
+            if not metadata or metadata.callbacks is None:
+                continue
+
+            args = metadata.callback_args or ()
+            kwargs = metadata.callback_kwargs or {}
+
+            # 1) Trigger dispatch: bool + JSON trigger aggregator
+            self._dispatch_trigger_callbacks(wid, metadata, args, kwargs)
+
+            # 2) JSON value change dispatch
+            if metadata.value_type == "json_value":
+                self._dispatch_json_change_callbacks(wid, metadata, args, kwargs)
+
+    def _execute_widget_callback(
+        self,
+        callback_fn: WidgetCallback,
+        cb_metadata: WidgetMetadata[Any],
+        cb_args: WidgetArgs,
+        cb_kwargs: dict[str, Any],
+    ) -> None:
+        """Execute a widget callback with fragment-aware context.
+
+        If the widget belongs to a fragment, temporarily marks the current
+        script context as being inside a fragment callback to adapt rerun
+        semantics. Attempts to call ``st.rerun()`` inside a widget callback are
+        converted to a user-visible warning and treated as a no-op.
+
+        Parameters
+        ----------
+        callback_fn : WidgetCallback
+            The user-provided callback to execute.
+        cb_metadata : WidgetMetadata[Any]
+            Metadata of the widget associated with the callback.
+        cb_args : WidgetArgs
+            Positional arguments passed to the callback.
+        cb_kwargs : dict[str, Any]
+            Keyword arguments passed to the callback.
+        """
+        from streamlit.runtime.scriptrunner import RerunException
+
+        ctx = get_script_run_ctx()
+        if ctx and cb_metadata.fragment_id is not None:
+            ctx.in_fragment_callback = True
+            try:
+                callback_fn(*cb_args, **cb_kwargs)
+            except RerunException:
+                get_dg_singleton_instance().main_dg.warning(
+                    "Calling st.rerun() within a callback is a no-op."
+                )
+            finally:
+                ctx.in_fragment_callback = False
+        else:
+            try:
+                callback_fn(*cb_args, **cb_kwargs)
+            except RerunException:
+                get_dg_singleton_instance().main_dg.warning(
+                    "Calling st.rerun() within a callback is a no-op."
+                )
+
+    def _dispatch_trigger_callbacks(
+        self,
+        wid: str,
+        metadata: WidgetMetadata[Any],
+        args: WidgetArgs,
+        kwargs: dict[str, Any],
+    ) -> None:
+        """Dispatch trigger-style callbacks for a widget.
+
+        Handles the JSON trigger aggregator. The JSON payload may be a single
+        event dict or a list of event dicts; each event must contain an
+        ``"event"`` field that maps to the corresponding callback name in
+        ``metadata.callbacks``.
+
+        Examples
+        --------
+        A component with a "submit" callback:
+
+        >>> metadata.callbacks = {"submit": on_submit}
+
+        The frontend can send a single event payload:
+
+        >>> {"event": "submit", "value": "payload"}
+
+        Or a list of event payloads to be processed in order:
+
+        >>> [{"event": "edit", ...}, {"event": "submit", ...}]
+
+        Parameters
+        ----------
+        wid : str
+            The widget ID.
+        metadata : WidgetMetadata[Any]
+            Metadata for the widget, including registered callbacks.
+        args : WidgetArgs
+            Positional arguments forwarded to the callback.
+        kwargs : dict[str, Any]
+            Keyword arguments forwarded to the callback.
+        """
+        widget_proto_state = self._new_widget_state.get_serialized(wid)
+        if not widget_proto_state:
+            return
+
+        # JSON trigger aggregator: value is deserialized by metadata.deserializer
+        if widget_proto_state.json_trigger_value:
+            try:
+                deserialized = self._new_widget_state[wid]
+            except KeyError:
+                deserialized = None
+
+            payloads: list[object]
+            if isinstance(deserialized, list):
+                payloads = deserialized
+            else:
+                payloads = [deserialized]
+
+            for payload in payloads:
+                if isinstance(payload, dict):
+                    event_name = payload.get("event")
+                    if isinstance(event_name, str) and metadata.callbacks:
+                        cb = metadata.callbacks.get(event_name)
+                        if cb is not None:
+                            self._execute_widget_callback(cb, metadata, args, kwargs)
+
+    def _dispatch_json_change_callbacks(
+        self,
+        wid: str,
+        metadata: WidgetMetadata[Any],
+        args: WidgetArgs,
+        kwargs: dict[str, Any],
+    ) -> None:
+        """Dispatch change callbacks for JSON-valued widgets.
+
+        Computes a shallow diff between the new and old JSON maps and invokes
+        callbacks for keys that changed or were added/removed.
+
+        Parameters
+        ----------
+        wid : str
+            The widget ID.
+        metadata : WidgetMetadata[Any]
+            Metadata for the widget, including registered callbacks.
+        args : WidgetArgs
+            Positional arguments forwarded to the callback.
+        kwargs : dict[str, Any]
+            Keyword arguments forwarded to the callback.
+        """
+        if not metadata.callbacks:
+            return
+
+        try:
+            new_val = self._new_widget_state.get(wid)
+        except KeyError:
+            new_val = None
+        old_val = self._old_state.get(wid)
+
+        def unwrap(obj: object) -> dict[str, object]:
+            if not isinstance(obj, dict):
+                return {}
+
+            obj = cast("dict[str, Any]", obj)
+            if set(obj.keys()) == {"value"}:
+                value = obj.get("value")
+                if isinstance(value, dict):
+                    return dict(value)  # shallow copy
+
+            return dict(obj)
+
+        new_map = unwrap(new_val)
+        old_map = unwrap(old_val)
+
+        if new_map or old_map:
+            all_keys = new_map.keys() | old_map.keys()
+            changed_keys = {k for k in all_keys if old_map.get(k) != new_map.get(k)}
+
+            for key in changed_keys:
+                cb = metadata.callbacks.get(key)
+                if cb is not None:
+                    self._execute_widget_callback(cb, metadata, args, kwargs)
 
     def _widget_changed(self, widget_id: str) -> bool:
         """True if the given widget's value changed between the previous
@@ -623,6 +821,7 @@ class SessionState:
                 elif metadata.value_type in {
                     "string_trigger_value",
                     "chat_input_value",
+                    "json_trigger_value",
                 }:
                     self._new_widget_state[state_id] = Value(None)
 
@@ -634,6 +833,7 @@ class SessionState:
                 elif metadata.value_type in {
                     "string_trigger_value",
                     "chat_input_value",
+                    "json_trigger_value",
                 }:
                     self._old_state[state_id] = None
 
@@ -663,6 +863,10 @@ class SessionState:
             )
         }
 
+    def _get_widget_metadata(self, widget_id: str) -> WidgetMetadata[Any] | None:
+        """Return the metadata for a widget id from the current widget state."""
+        return self._new_widget_state.widget_metadata.get(widget_id)
+
     def _set_widget_metadata(self, widget_metadata: WidgetMetadata[Any]) -> None:
         """Set a widget's metadata."""
         widget_id = widget_metadata.id

streamlit/runtime/state/widgets.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from streamlit.errors import StreamlitAPIException
 from streamlit.runtime.state.common import (
     RegisterWidgetResult,
     T,
@@ -26,6 +27,7 @@ from streamlit.runtime.state.common import (
     WidgetKwargs,
     WidgetMetadata,
     WidgetSerializer,
+    WidgetValuePresenter,
     user_key_from_element_id,
 )
 
@@ -39,10 +41,12 @@ def register_widget(
     deserializer: WidgetDeserializer[T],
     serializer: WidgetSerializer[T],
     ctx: ScriptRunContext | None,
+    callbacks: dict[str, WidgetCallback] | None = None,
     on_change_handler: WidgetCallback | None = None,
     args: WidgetArgs | None = None,
     kwargs: WidgetKwargs | None = None,
     value_type: ValueFieldName,
+    presenter: WidgetValuePresenter | None = None,
 ) -> RegisterWidgetResult[T]:
     """Register a widget with Streamlit, and return its current value.
     NOTE: This function should be called after the proto has been filled.
@@ -58,13 +62,15 @@ def register_widget(
         Called to convert a widget's value to its protobuf representation.
     ctx : ScriptRunContext or None
         Used to ensure uniqueness of widget IDs, and to look up widget values.
+    callbacks : dict[str, WidgetCallback] or None
+        A dictionary of callbacks for multi-callback support.
     on_change_handler : WidgetCallback or None
         An optional callback invoked when the widget's value changes.
     args : WidgetArgs or None
-        args to pass to on_change_handler when invoked
+        Positional arguments to pass to the `on_change_handler` or `callbacks`.
     kwargs : WidgetKwargs or None
-        kwargs to pass to on_change_handler when invoked
-    value_type: ValueType
+        Keyword arguments to pass to the `on_change_handler` or `callbacks`.
+    value_type: ValueFieldName
         The value_type the widget is going to use.
         We use this information to start with a best-effort guess for the value_type
         of each widget. Once we actually receive a proto for a widget from the
@@ -72,6 +78,9 @@ def register_widget(
         not able to always rely on the proto as the type may be needed earlier.
         Thankfully, in these cases (when value_type == "trigger_value"), the static
         table here being slightly inaccurate should never pose a problem.
+    presenter : WidgetValuePresenter or None
+        An optional hook that allows a widget to customize how its value should be
+        presented.
 
 
     Returns
@@ -98,6 +107,11 @@ def register_widget(
         For both paths a widget return value is provided, allowing the widgets
         to be used in a non-streamlit setting.
     """
+    if on_change_handler is not None and callbacks is not None:
+        raise StreamlitAPIException(
+            "Cannot provide both `on_change` and `callbacks` to a widget."
+        )
+
     # Create the widget's updated metadata, and register it with session_state.
     metadata = WidgetMetadata(
         element_id,
@@ -105,9 +119,11 @@ def register_widget(
         serializer,
         value_type=value_type,
         callback=on_change_handler,
+        callbacks=callbacks,
         callback_args=args,
         callback_kwargs=kwargs,
         fragment_id=ctx.current_fragment_id if ctx else None,
+        presenter=presenter,
     )
     return register_widget_from_metadata(metadata, ctx)