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

streamlit/components/v2/bidi_component/serialization.py

@@ -0,0 +1,272 @@
+# 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 json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, cast
+
+from streamlit.components.v2.bidi_component.constants import ARROW_REF_KEY
+from streamlit.dataframe_util import convert_anything_to_arrow_bytes, is_dataframe_like
+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, calc_md5
+
+if TYPE_CHECKING:
+    from streamlit.components.v2.bidi_component.state import BidiComponentState
+
+_LOGGER = get_logger(__name__)
+
+
+def _extract_dataframes_from_dict(
+    data: dict[str, Any], arrow_blobs: dict[str, bytes] | None = None
+) -> dict[str, Any]:
+    """Extract dataframe-like objects from a dictionary and replace them with
+    placeholders.
+
+    This function traverses the first level of a dictionary, detects any
+    dataframe-like objects, stores their Arrow bytes representation in the
+    `arrow_blobs` dictionary, and replaces them with JSON-serializable
+    placeholder objects.
+
+    Parameters
+    ----------
+    data
+        The dictionary to process. Only the first level is checked for
+        dataframe-like objects.
+    arrow_blobs
+        The dictionary to store the extracted Arrow bytes in, keyed by a unique
+        reference ID.
+
+    Returns
+    -------
+    dict[str, Any]
+        A new dictionary with dataframe-like objects replaced by placeholders.
+    """
+    if arrow_blobs is None:
+        arrow_blobs = {}
+
+    processed_data = {}
+
+    for key, value in data.items():
+        if is_dataframe_like(value):
+            # This is a dataframe-like object, serialize it to Arrow
+            try:
+                arrow_bytes = convert_anything_to_arrow_bytes(value)
+                # 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 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
+            processed_data[key] = value
+
+    return processed_data
+
+
+def serialize_mixed_data(data: Any, bidi_component_proto: BidiComponentProto) -> None:
+    """Serialize mixed data with automatic dataframe detection into a protobuf message.
+
+    This function detects dataframe-like objects in the first level of a dictionary,
+    extracts them into separate Arrow blobs, and populates a `MixedDataProto`
+    protobuf message for efficient serialization.
+
+    Parameters
+    ----------
+    data
+        The data structure to serialize. If it is a dictionary, its first
+        level will be scanned for dataframe-like objects.
+    bidi_component_proto
+        The protobuf message to populate with the serialized data.
+
+    """
+    arrow_blobs: dict[str, bytes] = {}
+
+    # Only process dictionaries for automatic dataframe detection
+    if isinstance(data, dict):
+        processed_data = _extract_dataframes_from_dict(data, arrow_blobs)
+    else:
+        # For non-dict data (lists, tuples, etc.), pass through as-is
+        # We don't automatically detect dataframes in these structures
+        processed_data = data
+
+    if arrow_blobs:
+        # We have dataframes, use mixed data serialization
+        mixed_proto = MixedDataProto()
+        try:
+            mixed_proto.json = json.dumps(processed_data)
+        except TypeError:
+            # If JSON serialization fails (e.g., due to undetected dataframes),
+            # fall back to string representation
+            mixed_proto.json = json.dumps(str(processed_data))
+
+        # Add Arrow blobs to the protobuf
+        for ref_id, arrow_bytes in arrow_blobs.items():
+            mixed_proto.arrow_blobs[ref_id].data = arrow_bytes
+
+        bidi_component_proto.mixed.CopyFrom(mixed_proto)
+    else:
+        # No dataframes found, use regular JSON serialization
+        try:
+            bidi_component_proto.json = json.dumps(processed_data)
+        except TypeError:
+            # If JSON serialization fails (e.g., due to dataframes in lists/tuples),
+            # fall back to string representation
+            bidi_component_proto.json = json.dumps(str(processed_data))
+
+
+def handle_deserialize(s: str | None) -> Any:
+    """Deserialize a JSON string, returning the string itself if it's not valid JSON.
+
+    Parameters
+    ----------
+    s
+        The string to deserialize.
+
+    Returns
+    -------
+    Any
+        The deserialized JSON object, or the original string if parsing fails.
+        Returns `None` if the input is `None`.
+
+    """
+    if s is None:
+        return None
+    try:
+        return json.loads(s)
+    except json.JSONDecodeError:
+        return s
+
+
+def deserialize_trigger_list(s: str | None) -> list[Any] | None:
+    """Deserialize trigger aggregator payloads as a list.
+
+    For bidirectional components, the frontend always sends a JSON array of payload
+    objects. This deserializer normalizes older or singular payloads into a list
+    while preserving ``None`` for cleared values.
+
+    Parameters
+    ----------
+    s
+        The JSON string to deserialize, hopefully representing a list of payloads.
+
+    Returns
+    -------
+    list[Any] or None
+        A list of payloads, or `None` if the input was `None`.
+
+    """
+    value = handle_deserialize(s)
+    if value is None:
+        return None
+    if isinstance(value, list):
+        return value
+    return [value]
+
+
+@dataclass
+class BidiComponentSerde:
+    """Serialization and deserialization logic for a bidirectional component.
+
+    This class handles the conversion of component state between the frontend
+    (JSON strings) and the backend (Python objects).
+
+    The canonical shape is a flat mapping of state keys to values.
+
+    Parameters
+    ----------
+    default
+        A dictionary of default values to be applied to the state when
+        deserializing, if the corresponding keys are not already present.
+
+    """
+
+    default: dict[str, Any] | None = None
+
+    def deserialize(self, ui_value: str | dict[str, Any] | None) -> BidiComponentState:
+        """Deserialize the component's state from a frontend value.
+
+        Parameters
+        ----------
+        ui_value
+            The value received from the frontend, which can be a JSON string,
+            a dictionary, or `None`.
+
+        Returns
+        -------
+        BidiComponentState
+            The deserialized state as a flat mapping.
+
+        """
+        # Normalize the incoming JSON payload into a dict. Any failure to decode
+        # (or an unexpected non-mapping structure) results in an empty mapping
+        # so that the returned type adheres to :class:`BidiComponentState`.
+
+        deserialized_value: dict[str, Any]
+
+        if isinstance(ui_value, dict):
+            deserialized_value = ui_value
+        elif isinstance(ui_value, str):
+            try:
+                parsed = json.loads(ui_value)
+                deserialized_value = parsed if isinstance(parsed, dict) else {}
+            except (json.JSONDecodeError, TypeError) as e:
+                _LOGGER.warning(
+                    "Failed to deserialize component state from frontend: %s",
+                    e,
+                    exc_info=e,
+                )
+                deserialized_value = {}
+        else:
+            deserialized_value = {}
+
+        # Apply default values for keys that don't exist in the current state
+        if self.default is not None:
+            for default_key, default_value in self.default.items():
+                if default_key not in deserialized_value:
+                    deserialized_value[default_key] = default_value
+
+        state: BidiComponentState = cast(
+            "BidiComponentState", AttributeDictionary(deserialized_value)
+        )
+        return state
+
+    def serialize(self, value: Any) -> str:
+        """Serialize the component's state into a JSON string for the frontend.
+
+        Parameters
+        ----------
+        value
+            The component state to serialize.
+
+        Returns
+        -------
+        str
+            A JSON string representation of the value.
+
+        """
+        return json.dumps(value)

streamlit/components/v2/bidi_component/state.py

@@ -0,0 +1,92 @@
+# 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 Any, TypedDict
+
+from streamlit.util import AttributeDictionary
+
+
+class BidiComponentState(TypedDict, total=False):
+    """
+    The schema for the state of a bidirectional component.
+
+    The state is a flat dictionary-like object (key -> value) that supports
+    both key and attribute notation via :class:`AttributeDictionary`.
+    """
+
+    # Flat mapping of state key -> value
+    # (kept empty to reflect open set of keys)
+
+
+class BidiComponentResult(AttributeDictionary):
+    """The schema for the custom component result object.
+
+    The custom component result object is a dictionary-like object that
+    supports both key and attribute notation. It contains all of the
+    component's state and trigger values.
+
+    Attributes
+    ----------
+    <state_keys> : Any
+        All state values from the component. State values are persistent across
+        app reruns until explicitly changed. You can have multiple state keys
+        as attributes.
+    <trigger_keys> : Any
+        All trigger values from the component. Trigger values are transient and
+        reset to ``None`` after one script run. You can have multiple trigger
+        keys as attributes.
+
+    """
+
+    def __init__(
+        self,
+        state_vals: dict[str, Any] | None = None,
+        trigger_vals: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize a BidiComponentResult.
+
+        Parameters
+        ----------
+        state_vals : dict[str, Any] or None
+            A dictionary of state values from the component.
+        trigger_vals : dict[str, Any] or None
+            A dictionary of trigger values from the component.
+        """
+        if state_vals is None:
+            state_vals = {}
+        if trigger_vals is None:
+            trigger_vals = {}
+
+        super().__init__(
+            {
+                # The order here matters, because all stateful values will
+                # always be returned, but trigger values may be transient. This
+                # mirrors presentation behavior in
+                # `make_bidi_component_presenter`.
+                **trigger_vals,
+                **state_vals,
+            }
+        )
+
+
+def unwrap_component_state(raw_state: Any) -> dict[str, Any]:
+    """Return flat mapping when given a dict; otherwise, empty dict.
+
+    The new canonical state is flat, so this is effectively an identity for
+    dict inputs and a guard for other types.
+    """
+
+    return dict(raw_state) if isinstance(raw_state, dict) else {}

streamlit/components/v2/component_definition_resolver.py

@@ -0,0 +1,143 @@
+# 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.
+
+"""Shared resolver for building component definitions with path validation.
+
+This module centralizes the logic for interpreting js/css inputs as inline
+content vs path/glob strings, validating them against a component's asset
+directory, and producing a BidiComponentDefinition with correct asset-relative
+URLs used by the server.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from streamlit.components.v2.component_path_utils import ComponentPathUtils
+from streamlit.components.v2.component_registry import BidiComponentDefinition
+from streamlit.errors import StreamlitAPIException
+
+if TYPE_CHECKING:
+    from streamlit.components.v2.component_manager import BidiComponentManager
+
+
+def build_definition_with_validation(
+    *,
+    manager: BidiComponentManager,
+    component_key: str,
+    html: str | None,
+    css: str | None,
+    js: str | None,
+) -> BidiComponentDefinition:
+    """Construct a definition and validate ``js``/``css`` inputs against ``asset_dir``.
+
+    Parameters
+    ----------
+    manager : BidiComponentManager
+        Component manager used to resolve the component's ``asset_dir`` and
+        related metadata.
+    component_key : str
+        Fully-qualified name of the component to build a definition for.
+    html : str | None
+        Inline HTML content to include in the definition. If ``None``, the
+        component will not include HTML content.
+    css : str | None
+        Either inline CSS content or a path/glob to a CSS file inside the
+        component's ``asset_dir``. Inline strings are kept as-is; file-backed
+        inputs are validated and converted to an ``asset_dir``-relative URL.
+    js : str | None
+        Either inline JavaScript content or a path/glob to a JS file inside the
+        component's ``asset_dir``. Inline strings are kept as-is; file-backed
+        inputs are validated and converted to an ``asset_dir``-relative URL.
+
+    Returns
+    -------
+    BidiComponentDefinition
+        A component definition with inline content preserved and file-backed
+        entries resolved to absolute filesystem paths plus their
+        ``asset_dir``-relative URLs.
+
+    Raises
+    ------
+    StreamlitAPIException
+        If a path/glob is provided but the component has no declared
+        ``asset_dir``, if a glob resolves to zero or multiple files, or if any
+        resolved path escapes the declared ``asset_dir``.
+
+    Notes
+    -----
+    - Inline strings are treated as content (no manifest required).
+    - Path-like strings require the component to be declared in the package
+      manifest with an ``asset_dir``.
+    - Globs are supported only within ``asset_dir`` and must resolve to exactly
+      one file.
+    - Relative paths are resolved strictly against the component's ``asset_dir``
+      and must remain within it after resolution. Absolute paths are not
+      allowed.
+    - For file-backed entries, the URL sent to the frontend is the
+      ``asset_dir``-relative path, served under
+      ``/_stcore/bidi-components/<component>/<relative_path>``.
+    """
+
+    asset_root = manager.get_component_asset_root(component_key)
+
+    def _resolve_entry(
+        value: str | None, *, kind: str
+    ) -> tuple[str | None, str | None]:
+        # Inline content: None rel URL
+        if value is None:
+            return None, None
+        if ComponentPathUtils.looks_like_inline_content(value):
+            return value, None
+
+        # For path-like strings, asset_root must exist
+        if asset_root is None:
+            raise StreamlitAPIException(
+                f"Component '{component_key}' must be declared in pyproject.toml with asset_dir "
+                f"to use file-backed {kind}."
+            )
+
+        value_str = value
+
+        # If looks like a glob, resolve strictly inside asset_root
+        if ComponentPathUtils.has_glob_characters(value_str):
+            resolved = ComponentPathUtils.resolve_glob_pattern(value_str, asset_root)
+            ComponentPathUtils.ensure_within_root(resolved, asset_root, kind=kind)
+            # Use resolved absolute paths to avoid macOS /private prefix mismatch
+            rel_url = str(
+                resolved.resolve().relative_to(asset_root.resolve()).as_posix()
+            )
+            return str(resolved), rel_url
+
+        # Concrete path: must be asset-dir-relative (reject absolute & traversal)
+        ComponentPathUtils.validate_path_security(value_str)
+        candidate = asset_root / Path(value_str)
+        ComponentPathUtils.ensure_within_root(candidate, asset_root, kind=kind)
+        resolved_candidate = candidate.resolve()
+        rel_url = str(resolved_candidate.relative_to(asset_root.resolve()).as_posix())
+        return str(resolved_candidate), rel_url
+
+    css_value, css_rel = _resolve_entry(css, kind="css")
+    js_value, js_rel = _resolve_entry(js, kind="js")
+
+    # Build definition with possible asset_dir-relative paths
+    return BidiComponentDefinition(
+        name=component_key,
+        html=html,
+        css=css_value,
+        js=js_value,
+        css_asset_relative_path=css_rel,
+        js_asset_relative_path=js_rel,
+    )