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

streamlit/runtime/runtime.py

@@ -23,6 +23,7 @@ from enum import Enum
 from typing import TYPE_CHECKING, Final, NamedTuple
 
 from streamlit.components.lib.local_component_registry import LocalComponentRegistry
+from streamlit.components.v2.component_manager import BidiComponentManager
 from streamlit.logger import get_logger
 from streamlit.proto.ForwardMsg_pb2 import ForwardMsg
 from streamlit.runtime.app_session import AppSession
@@ -101,6 +102,11 @@ class RuntimeConfig:
         default_factory=LocalComponentRegistry
     )
 
+    # The BidiComponentManager instance to use for v2 components.
+    bidi_component_registry: BidiComponentManager = field(
+        default_factory=BidiComponentManager
+    )
+
     # The SessionManager class to be used.
     session_manager_class: type[SessionManager] = WebsocketSessionManager
 
@@ -201,11 +207,15 @@ class Runtime:
 
         # Initialize managers
         self._component_registry = config.component_registry
+        self._bidi_component_registry = config.bidi_component_registry
         self._uploaded_file_mgr = config.uploaded_file_manager
         self._media_file_mgr = MediaFileManager(storage=config.media_file_storage)
         self._cache_storage_manager = config.cache_storage_manager
         self._script_cache = ScriptCache()
 
+        # Discover and register components for CCv2 from installed packages
+        self._bidi_component_registry.discover_and_register_components()
+
         self._session_mgr = config.session_manager_class(
             session_storage=config.session_storage,
             uploaded_file_manager=self._uploaded_file_mgr,
@@ -227,6 +237,10 @@ class Runtime:
     def component_registry(self) -> BaseComponentRegistry:
         return self._component_registry
 
+    @property
+    def bidi_component_registry(self) -> BidiComponentManager:
+        return self._bidi_component_registry
+
     @property
     def uploaded_file_mgr(self) -> UploadedFileManager:
         return self._uploaded_file_mgr

streamlit/runtime/scriptrunner/exec_code.py

@@ -15,7 +15,7 @@
 from __future__ import annotations
 
 import sys
-from typing import TYPE_CHECKING, Any, Callable, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 from streamlit import util
 from streamlit.delta_generator_singletons import (
@@ -30,6 +30,7 @@ from streamlit.runtime.scriptrunner_utils.exceptions import (
 )
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
     from types import TracebackType
 
     from streamlit.runtime.scriptrunner_utils.script_requests import RerunData

streamlit/runtime/scriptrunner/script_runner.py

@@ -21,7 +21,7 @@ import types
 from contextlib import contextmanager
 from enum import Enum
 from timeit import default_timer as timer
-from typing import TYPE_CHECKING, Any, Callable, Final, Literal, cast
+from typing import TYPE_CHECKING, Any, Final, Literal, cast
 
 from blinker import Signal
 
@@ -62,7 +62,7 @@ from streamlit.runtime.state import (
 from streamlit.source_util import page_sort_key
 
 if TYPE_CHECKING:
-    from collections.abc import Generator
+    from collections.abc import Callable, Generator
 
     from streamlit.runtime.fragment import FragmentStorage
     from streamlit.runtime.scriptrunner.script_cache import ScriptCache

streamlit/runtime/scriptrunner_utils/script_run_context.py

@@ -22,14 +22,11 @@ from collections import Counter
 from dataclasses import dataclass, field
 from typing import (
     TYPE_CHECKING,
-    Callable,
     Final,
-    Union,
+    TypeAlias,
 )
 from urllib import parse
 
-from typing_extensions import TypeAlias
-
 from streamlit.errors import (
     NoSessionContext,
     StreamlitAPIException,
@@ -41,7 +38,7 @@ from streamlit.runtime.forward_msg_cache import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Generator
+    from collections.abc import Callable, Generator
     from pathlib import Path
 
     from streamlit.cursor import RunningCursor
@@ -55,7 +52,7 @@ if TYPE_CHECKING:
     from streamlit.runtime.uploaded_file_manager import UploadedFileManager
 _LOGGER: Final = get_logger(__name__)
 
-UserInfo: TypeAlias = dict[str, Union[str, bool, None]]
+UserInfo: TypeAlias = dict[str, str | bool | None]
 
 
 # If true, it indicates that we are in a cached function that disallows the usage of

streamlit/runtime/secrets.py

@@ -16,11 +16,10 @@ from __future__ import annotations
 
 import os
 import threading
-from collections.abc import ItemsView, Iterator, KeysView, Mapping, ValuesView
+from collections.abc import Callable, ItemsView, Iterator, KeysView, Mapping, ValuesView
 from copy import deepcopy
 from typing import (
     Any,
-    Callable,
     Final,
     NoReturn,
 )
@@ -461,8 +460,7 @@ class Secrets(Mapping[str, Any]):
                 return value
             return AttrDict(value)
         # We add FileNotFoundError since __getattr__ is expected to only raise
-        # AttributeError. Without handling FileNotFoundError, unittests.mocks
-        # fails during mock creation on Python3.9
+        # AttributeError and mocking utilities expect that contract.
         except (KeyError, FileNotFoundError):
             raise AttributeError(_missing_attr_error_message(key))
 

streamlit/runtime/session_manager.py

@@ -16,9 +16,11 @@ from __future__ import annotations
 
 from abc import abstractmethod
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Callable, Protocol, cast
+from typing import TYPE_CHECKING, Protocol, cast
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from streamlit.proto.ForwardMsg_pb2 import ForwardMsg
     from streamlit.runtime.app_session import AppSession
     from streamlit.runtime.script_data import ScriptData

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