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

streamlit/__init__.py

@@ -180,6 +180,7 @@ container = _main.container
 dataframe = _main.dataframe
 data_editor = _main.data_editor
 date_input = _main.date_input
+datetime_input = _main.datetime_input
 divider = _main.divider
 download_button = _main.download_button
 expander = _main.expander

streamlit/commands/execution_control.py

@@ -15,9 +15,11 @@
 from __future__ import annotations
 
 import os
+import time
+from collections.abc import Iterable, Mapping
 from itertools import dropwhile
 from pathlib import Path
-from typing import Literal, NoReturn
+from typing import TYPE_CHECKING, Literal, NoReturn
 
 import streamlit as st
 from streamlit.errors import NoSessionContext, StreamlitAPIException
@@ -30,6 +32,9 @@ from streamlit.runtime.scriptrunner import (
     get_script_run_ctx,
 )
 
+if TYPE_CHECKING:
+    from streamlit.runtime.state.query_params import QueryParams, QueryParamsInput
+
 
 @gather_metrics("stop")
 def stop() -> NoReturn:  # type: ignore[misc]
@@ -99,6 +104,31 @@ def _new_fragment_id_queue(
     return new_queue
 
 
+def _set_query_params_for_switch(
+    query_params_state: QueryParams,
+    new_query_params: QueryParamsInput | None,
+) -> None:
+    """Set query params for a switch page."""
+
+    if new_query_params is None:
+        query_params_state.clear()
+        return
+
+    if isinstance(new_query_params, Mapping) or (
+        isinstance(new_query_params, Iterable)
+        and not isinstance(
+            new_query_params,  # type: ignore[unreachable]
+            (str, bytes),
+        )
+    ):
+        query_params_state.from_dict(new_query_params)
+        return
+
+    raise StreamlitAPIException(
+        f"`query_params` must be a mapping or an iterable of (key, value) pairs not a `{type(new_query_params)}`."
+    )
+
+
 @gather_metrics("rerun")
 def rerun(  # type: ignore[misc]
     *,  # The scope argument can only be passed via keyword.
@@ -155,7 +185,11 @@ def rerun(  # type: ignore[misc]
 
 
 @gather_metrics("switch_page")
-def switch_page(page: str | Path | StreamlitPage) -> NoReturn:  # type: ignore[misc]
+def switch_page(  # type: ignore[misc]
+    page: str | Path | StreamlitPage,
+    *,
+    query_params: QueryParamsInput | None = None,
+) -> NoReturn:  # ty: ignore[invalid-return-type]
     """Programmatically switch the current page in a multipage app.
 
     When ``st.switch_page`` is called, the current page execution stops and
@@ -166,20 +200,31 @@ def switch_page(page: str | Path | StreamlitPage) -> NoReturn:  # type: ignore[m
 
     Parameters
     ----------
-    page: str, Path, or st.Page
+    page : str, Path, or st.Page
         The file path (relative to the main script) or an st.Page indicating
         the page to switch to.
 
+    query_params : dict, list of tuples, or None
+        Query parameters to apply when navigating to the target page.
+        This can be a dictionary or an iterable of key-value tuples. Values can
+        be strings or iterables of strings (for repeated keys). When this is
+        ``None`` (default), all non-embed query parameters are cleared during
+        navigation.
 
-    Example
-    -------
-    Consider the following example given this file structure:
+    Examples
+    --------
+    **Example 1: Basic usage**
+
+    The following example shows how to switch to a different page in a
+    multipage app that uses the ``pages/`` directory:
 
-    >>> your-repository/
-    >>> ├── pages/
-    >>> │   ├── page_1.py
-    >>> │   └── page_2.py
-    >>> └── your_app.py
+    .. code-block:: text
+
+        your-repository/
+        ├── pages/
+        │   ├── page_1.py
+        │   └── page_2.py
+        └── your_app.py
 
     >>> import streamlit as st
     >>>
@@ -190,10 +235,35 @@ def switch_page(page: str | Path | StreamlitPage) -> NoReturn:  # type: ignore[m
     >>> if st.button("Page 2"):
     >>>     st.switch_page("pages/page_2.py")
 
-    .. output ::
+    .. output::
         https://doc-switch-page.streamlit.app/
         height: 350px
 
+    **Example 2: Passing query parameters**
+
+    The following example shows how to pass query parameters when switching to a
+    different page. This example uses ``st.navigation`` to create a multipage app.
+
+    .. code-block:: text
+
+        your-repository/
+        ├── page_2.py
+        └── your_app.py
+
+    >>> import streamlit as st
+    >>>
+    >>> def page_1():
+    >>>     st.title("Page 1")
+    >>>     if st.button("Switch to Page 2"):
+    >>>         st.switch_page("page_2.py", query_params={"utm_source": "page_1"})
+    >>>
+    >>> pg = st.navigation([page_1, "page_2.py"])
+    >>> pg.run()
+
+    .. output::
+        https://doc-switch-page-query-params.streamlit.app/
+        height: 350px
+
     """
 
     ctx = get_script_run_ctx()
@@ -227,9 +297,14 @@ def switch_page(page: str | Path | StreamlitPage) -> NoReturn:  # type: ignore[m
 
         page_script_hash = matched_pages[0]["page_script_hash"]
 
-    # We want to reset query params (with exception of embed) when switching pages
+    # Reset query params (with exception of embed) and optionally apply overrides.
     with ctx.session_state.query_params() as qp:
-        qp.clear()
+        _set_query_params_for_switch(qp, query_params)
+        # Additional safeguard to ensure the query params
+        #  are sent out to the frontend before the new rerun might clear
+        # outstanding messages. This uses the same time that is used as waiting
+        # in our event loop.
+        time.sleep(0.01)
 
     ctx.script_requests.request_rerun(
         RerunData(

streamlit/components/v1/component_arrow.py

@@ -24,7 +24,7 @@ from streamlit import dataframe_util
 from streamlit.elements.lib import pandas_styler_utils
 
 if TYPE_CHECKING:
-    from pandas import DataFrame, Index, Series
+    from pandas import DataFrame, Index
 
     from streamlit.proto.Components_pb2 import ArrowTable as ArrowTableProto
 
@@ -57,7 +57,7 @@ def marshall(
     _marshall_data(proto, df)
 
 
-def _marshall_index(proto: ArrowTableProto, index: Index) -> None:
+def _marshall_index(proto: ArrowTableProto, index: Index[Any]) -> None:
     """Marshall pandas.DataFrame index into an ArrowTable proto.
 
     Parameters
@@ -72,12 +72,12 @@ def _marshall_index(proto: ArrowTableProto, index: Index) -> None:
     """
     import pandas as pd
 
-    index_values = map(_maybe_tuple_to_list, index.values)
+    index_values = list(map(_maybe_tuple_to_list, index.values))
     index_df = pd.DataFrame(index_values)
     proto.index = dataframe_util.convert_pandas_df_to_arrow_bytes(index_df)
 
 
-def _marshall_columns(proto: ArrowTableProto, columns: Series) -> None:
+def _marshall_columns(proto: ArrowTableProto, columns: Index[Any]) -> None:
     """Marshall pandas.DataFrame columns into an ArrowTable proto.
 
     Parameters
@@ -85,15 +85,15 @@ def _marshall_columns(proto: ArrowTableProto, columns: Series) -> None:
     proto : proto.ArrowTable
         Output. The protobuf for a Streamlit ArrowTable proto.
 
-    columns : Series
+    columns : Index
         Column labels to use for resulting frame.
         Will default to RangeIndex (0, 1, 2, ..., n) if no column labels are provided.
 
     """
     import pandas as pd
 
-    values = map(_maybe_tuple_to_list, columns.values)
-    columns_df = pd.DataFrame(values)
+    column_values = list(map(_maybe_tuple_to_list, columns.values))
+    columns_df = pd.DataFrame(column_values)
     proto.columns = dataframe_util.convert_pandas_df_to_arrow_bytes(columns_df)
 
 

streamlit/components/v2/__init__.py

@@ -322,7 +322,7 @@ def component(
         if result.clicked:
             st.write(f"You clicked {result.clicked}!")
 
-    .. output ::
+    .. output::
         https://doc-components-markdown-links.streamlit.app/
         height: 250px
 
@@ -386,7 +386,7 @@ def component(
         elif result.clicked == "link_2":
             st.write("You clicked the second link!")
 
-    .. output ::
+    .. output::
         https://doc-components-custom-anchors.streamlit.app/
         height: 250px
 
@@ -445,10 +445,66 @@ def component(
         result = my_component(on_clicked_change=lambda: None)
         result
 
-    .. output ::
+    .. output::
         https://doc-components-interactive-svg.streamlit.app/
         height: 550px
 
+    **Example 4: Clean up your component's resources**
+
+    You can use the return value of the component's JavaScript function to
+    clean up any resources when the component is unmounted. For example, you
+    can disconnect a MutationObserver that was monitoring changes in the DOM.
+
+    .. code-block:: python
+
+        import streamlit as st
+
+        JS = """
+        export default function(component) {
+            const { setStateValue, parentElement } = component;
+            const sidebar = document.querySelector('section.stSidebar');
+            const initialState = sidebar.getAttribute('aria-expanded') === 'true';
+
+            // Create observer to watch for aria-expanded attribute changes
+            const observer = new MutationObserver((mutations) => {
+                mutations.forEach((mutation) => {
+                    if (mutation.type === 'attributes' && mutation.attributeName === 'aria-expanded') {
+                        const newIsExpanded = sidebar.getAttribute('aria-expanded') === 'true';
+                        setStateValue('expanded', newIsExpanded);
+                    }
+                });
+            });
+
+            // Start observing
+            observer.observe(sidebar, {
+                attributes: true,
+                attributeFilter: ['aria-expanded']
+            });
+
+            // Set initial state
+            setStateValue('expanded', initialState);
+
+            // Cleanup function to remove the observer
+            return () => {
+                observer.disconnect();
+            };
+
+        };
+        """
+
+        my_component = st.components.v2.component(
+            "sidebar_expansion_detector",
+            js=JS,
+        )
+
+        st.sidebar.write("Sidebar content")
+        result = my_component(on_expanded_change=lambda: None)
+        result
+
+    .. output::
+        https://doc-components-cleanup-function.streamlit.app/
+        height: 250px
+
     '''
     return _create_component_callable(name, html=html, css=css, js=js)
 

streamlit/components/v2/bidi_component/main.py

@@ -55,9 +55,11 @@ from streamlit.errors import (
 )
 from streamlit.proto.ArrowData_pb2 import ArrowData as ArrowDataProto
 from streamlit.proto.BidiComponent_pb2 import BidiComponent as BidiComponentProto
+from streamlit.proto.BidiComponent_pb2 import MixedData as MixedDataProto
 from streamlit.runtime.metrics_util import gather_metrics
 from streamlit.runtime.scriptrunner_utils.script_run_context import get_script_run_ctx
 from streamlit.runtime.state import register_widget
+from streamlit.util import calc_md5
 
 if TYPE_CHECKING:
     from streamlit.components.v2.types import (
@@ -117,6 +119,144 @@ def _make_trigger_id(base: str, event: str) -> str:
 class BidiComponentMixin:
     """Mixin class for the bidi_component DeltaGenerator method."""
 
+    def _canonicalize_json_for_identity(self, payload: str) -> str:
+        """Return a deterministic JSON string for identity comparisons.
+
+        Payloads that cannot be parsed (or re-serialized) are returned as-is to
+        avoid mutating developer data.
+        """
+
+        if not payload:
+            return payload
+
+        try:
+            parsed = json.loads(payload)
+        except (TypeError, ValueError):
+            return payload
+
+        try:
+            return json.dumps(parsed, sort_keys=True)
+        except (TypeError, ValueError):
+            return payload
+
+    def _canonical_json_digest_for_identity(self, payload: str) -> str:
+        """Return the hash of the canonicalized JSON payload for identity use.
+
+        Hashing keeps the kwargs passed to ``compute_and_register_element_id``
+        small even when the JSON payload is very large, while still changing the
+        identity whenever the canonical JSON content changes.
+        """
+
+        canonical = self._canonicalize_json_for_identity(payload)
+        return calc_md5(canonical)
+
+    def _build_bidi_identity_kwargs(
+        self,
+        *,
+        component_name: str,
+        isolate_styles: bool,
+        width: Width,
+        height: Height,
+        proto: BidiComponentProto,
+        data: BidiComponentData = None,
+    ) -> dict[str, Any]:
+        """Build deterministic identity kwargs for ID computation.
+
+        Construct a stable mapping of identity-relevant properties for
+        ``compute_and_register_element_id``. This includes structural
+        properties (name, style isolation, layout) and an explicit, typed
+        handling of the ``BidiComponent`` ``oneof data`` field to ensure
+        unkeyed components change identity when their serialized payload
+        changes.
+
+        Parameters
+        ----------
+        component_name : str
+            The registered component name.
+        isolate_styles : bool
+            Whether the component styles are rendered in a Shadow DOM.
+        width : Width
+            Desired width configuration passed to the component.
+        height : Height
+            Desired height configuration passed to the component.
+        proto : BidiComponentProto
+            The populated component protobuf. Its ``data`` oneof determines
+            which serialized payload (JSON, Arrow, bytes, or Mixed) contributes
+            to identity.
+        data : BidiComponentData
+            The raw data passed to the component. Used to optimize identity
+            calculation for JSON payloads by avoiding a parse/serialize cycle.
+
+        Returns
+        -------
+        dict[str, Any]
+            A mapping of deterministic values to be forwarded into
+            ``compute_and_register_element_id``.
+
+        Raises
+        ------
+        RuntimeError
+            If an unhandled ``oneof data`` variant is encountered (guards
+            against adding new fields without updating identity computation).
+        """
+        identity: dict[str, Any] = {
+            "component_name": component_name,
+            "isolate_styles": isolate_styles,
+            "width": width,
+            "height": height,
+        }
+
+        data_field = proto.WhichOneof("data")
+        if data_field is None:
+            return identity
+
+        if data_field == "json":
+            # Canonicalize only for identity so unkeyed widgets don't churn when
+            # dict insertion order changes.
+            #
+            # Optimization: Use raw `data` if available to avoid the overhead of
+            # parsing `proto.json` back into a dict.
+            canonical_digest = None
+
+            if data is not None:
+                try:
+                    canonical = json.dumps(data, sort_keys=True)
+                    canonical_digest = calc_md5(canonical)
+                except (TypeError, ValueError):
+                    # Fallback to existing logic if direct dump fails
+                    pass
+
+            if canonical_digest is None:
+                canonical_digest = self._canonical_json_digest_for_identity(proto.json)
+
+            identity["json"] = canonical_digest
+        elif data_field == "arrow_data":
+            # Hash large payloads instead of shoving raw bytes through the ID
+            # hasher for performance.
+            identity["arrow_data"] = calc_md5(proto.arrow_data.data)
+        elif data_field == "bytes":
+            # Same story for arbitrary bytes payloads: content-address the data
+            # so identity changes track real mutations without re-hashing the
+            # whole blob every run.
+            identity["bytes"] = calc_md5(proto.bytes)
+        elif data_field == "mixed":
+            mixed: MixedDataProto = proto.mixed
+            # Add the JSON content of the MixedData to the identity.
+            identity["mixed_json"] = self._canonical_json_digest_for_identity(
+                mixed.json
+            )
+            # Add the sorted content-addressed ref IDs of the Arrow blobs to the identity.
+            # Unlike other data types where we include actual bytes, here we only include
+            # the blob keys. This is sufficient because keys are MD5 hashes of the blob
+            # content (content-addressed), so identical content produces identical keys.
+            identity["mixed_arrow_blobs"] = ",".join(sorted(mixed.arrow_blobs.keys()))
+        else:
+            raise RuntimeError(
+                f"Unhandled BidiComponent.data oneof field: {data_field}"
+            )
+
+        return identity
+
     @gather_metrics("_bidi_component")
     def _bidi_component(
         self,
@@ -206,18 +346,6 @@ class BidiComponentMixin:
         if not has_js and not has_html:
             raise BidiComponentMissingContentError(component_name)
 
-        # Compute a unique ID for this component instance
-        computed_id = compute_and_register_element_id(
-            "bidi_component",
-            user_key=key,
-            component_name=component_name,
-            isolate_styles=isolate_styles,
-            width=width,
-            height=height,
-            dg=self.dg,
-            key_as_main_identity=True,
-        )
-
         # ------------------------------------------------------------------
         # 1. Parse user-supplied callbacks
         # ------------------------------------------------------------------
@@ -253,7 +381,6 @@ class BidiComponentMixin:
 
         # Set up the component proto
         bidi_component_proto = BidiComponentProto()
-        bidi_component_proto.id = computed_id
         bidi_component_proto.component_name = component_name
         bidi_component_proto.isolate_styles = isolate_styles
         bidi_component_proto.js_content = component_def.js_content or ""
@@ -298,6 +425,27 @@ class BidiComponentMixin:
                     raise BidiComponentUnserializableDataError()
         bidi_component_proto.form_id = current_form_id(self.dg)
 
+        # Build identity kwargs for the component instance now that the proto is
+        # populated.
+        identity_kwargs = self._build_bidi_identity_kwargs(
+            component_name=component_name,
+            isolate_styles=isolate_styles,
+            width=width,
+            height=height,
+            proto=bidi_component_proto,
+            data=data,
+        )
+        # Compute a unique ID for this component instance now that the proto is
+        # populated.
+        computed_id = compute_and_register_element_id(
+            "bidi_component",
+            user_key=key,
+            key_as_main_identity=True,
+            dg=self.dg,
+            **identity_kwargs,
+        )
+        bidi_component_proto.id = computed_id
+
         # Instantiate the Serde for this component instance
         serde = BidiComponentSerde(default=default)
 

streamlit/components/v2/bidi_component/serialization.py

@@ -23,7 +23,7 @@ from streamlit.dataframe_util import convert_anything_to_arrow_bytes, is_datafra
 from streamlit.logger import get_logger
 from streamlit.proto.BidiComponent_pb2 import BidiComponent as BidiComponentProto
 from streamlit.proto.BidiComponent_pb2 import MixedData as MixedDataProto
-from streamlit.util import AttributeDictionary
+from streamlit.util import AttributeDictionary, calc_md5
 
 if TYPE_CHECKING:
     from streamlit.components.v2.bidi_component.state import BidiComponentState
@@ -56,8 +56,6 @@ def _extract_dataframes_from_dict(
     dict[str, Any]
         A new dictionary with dataframe-like objects replaced by placeholders.
     """
-    import uuid
-
     if arrow_blobs is None:
         arrow_blobs = {}
 
@@ -68,11 +66,20 @@ def _extract_dataframes_from_dict(
             # This is a dataframe-like object, serialize it to Arrow
             try:
                 arrow_bytes = convert_anything_to_arrow_bytes(value)
-                ref_id = str(uuid.uuid4())
+                # Use deterministic, content-addressed ref IDs so placeholders
+                # are stable for identical content on each run. This also provides
+                # natural deduplication - identical DataFrames share a single blob.
+                ref_id = calc_md5(arrow_bytes)
                 arrow_blobs[ref_id] = arrow_bytes
                 processed_data[key] = {ARROW_REF_KEY: ref_id}
-            except Exception:
-                # If Arrow serialization fails, keep the original value for JSON serialization
+            except Exception as e:
+                # If Arrow serialization fails, keep the original value for JSON
+                # serialization attempt downstream.
+                _LOGGER.debug(
+                    "Arrow serialization failed for key %r, keeping original value: %s",
+                    key,
+                    e,
+                )
                 processed_data[key] = value
         else:
             # Not dataframe-like, keep as-is

streamlit/components/v2/component_manager.py

@@ -304,11 +304,18 @@ class BidiComponentManager:
         else:
             _LOGGER.debug("File watching not started")
 
-    def discover_and_register_components(self) -> None:
+    def discover_and_register_components(
+        self, *, start_file_watching: bool = True
+    ) -> None:
         """Discover installed v2 components and register them.
 
         This scans installed distributions for manifests, registers all discovered
         components, and starts file watching for development workflows.
+
+        Parameters
+        ----------
+        start_file_watching : bool
+            Whether to start file watching after components are registered.
         """
         try:
             from streamlit.components.v2.manifest_scanner import (
@@ -318,14 +325,15 @@ class BidiComponentManager:
             manifests = scan_component_manifests()
             for manifest, package_root in manifests:
                 self.register_from_manifest(manifest, package_root)
-                _LOGGER.info(
+                _LOGGER.debug(
                     "Registered components from pyproject.toml: %s v%s",
                     manifest.name,
                     manifest.version,
                 )
 
             # Start file watching for development mode after all components are registered
-            self.start_file_watching()
+            if start_file_watching:
+                self.start_file_watching()
 
         except Exception as e:
             _LOGGER.warning("Failed to scan component manifests: %s", e)

streamlit/components/v2/component_registry.py

@@ -164,6 +164,16 @@ class BidiComponentDefinition:
         # If we get here, it's content, not a path
         return False, None
 
+    @property
+    def is_placeholder(self) -> bool:
+        """Return True if this definition is a placeholder (no content).
+
+        Placeholders are typically created during the manifest scanning phase
+        when we discover a component's existence but haven't yet loaded its
+        content via the public API.
+        """
+        return self.html is None and self.css is None and self.js is None
+
     @property
     def css_url(self) -> str | None:
         """Return the asset-dir-relative URL path for CSS when file-backed.
@@ -329,7 +339,14 @@ class BidiComponentRegistry:
             name = definition.name
             if name in self._components:
                 existing_definition = self._components[name]
-                if existing_definition != definition:
+                # Check if the existing definition is different and NOT a placeholder.
+                # We expect placeholders (from manifest scanning) to be overwritten
+                # by the actual definition from the script execution, so we silence
+                # the warning in that specific case.
+                if (
+                    existing_definition != definition
+                    and not existing_definition.is_placeholder
+                ):
                     _LOGGER.warning(
                         "Component %s is already registered. Overwriting "
                         "previous definition. This may lead to unexpected behavior "

streamlit/components/v2/types.py

@@ -245,7 +245,7 @@ class BidiComponentCallable(Protocol):
         st.write("Result:", result)
         st.write("Session state:", st.session_state)
 
-    .. output ::
+    .. output::
         https://doc-components-text-input.streamlit.app/
         height: 600px
 
@@ -296,7 +296,7 @@ class BidiComponentCallable(Protocol):
         )
         result_2
 
-    .. output ::
+    .. output::
         https://doc-components-tailwind-button.streamlit.app/
         height: 350px
 

streamlit/connections/snowflake_connection.py

@@ -357,7 +357,7 @@ class SnowflakeConnection(BaseConnection["InternalSnowflakeConnection"]):
         def _query(sql: str) -> DataFrame:
             cur = self._instance.cursor()
             cur.execute(sql, params=params, **kwargs)
-            return cur.fetch_pandas_all()
+            return cur.fetch_pandas_all()  # type: ignore
 
         # We modify our helper function's `__qualname__` here to work around default
         # `@st.cache_data` behavior. Otherwise, `.query()` being called with different

streamlit/connections/snowpark_connection.py

@@ -146,7 +146,7 @@ class SnowparkConnection(BaseConnection["Session"]):
         )
         def _query(sql: str) -> DataFrame:
             with self._lock:
-                return self._instance.sql(sql).to_pandas()
+                return self._instance.sql(sql).to_pandas()  # type: ignore
 
         # We modify our helper function's `__qualname__` here to work around default
         # `@st.cache_data` behavior. Otherwise, `.query()` being called with different