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

streamlit/elements/lib/mutable_status_container.py

@@ -0,0 +1,183 @@
+# 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 time
+from typing import TYPE_CHECKING, Literal, cast
+
+from typing_extensions import Self, TypeAlias
+
+from streamlit.delta_generator import DeltaGenerator
+from streamlit.errors import StreamlitAPIException
+from streamlit.proto.Block_pb2 import Block as BlockProto
+from streamlit.proto.ForwardMsg_pb2 import ForwardMsg
+from streamlit.runtime.scriptrunner_utils.script_run_context import enqueue_message
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from streamlit.cursor import Cursor
+
+States: TypeAlias = Literal["running", "complete", "error"]
+
+
+class StatusContainer(DeltaGenerator):
+    @staticmethod
+    def _create(
+        parent: DeltaGenerator,
+        label: str,
+        expanded: bool = False,
+        state: States = "running",
+    ) -> StatusContainer:
+        expandable_proto = BlockProto.Expandable()
+        expandable_proto.expanded = expanded
+        expandable_proto.label = label or ""
+
+        if state == "running":
+            expandable_proto.icon = "spinner"
+        elif state == "complete":
+            expandable_proto.icon = ":material/check:"
+        elif state == "error":
+            expandable_proto.icon = ":material/error:"
+        else:
+            raise StreamlitAPIException(
+                f"Unknown state ({state}). Must be one of 'running', 'complete', or 'error'."
+            )
+
+        block_proto = BlockProto()
+        block_proto.allow_empty = True
+        block_proto.expandable.CopyFrom(expandable_proto)
+
+        delta_path: list[int] = (
+            parent._active_dg._cursor.delta_path if parent._active_dg._cursor else []
+        )
+
+        status_container = cast(
+            StatusContainer,
+            parent._block(block_proto=block_proto, dg_type=StatusContainer),
+        )
+
+        # Apply initial configuration
+        status_container._delta_path = delta_path
+        status_container._current_proto = block_proto
+        status_container._current_state = state
+
+        # We need to sleep here for a very short time to prevent issues when
+        # the status is updated too quickly. If an .update() directly follows the
+        # the initialization, sometimes only the latest update is applied.
+        # Adding a short timeout here allows the frontend to render the update before.
+        time.sleep(0.05)
+
+        return status_container
+
+    def __init__(
+        self,
+        root_container: int | None,
+        cursor: Cursor | None,
+        parent: DeltaGenerator | None,
+        block_type: str | None,
+    ):
+        super().__init__(root_container, cursor, parent, block_type)
+
+        # Initialized in `_create()`:
+        self._current_proto: BlockProto | None = None
+        self._current_state: States | None = None
+        self._delta_path: list[int] | None = None
+
+    def update(
+        self,
+        *,
+        label: str | None = None,
+        expanded: bool | None = None,
+        state: States | None = None,
+    ) -> None:
+        """Update the status container.
+
+        Only specified arguments are updated. Container contents and unspecified
+        arguments remain unchanged.
+
+        Parameters
+        ----------
+        label : str or None
+            A new label of the status container. If None, the label is not
+            changed.
+
+        expanded : bool or None
+            The new expanded state of the status container. If None,
+            the expanded state is not changed.
+
+        state : "running", "complete", "error", or None
+            The new state of the status container. This mainly changes the
+            icon. If None, the state is not changed.
+        """
+        assert self._current_proto is not None, "Status not correctly initialized!"
+        assert self._delta_path is not None, "Status not correctly initialized!"
+
+        msg = ForwardMsg()
+        msg.metadata.delta_path[:] = self._delta_path
+        msg.delta.add_block.CopyFrom(self._current_proto)
+
+        if expanded is not None:
+            msg.delta.add_block.expandable.expanded = expanded
+        else:
+            msg.delta.add_block.expandable.ClearField("expanded")
+
+        if label is not None:
+            msg.delta.add_block.expandable.label = label
+
+        if state is not None:
+            if state == "running":
+                msg.delta.add_block.expandable.icon = "spinner"
+            elif state == "complete":
+                msg.delta.add_block.expandable.icon = ":material/check:"
+            elif state == "error":
+                msg.delta.add_block.expandable.icon = ":material/error:"
+            else:
+                raise StreamlitAPIException(
+                    f"Unknown state ({state}). Must be one of 'running', 'complete', or 'error'."
+                )
+            self._current_state = state
+
+        self._current_proto = msg.delta.add_block
+        enqueue_message(msg)
+
+    def __enter__(self) -> Self:  # type: ignore[override]
+        # This is a little dubious: we're returning a different type than
+        # our superclass' `__enter__` function. Maybe DeltaGenerator.__enter__
+        # should always return `self`?
+        super().__enter__()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> Literal[False]:
+        # Only update if the current state is running
+        if self._current_state == "running":
+            # We need to sleep here for a very short time to prevent issues when
+            # the status is updated too quickly. If an .update() is directly followed
+            # by the exit of the context manager, sometimes only the last update
+            # (to complete) is applied. Adding a short timeout here allows the frontend
+            # to render the update before.
+            time.sleep(0.05)
+            if exc_type is not None:
+                # If an exception was raised in the context,
+                # we want to update the status to error.
+                self.update(state="error")
+            else:
+                self.update(state="complete")
+        return super().__exit__(exc_type, exc_val, exc_tb)

streamlit/elements/lib/options_selector_utils.py

@@ -0,0 +1,250 @@
+# 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 enum import Enum, EnumMeta
+from typing import TYPE_CHECKING, Any, Final, TypeVar, overload
+
+from streamlit import config, logger
+from streamlit.dataframe_util import OptionSequence, convert_anything_to_list
+from streamlit.errors import StreamlitAPIException
+from streamlit.runtime.state.common import RegisterWidgetResult
+from streamlit.type_util import (
+    T,
+    check_python_comparable,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+_LOGGER: Final = logger.get_logger(__name__)
+
+_FLOAT_EQUALITY_EPSILON: Final[float] = 0.000000000005
+_Value = TypeVar("_Value")
+
+
+def index_(iterable: Iterable[_Value], x: _Value) -> int:
+    """Return zero-based index of the first item whose value is equal to x.
+    Raises a ValueError if there is no such item.
+
+    We need a custom implementation instead of the built-in list .index() to
+    be compatible with NumPy array and Pandas Series.
+
+    Parameters
+    ----------
+    iterable : list, tuple, numpy.ndarray, pandas.Series
+    x : Any
+
+    Returns
+    -------
+    int
+    """
+    for i, value in enumerate(iterable):
+        if x == value:
+            return i
+        elif isinstance(value, float) and isinstance(x, float):
+            if abs(x - value) < _FLOAT_EQUALITY_EPSILON:
+                return i
+    raise ValueError(f"{str(x)} is not in iterable")
+
+
+def check_and_convert_to_indices(
+    opt: Sequence[Any], default_values: Sequence[Any] | Any | None
+) -> list[int] | None:
+    """Perform validation checks and return indices based on the default values."""
+    if default_values is None:
+        return None
+
+    default_values = convert_anything_to_list(default_values)
+
+    for value in default_values:
+        if value not in opt:
+            raise StreamlitAPIException(
+                f"The default value '{value}' is not part of the options. "
+                "Please make sure that every default values also exists in the options."
+            )
+
+    return [opt.index(value) for value in default_values]
+
+
+def convert_to_sequence_and_check_comparable(options: OptionSequence[T]) -> Sequence[T]:
+    indexable_options = convert_anything_to_list(options)
+    check_python_comparable(indexable_options)
+    return indexable_options
+
+
+def get_default_indices(
+    indexable_options: Sequence[T], default: Sequence[Any] | Any | None = None
+) -> list[int]:
+    default_indices = check_and_convert_to_indices(indexable_options, default)
+    default_indices = default_indices if default_indices is not None else []
+    return default_indices
+
+
+E1 = TypeVar("E1", bound=Enum)
+E2 = TypeVar("E2", bound=Enum)
+
+_ALLOWED_ENUM_COERCION_CONFIG_SETTINGS = ("off", "nameOnly", "nameAndValue")
+
+
+def _coerce_enum(from_enum_value: E1, to_enum_class: type[E2]) -> E1 | E2:
+    """Attempt to coerce an Enum value to another EnumMeta.
+
+    An Enum value of EnumMeta E1 is considered coercable to EnumType E2
+    if the EnumMeta __qualname__ match and the names of their members
+    match as well. (This is configurable in streamlist configs)
+    """
+    if not isinstance(from_enum_value, Enum):
+        raise ValueError(
+            f"Expected an Enum in the first argument. Got {type(from_enum_value)}"
+        )
+    if not isinstance(to_enum_class, EnumMeta):
+        raise ValueError(
+            f"Expected an EnumMeta/Type in the second argument. Got {type(to_enum_class)}"
+        )
+    if isinstance(from_enum_value, to_enum_class):
+        return from_enum_value  # Enum is already a member, no coersion necessary
+
+    coercion_type = config.get_option("runner.enumCoercion")
+    if coercion_type not in _ALLOWED_ENUM_COERCION_CONFIG_SETTINGS:
+        raise StreamlitAPIException(
+            "Invalid value for config option runner.enumCoercion. "
+            f"Expected one of {_ALLOWED_ENUM_COERCION_CONFIG_SETTINGS}, "
+            f"but got '{coercion_type}'."
+        )
+    if coercion_type == "off":
+        return from_enum_value  # do not attempt to coerce
+
+    # We now know this is an Enum AND the user has configured coercion enabled.
+    # Check if we do NOT meet the required conditions and log a failure message
+    # if that is the case.
+    from_enum_class = from_enum_value.__class__
+    if (
+        from_enum_class.__qualname__ != to_enum_class.__qualname__
+        or (
+            coercion_type == "nameOnly"
+            and set(to_enum_class._member_names_) != set(from_enum_class._member_names_)
+        )
+        or (
+            coercion_type == "nameAndValue"
+            and set(to_enum_class._value2member_map_)
+            != set(from_enum_class._value2member_map_)
+        )
+    ):
+        _LOGGER.debug("Failed to coerce %s to class %s", from_enum_value, to_enum_class)
+        return from_enum_value  # do not attempt to coerce
+
+    # At this point we think the Enum is coercable, and we know
+    # E1 and E2 have the same member names. We convert from E1 to E2 using _name_
+    # (since user Enum subclasses can override the .name property in 3.11)
+    _LOGGER.debug("Coerced %s to class %s", from_enum_value, to_enum_class)
+    return to_enum_class[from_enum_value._name_]
+
+
+def _extract_common_class_from_iter(iterable: Iterable[Any]) -> Any:
+    """Return the common class of all elements in a iterable if they share one.
+    Otherwise, return None."""
+    try:
+        inner_iter = iter(iterable)
+        first_class = type(next(inner_iter))
+    except StopIteration:
+        return None
+    if all(type(item) is first_class for item in inner_iter):
+        return first_class
+    return None
+
+
+@overload
+def maybe_coerce_enum(
+    register_widget_result: RegisterWidgetResult[Enum],
+    options: type[Enum],
+    opt_sequence: Sequence[Any],
+) -> RegisterWidgetResult[Enum]: ...
+
+
+@overload
+def maybe_coerce_enum(
+    register_widget_result: RegisterWidgetResult[T],
+    options: OptionSequence[T],
+    opt_sequence: Sequence[T],
+) -> RegisterWidgetResult[T]: ...
+
+
+def maybe_coerce_enum(register_widget_result, options, opt_sequence):
+    """Maybe Coerce a RegisterWidgetResult with an Enum member value to
+    RegisterWidgetResult[option] if option is an EnumType, otherwise just return
+    the original RegisterWidgetResult."""
+
+    # If the value is not a Enum, return early
+    if not isinstance(register_widget_result.value, Enum):
+        return register_widget_result
+
+    coerce_class: EnumMeta | None
+    if isinstance(options, EnumMeta):
+        coerce_class = options
+    else:
+        coerce_class = _extract_common_class_from_iter(opt_sequence)
+        if coerce_class is None:
+            return register_widget_result
+
+    return RegisterWidgetResult(
+        _coerce_enum(register_widget_result.value, coerce_class),
+        register_widget_result.value_changed,
+    )
+
+
+# slightly ugly typing because TypeVars with Generic Bounds are not supported
+# (https://github.com/python/typing/issues/548)
+@overload
+def maybe_coerce_enum_sequence(
+    register_widget_result: RegisterWidgetResult[list[T]],
+    options: OptionSequence[T],
+    opt_sequence: Sequence[T],
+) -> RegisterWidgetResult[list[T]]: ...
+
+
+@overload
+def maybe_coerce_enum_sequence(
+    register_widget_result: RegisterWidgetResult[tuple[T, T]],
+    options: OptionSequence[T],
+    opt_sequence: Sequence[T],
+) -> RegisterWidgetResult[tuple[T, T]]: ...
+
+
+def maybe_coerce_enum_sequence(register_widget_result, options, opt_sequence):
+    """Maybe Coerce a RegisterWidgetResult with a sequence of Enum members as value
+    to RegisterWidgetResult[Sequence[option]] if option is an EnumType, otherwise just return
+    the original RegisterWidgetResult."""
+
+    # If not all widget values are Enums, return early
+    if not all(isinstance(val, Enum) for val in register_widget_result.value):
+        return register_widget_result
+
+    # Extract the class to coerce
+    coerce_class: EnumMeta | None
+    if isinstance(options, EnumMeta):
+        coerce_class = options
+    else:
+        coerce_class = _extract_common_class_from_iter(opt_sequence)
+        if coerce_class is None:
+            return register_widget_result
+
+    # Return a new RegisterWidgetResult with the coerced enum values sequence
+    return RegisterWidgetResult(
+        type(register_widget_result.value)(
+            _coerce_enum(val, coerce_class) for val in register_widget_result.value
+        ),
+        register_widget_result.value_changed,
+    )

streamlit/elements/lib/pandas_styler_utils.py

@@ -0,0 +1,274 @@
+# 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 Mapping
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from streamlit import dataframe_util
+from streamlit.errors import StreamlitAPIException
+
+if TYPE_CHECKING:
+    from pandas import DataFrame
+    from pandas.io.formats.style import Styler
+
+    from streamlit.proto.Arrow_pb2 import Arrow as ArrowProto
+
+
+def marshall_styler(proto: ArrowProto, styler: Styler, default_uuid: str) -> None:
+    """Marshall pandas.Styler into an Arrow proto.
+
+    Parameters
+    ----------
+    proto : proto.Arrow
+        Output. The protobuf for Streamlit Arrow proto.
+
+    styler : pandas.Styler
+        Helps style a DataFrame or Series according to the data with HTML and CSS.
+
+    default_uuid : str
+        If pandas.Styler uuid is not provided, this value will be used.
+
+    """
+    import pandas as pd
+
+    styler_data_df: pd.DataFrame = styler.data
+    if styler_data_df.size > int(pd.options.styler.render.max_elements):
+        raise StreamlitAPIException(
+            f"The dataframe has `{styler_data_df.size}` cells, but the maximum number "
+            "of cells allowed to be rendered by Pandas Styler is configured to "
+            f"`{pd.options.styler.render.max_elements}`. To allow more cells to be "
+            'styled, you can change the `"styler.render.max_elements"` config. For example: '
+            f'`pd.set_option("styler.render.max_elements", {styler_data_df.size})`'
+        )
+
+    # pandas.Styler uuid should be set before _compute is called.
+    _marshall_uuid(proto, styler, default_uuid)
+
+    # We're using protected members of pandas.Styler to get styles,
+    # which is not ideal and could break if the interface changes.
+    styler._compute()
+
+    pandas_styles = styler._translate(False, False)
+
+    _marshall_caption(proto, styler)
+    _marshall_styles(proto, styler, pandas_styles)
+    _marshall_display_values(proto, styler_data_df, pandas_styles)
+
+
+def _marshall_uuid(proto: ArrowProto, styler: Styler, default_uuid: str) -> None:
+    """Marshall pandas.Styler uuid into an Arrow proto.
+
+    Parameters
+    ----------
+    proto : proto.Arrow
+        Output. The protobuf for Streamlit Arrow proto.
+
+    styler : pandas.Styler
+        Helps style a DataFrame or Series according to the data with HTML and CSS.
+
+    default_uuid : str
+        If pandas.Styler uuid is not provided, this value will be used.
+
+    """
+    if styler.uuid is None:
+        styler.set_uuid(default_uuid)
+
+    proto.styler.uuid = str(styler.uuid)
+
+
+def _marshall_caption(proto: ArrowProto, styler: Styler) -> None:
+    """Marshall pandas.Styler caption into an Arrow proto.
+
+    Parameters
+    ----------
+    proto : proto.Arrow
+        Output. The protobuf for Streamlit Arrow proto.
+
+    styler : pandas.Styler
+        Helps style a DataFrame or Series according to the data with HTML and CSS.
+
+    """
+    if styler.caption is not None:
+        proto.styler.caption = styler.caption
+
+
+def _marshall_styles(
+    proto: ArrowProto, styler: Styler, styles: Mapping[str, Any]
+) -> None:
+    """Marshall pandas.Styler styles into an Arrow proto.
+
+    Parameters
+    ----------
+    proto : proto.Arrow
+        Output. The protobuf for Streamlit Arrow proto.
+
+    styler : pandas.Styler
+        Helps style a DataFrame or Series according to the data with HTML and CSS.
+
+    styles : dict
+        pandas.Styler translated styles.
+
+    """
+    css_rules = []
+
+    if "table_styles" in styles:
+        table_styles = styles["table_styles"]
+        table_styles = _trim_pandas_styles(table_styles)
+        for style in table_styles:
+            # styles in "table_styles" have a space
+            # between the uuid and selector.
+            rule = _pandas_style_to_css(
+                "table_styles", style, styler.uuid, separator=" "
+            )
+            css_rules.append(rule)
+
+    if "cellstyle" in styles:
+        cellstyle = styles["cellstyle"]
+        cellstyle = _trim_pandas_styles(cellstyle)
+        for style in cellstyle:
+            rule = _pandas_style_to_css("cell_style", style, styler.uuid, separator="_")
+            css_rules.append(rule)
+
+    if len(css_rules) > 0:
+        proto.styler.styles = "\n".join(css_rules)
+
+
+M = TypeVar("M", bound=Mapping[str, Any])
+
+
+def _trim_pandas_styles(styles: list[M]) -> list[M]:
+    """Filter out empty styles.
+
+    Every cell will have a class, but the list of props
+    may just be [['', '']].
+
+    Parameters
+    ----------
+    styles : list
+        pandas.Styler translated styles.
+
+    """
+    return [x for x in styles if any(any(y) for y in x["props"])]
+
+
+def _pandas_style_to_css(
+    style_type: str,
+    style: Mapping[str, Any],
+    uuid: str,
+    separator: str = "_",
+) -> str:
+    """Convert pandas.Styler translated style to CSS.
+
+    Parameters
+    ----------
+    style_type : str
+        Either "table_styles" or "cell_style".
+
+    style : dict
+        pandas.Styler translated style.
+
+    uuid : str
+        pandas.Styler uuid.
+
+    separator : str
+        A string separator used between table and cell selectors.
+
+    """
+    declarations = []
+    for css_property, css_value in style["props"]:
+        declaration = str(css_property).strip() + ": " + str(css_value).strip()
+        declarations.append(declaration)
+
+    table_selector = f"#T_{uuid}"
+
+    # In pandas >= 1.1.0
+    # translated_style["cellstyle"] has the following shape:
+    # [
+    #   {
+    #       "props": [("color", " black"), ("background-color", "orange"), ("", "")],
+    #       "selectors": ["row0_col0"]
+    #   }
+    #   ...
+    # ]
+    if style_type == "table_styles":
+        cell_selectors = [style["selector"]]
+    else:
+        cell_selectors = style["selectors"]
+
+    selectors = []
+    for cell_selector in cell_selectors:
+        selectors.append(table_selector + separator + cell_selector)
+    selector = ", ".join(selectors)
+
+    declaration_block = "; ".join(declarations)
+    rule_set = selector + " { " + declaration_block + " }"
+
+    return rule_set
+
+
+def _marshall_display_values(
+    proto: ArrowProto, df: DataFrame, styles: Mapping[str, Any]
+) -> None:
+    """Marshall pandas.Styler display values into an Arrow proto.
+
+    Parameters
+    ----------
+    proto : proto.Arrow
+        Output. The protobuf for Streamlit Arrow proto.
+
+    df : pandas.DataFrame
+        A dataframe with original values.
+
+    styles : dict
+        pandas.Styler translated styles.
+
+    """
+    new_df = _use_display_values(df, styles)
+    proto.styler.display_values = dataframe_util.convert_pandas_df_to_arrow_bytes(
+        new_df
+    )
+
+
+def _use_display_values(df: DataFrame, styles: Mapping[str, Any]) -> DataFrame:
+    """Create a new pandas.DataFrame where display values are used instead of original ones.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        A dataframe with original values.
+
+    styles : dict
+        pandas.Styler translated styles.
+
+    """
+    import re
+
+    # If values in a column are not of the same type, Arrow
+    # serialization would fail. Thus, we need to cast all values
+    # of the dataframe to strings before assigning them display values.
+    new_df = df.astype(str)
+
+    cell_selector_regex = re.compile(r"row(\d+)_col(\d+)")
+    if "body" in styles:
+        rows = styles["body"]
+        for row in rows:
+            for cell in row:
+                if "id" in cell:
+                    if match := cell_selector_regex.match(cell["id"]):
+                        r, c = map(int, match.groups())
+                        new_df.iloc[r, c] = str(cell["display_value"])
+
+    return new_df