streamlit 1.49.1__py3-none-any.whl → 1.51.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,33 @@ 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 (
+    LayoutConfig,
+    Width,
+    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 +84,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 +277,61 @@ 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
+
+
 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",
         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 +347,9 @@ class PlotlyMixin:
     def plotly_chart(
         self,
         figure_or_data: FigureOrData,
-        use_container_width: bool = True,
+        use_container_width: bool | None = None,
         *,
+        width: Width = "stretch",
         theme: Literal["streamlit"] | None = "streamlit",
         key: Key | None = None,
         on_select: Literal["rerun"] | WidgetCallback = "rerun",
@@ -306,8 +365,9 @@ class PlotlyMixin:
     def plotly_chart(
         self,
         figure_or_data: FigureOrData,
-        use_container_width: bool = True,
+        use_container_width: bool | None = None,
         *,
+        width: Width = "stretch",
         theme: Literal["streamlit"] | None = "streamlit",
         key: Key | None = None,
         on_select: Literal["rerun", "ignore"] | WidgetCallback = "ignore",
@@ -316,6 +376,7 @@ class PlotlyMixin:
             "box",
             "lasso",
         ),
+        config: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> DeltaGenerator | PlotlyState:
         """Display an interactive Plotly chart.
@@ -356,13 +417,33 @@ 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.
+
+        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),
@@ -415,6 +496,12 @@ class PlotlyMixin:
 
             All selections modes are activated by default.
 
+        config : dict or None
+            A dictionary of Plotly configuration options. This is passed to
+            Plotly's ``show()`` function. For more information about Plotly
+            configuration options, see Plotly's documentation on `Configuration
+            in Python <https://plotly.com/python/configuration-options/>`_.
+
         **kwargs
             Additional arguments accepted by Plotly's ``plot()`` function.
 
@@ -423,6 +510,10 @@ class PlotlyMixin:
             see Plotly's documentation on `Configuration in Python
             <https://plotly.com/python/configuration-options/>`_.
 
+            .. deprecated::
+               ``**kwargs`` are deprecated and will be removed in a future
+               release. Use ``config`` instead.
+
         Returns
         -------
         element or dict
@@ -486,6 +577,25 @@ 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)
+
         import plotly.io
         import plotly.tools
 
@@ -493,11 +603,11 @@ class PlotlyMixin:
         # for their main parameter. I don't like the name, but it's best to
         # keep it in sync with what Plotly calls it.
 
-        if "sharing" in kwargs:
+        if kwargs:
             show_deprecation_warning(
-                "The `sharing` parameter has been deprecated and will be removed "
-                "in a future release. Plotly charts will always be rendered using "
-                "Streamlit's offline mode."
+                "The keyword arguments have been deprecated and will be removed "
+                "in a future release. Use `config` instead to specify Plotly "
+                "configuration options."
             )
 
         if theme not in ["streamlit", None]:
@@ -538,15 +648,10 @@ 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)
 
-        config = dict(kwargs.get("config", {}))
-        # Copy over some kwargs to config dict. Plotly does the same in plot().
-        config.setdefault("showLink", kwargs.get("show_link", False))
-        config.setdefault("linkText", kwargs.get("link_text", False))
-
+        config = config or {}
         plotly_chart_proto.spec = plotly.io.to_json(figure, validate=False)
         plotly_chart_proto.config = json.dumps(config)
 
@@ -558,15 +663,19 @@ class PlotlyMixin:
         plotly_chart_proto.id = compute_and_register_element_id(
             "plotly_chart",
             user_key=key,
+            key_as_main_identity=False,
             dg=self.dg,
             plotly_spec=plotly_chart_proto.spec,
             plotly_config=plotly_chart_proto.config,
             selection_mode=selection_mode,
             is_selection_activated=is_selection_activated,
             theme=theme,
-            use_container_width=use_container_width,
+            width=width,
         )
 
+        # Handle "content" width by inspecting the figure's natural width
+        final_width = _resolve_content_width(width, figure)
+
         if is_selection_activated:
             # Selections are activated, treat plotly chart as a widget:
             plotly_chart_proto.selection_mode.extend(
@@ -584,9 +693,16 @@ class PlotlyMixin:
                 value_type="string_value",
             )
 
-            self.dg._enqueue("plotly_chart", plotly_chart_proto)
+            layout_config = LayoutConfig(width=final_width)
+            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)
+        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/pyplot.py

@@ -99,15 +99,15 @@ class PyplotMixin:
             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"``. For ``use_container_width=False``, use
+                ``width="content"``.
+
         **kwargs : any
             Arguments to pass to Matplotlib's savefig function.
 
-        .. deprecated::
-            ``use_container_width`` is deprecated and will be removed in a
-            future release. For ``use_container_width=True``, use
-            ``width="stretch"``. For ``use_container_width=False``, use
-            ``width="content"``.
-
         Example
         -------
         >>> import matplotlib.pyplot as plt

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)