streamlit 1.50.0__py3-none-any.whl → 1.52.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/query_params.py

@@ -14,18 +14,21 @@
 
 from __future__ import annotations
 
-from collections.abc import Iterable, Iterator, MutableMapping
+from collections.abc import Iterable, Iterator, Mapping, MutableMapping
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Final, cast
 from urllib import parse
 
-from streamlit.errors import StreamlitAPIException
+from streamlit.errors import StreamlitAPIException, StreamlitQueryParamDictValueError
 from streamlit.proto.ForwardMsg_pb2 import ForwardMsg
 from streamlit.runtime.scriptrunner_utils.script_run_context import get_script_run_ctx
 
 if TYPE_CHECKING:
     from _typeshed import SupportsKeysAndGetItem
 
+QueryParamValue = str | Iterable[str]
+QueryParamsInput = Mapping[str, QueryParamValue] | Iterable[tuple[str, QueryParamValue]]
+
 
 EMBED_QUERY_PARAM: Final[str] = "embed"
 EMBED_OPTIONS_QUERY_PARAM: Final[str] = "embed_options"
@@ -47,7 +50,9 @@ class QueryParams(MutableMapping[str, str]):
         self._ensure_single_query_api_used()
 
         return iter(
-            key for key in self._query_params if key not in EMBED_QUERY_PARAMS_KEYS
+            key
+            for key in self._query_params
+            if key.lower() not in EMBED_QUERY_PARAMS_KEYS
         )
 
     def __getitem__(self, key: str) -> str:
@@ -56,7 +61,7 @@ class QueryParams(MutableMapping[str, str]):
         If the key is not present, raise KeyError.
         """
         self._ensure_single_query_api_used()
-        if key in EMBED_QUERY_PARAMS_KEYS:
+        if key.lower() in EMBED_QUERY_PARAMS_KEYS:
             raise KeyError(missing_key_error_message(key))
 
         try:
@@ -73,29 +78,15 @@ class QueryParams(MutableMapping[str, str]):
 
     def __setitem__(self, key: str, value: str | Iterable[str]) -> None:
         self._ensure_single_query_api_used()
-        self.__set_item_internal(key, value)
+        self._set_item_internal(key, value)
         self._send_query_param_msg()
 
-    def __set_item_internal(self, key: str, value: str | Iterable[str]) -> None:
-        if isinstance(value, dict):
-            raise StreamlitAPIException(
-                f"You cannot set a query params key `{key}` to a dictionary."
-            )
-
-        if key in EMBED_QUERY_PARAMS_KEYS:
-            raise StreamlitAPIException(
-                "Query param embed and embed_options (case-insensitive) cannot be set programmatically."
-            )
-        # Type checking users should handle the string serialization themselves
-        # We will accept any type for the list and serialize to str just in case
-        if isinstance(value, Iterable) and not isinstance(value, str):
-            self._query_params[key] = [str(item) for item in value]
-        else:
-            self._query_params[key] = str(value)
+    def _set_item_internal(self, key: str, value: str | Iterable[str]) -> None:
+        _set_item_in_dict(self._query_params, key, value)
 
     def __delitem__(self, key: str) -> None:
         self._ensure_single_query_api_used()
-        if key in EMBED_QUERY_PARAMS_KEYS:
+        if key.lower() in EMBED_QUERY_PARAMS_KEYS:
             raise KeyError(missing_key_error_message(key))
         try:
             del self._query_params[key]
@@ -116,17 +107,17 @@ class QueryParams(MutableMapping[str, str]):
         if hasattr(other, "keys") and hasattr(other, "__getitem__"):
             other = cast("SupportsKeysAndGetItem[str, str | Iterable[str]]", other)
             for key in other.keys():  # noqa: SIM118
-                self.__set_item_internal(key, other[key])
+                self._set_item_internal(key, other[key])
         else:
             for key, value in other:
-                self.__set_item_internal(key, value)
+                self._set_item_internal(key, value)
         for key, value in kwds.items():
-            self.__set_item_internal(key, value)
+            self._set_item_internal(key, value)
         self._send_query_param_msg()
 
     def get_all(self, key: str) -> list[str]:
         self._ensure_single_query_api_used()
-        if key not in self._query_params or key in EMBED_QUERY_PARAMS_KEYS:
+        if key not in self._query_params or key.lower() in EMBED_QUERY_PARAMS_KEYS:
             return []
         value = self._query_params[key]
         return value if isinstance(value, list) else [value]
@@ -134,7 +125,11 @@ class QueryParams(MutableMapping[str, str]):
     def __len__(self) -> int:
         self._ensure_single_query_api_used()
         return len(
-            {key for key in self._query_params if key not in EMBED_QUERY_PARAMS_KEYS}
+            {
+                key
+                for key in self._query_params
+                if key.lower() not in EMBED_QUERY_PARAMS_KEYS
+            }
         )
 
     def __str__(self) -> str:
@@ -165,7 +160,7 @@ class QueryParams(MutableMapping[str, str]):
         return {
             key: self[key]
             for key in self._query_params
-            if key not in EMBED_QUERY_PARAMS_KEYS
+            if key.lower() not in EMBED_QUERY_PARAMS_KEYS
         }
 
     def from_dict(
@@ -190,7 +185,7 @@ class QueryParams(MutableMapping[str, str]):
         self._query_params = {
             key: value
             for key, value in self._query_params.items()
-            if key in EMBED_QUERY_PARAMS_KEYS and preserve_embed
+            if key.lower() in EMBED_QUERY_PARAMS_KEYS and preserve_embed
         }
 
     def _ensure_single_query_api_used(self) -> None:
@@ -202,3 +197,59 @@ class QueryParams(MutableMapping[str, str]):
 
 def missing_key_error_message(key: str) -> str:
     return f'st.query_params has no key "{key}".'
+
+
+def _set_item_in_dict(
+    target_dict: dict[str, list[str] | str], key: str, value: str | Iterable[str]
+) -> None:
+    """Set an item in a dictionary."""
+    if isinstance(value, dict):
+        raise StreamlitQueryParamDictValueError(key)
+
+    if key.lower() in EMBED_QUERY_PARAMS_KEYS:
+        raise StreamlitAPIException(
+            "Query param embed and embed_options (case-insensitive) cannot be set programmatically."
+        )
+    # Type checking users should handle the string serialization themselves
+    # We will accept any type for the list and serialize to str just in case
+    if isinstance(value, Iterable) and not isinstance(value, str):
+        target_dict[key] = [str(item) for item in value]
+    else:
+        target_dict[key] = str(value)
+
+
+def process_query_params(
+    query_params: Iterable[tuple[str, str | Iterable[str]]]
+    | SupportsKeysAndGetItem[str, str | Iterable[str]],
+) -> str:
+    """Convert query params into a URL-encoded query string."""
+    processed_params: dict[str, list[str] | str] = {}
+
+    if hasattr(query_params, "keys") and hasattr(query_params, "__getitem__"):
+        query_params = cast(
+            "SupportsKeysAndGetItem[str, str | Iterable[str]]", query_params
+        )
+        for key in query_params.keys():  # noqa: SIM118
+            value = query_params[key]
+            _set_item_in_dict(processed_params, key, value)
+    else:
+        for key, value in query_params:
+            if key in processed_params:
+                # If the key already exists, we need to accumulate the values.
+                if isinstance(value, dict):
+                    raise StreamlitQueryParamDictValueError(key)
+
+                current_val = processed_params[key]
+                if not isinstance(current_val, list):
+                    current_val = [current_val]
+
+                if isinstance(value, Iterable) and not isinstance(value, str):
+                    current_val.extend([str(item) for item in value])
+                else:
+                    current_val.append(str(value))
+
+                processed_params[key] = current_val
+            else:
+                _set_item_in_dict(processed_params, key, value)
+
+    return parse.urlencode(processed_params, doseq=True)

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