streamlit-nightly 1.43.2.dev20250307__py3-none-any.whl

streamlit/runtime/state/query_params.py

@@ -0,0 +1,205 @@
+# 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 collections.abc import Iterable, Iterator, MutableMapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Final
+from urllib import parse
+
+from streamlit.errors import StreamlitAPIException
+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
+
+
+EMBED_QUERY_PARAM: Final[str] = "embed"
+EMBED_OPTIONS_QUERY_PARAM: Final[str] = "embed_options"
+EMBED_QUERY_PARAMS_KEYS: Final[list[str]] = [
+    EMBED_QUERY_PARAM,
+    EMBED_OPTIONS_QUERY_PARAM,
+]
+
+
+@dataclass
+class QueryParams(MutableMapping[str, str]):
+    """A lightweight wrapper of a dict that sends forwardMsgs when state changes.
+    It stores str keys with str and List[str] values.
+    """
+
+    _query_params: dict[str, list[str] | str] = field(default_factory=dict)
+
+    def __iter__(self) -> Iterator[str]:
+        self._ensure_single_query_api_used()
+
+        return iter(
+            key
+            for key in self._query_params.keys()
+            if key not in EMBED_QUERY_PARAMS_KEYS
+        )
+
+    def __getitem__(self, key: str) -> str:
+        """Retrieves a value for a given key in query parameters.
+        Returns the last item in a list or an empty string if empty.
+        If the key is not present, raise KeyError.
+        """
+        self._ensure_single_query_api_used()
+        try:
+            if key in EMBED_QUERY_PARAMS_KEYS:
+                raise KeyError(missing_key_error_message(key))
+            value = self._query_params[key]
+            if isinstance(value, list):
+                if len(value) == 0:
+                    return ""
+                else:
+                    # Return the last value to mimic Tornado's behavior
+                    # https://www.tornadoweb.org/en/stable/web.html#tornado.web.RequestHandler.get_query_argument
+                    return value[-1]
+            return value
+        except KeyError:
+            raise KeyError(missing_key_error_message(key))
+
+    def __setitem__(self, key: str, value: str | Iterable[str]) -> None:
+        self._ensure_single_query_api_used()
+        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 __delitem__(self, key: str) -> None:
+        self._ensure_single_query_api_used()
+        try:
+            if key in EMBED_QUERY_PARAMS_KEYS:
+                raise KeyError(missing_key_error_message(key))
+            del self._query_params[key]
+            self._send_query_param_msg()
+        except KeyError:
+            raise KeyError(missing_key_error_message(key))
+
+    def update(
+        self,
+        other: Iterable[tuple[str, str | Iterable[str]]]
+        | SupportsKeysAndGetItem[str, str | Iterable[str]] = (),
+        /,
+        **kwds: str,
+    ):
+        # This overrides the `update` provided by MutableMapping
+        # to ensure only one one ForwardMsg is sent.
+        self._ensure_single_query_api_used()
+        if hasattr(other, "keys") and hasattr(other, "__getitem__"):
+            for key in other.keys():
+                self.__set_item_internal(key, other[key])
+        else:
+            for key, value in other:
+                self.__set_item_internal(key, value)
+        for key, value in kwds.items():
+            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:
+            return []
+        value = self._query_params[key]
+        return value if isinstance(value, list) else [value]
+
+    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}
+        )
+
+    def __str__(self) -> str:
+        self._ensure_single_query_api_used()
+        return str(self._query_params)
+
+    def _send_query_param_msg(self) -> None:
+        ctx = get_script_run_ctx()
+        if ctx is None:
+            return
+        self._ensure_single_query_api_used()
+
+        msg = ForwardMsg()
+        msg.page_info_changed.query_string = parse.urlencode(
+            self._query_params, doseq=True
+        )
+        ctx.query_string = msg.page_info_changed.query_string
+        ctx.enqueue(msg)
+
+    def clear(self) -> None:
+        self._ensure_single_query_api_used()
+        self.clear_with_no_forward_msg(preserve_embed=True)
+        self._send_query_param_msg()
+
+    def to_dict(self) -> dict[str, str]:
+        self._ensure_single_query_api_used()
+        # return the last query param if multiple values are set
+        return {
+            key: self[key]
+            for key in self._query_params
+            if key not in EMBED_QUERY_PARAMS_KEYS
+        }
+
+    def from_dict(
+        self,
+        _dict: Iterable[tuple[str, str | Iterable[str]]]
+        | SupportsKeysAndGetItem[str, str | Iterable[str]],
+    ):
+        self._ensure_single_query_api_used()
+        old_value = self._query_params.copy()
+        self.clear_with_no_forward_msg(preserve_embed=True)
+        try:
+            self.update(_dict)
+        except StreamlitAPIException:
+            # restore the original from before we made any changes.
+            self._query_params = old_value
+            raise
+
+    def set_with_no_forward_msg(self, key: str, val: list[str] | str) -> None:
+        self._query_params[key] = val
+
+    def clear_with_no_forward_msg(self, preserve_embed: bool = False) -> None:
+        self._query_params = {
+            key: value
+            for key, value in self._query_params.items()
+            if key in EMBED_QUERY_PARAMS_KEYS and preserve_embed
+        }
+
+    def _ensure_single_query_api_used(self):
+        ctx = get_script_run_ctx()
+        if ctx is None:
+            return
+        ctx.mark_production_query_params_used()
+
+
+def missing_key_error_message(key: str) -> str:
+    return f'st.query_params has no key "{key}".'

streamlit/runtime/state/query_params_proxy.py

@@ -0,0 +1,218 @@
+# 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 collections.abc import Iterable, Iterator, MutableMapping
+from typing import TYPE_CHECKING, overload
+
+from streamlit.runtime.metrics_util import gather_metrics
+from streamlit.runtime.state.session_state_proxy import get_session_state
+
+if TYPE_CHECKING:
+    from _typeshed import SupportsKeysAndGetItem
+
+
+class QueryParamsProxy(MutableMapping[str, str]):
+    """
+    A stateless singleton that proxies ``st.query_params`` interactions
+    to the current script thread's QueryParams instance.
+    """
+
+    def __iter__(self) -> Iterator[str]:
+        with get_session_state().query_params() as qp:
+            return iter(qp)
+
+    def __len__(self) -> int:
+        with get_session_state().query_params() as qp:
+            return len(qp)
+
+    def __str__(self) -> str:
+        with get_session_state().query_params() as qp:
+            return str(qp)
+
+    @gather_metrics("query_params.get_item")
+    def __getitem__(self, key: str) -> str:
+        with get_session_state().query_params() as qp:
+            try:
+                return qp[key]
+            except KeyError:
+                raise KeyError(self.missing_key_error_message(key))
+
+    def __delitem__(self, key: str) -> None:
+        with get_session_state().query_params() as qp:
+            del qp[key]
+
+    @gather_metrics("query_params.set_item")
+    def __setitem__(self, key: str, value: str | Iterable[str]) -> None:
+        with get_session_state().query_params() as qp:
+            qp[key] = value
+
+    @gather_metrics("query_params.get_attr")
+    def __getattr__(self, key: str) -> str:
+        with get_session_state().query_params() as qp:
+            try:
+                return qp[key]
+            except KeyError:
+                raise AttributeError(self.missing_attr_error_message(key))
+
+    def __delattr__(self, key: str) -> None:
+        with get_session_state().query_params() as qp:
+            try:
+                del qp[key]
+            except KeyError:
+                raise AttributeError(self.missing_key_error_message(key))
+
+    @overload
+    def update(
+        self, mapping: SupportsKeysAndGetItem[str, str | Iterable[str]], /, **kwds: str
+    ) -> None: ...
+
+    @overload
+    def update(
+        self, keys_and_values: Iterable[tuple[str, str | Iterable[str]]], /, **kwds: str
+    ) -> None: ...
+
+    @overload
+    def update(self, **kwds: str | Iterable[str]) -> None: ...
+
+    def update(self, other=(), /, **kwds):
+        """
+        Update one or more values in query_params at once from a dictionary or
+        dictionary-like object.
+
+        See `Mapping.update()` from Python's `collections` library.
+
+        Parameters
+        ----------
+        other: SupportsKeysAndGetItem[str, str] | Iterable[tuple[str, str]]
+            A dictionary or mapping of strings to strings.
+        **kwds: str
+            Additional key/value pairs to update passed as keyword arguments.
+        """
+        with get_session_state().query_params() as qp:
+            qp.update(other, **kwds)
+
+    @gather_metrics("query_params.set_attr")
+    def __setattr__(self, key: str, value: str | Iterable[str]) -> None:
+        with get_session_state().query_params() as qp:
+            qp[key] = value
+
+    @gather_metrics("query_params.get_all")
+    def get_all(self, key: str) -> list[str]:
+        """
+        Get a list of all query parameter values associated to a given key.
+
+        When a key is repeated as a query parameter within the URL, this method
+        allows all values to be obtained. In contrast, dict-like methods only
+        retrieve the last value when a key is repeated in the URL.
+
+        Parameters
+        ----------
+        key: str
+            The label of the query parameter in the URL.
+
+        Returns
+        -------
+        List[str]
+            A list of values associated to the given key. May return zero, one,
+            or multiple values.
+        """
+        with get_session_state().query_params() as qp:
+            return qp.get_all(key)
+
+    @gather_metrics("query_params.clear")
+    def clear(self) -> None:
+        """
+        Clear all query parameters from the URL of the app.
+
+        Returns
+        -------
+        None
+        """
+        with get_session_state().query_params() as qp:
+            qp.clear()
+
+    @gather_metrics("query_params.to_dict")
+    def to_dict(self) -> dict[str, str]:
+        """
+        Get all query parameters as a dictionary.
+
+        This method primarily exists for internal use and is not needed for
+        most cases. ``st.query_params`` returns an object that inherits from
+        ``dict`` by default.
+
+        When a key is repeated as a query parameter within the URL, this method
+        will return only the last value of each unique key.
+
+        Returns
+        -------
+        Dict[str,str]
+            A dictionary of the current query paramters in the app's URL.
+        """
+        with get_session_state().query_params() as qp:
+            return qp.to_dict()
+
+    @overload
+    def from_dict(
+        self, keys_and_values: Iterable[tuple[str, str | Iterable[str]]]
+    ) -> None: ...
+
+    @overload
+    def from_dict(
+        self, mapping: SupportsKeysAndGetItem[str, str | Iterable[str]]
+    ) -> None: ...
+
+    @gather_metrics("query_params.from_dict")
+    def from_dict(self, params):
+        """
+        Set all of the query parameters from a dictionary or dictionary-like object.
+
+        This method primarily exists for advanced users who want to control
+        multiple query parameters in a single update. To set individual query
+        parameters, use key or attribute notation instead.
+
+        This method inherits limitations from ``st.query_params`` and can't be
+        used to set embedding options as described in `Embed your app \
+        <https://docs.streamlit.io/deploy/streamlit-community-cloud/share-your-app/embed-your-app#embed-options>`_.
+
+        To handle repeated keys, the value in a key-value pair should be a list.
+
+        .. note::
+            ``.from_dict()`` is not a direct inverse of ``.to_dict()`` if
+            you are working with repeated keys. A true inverse operation is
+            ``{key: st.query_params.get_all(key) for key in st.query_params}``.
+
+        Parameters
+        ----------
+        params: dict
+            A dictionary used to replace the current query parameters.
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>>
+        >>> st.query_params.from_dict({"foo": "bar", "baz": [1, "two"]})
+
+        """
+        with get_session_state().query_params() as qp:
+            return qp.from_dict(params)
+
+    @staticmethod
+    def missing_key_error_message(key: str) -> str:
+        return f'st.query_params has no key "{key}".'
+
+    @staticmethod
+    def missing_attr_error_message(key: str) -> str:
+        return f'st.query_params has no attribute "{key}".'

streamlit/runtime/state/safe_session_state.py

@@ -0,0 +1,138 @@
+# 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
+
+import threading
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from streamlit.proto.WidgetStates_pb2 import WidgetState as WidgetStateProto
+    from streamlit.proto.WidgetStates_pb2 import WidgetStates as WidgetStatesProto
+    from streamlit.runtime.state.common import RegisterWidgetResult, T, WidgetMetadata
+    from streamlit.runtime.state.query_params import QueryParams
+    from streamlit.runtime.state.session_state import SessionState
+
+
+class SafeSessionState:
+    """Thread-safe wrapper around SessionState.
+
+    When AppSession gets a re-run request, it can interrupt its existing
+    ScriptRunner and spin up a new ScriptRunner to handle the request.
+    When this happens, the existing ScriptRunner will continue executing
+    its script until it reaches a yield point - but during this time, it
+    must not mutate its SessionState.
+    """
+
+    _state: SessionState
+    _lock: threading.RLock
+    _yield_callback: Callable[[], None]
+
+    def __init__(self, state: SessionState, yield_callback: Callable[[], None]):
+        # Fields must be set using the object's setattr method to avoid
+        # infinite recursion from trying to look up the fields we're setting.
+        object.__setattr__(self, "_state", state)
+        # TODO: we'd prefer this be a threading.Lock instead of RLock -
+        #  but `call_callbacks` first needs to be rewritten.
+        object.__setattr__(self, "_lock", threading.RLock())
+        object.__setattr__(self, "_yield_callback", yield_callback)
+
+    def register_widget(
+        self, metadata: WidgetMetadata[T], user_key: str | None
+    ) -> RegisterWidgetResult[T]:
+        self._yield_callback()
+        with self._lock:
+            return self._state.register_widget(metadata, user_key)
+
+    def on_script_will_rerun(self, latest_widget_states: WidgetStatesProto) -> None:
+        self._yield_callback()
+        with self._lock:
+            # TODO: rewrite this to copy the callbacks list into a local
+            #  variable so that we don't need to hold our lock for the
+            #  duration. (This will also allow us to downgrade our RLock
+            #  to a Lock.)
+            self._state.on_script_will_rerun(latest_widget_states)
+
+    def on_script_finished(self, widget_ids_this_run: set[str]) -> None:
+        with self._lock:
+            self._state.on_script_finished(widget_ids_this_run)
+
+    def maybe_check_serializable(self) -> None:
+        with self._lock:
+            self._state.maybe_check_serializable()
+
+    def get_widget_states(self) -> list[WidgetStateProto]:
+        """Return a list of serialized widget values for each widget with a value."""
+        with self._lock:
+            return self._state.get_widget_states()
+
+    def is_new_state_value(self, user_key: str) -> bool:
+        with self._lock:
+            return self._state.is_new_state_value(user_key)
+
+    @property
+    def filtered_state(self) -> dict[str, Any]:
+        """The combined session and widget state, excluding keyless widgets."""
+        with self._lock:
+            return self._state.filtered_state
+
+    def __getitem__(self, key: str) -> Any:
+        self._yield_callback()
+        with self._lock:
+            return self._state[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self._yield_callback()
+        with self._lock:
+            self._state[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        self._yield_callback()
+        with self._lock:
+            del self._state[key]
+
+    def __contains__(self, key: str) -> bool:
+        self._yield_callback()
+        with self._lock:
+            return key in self._state
+
+    def __getattr__(self, key: str) -> Any:
+        try:
+            return self[key]
+        except KeyError:
+            raise AttributeError(f"{key} not found in session_state.")
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        self[key] = value
+
+    def __delattr__(self, key: str) -> None:
+        try:
+            del self[key]
+        except KeyError:
+            raise AttributeError(f"{key} not found in session_state.")
+
+    def __repr__(self):
+        """Presents itself as a simple dict of the underlying SessionState instance"""
+        kv = ((k, self._state[k]) for k in self._state._keys())
+        s = ", ".join(f"{k}: {v!r}" for k, v in kv)
+        return f"{{{s}}}"
+
+    @contextmanager
+    def query_params(self) -> Iterator[QueryParams]:
+        self._yield_callback()
+        with self._lock:
+            yield self._state.query_params