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

streamlit/elements/plotly_chart.py

@@ -12,8 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Streamlit support for Plotly charts."""
-
 from __future__ import annotations
 
 import json
@@ -23,23 +21,35 @@ from typing import (
     Any,
     Final,
     Literal,
+    TypeAlias,
     TypedDict,
     Union,
     cast,
     overload,
 )
 
-from typing_extensions import Required, TypeAlias
+from typing_extensions import Required
 
 from streamlit import type_util
-from streamlit.deprecation_util import show_deprecation_warning
+from streamlit.deprecation_util import (
+    make_deprecated_name_warning,
+    show_deprecation_warning,
+)
 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
 from streamlit.elements.lib.streamlit_plotly_theme import (
     configure_streamlit_plotly_theme,
 )
 from streamlit.elements.lib.utils import Key, compute_and_register_element_id, to_key
 from streamlit.errors import StreamlitAPIException
+from streamlit.logger import get_logger
 from streamlit.proto.PlotlyChart_pb2 import PlotlyChart as PlotlyChartProto
 from streamlit.runtime.metrics_util import gather_metrics
 from streamlit.runtime.scriptrunner_utils.script_run_context import get_script_run_ctx
@@ -76,6 +86,8 @@ FigureOrData: TypeAlias = Union[
 SelectionMode: TypeAlias = Literal["lasso", "points", "box"]
 _SELECTION_MODES: Final[set[SelectionMode]] = {"lasso", "points", "box"}
 
+_LOGGER: Final = get_logger(__name__)
+
 
 class PlotlySelectionState(TypedDict, total=False):
     """
@@ -267,13 +279,109 @@ def parse_selection_mode(
     return set(parsed_selection_modes)
 
 
+def _resolve_content_width(width: Width, figure: Any) -> Width:
+    """Resolve "content" width by inspecting the figure's layout width.
+
+    For content width, we check if the plotly figure has an explicit width
+    in its layout. If so, we use that as a pixel width. If not, we default
+    to 700 pixels which matches the plotly.js default width.
+
+    Args
+    ----
+    width : Width
+        The original width parameter
+    figure : Any
+        The plotly figure object (Figure, dict, or other supported formats)
+
+    Returns
+    -------
+    Width
+        The resolved width (either original width, figure width as pixels, or 700)
+    """
+
+    if width != "content":
+        return width
+
+    # Extract width 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_width = None
+    if isinstance(figure, dict):
+        figure_width = figure.get("layout", {}).get("width")
+    else:
+        # Handle Figure objects from matplotlib conversion
+        try:
+            figure_width = figure.layout.width
+        except (AttributeError, TypeError):
+            _LOGGER.debug("Could not parse width from figure")
+
+    if (
+        figure_width is not None
+        and isinstance(figure_width, (int, float))
+        and figure_width > 0
+    ):
+        return int(figure_width)
+
+    # Default to 700 pixels (plotly.js default) when no width is specified
+    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(
         self,
         figure_or_data: FigureOrData,
-        use_container_width: bool = True,
+        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
@@ -289,8 +397,10 @@ class PlotlyMixin:
     def plotly_chart(
         self,
         figure_or_data: FigureOrData,
-        use_container_width: bool = True,
+        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",
@@ -306,8 +416,10 @@ class PlotlyMixin:
     def plotly_chart(
         self,
         figure_or_data: FigureOrData,
-        use_container_width: bool = True,
+        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",
@@ -357,13 +469,46 @@ class PlotlyMixin:
                 render in SVG mode when passed to ``st.plotly_chart``:
                 ``px.line(df, x="x", y="y", render_mode="svg")``.
 
-        use_container_width : bool
+        width : "stretch", "content", or int
+            The width of the chart element. This can be one of the following:
+
+            - ``"stretch"`` (default): The width of the element matches the
+              width of the parent container.
+            - ``"content"``: The width of the element matches the width of its
+              content, but doesn't exceed the width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              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. If ``use_container_width`` is ``True`` (default),
-            Streamlit sets the width of the figure to match the width of the parent
-            container. If ``use_container_width`` is ``False``, Streamlit sets the
-            width of the chart to fit its contents according to the plotting library,
-            up to the width of the parent container.
+            the parent container. This can be one of the following:
+
+            - ``None`` (default): Streamlit will use the value of ``width``.
+            - ``True``: Streamlit sets the width of the figure to match the
+              width of the parent container.
+            - ``False``: Streamlit sets the width of the figure to fit its
+              contents according to the plotting library, up to the width of
+              the parent container.
+
+            .. deprecated::
+               ``use_container_width`` is deprecated and will be removed in a
+                future release. For ``use_container_width=True``, use
+                ``width="stretch"``.
 
         theme : "streamlit" or None
             The theme of the chart. If ``theme`` is ``"streamlit"`` (default),
@@ -497,6 +642,26 @@ class PlotlyMixin:
            height: 550px
 
         """
+        if use_container_width is not None:
+            show_deprecation_warning(
+                make_deprecated_name_warning(
+                    "use_container_width",
+                    "width",
+                    "2025-12-31",
+                    "For `use_container_width=True`, use `width='stretch'`. "
+                    "For `use_container_width=False`, use `width='content'`.",
+                    include_st_prefix=False,
+                ),
+                show_in_browser=False,
+            )
+            if use_container_width:
+                width = "stretch"
+            elif not isinstance(width, int):
+                width = "content"
+
+        validate_width(width, allow_content=True)
+        validate_height(height, allow_content=True)
+
         import plotly.io
         import plotly.tools
 
@@ -506,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]:
@@ -549,7 +715,6 @@ class PlotlyMixin:
             )
 
         plotly_chart_proto = PlotlyChartProto()
-        plotly_chart_proto.use_container_width = use_container_width
         plotly_chart_proto.theme = theme or ""
         plotly_chart_proto.form_id = current_form_id(self.dg)
 
@@ -572,9 +737,14 @@ class PlotlyMixin:
             selection_mode=selection_mode,
             is_selection_activated=is_selection_activated,
             theme=theme,
-            use_container_width=use_container_width,
+            width=width,
+            height=height,
         )
 
+        # 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:
             plotly_chart_proto.selection_mode.extend(
@@ -592,9 +762,16 @@ class PlotlyMixin:
                 value_type="string_value",
             )
 
-            self.dg._enqueue("plotly_chart", plotly_chart_proto)
+            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
-        return self.dg._enqueue("plotly_chart", plotly_chart_proto)
+
+        layout_config = LayoutConfig(width=final_width, height=final_height)
+        return self.dg._enqueue(
+            "plotly_chart", plotly_chart_proto, layout_config=layout_config
+        )
 
     @property
     def dg(self) -> DeltaGenerator:

streamlit/elements/progress.py

@@ -15,9 +15,7 @@
 from __future__ import annotations
 
 import math
-from typing import TYPE_CHECKING, Union, cast
-
-from typing_extensions import TypeAlias
+from typing import TYPE_CHECKING, TypeAlias, cast
 
 from streamlit.elements.lib.layout_utils import LayoutConfig, validate_width
 from streamlit.errors import StreamlitAPIException
@@ -31,7 +29,7 @@ if TYPE_CHECKING:
 
 # Currently, equates to just float, but we can't use `numbers.Real` due to
 # https://github.com/python/mypy/issues/3186
-FloatOrInt: TypeAlias = Union[int, float]
+FloatOrInt: TypeAlias = int | float
 
 
 def _check_float_between(value: float, low: float = 0.0, high: float = 1.0) -> bool:

streamlit/elements/space.py

@@ -0,0 +1,113 @@
+# 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 TYPE_CHECKING, cast
+
+from streamlit.elements.lib.layout_utils import (
+    LayoutConfig,
+    SpaceSize,
+    validate_space_size,
+)
+from streamlit.proto.Space_pb2 import Space as SpaceProto
+from streamlit.runtime.metrics_util import gather_metrics
+
+if TYPE_CHECKING:
+    from streamlit.delta_generator import DeltaGenerator
+
+
+class SpaceMixin:
+    @gather_metrics("space")
+    def space(
+        self,
+        size: SpaceSize = "small",
+    ) -> DeltaGenerator:
+        """Add vertical or horizontal space.
+
+        This command adds space in the direction of its parent container. In
+        a vertical layout, it adds vertical space. In a horizontal layout, it
+        adds horizontal space.
+
+        Parameters
+        ----------
+        size : "small", "medium", "large", "stretch", or int
+            The size of the space. This can be one of the following values:
+
+            - ``"small"`` (default): 0.75rem, which is the height of a widget
+              label. This is useful for aligning buttons with labeled widgets.
+            - ``"medium"``: 2.5rem, which is the height of a button or
+              (unlabeled) input field.
+            - ``"large"``: 4.25rem, which is the height of a labeled input
+              field or unlabeled media widget, like `st.file_uploader`.
+            - ``"stretch"``: Expands to fill remaining space in the container.
+            - An integer: Fixed size in pixels.
+
+        Examples
+        --------
+        **Example 1: Use vertical space to align elements**
+
+        Use small spaces to replace label heights. Use medium spaces to replace
+        two label heights or a button.
+
+        >>> import streamlit as st
+        >>>
+        >>> left, middle, right = st.columns(3)
+        >>>
+        >>> left.space("medium")
+        >>> left.button("Left button", width="stretch")
+        >>>
+        >>> middle.space("small")
+        >>> middle.text_input("Middle input")
+        >>>
+        >>> right.audio_input("Right uploader")
+
+        .. output::
+            https://doc-space-vertical.streamlit.app/
+            height: 260px
+
+        **Example 2: Add horizontal space in a container**
+
+        Use stretch space to float elements left and right.
+
+        >>> import streamlit as st
+        >>>
+        >>> with st.container(horizontal=True):
+        ...     st.button("Left")
+        ...     st.space("stretch")
+        ...     st.button("Right")
+
+        .. output::
+            https://doc-space-horizontal.streamlit.app/
+            height: 200px
+
+        """
+        space_proto = SpaceProto()
+
+        validate_space_size(size)
+
+        # In vertical layouts, size controls height.
+        # In horizontal layouts, size controls width.
+        # We set both width and height configs to the same size value.
+        # The frontend uses FlexContext to determine container direction and
+        # applies ONLY the relevant dimension (width for horizontal, height for vertical)
+        # to avoid unintended cross-axis spacing.
+        layout_config = LayoutConfig(width=size, height=size)
+
+        return self.dg._enqueue("space", space_proto, layout_config=layout_config)
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        """Get our DeltaGenerator."""
+        return cast("DeltaGenerator", self)

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: