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

streamlit/elements/heading.py

@@ -25,7 +25,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
 
 
@@ -49,6 +49,7 @@ class HeadingMixin:
         help: str | None = None,
         divider: Divider = False,
         width: Width = "stretch",
+        text_alignment: TextAlignment = "left",
     ) -> DeltaGenerator:
         """Display text in header formatting.
 
@@ -97,6 +98,22 @@ class HeadingMixin:
               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
@@ -115,7 +132,7 @@ class HeadingMixin:
 
         """
         validate_width(width, allow_content=True)
-        layout_config = LayoutConfig(width=width)
+        layout_config = LayoutConfig(width=width, text_alignment=text_alignment)
 
         return self.dg._enqueue(
             "heading",
@@ -138,6 +155,7 @@ class HeadingMixin:
         help: str | None = None,
         divider: Divider = False,
         width: Width = "stretch",
+        text_alignment: TextAlignment = "left",
     ) -> DeltaGenerator:
         """Display text in subheader formatting.
 
@@ -186,6 +204,22 @@ class HeadingMixin:
               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
@@ -204,7 +238,7 @@ class HeadingMixin:
 
         """
         validate_width(width, allow_content=True)
-        layout_config = LayoutConfig(width=width)
+        layout_config = LayoutConfig(width=width, text_alignment=text_alignment)
 
         return self.dg._enqueue(
             "heading",
@@ -226,6 +260,7 @@ class HeadingMixin:
         *,  # keyword-only arguments:
         help: str | None = None,
         width: Width = "stretch",
+        text_alignment: TextAlignment = "left",
     ) -> DeltaGenerator:
         """Display text in title formatting.
 
@@ -269,6 +304,22 @@ class HeadingMixin:
               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
@@ -282,12 +333,15 @@ class HeadingMixin:
 
         """
         validate_width(width, allow_content=True)
-        layout_config = LayoutConfig(width=width)
+        layout_config = LayoutConfig(width=width, text_alignment=text_alignment)
 
         return self.dg._enqueue(
             "heading",
             HeadingMixin._create_heading_proto(
-                tag=HeadingProtoTag.TITLE_TAG, body=body, anchor=anchor, help=help
+                tag=HeadingProtoTag.TITLE_TAG,
+                body=body,
+                anchor=anchor,
+                help=help,
             ),
             layout_config=layout_config,
         )
@@ -349,4 +403,5 @@ class HeadingMixin:
 
         if help:
             proto.help = help
+
         return proto

streamlit/elements/html.py

@@ -42,6 +42,7 @@ class HtmlMixin:
         body: str | Path | SupportsStr | SupportsReprHtml,
         *,  # keyword-only arguments:
         width: Width = "stretch",
+        unsafe_allow_javascript: bool = False,
     ) -> DeltaGenerator:
         """Insert HTML into your app.
 
@@ -52,8 +53,10 @@ class HtmlMixin:
         loading external code can increase the risk of vulnerabilities in your
         app.
 
-        ``st.html`` content is **not** iframed. Executing JavaScript is not
-        supported at this time.
+        ``st.html`` content is **not** iframed. By default, JavaScript is
+        ignored. To execute JavaScript contained in your HTML, set
+        ``unsafe_allow_javascript=True``. Use this with caution and never pass
+        untrusted input.
 
         Parameters
         ----------
@@ -89,6 +92,12 @@ class HtmlMixin:
               the parent container, the width of the element matches the width
               of the parent container.
 
+        unsafe_allow_javascript : bool
+            Whether to execute JavaScript contained in your HTML. If this is
+            ``False`` (default), JavaScript is ignored. If this is ``True``,
+            JavaScript is executed. Use this with caution and never pass
+            untrusted input.
+
         Example
         -------
         >>> import streamlit as st
@@ -136,6 +145,8 @@ class HtmlMixin:
             html_proto.body = html_content
             return self._event_dg._enqueue("html", html_proto)
         # Otherwise, send the html to the main container as normal
+        # Only set the unsafe JS flag for non-style-only HTML content
+        html_proto.unsafe_allow_javascript = unsafe_allow_javascript
         html_proto.body = html_content
         return self.dg._enqueue("html", html_proto, layout_config=layout_config)
 

streamlit/elements/image.py

@@ -171,7 +171,7 @@ class ImageMixin:
 
             show_deprecation_warning(
                 "The `use_column_width` parameter has been deprecated and will be removed "
-                "in a future release. Please utilize the `use_container_width` parameter instead."
+                "in a future release. Please utilize the `width` parameter instead."
             )
             if use_column_width in {"auto", "never"} or use_column_width is False:
                 width = "content"

streamlit/elements/layouts.py

@@ -62,7 +62,7 @@ class LayoutsMixin:
         *,
         border: bool | None = None,
         key: Key | None = None,
-        width: WidthWithoutContent = "stretch",
+        width: Width = "stretch",
         height: Height = "content",
         horizontal: bool = False,
         horizontal_alignment: HorizontalAlignment = "left",
@@ -92,11 +92,13 @@ class LayoutsMixin:
             Additionally, if ``key`` is provided, it will be used as CSS
             class name prefixed with ``st-key-``.
 
-        width : "stretch" or int
+        width : "stretch", "content", or int
             The width of the container. This can be one of the following:
 
             - ``"stretch"`` (default): The width of the container matches the
               width of the parent container.
+            - ``"content"``: The width of the container matches the width of
+              its content.
             - An integer specifying the width in pixels: The container has a
               fixed width. If the specified width is greater than the width of
               the parent container, the width of the container matches the width
@@ -199,7 +201,7 @@ class LayoutsMixin:
         >>>
         >>> st.write("This is outside the container")
 
-        .. output ::
+        .. output::
             https://doc-container1.streamlit.app/
             height: 520px
 
@@ -218,7 +220,7 @@ class LayoutsMixin:
         >>>
         >>> container.write("This is inside too")
 
-        .. output ::
+        .. output::
             https://doc-container2.streamlit.app/
             height: 300px
 
@@ -236,7 +238,7 @@ class LayoutsMixin:
         >>>     tile = col.container(height=120)
         >>>     tile.title(":balloon:")
 
-        .. output ::
+        .. output::
             https://doc-container3.streamlit.app/
             height: 350px
 
@@ -252,7 +254,7 @@ class LayoutsMixin:
         >>> with st.container(height=300):
         >>>     st.markdown(long_text)
 
-        .. output ::
+        .. output::
             https://doc-container4.streamlit.app/
             height: 400px
 
@@ -268,7 +270,7 @@ class LayoutsMixin:
         >>> for card in range(3):
         >>>     flex.button(f"Button {card + 1}")
 
-        .. output ::
+        .. output::
             https://doc-container5.streamlit.app/
             height: 250px
 
@@ -298,7 +300,7 @@ class LayoutsMixin:
             block_proto.flex_container.justify = get_justify(vertical_alignment)
             block_proto.flex_container.align = get_align(horizontal_alignment)
 
-        validate_width(width)
+        validate_width(width, allow_content=True)
         block_proto.width_config.CopyFrom(get_width_config(width))
 
         if isinstance(height, int) or border:
@@ -420,7 +422,7 @@ class LayoutsMixin:
         ...     st.header("An owl")
         ...     st.image("https://static.streamlit.io/examples/owl.jpg")
 
-        .. output ::
+        .. output::
             https://doc-columns1.streamlit.app/
             height: 620px
 
@@ -441,7 +443,7 @@ class LayoutsMixin:
         >>> col2.subheader("A narrow column with the data")
         >>> col2.write(df)
 
-        .. output ::
+        .. output::
             https://doc-columns2.streamlit.app/
             height: 550px
 
@@ -457,7 +459,7 @@ class LayoutsMixin:
         >>> middle.button("Click me", use_container_width=True)
         >>> right.checkbox("Check me")
 
-        .. output ::
+        .. output::
             https://doc-columns-bottom-widgets.streamlit.app/
             height: 200px
 
@@ -476,7 +478,7 @@ class LayoutsMixin:
         >>> middle.image("https://static.streamlit.io/examples/dog.jpg")
         >>> right.image("https://static.streamlit.io/examples/owl.jpg")
 
-        .. output ::
+        .. output::
             https://doc-columns-vertical-alignment.streamlit.app/
             height: 600px
 
@@ -493,7 +495,7 @@ class LayoutsMixin:
         >>> middle.markdown("Lorem ipsum " * 5)
         >>> right.markdown("Lorem ipsum ")
 
-        .. output ::
+        .. output::
             https://doc-columns-borders.streamlit.app/
             height: 250px
 
@@ -640,7 +642,7 @@ class LayoutsMixin:
         ...     st.header("An owl")
         ...     st.image("https://static.streamlit.io/examples/owl.jpg", width=200)
 
-        .. output ::
+        .. output::
             https://doc-tabs1.streamlit.app/
             height: 620px
 
@@ -661,7 +663,7 @@ class LayoutsMixin:
         >>> tab2.subheader("A tab with the data")
         >>> tab2.write(df)
 
-        .. output ::
+        .. output::
             https://doc-tabs2.streamlit.app/
             height: 700px
 
@@ -686,7 +688,7 @@ class LayoutsMixin:
         >>>     st.header("An owl")
         >>>     st.image("https://static.streamlit.io/examples/owl.jpg", width=200)
 
-        .. output ::
+        .. output::
             https://doc-tabs3.streamlit.app/
             height: 620px
 
@@ -791,6 +793,8 @@ class LayoutsMixin:
               <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
               font library.
 
+            - ``"spinner"``: Displays a spinner as an icon.
+
         width : "stretch" or int
             The width of the expander container. This can be one of the following:
 
@@ -817,7 +821,7 @@ class LayoutsMixin:
         ...     ''')
         ...     st.image("https://static.streamlit.io/examples/dice.jpg")
 
-        .. output ::
+        .. output::
             https://doc-expander.streamlit.app/
             height: 750px
 
@@ -835,7 +839,7 @@ class LayoutsMixin:
         ... ''')
         >>> expander.image("https://static.streamlit.io/examples/dice.jpg")
 
-        .. output ::
+        .. output::
             https://doc-expander.streamlit.app/
             height: 750px
 
@@ -941,6 +945,8 @@ class LayoutsMixin:
               <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
               font library.
 
+            - ``"spinner"``: Displays a spinner as an icon.
+
         disabled : bool
             An optional boolean that disables the popover button if set to
             ``True``. The default is ``False``.
@@ -993,7 +999,7 @@ class LayoutsMixin:
         >>>
         >>> st.write("Your name:", name)
 
-        .. output ::
+        .. output::
             https://doc-popover.streamlit.app/
             height: 400px
 
@@ -1010,7 +1016,7 @@ class LayoutsMixin:
         >>> if blue:
         ...     st.write(":blue[This is a blue item.]")
 
-        .. output ::
+        .. output::
             https://doc-popover2.streamlit.app/
             height: 400px
 
@@ -1142,7 +1148,7 @@ class LayoutsMixin:
         >>>
         >>> st.button("Rerun")
 
-        .. output ::
+        .. output::
             https://doc-status.streamlit.app/
             height: 300px
 
@@ -1165,7 +1171,7 @@ class LayoutsMixin:
         >>>
         >>> st.button("Rerun")
 
-        .. output ::
+        .. output::
             https://doc-status-update.streamlit.app/
             height: 300px
 

streamlit/elements/lib/built_in_chart_utils.py

@@ -46,6 +46,11 @@ if TYPE_CHECKING:
 VegaLiteType: TypeAlias = Literal["quantitative", "ordinal", "temporal", "nominal"]
 ChartStackType: TypeAlias = Literal["normalize", "center", "layered"]
 
+# Threshold for applying hover event throttling on large datasets.
+# For datasets with more points than this threshold, hover events are throttled
+# to 16ms (~60fps) to improve performance.
+_LARGE_DATASET_POINT_THRESHOLD: Final = 1000
+
 
 class PrepDataColumns(TypedDict):
     """Columns used for the prep_data step in Altair Arrow charts."""
@@ -286,37 +291,65 @@ def generate_chart(
         and is_altair_version_5_or_greater
     ):
         return _add_improved_hover_tooltips(
-            chart, x_column, chart_width, chart_height
+            chart, x_column, chart_width, chart_height, len(df)
         ).interactive(), add_rows_metadata
 
     return chart.interactive(), add_rows_metadata
 
 
 def _add_improved_hover_tooltips(
-    chart: alt.Chart, x_column: str, width: int | None, height: int | None
+    chart: alt.Chart,
+    x_column: str,
+    width: int | None,
+    height: int | None,
+    data_point_count: int,
 ) -> alt.LayerChart:
-    """Adds improved hover tooltips to an existing line chart."""
+    """Adds improved hover tooltips to an existing line chart.
+
+    This implementation uses a three-layer approach for better performance:
+    1. Base chart layer: The original line chart
+    2. Detection layer: Invisible points for detecting the nearest point on hover
+    3. Highlight layer: Only renders the selected point(s) using transform_filter
+
+    The filter-based approach is more efficient than using conditional opacity
+    because it only renders the selected point(s) rather than evaluating opacity
+    for every single data point on each hover event.
+    """
 
     import altair as alt
 
-    # Create a selection that chooses the nearest point & selects based on x-value
+    # Throttle hover events for large datasets to 16ms (~60fps) to improve performance.
+    # For smaller datasets, use standard mousemove without throttling.
+    hover_event = (
+        "mousemove{16}"
+        if data_point_count > _LARGE_DATASET_POINT_THRESHOLD
+        else "mousemove"
+    )
+
+    # Create a selection that chooses the nearest point & selects based on x-value.
+    # Uses mouseleave instead of mouseout/pointerout for more reliable hover clearing
+    # (mouseout fires when moving over child elements like tooltips).
     nearest = alt.selection_point(
         nearest=True,
-        on="pointerover",
+        on=hover_event,
         fields=[x_column],
         empty=False,
-        clear="pointerout",
+        clear="mouseleave",
     )
 
-    # Draw points on the line, and highlight based on selection
-    points = (
-        chart.mark_point(filled=True, size=65)
-        .encode(opacity=alt.condition(nearest, alt.value(1), alt.value(0)))
-        .add_params(nearest)
+    # Detection layer: Invisible points for detecting the nearest point.
+    # This layer is needed because selections must be attached to a mark.
+    detection_points = chart.mark_point(opacity=0).add_params(nearest)
+
+    # Highlight layer: Only renders the selected point(s) using transform_filter.
+    # This is more efficient than conditional opacity because it only renders
+    # the filtered data (typically 1-2 points) rather than all points.
+    highlighted_points = chart.mark_point(filled=True, size=65).transform_filter(
+        nearest
     )
 
     layer_chart = (
-        alt.layer(chart, points)
+        alt.layer(chart, detection_points, highlighted_points)
         .configure_legend(symbolType="stroke")
         .properties(
             width=width or 0,
@@ -338,7 +371,7 @@ def prep_chart_data_for_add_rows(
     """
     import pandas as pd
 
-    df = cast("pd.DataFrame", dataframe_util.convert_anything_to_pandas_df(data))
+    df = dataframe_util.convert_anything_to_pandas_df(data)
 
     # Make range indices start at last_index.
     if isinstance(df.index, pd.RangeIndex):
@@ -431,7 +464,7 @@ def _infer_vegalite_type(
 
 
 def _get_pandas_index_attr(
-    data: pd.DataFrame | pd.Series,
+    data: pd.DataFrame | pd.Series[Any],
     attr: str,
 ) -> Any | None:
     return getattr(data.index, attr, None)
@@ -634,7 +667,7 @@ def _drop_unused_columns(df: pd.DataFrame, *column_names: str | None) -> pd.Data
         seen.add(x)
         keep.append(x)
 
-    return df[keep]
+    return df[keep]  # ty: ignore[invalid-return-type]
 
 
 def _maybe_convert_color_column_in_place(
@@ -651,7 +684,7 @@ def _maybe_convert_color_column_in_place(
         pass
     elif is_color_tuple_like(first_color_datum):
         # Tuples need to be converted to CSS-valid.
-        df.loc[:, color_column] = df[color_column].map(to_css_color)
+        df.loc[:, color_column] = df[color_column].apply(to_css_color)
     else:
         # Other kinds of colors columns (i.e. pure numbers or nominal strings) shouldn't
         # be converted since they are treated by Vega-Lite as sequential or categorical

streamlit/elements/lib/color_util.py

@@ -219,7 +219,7 @@ def _normalize_tuple(
         r = rgb_formatter(color_4tuple[0], color_4tuple)
         g = rgb_formatter(color_4tuple[1], color_4tuple)
         b = rgb_formatter(color_4tuple[2], color_4tuple)
-        alpha = alpha_formatter(color_4tuple[3], color_4tuple)
+        alpha = alpha_formatter(color_4tuple[3], color_4tuple)  # ty: ignore[index-out-of-bounds]
         return r, g, b, alpha
 
     raise StreamlitInvalidColorError(color)

streamlit/elements/lib/column_config_utils.py

@@ -18,7 +18,7 @@ import copy
 import json
 from collections.abc import Mapping
 from enum import Enum
-from typing import TYPE_CHECKING, Final, Literal, TypeAlias
+from typing import TYPE_CHECKING, Any, Final, Literal, TypeAlias
 
 from streamlit.dataframe_util import DataFormat
 from streamlit.elements.lib.column_types import ColumnConfig, ColumnType
@@ -208,7 +208,7 @@ def _determine_data_kind_via_arrow(field: pa.Field) -> ColumnDataKind:
 
 
 def _determine_data_kind_via_pandas_dtype(
-    column: Series | Index,
+    column: Series[Any] | Index[Any],
 ) -> ColumnDataKind:
     """Determine the data kind by using the pandas dtype.
 
@@ -262,7 +262,7 @@ def _determine_data_kind_via_pandas_dtype(
 
 
 def _determine_data_kind_via_inferred_type(
-    column: Series | Index,
+    column: Series[Any] | Index[Any],
 ) -> ColumnDataKind:
     """Determine the data kind by inferring it from the underlying data.
 
@@ -331,7 +331,7 @@ def _determine_data_kind_via_inferred_type(
 
 
 def _determine_data_kind(
-    column: Series | Index, field: pa.Field | None = None
+    column: Series[Any] | Index[Any], field: pa.Field | None = None
 ) -> ColumnDataKind:
     """Determine the data kind of a column.
 
@@ -395,7 +395,8 @@ def determine_dataframe_schema(
 
     # Add types for all columns:
     for i, column in enumerate(data_df.items()):
-        column_name, column_data = column
+        column_name = str(column[0])
+        column_data = column[1]
         dataframe_schema[column_name] = _determine_data_kind(
             column_data, arrow_schema.field(i)
         )

streamlit/elements/lib/layout_utils.py

@@ -21,12 +21,14 @@ from streamlit.errors import (
     StreamlitInvalidHeightError,
     StreamlitInvalidHorizontalAlignmentError,
     StreamlitInvalidSizeError,
+    StreamlitInvalidTextAlignmentError,
     StreamlitInvalidVerticalAlignmentError,
     StreamlitInvalidWidthError,
 )
 from streamlit.proto.Block_pb2 import Block
 from streamlit.proto.GapSize_pb2 import GapSize
 from streamlit.proto.HeightConfig_pb2 import HeightConfig
+from streamlit.proto.TextAlignmentConfig_pb2 import TextAlignmentConfig
 from streamlit.proto.WidthConfig_pb2 import WidthConfig
 
 WidthWithoutContent: TypeAlias = int | Literal["stretch"]
@@ -37,6 +39,7 @@ SpaceSize: TypeAlias = int | Literal["stretch", "small", "medium", "large"]
 Gap: TypeAlias = Literal["small", "medium", "large"]
 HorizontalAlignment: TypeAlias = Literal["left", "center", "right", "distribute"]
 VerticalAlignment: TypeAlias = Literal["top", "center", "bottom", "distribute"]
+TextAlignment: TypeAlias = Literal["left", "center", "right", "justify"]
 
 # Mapping of size literals to rem values for st.space
 # If changing these, also check streamlit/frontend/lib/src/theme/primitives/sizes.ts
@@ -52,6 +55,7 @@ SIZE_TO_REM_MAPPING = {
 class LayoutConfig:
     width: Width | SpaceSize | None = None
     height: Height | SpaceSize | None = None
+    text_alignment: TextAlignment | None = None
 
 
 def validate_width(width: Width, allow_content: bool = False) -> None:
@@ -210,6 +214,24 @@ def validate_vertical_alignment(vertical_alignment: VerticalAlignment) -> None:
         raise StreamlitInvalidVerticalAlignmentError(vertical_alignment, "st.container")
 
 
+def validate_text_alignment(text_alignment: TextAlignment) -> None:
+    """Validate the text_alignment parameter.
+
+    Parameters
+    ----------
+    text_alignment : TextAlignment
+        The text alignment value to validate.
+
+    Raises
+    ------
+    StreamlitInvalidTextAlignmentError
+        If the text_alignment value is invalid.
+    """
+    valid_alignments = ["left", "center", "right", "justify"]
+    if text_alignment not in valid_alignments:
+        raise StreamlitInvalidTextAlignmentError(text_alignment)
+
+
 map_to_flex_terminology = {
     "left": "start",
     "center": "center",
@@ -249,3 +271,31 @@ def get_align(
         "Block.FlexContainer.Align.ValueType",
         getattr(Block.FlexContainer.Align, f"ALIGN_{align.upper()}"),
     )
+
+
+def get_text_alignment_config(
+    text_alignment: TextAlignment,
+) -> TextAlignmentConfig:
+    """Convert text alignment string to proto config.
+
+    Parameters
+    ----------
+    text_alignment : TextAlignment
+        The text alignment value ("left", "center", "right", "justify").
+
+    Returns
+    -------
+    TextAlignmentConfig
+        Proto message with alignment set.
+    """
+
+    alignment_mapping = {
+        "left": TextAlignmentConfig.Alignment.LEFT,
+        "center": TextAlignmentConfig.Alignment.CENTER,
+        "right": TextAlignmentConfig.Alignment.RIGHT,
+        "justify": TextAlignmentConfig.Alignment.JUSTIFY,
+    }
+
+    config = TextAlignmentConfig()
+    config.alignment = alignment_mapping[text_alignment]
+    return config