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

streamlit/elements/lib/pandas_styler_utils.py

@@ -47,7 +47,7 @@ def marshall_styler(proto: ArrowProto, styler: Styler, default_uuid: str) -> Non
     """
     import pandas as pd
 
-    styler_data_df: pd.DataFrame = styler.data
+    styler_data_df: pd.DataFrame = styler.data  # type: ignore[attr-defined]
     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 "
@@ -62,9 +62,9 @@ def marshall_styler(proto: ArrowProto, styler: Styler, default_uuid: str) -> Non
 
     # We're using protected members of pandas.Styler to get styles,
     # which is not ideal and could break if the interface changes.
-    styler._compute()
+    styler._compute()  # type: ignore
 
-    pandas_styles = styler._translate(False, False)
+    pandas_styles = styler._translate(False, False)  # type: ignore
 
     _marshall_caption(proto, styler)
     _marshall_styles(proto, styler, pandas_styles)
@@ -86,10 +86,10 @@ def _marshall_uuid(proto: ArrowProto, styler: Styler, default_uuid: str) -> None
         If pandas.Styler uuid is not provided, this value will be used.
 
     """
-    if styler.uuid is None:
+    if styler.uuid is None:  # type: ignore[attr-defined]
         styler.set_uuid(default_uuid)
 
-    proto.styler.uuid = str(styler.uuid)
+    proto.styler.uuid = str(styler.uuid)  # type: ignore[attr-defined]
 
 
 def _marshall_caption(proto: ArrowProto, styler: Styler) -> None:
@@ -104,8 +104,8 @@ def _marshall_caption(proto: ArrowProto, styler: Styler) -> None:
         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
+    if styler.caption is not None:  # type: ignore[attr-defined]
+        proto.styler.caption = styler.caption  # type: ignore[attr-defined]
 
 
 def _marshall_styles(
@@ -134,7 +134,10 @@ def _marshall_styles(
             # styles in "table_styles" have a space
             # between the uuid and selector.
             rule = _pandas_style_to_css(
-                "table_styles", style, styler.uuid, separator=" "
+                "table_styles",
+                style,
+                styler.uuid,  # type: ignore[attr-defined]
+                separator=" ",
             )
             css_rules.append(rule)
 
@@ -142,7 +145,12 @@ def _marshall_styles(
         cellstyle = styles["cellstyle"]
         cellstyle = _trim_pandas_styles(cellstyle)
         for style in cellstyle:
-            rule = _pandas_style_to_css("cell_style", style, styler.uuid, separator="_")
+            rule = _pandas_style_to_css(
+                "cell_style",
+                style,
+                styler.uuid,  # type: ignore[attr-defined]
+                separator="_",
+            )
             css_rules.append(rule)
 
     if len(css_rules) > 0:

streamlit/elements/lib/shortcut_utils.py

@@ -0,0 +1,152 @@
+# 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 (
+    Final,
+)
+
+from streamlit.errors import (
+    StreamlitAPIException,
+)
+
+_MODIFIER_ALIASES: Final[dict[str, str]] = {
+    "ctrl": "ctrl",
+    "control": "ctrl",
+    "cmd": "cmd",
+    "command": "cmd",
+    "meta": "cmd",
+    "alt": "alt",
+    "option": "alt",
+    "shift": "shift",
+    "mod": "ctrl",
+}
+
+_MODIFIER_ORDER: Final[tuple[str, ...]] = ("ctrl", "cmd", "alt", "shift")
+
+_KEY_ALIASES: Final[dict[str, str]] = {
+    "enter": "enter",
+    "return": "enter",
+    "space": "space",
+    "spacebar": "space",
+    "tab": "tab",
+    "escape": "escape",
+    "esc": "escape",
+    "backspace": "backspace",
+    "delete": "delete",
+    "del": "delete",
+    "home": "home",
+    "end": "end",
+    "pageup": "pageup",
+    "pagedown": "pagedown",
+    "left": "left",
+    "arrowleft": "left",
+    "right": "right",
+    "arrowright": "right",
+    "up": "up",
+    "arrowup": "up",
+    "down": "down",
+    "arrowdown": "down",
+}
+
+_RESERVED_KEYS: Final[set[str]] = {"c", "r"}
+
+
+def _normalize_key_token(lower_token: str) -> str:
+    """Normalize a key token to a format that can be used on the client side."""
+
+    if lower_token in _KEY_ALIASES:
+        return _KEY_ALIASES[lower_token]
+
+    if len(lower_token) == 1 and lower_token.isalnum():
+        return lower_token
+
+    if lower_token.startswith("f") and lower_token[1:].isdigit():
+        return lower_token
+
+    raise StreamlitAPIException(
+        "shortcut must include a single character or one of the supported keys "
+        "(e.g. Enter, Space, Tab, Escape)."
+    )
+
+
+def normalize_shortcut(shortcut: str) -> str:
+    """Normalize a shortcut string to a format that can be used on the client side.
+
+    Parameters
+    ----------
+    shortcut : str
+        The shortcut string to normalize.
+
+    Returns
+    -------
+    str
+        The normalized shortcut string.
+
+    Raises
+    ------
+    StreamlitAPIException
+        If the shortcut is not a string value.
+        If the shortcut does not contain at least one key or modifier.
+        If the shortcut contains a single non-modifier key.
+        If the shortcut uses the keys 'C' or 'R', with or without modifiers.
+        If the shortcut does not include a non-modifier key.
+    """
+    if not isinstance(shortcut, str):
+        raise StreamlitAPIException("shortcut must be a string value.")
+
+    tokens = [token.strip() for token in shortcut.split("+") if token.strip()]
+    if not tokens:
+        raise StreamlitAPIException(
+            "The `shortcut` must contain at least one key or modifier."
+        )
+
+    modifiers: list[str] = []
+    key: str | None = None
+
+    for raw_token in tokens:
+        lower_token = raw_token.lower()
+        if lower_token in _MODIFIER_ALIASES:
+            normalized_modifier = _MODIFIER_ALIASES[lower_token]
+            if normalized_modifier not in modifiers:
+                modifiers.append(normalized_modifier)
+            continue
+
+        if key is not None:
+            raise StreamlitAPIException(
+                "The `shortcut` may only specify a single non-modifier key."
+            )
+
+        normalized_key = _normalize_key_token(lower_token)
+        if normalized_key in _RESERVED_KEYS:
+            raise StreamlitAPIException(
+                "The `shortcut` cannot use the keys 'C' or 'R', with or without modifiers."
+            )
+
+        key = normalized_key
+
+    if key is None:
+        raise StreamlitAPIException(
+            "The `shortcut` must include a non-modifier key such as 'K' or 'Ctrl+K'."
+        )
+
+    normalized_tokens: list[str] = [
+        modifier for modifier in _MODIFIER_ORDER if modifier in modifiers
+    ]
+    if key is not None:
+        normalized_tokens.append(key)
+
+    return "+".join(normalized_tokens)

streamlit/elements/markdown.py

@@ -18,6 +18,7 @@ from typing import TYPE_CHECKING, Final, Literal, cast
 
 from streamlit.elements.lib.layout_utils import (
     LayoutConfig,
+    TextAlignment,
     Width,
     WidthWithoutContent,
     validate_width,
@@ -44,6 +45,7 @@ class MarkdownMixin:
         *,  # keyword-only arguments:
         help: str | None = None,
         width: Width = "stretch",
+        text_alignment: TextAlignment = "left",
     ) -> DeltaGenerator:
         r"""Display string formatted as Markdown.
 
@@ -129,6 +131,22 @@ class MarkdownMixin:
               the parent container, the width of the element matches the width
               of the parent container.
 
+        text_alignment : "left", "center", "right", or "justify"
+            The horizontal alignment of the text within the element. This can
+            be one of the following:
+
+            - ``"left"`` (default): Text is aligned to the left edge.
+            - ``"center"``: Text is centered.
+            - ``"right"``: Text is aligned to the right edge.
+            - ``"justify"``: Text is justified (stretched to fill the available
+              width with the last line left-aligned).
+
+            .. note::
+                For text alignment to have a visible effect, the element's
+                width must be wider than its content. If you use
+                ``width="content"`` with short text, the alignment may not be
+                noticeable.
+
         Examples
         --------
         >>> import streamlit as st
@@ -161,7 +179,7 @@ class MarkdownMixin:
             markdown_proto.help = help
 
         validate_width(width, allow_content=True)
-        layout_config = LayoutConfig(width=width)
+        layout_config = LayoutConfig(width=width, text_alignment=text_alignment)
 
         return self.dg._enqueue("markdown", markdown_proto, layout_config=layout_config)
 
@@ -173,6 +191,7 @@ class MarkdownMixin:
         *,  # keyword-only arguments:
         help: str | None = None,
         width: Width = "stretch",
+        text_alignment: TextAlignment = "left",
     ) -> DeltaGenerator:
         """Display text in small font.
 
@@ -224,6 +243,22 @@ class MarkdownMixin:
               the parent container, the width of the element matches the width
               of the parent container.
 
+        text_alignment : "left", "center", "right", or "justify"
+            The horizontal alignment of the text within the element. This can
+            be one of the following:
+
+            - ``"left"`` (default): Text is aligned to the left edge.
+            - ``"center"``: Text is centered.
+            - ``"right"``: Text is aligned to the right edge.
+            - ``"justify"``: Text is justified (stretched to fill the available
+              width with the last line left-aligned).
+
+            .. note::
+                For text alignment to have a visible effect, the element's
+                width must be wider than its content. If you use
+                ``width="content"`` with short text, the alignment may not be
+                noticeable.
+
         Examples
         --------
         >>> import streamlit as st
@@ -241,7 +276,7 @@ class MarkdownMixin:
             caption_proto.help = help
 
         validate_width(width, allow_content=True)
-        layout_config = LayoutConfig(width=width)
+        layout_config = LayoutConfig(width=width, text_alignment=text_alignment)
 
         return self.dg._enqueue("markdown", caption_proto, layout_config=layout_config)
 
@@ -370,6 +405,7 @@ class MarkdownMixin:
             "primary",
         ] = "blue",
         width: Width = "content",
+        help: str | None = None,
     ) -> DeltaGenerator:
         """Display a colored badge with an icon and label.
 
@@ -437,6 +473,14 @@ class MarkdownMixin:
               the parent container, the width of the element matches the width
               of the parent container.
 
+        help : str or None
+            A tooltip to display when hovering over the badge. If this is
+            ``None`` (default), no tooltip is displayed.
+
+            The tooltip can optionally contain GitHub-flavored Markdown,
+            including the Markdown directives described in the ``body``
+            parameter of ``st.markdown``.
+
         Examples
         --------
         Create standalone badges with ``st.badge`` (with or without icons). If
@@ -452,7 +496,7 @@ class MarkdownMixin:
         >>>     ":violet-badge[:material/star: Favorite] :orange-badge[⚠️ Needs review] :gray-badge[Deprecated]"
         >>> )
 
-        .. output ::
+        .. output::
             https://doc-badge.streamlit.app/
             height: 220px
 
@@ -466,6 +510,9 @@ class MarkdownMixin:
         badge_proto.body = f":{color}-badge[{icon_str}{escaped_label}]"
         badge_proto.element_type = MarkdownProto.Type.NATIVE
 
+        if help is not None:
+            badge_proto.help = help
+
         validate_width(width, allow_content=True)
         layout_config = LayoutConfig(width=width)
 

streamlit/elements/metric.py

@@ -31,7 +31,7 @@ from streamlit.elements.lib.utils import (
     LabelVisibility,
     get_label_visibility_proto_value,
 )
-from streamlit.errors import StreamlitAPIException
+from streamlit.errors import StreamlitAPIException, StreamlitValueError
 from streamlit.proto.Metric_pb2 import Metric as MetricProto
 from streamlit.runtime.metrics_util import gather_metrics
 from streamlit.string_util import AnyNumber, clean_text, from_number
@@ -43,6 +43,7 @@ if TYPE_CHECKING:
 Value: TypeAlias = AnyNumber | str | None
 Delta: TypeAlias = AnyNumber | str | None
 DeltaColor: TypeAlias = Literal["normal", "inverse", "off"]
+DeltaArrow: TypeAlias = Literal["auto", "up", "down", "off"]
 
 
 @dataclass(frozen=True)
@@ -67,6 +68,7 @@ class MetricMixin:
         height: Height = "content",
         chart_data: OptionSequence[Any] | None = None,
         chart_type: Literal["line", "bar", "area"] = "line",
+        delta_arrow: DeltaArrow = "auto",
     ) -> DeltaGenerator:
         r"""Display a metric in big bold font, with an optional indicator of how the metric changed.
 
@@ -172,6 +174,17 @@ class MetricMixin:
             - ``"area"``: A sparkline with area shading.
             - ``"bar"``: A bar chart.
 
+        delta_arrow : "auto", "up", "down", or "off"
+            Controls the direction of the delta indicator arrow. This can be
+            one of the following strings:
+
+            - ``"auto"`` (default): The arrow direction follows the sign of
+              ``delta``.
+            - ``"up"`` or ``"down"``: The arrow is forced to point in the
+              specified direction.
+            - ``"off"``: No arrow is shown, but the delta value remains
+              visible.
+
         Examples
         --------
         **Example 1: Show a metric**
@@ -280,6 +293,17 @@ class MetricMixin:
         )
         metric_proto.color = color_and_direction.color
         metric_proto.direction = color_and_direction.direction
+        parsed_delta_arrow = _parse_delta_arrow(
+            cast("DeltaArrow", clean_text(delta_arrow))
+        )
+
+        if parsed_delta_arrow != "auto":
+            if parsed_delta_arrow == "off":
+                metric_proto.direction = MetricProto.MetricDirection.NONE
+            elif parsed_delta_arrow == "up":
+                metric_proto.direction = MetricProto.MetricDirection.UP
+            elif parsed_delta_arrow == "down":
+                metric_proto.direction = MetricProto.MetricDirection.DOWN
         metric_proto.label_visibility.value = get_label_visibility_proto_value(
             label_visibility
         )
@@ -322,6 +346,12 @@ def _parse_chart_type(
     return MetricProto.ChartType.LINE
 
 
+def _parse_delta_arrow(delta_arrow: DeltaArrow) -> DeltaArrow:
+    if delta_arrow not in {"auto", "up", "down", "off"}:
+        raise StreamlitValueError("delta_arrow", ["auto", "up", "down", "off"])
+    return delta_arrow
+
+
 def _parse_label(label: str) -> str:
     if not isinstance(label, str):
         raise TypeError(

streamlit/elements/plotly_chart.py

@@ -37,8 +37,10 @@ from streamlit.deprecation_util import (
 )
 from streamlit.elements.lib.form_utils import current_form_id
 from streamlit.elements.lib.layout_utils import (
+    Height,
     LayoutConfig,
     Width,
+    validate_height,
     validate_width,
 )
 from streamlit.elements.lib.policies import check_widget_policies
@@ -324,6 +326,53 @@ def _resolve_content_width(width: Width, figure: Any) -> Width:
     return 700
 
 
+def _resolve_content_height(height: Height, figure: Any) -> Height:
+    """Resolve "content" height by inspecting the figure's layout height.
+
+    For content height, we check if the plotly figure has an explicit height
+    in its layout. If so, we use that as a pixel height. If not, we default
+    to 450 pixels which matches the plotly.js default height.
+
+    Args
+    ----
+    height : Height
+        The original height parameter
+    figure : Any
+        The plotly figure object (Figure, dict, or other supported formats)
+
+    Returns
+    -------
+    Height
+        The resolved height (either original height, figure height as pixels, or 450)
+    """
+
+    if height != "content":
+        return height
+
+    # Extract height from the figure's layout
+    # plotly.tools.mpl_to_plotly() returns Figure objects with .layout attribute
+    # plotly.tools.return_figure_from_figure_or_data() returns dictionaries
+    figure_height = None
+    if isinstance(figure, dict):
+        figure_height = figure.get("layout", {}).get("height")
+    else:
+        # Handle Figure objects from matplotlib conversion
+        try:
+            figure_height = figure.layout.height
+        except (AttributeError, TypeError):
+            _LOGGER.debug("Could not parse height from figure")
+
+    if (
+        figure_height is not None
+        and isinstance(figure_height, (int, float))
+        and figure_height > 0
+    ):
+        return int(figure_height)
+
+    # Default to 450 pixels (plotly.js default) when no height is specified
+    return 450
+
+
 class PlotlyMixin:
     @overload
     def plotly_chart(
@@ -332,6 +381,7 @@ class PlotlyMixin:
         use_container_width: bool | None = None,
         *,
         width: Width = "stretch",
+        height: Height = "content",
         theme: Literal["streamlit"] | None = "streamlit",
         key: Key | None = None,
         on_select: Literal["ignore"],  # No default value here to make it work with mypy
@@ -350,6 +400,7 @@ class PlotlyMixin:
         use_container_width: bool | None = None,
         *,
         width: Width = "stretch",
+        height: Height = "content",
         theme: Literal["streamlit"] | None = "streamlit",
         key: Key | None = None,
         on_select: Literal["rerun"] | WidgetCallback = "rerun",
@@ -368,6 +419,7 @@ class PlotlyMixin:
         use_container_width: bool | None = None,
         *,
         width: Width = "stretch",
+        height: Height = "content",
         theme: Literal["streamlit"] | None = "streamlit",
         key: Key | None = None,
         on_select: Literal["rerun", "ignore"] | WidgetCallback = "ignore",
@@ -429,6 +481,19 @@ class PlotlyMixin:
               the parent container, the width of the element matches the width
               of the parent container.
 
+        height : "content", "stretch", or int
+            The height of the chart element. This can be one of the following:
+
+            - ``"content"`` (default): The height of the element matches the
+              height of its content.
+            - ``"stretch"``: The height of the element matches the height of
+              its content or the height of the parent container, whichever is
+              larger. If the element is not in a parent container, the height
+              of the element matches the height of its content.
+            - An integer specifying the height in pixels: The element has a
+              fixed height. If the content is larger than the specified
+              height, scrolling is enabled.
+
         use_container_width : bool or None
             Whether to override the figure's native width with the width of
             the parent container. This can be one of the following:
@@ -595,6 +660,7 @@ class PlotlyMixin:
                 width = "content"
 
         validate_width(width, allow_content=True)
+        validate_height(height, allow_content=True)
 
         import plotly.io
         import plotly.tools
@@ -605,9 +671,10 @@ class PlotlyMixin:
 
         if kwargs:
             show_deprecation_warning(
-                "The keyword arguments have been deprecated and will be removed "
-                "in a future release. Use `config` instead to specify Plotly "
-                "configuration options."
+                "Variable keyword arguments for `st.plotly_chart` have been "
+                "deprecated and will be removed in a future release. Use the "
+                "`config` argument instead to specify Plotly configuration "
+                "options."
             )
 
         if theme not in ["streamlit", None]:
@@ -671,10 +738,12 @@ class PlotlyMixin:
             is_selection_activated=is_selection_activated,
             theme=theme,
             width=width,
+            height=height,
         )
 
-        # Handle "content" width by inspecting the figure's natural width
+        # Handle "content" width and height by inspecting the figure's natural dimensions
         final_width = _resolve_content_width(width, figure)
+        final_height = _resolve_content_height(height, figure)
 
         if is_selection_activated:
             # Selections are activated, treat plotly chart as a widget:
@@ -693,13 +762,13 @@ class PlotlyMixin:
                 value_type="string_value",
             )
 
-            layout_config = LayoutConfig(width=final_width)
+            layout_config = LayoutConfig(width=final_width, height=final_height)
             self.dg._enqueue(
                 "plotly_chart", plotly_chart_proto, layout_config=layout_config
             )
             return widget_state.value
 
-        layout_config = LayoutConfig(width=final_width)
+        layout_config = LayoutConfig(width=final_width, height=final_height)
         return self.dg._enqueue(
             "plotly_chart", plotly_chart_proto, layout_config=layout_config
         )

streamlit/elements/spinner.py

@@ -88,7 +88,7 @@ def spinner(
     >>> st.success("Done!")
     >>> st.button("Rerun")
 
-    .. output ::
+    .. output::
         https://doc-spinner.streamlit.app/
         height: 210px
 

streamlit/elements/text.py

@@ -23,7 +23,7 @@ from streamlit.string_util import clean_text
 
 if TYPE_CHECKING:
     from streamlit.delta_generator import DeltaGenerator
-    from streamlit.elements.lib.layout_utils import Width
+    from streamlit.elements.lib.layout_utils import TextAlignment, Width
     from streamlit.type_util import SupportsStr
 
 
@@ -35,6 +35,7 @@ class TextMixin:
         *,  # keyword-only arguments:
         help: str | None = None,
         width: Width = "content",
+        text_alignment: TextAlignment = "left",
     ) -> DeltaGenerator:
         r"""Write text without Markdown or HTML parsing.
 
@@ -69,13 +70,29 @@ class TextMixin:
               the parent container, the width of the element matches the width
               of the parent container.
 
+        text_alignment : "left", "center", "right", or "justify"
+            The horizontal alignment of the text within the element. This can
+            be one of the following:
+
+            - ``"left"`` (default): Text is aligned to the left edge.
+            - ``"center"``: Text is centered.
+            - ``"right"``: Text is aligned to the right edge.
+            - ``"justify"``: Text is justified (stretched to fill the available
+              width with the last line left-aligned).
+
+            .. note::
+                For text alignment to have a visible effect, the element's
+                width must be wider than its content. If you use
+                ``width="content"`` with short text, the alignment may not be
+                noticeable.
+
         Example
         -------
         >>> import streamlit as st
         >>>
         >>> st.text("This is text\n[and more text](that's not a Markdown link).")
 
-        .. output ::
+        .. output::
             https://doc-text.streamlit.app/
             height: 220px
 
@@ -86,7 +103,7 @@ class TextMixin:
             text_proto.help = help
 
         validate_width(width, allow_content=True)
-        layout_config = LayoutConfig(width=width)
+        layout_config = LayoutConfig(width=width, text_alignment=text_alignment)
 
         return self.dg._enqueue("text", text_proto, layout_config=layout_config)
 

streamlit/elements/toast.py

@@ -80,6 +80,8 @@ class ToastMixin:
               <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
               font library.
 
+            - ``"spinner"``: Displays a spinner as an icon.
+
         duration : "short", "long", "infinite", or int
             The time to display the toast message. This can be one of the
             following: