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

streamlit/runtime/state/session_state_proxy.py

@@ -0,0 +1,153 @@
+# 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 Iterator, MutableMapping
+from typing import Any, Final
+
+from streamlit import logger as _logger
+from streamlit import runtime
+from streamlit.elements.lib.utils import Key
+from streamlit.runtime.metrics_util import gather_metrics
+from streamlit.runtime.state.common import require_valid_user_key
+from streamlit.runtime.state.safe_session_state import SafeSessionState
+from streamlit.runtime.state.session_state import SessionState
+
+_LOGGER: Final = _logger.get_logger(__name__)
+
+
+_state_use_warning_already_displayed: bool = False
+# The mock session state is used as a fallback if the script is run without `streamlit run`
+_mock_session_state: SafeSessionState | None = None
+
+
+def get_session_state() -> SafeSessionState:
+    """Get the SessionState object for the current session.
+
+    Note that in streamlit scripts, this function should not be called
+    directly. Instead, SessionState objects should be accessed via
+    st.session_state.
+    """
+    global _state_use_warning_already_displayed
+    from streamlit.runtime.scriptrunner_utils.script_run_context import (
+        get_script_run_ctx,
+    )
+
+    ctx = get_script_run_ctx()
+
+    # If there is no script run context because the script is run bare, we
+    # use a global mock session state version to allow bare script execution (via python script.py)
+    if ctx is None:
+        if not _state_use_warning_already_displayed:
+            _state_use_warning_already_displayed = True
+            if not runtime.exists():
+                _LOGGER.warning(
+                    "Session state does not function when running a script without `streamlit run`"
+                )
+
+        global _mock_session_state
+
+        if _mock_session_state is None:
+            # Lazy initialize the mock session state
+            _mock_session_state = SafeSessionState(SessionState(), lambda: None)
+        return _mock_session_state
+    return ctx.session_state
+
+
+class SessionStateProxy(MutableMapping[Key, Any]):
+    """A stateless singleton that proxies `st.session_state` interactions
+    to the current script thread's SessionState instance.
+
+    The proxy API differs slightly from SessionState: it does not allow
+    callers to get, set, or iterate over "keyless" widgets (that is, widgets
+    that were created without a user_key, and have autogenerated keys).
+    """
+
+    def __iter__(self) -> Iterator[Any]:
+        """Iterator over user state and keyed widget values."""
+        # TODO: this is unsafe if fastReruns is true! Let's deprecate/remove.
+        return iter(get_session_state().filtered_state)
+
+    def __len__(self) -> int:
+        """Number of user state and keyed widget values in session_state."""
+        return len(get_session_state().filtered_state)
+
+    def __str__(self) -> str:
+        """String representation of user state and keyed widget values."""
+        return str(get_session_state().filtered_state)
+
+    def __getitem__(self, key: Key) -> Any:
+        """Return the state or widget value with the given key.
+
+        Raises
+        ------
+        StreamlitAPIException
+            If the key is not a valid SessionState user key.
+        """
+        key = str(key)
+        require_valid_user_key(key)
+        return get_session_state()[key]
+
+    @gather_metrics("session_state.set_item")
+    def __setitem__(self, key: Key, value: Any) -> None:
+        """Set the value of the given key.
+
+        Raises
+        ------
+        StreamlitAPIException
+            If the key is not a valid SessionState user key.
+        """
+        key = str(key)
+        require_valid_user_key(key)
+        get_session_state()[key] = value
+
+    def __delitem__(self, key: Key) -> None:
+        """Delete the value with the given key.
+
+        Raises
+        ------
+        StreamlitAPIException
+            If the key is not a valid SessionState user key.
+        """
+        key = str(key)
+        require_valid_user_key(key)
+        del get_session_state()[key]
+
+    def __getattr__(self, key: str) -> Any:
+        try:
+            return self[key]
+        except KeyError:
+            raise AttributeError(_missing_attr_error_message(key))
+
+    @gather_metrics("session_state.set_attr")
+    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(_missing_attr_error_message(key))
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a dict containing all session_state and keyed widget values."""
+        return get_session_state().filtered_state
+
+
+def _missing_attr_error_message(attr_name: str) -> str:
+    return (
+        f'st.session_state has no attribute "{attr_name}". Did you forget to initialize it? '
+        f"More info: https://docs.streamlit.io/develop/concepts/architecture/session-state#initialization"
+    )

streamlit/runtime/state/widgets.py

@@ -0,0 +1,135 @@
+# 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
+
+from streamlit.runtime.state.common import (
+    RegisterWidgetResult,
+    T,
+    ValueFieldName,
+    WidgetArgs,
+    WidgetCallback,
+    WidgetDeserializer,
+    WidgetKwargs,
+    WidgetMetadata,
+    WidgetSerializer,
+    user_key_from_element_id,
+)
+
+if TYPE_CHECKING:
+    from streamlit.runtime.scriptrunner import ScriptRunContext
+
+
+def register_widget(
+    element_id: str,
+    *,
+    deserializer: WidgetDeserializer[T],
+    serializer: WidgetSerializer[T],
+    ctx: ScriptRunContext | None,
+    on_change_handler: WidgetCallback | None = None,
+    args: WidgetArgs | None = None,
+    kwargs: WidgetKwargs | None = None,
+    value_type: ValueFieldName,
+) -> RegisterWidgetResult[T]:
+    """Register a widget with Streamlit, and return its current value.
+    NOTE: This function should be called after the proto has been filled.
+
+    Parameters
+    ----------
+    element_id : str
+        The id of the element. Must be unique.
+    deserializer : WidgetDeserializer[T]
+        Called to convert a widget's protobuf value to the value returned by
+        its st.<widget_name> function.
+    serializer : WidgetSerializer[T]
+        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.
+    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
+    kwargs : WidgetKwargs or None
+        kwargs to pass to on_change_handler when invoked
+    value_type: ValueType
+        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
+        frontend, the guess is updated to be the correct type. Unfortunately, we're
+        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.
+
+
+    Returns
+    -------
+    register_widget_result : RegisterWidgetResult[T]
+        Provides information on which value to return to the widget caller,
+        and whether the UI needs updating.
+
+        - Unhappy path:
+            - Our ScriptRunContext doesn't exist (meaning that we're running
+            as a "bare script" outside streamlit).
+            - We are disconnected from the SessionState instance.
+            In both cases we'll return a fallback RegisterWidgetResult[T].
+        - Happy path:
+            - The widget has already been registered on a previous run but the
+            user hasn't interacted with it on the client. The widget will have
+            the default value it was first created with. We then return a
+            RegisterWidgetResult[T], containing this value.
+            - The widget has already been registered and the user *has*
+            interacted with it. The widget will have that most recent
+            user-specified value. We then return a RegisterWidgetResult[T],
+            containing this value.
+
+        For both paths a widget return value is provided, allowing the widgets
+        to be used in a non-streamlit setting.
+    """
+    # Create the widget's updated metadata, and register it with session_state.
+    metadata = WidgetMetadata(
+        element_id,
+        deserializer,
+        serializer,
+        value_type=value_type,
+        callback=on_change_handler,
+        callback_args=args,
+        callback_kwargs=kwargs,
+        fragment_id=ctx.current_fragment_id if ctx else None,
+    )
+    return register_widget_from_metadata(metadata, ctx)
+
+
+def register_widget_from_metadata(
+    metadata: WidgetMetadata[T],
+    ctx: ScriptRunContext | None,
+) -> RegisterWidgetResult[T]:
+    """Register a widget and return its value, using an already constructed
+    `WidgetMetadata`.
+
+    This is split out from `register_widget` to allow caching code to replay
+    widgets by saving and reusing the completed metadata.
+
+    See `register_widget` for details on what this returns.
+    """
+    if ctx is None:
+        # Early-out if we don't have a script run context (which probably means
+        # we're running as a "bare" Python script, and not via `streamlit run`).
+        return RegisterWidgetResult.failure(deserializer=metadata.deserializer)
+
+    widget_id = metadata.id
+    user_key = user_key_from_element_id(widget_id)
+
+    return ctx.session_state.register_widget(metadata, user_key)

streamlit/runtime/stats.py

@@ -0,0 +1,109 @@
+# 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 itertools
+from abc import abstractmethod
+from typing import TYPE_CHECKING, NamedTuple, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from streamlit.proto.openmetrics_data_model_pb2 import Metric as MetricProto
+
+
+class CacheStat(NamedTuple):
+    """Describes a single cache entry.
+
+    Properties
+    ----------
+    category_name : str
+        A human-readable name for the cache "category" that the entry belongs
+        to - e.g. "st.memo", "session_state", etc.
+    cache_name : str
+        A human-readable name for cache instance that the entry belongs to.
+        For "st.memo" and other function decorator caches, this might be the
+        name of the cached function. If the cache category doesn't have
+        multiple separate cache instances, this can just be the empty string.
+    byte_length : int
+        The entry's memory footprint in bytes.
+    """
+
+    category_name: str
+    cache_name: str
+    byte_length: int
+
+    def to_metric_str(self) -> str:
+        return f'cache_memory_bytes{{cache_type="{self.category_name}",cache="{self.cache_name}"}} {self.byte_length}'
+
+    def marshall_metric_proto(self, metric: MetricProto) -> None:
+        """Fill an OpenMetrics `Metric` protobuf object."""
+        label = metric.labels.add()
+        label.name = "cache_type"
+        label.value = self.category_name
+
+        label = metric.labels.add()
+        label.name = "cache"
+        label.value = self.cache_name
+
+        metric_point = metric.metric_points.add()
+        metric_point.gauge_value.int_value = self.byte_length
+
+
+def group_stats(stats: list[CacheStat]) -> list[CacheStat]:
+    """Group a list of CacheStats by category_name and cache_name and sum byte_length"""
+
+    def key_function(individual_stat):
+        return individual_stat.category_name, individual_stat.cache_name
+
+    result: list[CacheStat] = []
+
+    sorted_stats = sorted(stats, key=key_function)
+    grouped_stats = itertools.groupby(sorted_stats, key=key_function)
+
+    for (category_name, cache_name), single_group_stats in grouped_stats:
+        result.append(
+            CacheStat(
+                category_name=category_name,
+                cache_name=cache_name,
+                byte_length=sum(item.byte_length for item in single_group_stats),
+            )
+        )
+    return result
+
+
+@runtime_checkable
+class CacheStatsProvider(Protocol):
+    @abstractmethod
+    def get_stats(self) -> list[CacheStat]:
+        raise NotImplementedError
+
+
+class StatsManager:
+    def __init__(self):
+        self._cache_stats_providers: list[CacheStatsProvider] = []
+
+    def register_provider(self, provider: CacheStatsProvider) -> None:
+        """Register a CacheStatsProvider with the manager.
+        This function is not thread-safe. Call it immediately after
+        creation.
+        """
+        self._cache_stats_providers.append(provider)
+
+    def get_stats(self) -> list[CacheStat]:
+        """Return a list containing all stats from each registered provider."""
+        all_stats: list[CacheStat] = []
+        for provider in self._cache_stats_providers:
+            all_stats.extend(provider.get_stats())
+
+        return all_stats

streamlit/runtime/uploaded_file_manager.py

@@ -0,0 +1,148 @@
+# 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 io
+from abc import abstractmethod
+from typing import TYPE_CHECKING, NamedTuple, Protocol
+
+from streamlit import util
+from streamlit.runtime.stats import CacheStatsProvider
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from streamlit.proto.Common_pb2 import FileURLs as FileURLsProto
+
+
+class UploadedFileRec(NamedTuple):
+    """Metadata and raw bytes for an uploaded file. Immutable."""
+
+    file_id: str
+    name: str
+    type: str
+    data: bytes
+
+
+class UploadFileUrlInfo(NamedTuple):
+    """Information we provide for single file in get_upload_urls"""
+
+    file_id: str
+    upload_url: str
+    delete_url: str
+
+
+class DeletedFile(NamedTuple):
+    """Represents a deleted file in deserialized values for st.file_uploader and
+    st.camera_input
+
+    Return this from st.file_uploader and st.camera_input deserialize (so they can
+    be used in session_state), when widget value contains file record that is missing
+    from the storage.
+    DeleteFile instances filtered out before return final value to the user in script,
+    or before sending to frontend."""
+
+    file_id: str
+
+
+class UploadedFile(io.BytesIO):
+    """A mutable uploaded file.
+
+    This class extends BytesIO, which has copy-on-write semantics when
+    initialized with `bytes`.
+    """
+
+    def __init__(self, record: UploadedFileRec, file_urls: FileURLsProto):
+        # BytesIO's copy-on-write semantics doesn't seem to be mentioned in
+        # the Python docs - possibly because it's a CPython-only optimization
+        # and not guaranteed to be in other Python runtimes. But it's detailed
+        # here: https://hg.python.org/cpython/rev/79a5fbe2c78f
+        super().__init__(record.data)
+        self.file_id = record.file_id
+        self.name = record.name
+        self.type = record.type
+        self.size = len(record.data)
+        self._file_urls = file_urls
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, UploadedFile):
+            return NotImplemented
+        return self.file_id == other.file_id
+
+    def __repr__(self) -> str:
+        return util.repr_(self)
+
+
+class UploadedFileManager(CacheStatsProvider, Protocol):
+    """UploadedFileManager protocol, that should be implemented by the concrete
+    uploaded file managers.
+
+    It is responsible for:
+        - retrieving files by session_id and file_id for st.file_uploader and
+            st.camera_input
+        - cleaning up uploaded files associated with session on session end
+
+    It should be created during Runtime initialization.
+
+    Optionally UploadedFileManager could be responsible for issuing URLs which will be
+    used by frontend to upload files to.
+    """
+
+    @abstractmethod
+    def get_files(
+        self, session_id: str, file_ids: Sequence[str]
+    ) -> list[UploadedFileRec]:
+        """Return a  list of UploadedFileRec for a given sequence of file_ids.
+
+        Parameters
+        ----------
+        session_id
+            The ID of the session that owns the files.
+        file_ids
+            The sequence of ids associated with files to retrieve.
+
+        Returns
+        -------
+        List[UploadedFileRec]
+            A list of URL UploadedFileRec instances, each instance contains information
+            about uploaded file.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def remove_session_files(self, session_id: str) -> None:
+        """Remove all files associated with a given session."""
+        raise NotImplementedError
+
+    def get_upload_urls(
+        self, session_id: str, file_names: Sequence[str]
+    ) -> list[UploadFileUrlInfo]:
+        """Return a list of UploadFileUrlInfo for a given sequence of file_names.
+        Optional to implement, issuing of URLs could be done by other service.
+
+        Parameters
+        ----------
+        session_id
+            The ID of the session that request URLs.
+        file_names
+            The sequence of file names for which URLs are requested
+
+        Returns
+        -------
+        List[UploadFileUrlInfo]
+            A list of UploadFileUrlInfo instances, each instance contains information
+            about uploaded file URLs.
+        """
+        raise NotImplementedError