streamlit 1.48.1__py3-none-any.whl → 1.49.0__py3-none-any.whl

streamlit/elements/metric.py

@@ -20,6 +20,7 @@ from typing import TYPE_CHECKING, Any, Literal, Union, cast
 
 from typing_extensions import TypeAlias
 
+from streamlit.dataframe_util import OptionSequence, convert_anything_to_list
 from streamlit.elements.lib.layout_utils import (
     Height,
     LayoutConfig,
@@ -62,11 +63,14 @@ class MetricMixin:
         value: Value,
         delta: Delta = None,
         delta_color: DeltaColor = "normal",
+        *,
         help: str | None = None,
         label_visibility: LabelVisibility = "visible",
         border: bool = False,
         width: Width = "stretch",
         height: Height = "content",
+        chart_data: OptionSequence[Any] | None = None,
+        chart_type: Literal["line", "bar", "area"] = "line",
     ) -> DeltaGenerator:
         r"""Display a metric in big bold font, with an optional indicator of how the metric changed.
 
@@ -156,6 +160,22 @@ class MetricMixin:
               the parent container, the width of the element matches the width
               of the parent container.
 
+        chart_data : Iterable or None
+            A sequence of numeric values to display as a sparkline chart. If
+            this is ``None`` (default), no chart is displayed. The sequence can
+            be anything supported by ``st.dataframe``, including a ``list`` or
+            ``set``. If the sequence is dataframe-like, the first column will
+            be used. Each value will be cast to ``float`` internally by
+            default.
+
+        chart_type : "line", "bar", or "area"
+            The type of sparkline chart to display. This can be one of the
+            following:
+
+            - ``"line"`` (default): A simple sparkline.
+            - ``"area"``: A sparkline with area shading.
+            - ``"bar"``: A bar chart.
+
         Examples
         --------
         **Example 1: Show a metric**
@@ -192,7 +212,10 @@ class MetricMixin:
         >>> st.metric(label="Gas price", value=4, delta=-0.5, delta_color="inverse")
         >>>
         >>> st.metric(
-        ...     label="Active developers", value=123, delta=123, delta_color="off"
+        ...     label="Active developers",
+        ...     value=123,
+        ...     delta=123,
+        ...     delta_color="off",
         ... )
 
         .. output::
@@ -218,6 +241,33 @@ class MetricMixin:
             https://doc-metric-example4.streamlit.app/
             height: 350px
 
+        **Example 5: Show sparklines**
+
+        To show trends over time, add sparklines.
+
+        >>> import streamlit as st
+        >>> from numpy.random import default_rng as rng
+        >>>
+        >>> changes = list(rng(4).standard_normal(20))
+        >>> data = [sum(changes[:i]) for i in range(20)]
+        >>> delta = round(data[-1], 2)
+        >>>
+        >>> row = st.container(horizontal=True)
+        >>> with row:
+        >>>     st.metric(
+        ...         "Line", 10, delta, chart_data=data, chart_type="line", border=True
+        ...     )
+        >>>     st.metric(
+        ...         "Area", 10, delta, chart_data=data, chart_type="area", border=True
+        ...     )
+        >>>     st.metric(
+        ...         "Bar", 10, delta, chart_data=data, chart_type="bar", border=True
+        ...     )
+
+        .. output::
+            https://doc-metric-example5.streamlit.app/
+            height: 300px
+
         """
         maybe_raise_label_warnings(label, label_visibility)
 
@@ -238,6 +288,22 @@ class MetricMixin:
             label_visibility
         )
 
+        if chart_data is not None:
+            prepared_data: list[float] = []
+            for val in convert_anything_to_list(chart_data):
+                try:
+                    prepared_data.append(float(val))
+                except Exception as ex:  # noqa: PERF203
+                    raise StreamlitAPIException(
+                        "Only numeric values are supported for chart data sequence. The "
+                        f"value '{val}' is of type {type(val)} and "
+                        "cannot be converted to float."
+                    ) from ex
+            if len(prepared_data) > 0:
+                metric_proto.chart_data.extend(prepared_data)
+
+        metric_proto.chart_type = _parse_chart_type(chart_type)
+
         validate_height(height, allow_content=True)
         validate_width(width, allow_content=True)
         layout_config = LayoutConfig(width=width, height=height)
@@ -249,6 +315,17 @@ class MetricMixin:
         return cast("DeltaGenerator", self)
 
 
+def _parse_chart_type(
+    chart_type: Literal["line", "bar", "area"],
+) -> MetricProto.ChartType.ValueType:
+    if chart_type == "bar":
+        return MetricProto.ChartType.BAR
+    if chart_type == "area":
+        return MetricProto.ChartType.AREA
+    # Use line as default chart:
+    return MetricProto.ChartType.LINE
+
+
 def _parse_label(label: str) -> str:
     if not isinstance(label, str):
         raise TypeError(

streamlit/elements/pdf.py

@@ -0,0 +1,192 @@
+# 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 io
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Union, cast
+
+from typing_extensions import TypeAlias
+
+from streamlit import url_util
+from streamlit.elements.lib.layout_utils import validate_height
+from streamlit.errors import StreamlitAPIException
+from streamlit.runtime.metrics_util import gather_metrics
+
+if TYPE_CHECKING:
+    from streamlit.delta_generator import DeltaGenerator
+    from streamlit.elements.lib.layout_utils import HeightWithoutContent
+
+PdfData: TypeAlias = Union[str, Path, bytes, io.BytesIO]
+
+
+def _get_pdf_component() -> Any | None:
+    """Get the PDF custom component if available.
+
+    Returns
+    -------
+    Any | None
+        The pdf_viewer function if the streamlit-pdf component is available,
+        None otherwise.
+    """
+    try:
+        import streamlit_pdf  # type: ignore
+
+        return streamlit_pdf.pdf_viewer
+    except ImportError:
+        return None
+
+
+class PdfMixin:
+    @gather_metrics("pdf")
+    def pdf(
+        self,
+        data: PdfData,
+        *,
+        height: HeightWithoutContent = 500,
+        key: str | None = None,
+    ) -> DeltaGenerator:
+        """Display a PDF viewer.
+
+        .. Important::
+
+            You must install |streamlit-pdf|_ to use this command. You can
+            install it as an extra with Streamlit:
+
+            .. code-block:: shell
+
+                pip install streamlit[pdf]
+
+        .. |streamlit-pdf| replace:: ``streamlit-pdf``
+        .. _streamlit-pdf: https://github.com/streamlit/streamlit-pdf
+
+        Parameters
+        ----------
+        data : str, Path, BytesIO, or bytes
+            The PDF file to show. This can be one of the following:
+
+            - A URL (string) for a hosted PDF file.
+            - A path to a local PDF file. If you use a relative path, it must
+              be relative to the current working directory.
+            - A file-like object. For example, this can be an ``UploadedFile``
+              from ``st.file_uploader``, or this can be a local file opened
+              with ``open()``.
+            - Raw bytes data.
+
+        height : int or "stretch"
+            The height of the PDF viewer. This can be one of the following:
+
+            - An integer specifying the height in pixels: The viewer has a
+              fixed height. If the content is larger than the specified
+              height, scrolling is enabled. This is ``500`` by default.
+            - ``"stretch"``: The height of the viewer matches the height of
+              its content or the height of the parent container, whichever is
+              larger. If the viewer is not in a parent container, the height
+              of the viewer matches the height of its content.
+
+        Example
+        -------
+        >>> st.pdf("https://example.com/sample.pdf")
+        >>> st.pdf("https://example.com/sample.pdf", height=600)
+        """
+        # Validate data parameter early
+        if data is None:
+            raise StreamlitAPIException(
+                "The PDF data cannot be None. Please provide a valid PDF file path, URL, "
+                "bytes data, or file-like object."
+            )
+
+        # Check if custom PDF component is available first
+        pdf_component = _get_pdf_component()
+        if pdf_component is None:
+            return self._show_pdf_warning()
+
+        return self._call_pdf_component(pdf_component, data, height, key)
+
+    def _call_pdf_component(
+        self,
+        pdf_component: Any,
+        data: PdfData,
+        height: HeightWithoutContent,
+        key: str | None,
+    ) -> DeltaGenerator:
+        """Call the custom PDF component with the provided data."""
+        # Validate height parameter after confirming component is available
+        validate_height(height, allow_content=False)
+
+        # Convert data to the format expected by pdf_viewer component
+        file_param: str | bytes
+
+        if isinstance(data, (str, Path)):
+            data_str = str(data).strip()  # Strip whitespace from URLs
+            if url_util.is_url(data_str, allowed_schemas=("http", "https")):
+                # It's a URL - pass directly
+                file_param = data_str
+            else:
+                # It's a local file path - read the content as bytes for security
+                try:
+                    with open(data_str, "rb") as file:
+                        file_param = file.read()
+                except (FileNotFoundError, PermissionError) as e:
+                    raise StreamlitAPIException(
+                        f"Unable to read file '{data_str}': {e}"
+                    )
+
+        elif isinstance(data, bytes):
+            # Pass bytes directly - the component will handle uploading to media storage
+            file_param = data
+        elif hasattr(data, "read") and hasattr(data, "getvalue"):
+            # Handle BytesIO and similar
+            file_param = data.getvalue()
+        elif hasattr(data, "read"):
+            # Handle other file-like objects
+            file_param = data.read()
+        else:
+            # Provide a more helpful error message
+            raise StreamlitAPIException(
+                f"Unsupported data type for PDF: {type(data).__name__}. "
+                f"Please provide a file path (str or Path), URL (str), bytes data, "
+                f"or file-like object (such as BytesIO or UploadedFile)."
+            )
+
+        # Convert to component-compatible format
+        if height == "stretch":
+            # For stretch, we need to pass a special value the component understands
+            # This maintains compatibility with the component while using standard layout
+            component_height = "stretch"
+        else:
+            component_height = str(height)
+
+        result = pdf_component(
+            file=file_param,
+            height=component_height,
+            key=key,
+        )
+        return cast("DeltaGenerator", result)
+
+    def _show_pdf_warning(self) -> DeltaGenerator:
+        """Raise an exception that the PDF component is not available."""
+        raise StreamlitAPIException(
+            "The PDF viewer requires the `streamlit-pdf` component to be installed.\n\n"
+            "Please run `pip install streamlit[pdf]` to install it.\n\n"
+            "For more information, see the Streamlit PDF documentation at "
+            "https://docs.streamlit.io/develop/api-reference/media/st.pdf."
+            # TODO: Update this URL when docs are updated
+        )
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        """Get our DeltaGenerator."""
+        return cast("DeltaGenerator", self)

streamlit/elements/plotly_chart.py

@@ -333,7 +333,9 @@ class PlotlyMixin:
             can install all charting dependencies (except Bokeh) as an extra
             with Streamlit:
 
-            >>> pip install streamlit[charts]
+            .. code-block:: shell
+
+               pip install streamlit[charts]
 
         Parameters
         ----------
@@ -556,7 +558,6 @@ class PlotlyMixin:
         plotly_chart_proto.id = compute_and_register_element_id(
             "plotly_chart",
             user_key=key,
-            form_id=plotly_chart_proto.form_id,
             dg=self.dg,
             plotly_spec=plotly_chart_proto.spec,
             plotly_config=plotly_chart_proto.config,

streamlit/elements/pyplot.py

@@ -19,8 +19,12 @@ from __future__ import annotations
 import io
 from typing import TYPE_CHECKING, Any, cast
 
-from streamlit.deprecation_util import show_deprecation_warning
-from streamlit.elements.lib.image_utils import WidthBehavior, marshall_images
+from streamlit.deprecation_util import (
+    make_deprecated_name_warning,
+    show_deprecation_warning,
+)
+from streamlit.elements.lib.image_utils import marshall_images
+from streamlit.elements.lib.layout_utils import LayoutConfig, Width, validate_width
 from streamlit.proto.Image_pb2 import ImageList as ImageListProto
 from streamlit.runtime.metrics_util import gather_metrics
 
@@ -36,7 +40,9 @@ class PyplotMixin:
         self,
         fig: Figure | None = None,
         clear_figure: bool | None = None,
-        use_container_width: bool = True,
+        *,
+        width: Width = "stretch",
+        use_container_width: bool | None = None,
         **kwargs: Any,
     ) -> DeltaGenerator:
         """Display a matplotlib.pyplot figure.
@@ -46,7 +52,9 @@ class PyplotMixin:
             install all charting dependencies (except Bokeh) as an extra with
             Streamlit:
 
-            >>> pip install streamlit[charts]
+            .. code-block:: shell
+
+               pip install streamlit[charts]
 
         Parameters
         ----------
@@ -69,6 +77,19 @@ class PyplotMixin:
             - If ``fig`` is not set, defaults to ``True``. This simulates Jupyter's
               approach to matplotlib rendering.
 
+        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
             Whether to override the figure's native width with the width of
             the parent container. If ``use_container_width`` is ``True``
@@ -81,6 +102,12 @@ class PyplotMixin:
         **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
@@ -106,6 +133,21 @@ class PyplotMixin:
 
         """
 
+        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,
+            )
+
+            width = "stretch" if use_container_width else "content"
+
         if not fig:
             show_deprecation_warning("""
 Calling `st.pyplot()` without providing a figure argument has been deprecated
@@ -125,16 +167,19 @@ If you have a specific use case that requires this functionality, please let us
 know via [issue on Github](https://github.com/streamlit/streamlit/issues).
 """)
 
+        validate_width(width, allow_content=True)
+        layout_config = LayoutConfig(width=width)
+
         image_list_proto = ImageListProto()
         marshall(
             self.dg._get_delta_path_str(),
             image_list_proto,
+            layout_config,
             fig,
             clear_figure,
-            use_container_width,
             **kwargs,
         )
-        return self.dg._enqueue("imgs", image_list_proto)
+        return self.dg._enqueue("imgs", image_list_proto, layout_config=layout_config)
 
     @property
     def dg(self) -> DeltaGenerator:
@@ -145,9 +190,9 @@ know via [issue on Github](https://github.com/streamlit/streamlit/issues).
 def marshall(
     coordinates: str,
     image_list_proto: ImageListProto,
+    layout_config: LayoutConfig,
     fig: Figure | None = None,
     clear_figure: bool | None = True,
-    use_container_width: bool = True,
     **kwargs: Any,
 ) -> None:
     try:
@@ -178,14 +223,11 @@ def marshall(
 
     image = io.BytesIO()
     fig.savefig(image, **kwargs)
-    image_width = (
-        WidthBehavior.COLUMN if use_container_width else WidthBehavior.ORIGINAL
-    )
     marshall_images(
         coordinates=coordinates,
         image=image,
         caption=None,
-        width=image_width,
+        layout_config=layout_config,
         proto_imgs=image_list_proto,
         clamp=False,
         channels="RGB",

streamlit/elements/toast.py

@@ -14,9 +14,9 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING, Literal, cast
 
-from streamlit.errors import StreamlitAPIException
+from streamlit.errors import StreamlitAPIException, StreamlitValueError
 from streamlit.proto.Toast_pb2 import Toast as ToastProto
 from streamlit.runtime.metrics_util import gather_metrics
 from streamlit.string_util import clean_text, validate_icon_or_emoji
@@ -41,6 +41,7 @@ class ToastMixin:
         body: SupportsStr,
         *,  # keyword-only args:
         icon: str | None = None,
+        duration: Literal["short", "long", "infinite"] | int = "short",
     ) -> DeltaGenerator:
         """Display a short message, known as a notification "toast".
         The toast appears in the app's top-right corner and disappears after four seconds.
@@ -79,16 +80,91 @@ class ToastMixin:
               <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
               font library.
 
+        duration : "short", "long", "infinite", or int
+            The time to display the toast message. This can be one of the
+            following:
 
-        Example
-        -------
+            - ``"short"`` (default): Displays for 4 seconds.
+            - ``"long"``: Displays for 10 seconds.
+            - ``"infinite"``: Shows the toast until the user dismisses it.
+            - An integer: Displays for the specified number of seconds.
+
+        Examples
+        --------
+        **Example 1: Show a toast message**
+
+        >>> import streamlit as st
+        >>>
+        >>> st.toast("Your edited image was saved!", icon="😍")
+
+        .. output::
+            https://doc-status-toast.streamlit.app
+            height: 200px
+
+        **Example 2: Show multiple toasts**
+
+        When multiple toasts are generated, they will stack. Hovering over a
+        toast will stop it from disappearing. When hovering ends, the toast
+        will disappear after time specified in ``duration``.
+
+        >>> import time
         >>> import streamlit as st
         >>>
-        >>> st.toast('Your edited image was saved!', icon='😍')
+        >>> if st.button("Three cheers"):
+        >>>     st.toast("Hip!")
+        >>>     time.sleep(0.5)
+        >>>     st.toast("Hip!")
+        >>>     time.sleep(0.5)
+        >>>     st.toast("Hooray!", icon="🎉")
+
+        .. output::
+            https://doc-status-toast1.streamlit.app
+            height: 300px
+
+        **Example 3: Update a toast message**
+
+        Toast messages can also be updated. Assign ``st.toast(my_message)`` to
+        a variable and use the ``.toast()`` method to update it. If a toast has
+        already disappeared or been dismissed, the update will not be seen.
+
+        >>> import time
+        >>> import streamlit as st
+        >>>
+        >>> def cook_breakfast():
+        >>>     msg = st.toast("Gathering ingredients...")
+        >>>     time.sleep(1)
+        >>>     msg.toast("Cooking...")
+        >>>     time.sleep(1)
+        >>>     msg.toast("Ready!", icon="🥞")
+        >>>
+        >>> if st.button("Cook breakfast"):
+        >>>     cook_breakfast()
+
+        .. output::
+            https://doc-status-toast2.streamlit.app
+            height: 200px
+
         """
         toast_proto = ToastProto()
         toast_proto.body = clean_text(validate_text(body))
         toast_proto.icon = validate_icon_or_emoji(icon)
+
+        if duration in ["short", "long", "infinite"] or (
+            isinstance(duration, int) and duration > 0
+        ):
+            if duration == "short":
+                toast_proto.duration = 4
+            elif duration == "long":
+                toast_proto.duration = 10
+            elif duration == "infinite":
+                toast_proto.duration = 0
+            else:
+                toast_proto.duration = duration
+        else:
+            raise StreamlitValueError(
+                "duration", ["short", "long", "infinite", "a positive integer"]
+            )
+
         return self.dg._enqueue("toast", toast_proto)
 
     @property

streamlit/elements/vega_charts.py

@@ -387,18 +387,14 @@ def _convert_altair_to_vega_lite_spec(
     alt.data_transformers.register("id", id_transform)  # type: ignore[arg-type,attr-defined,unused-ignore]
 
     # alt.themes was deprecated in Altair 5.5.0 in favor of alt.theme
-    altair_theme = (
-        alt.themes if type_util.is_altair_version_less_than("5.5.0") else alt.theme
+    alt_theme = (
+        alt.themes if type_util.is_altair_version_less_than("5.5.0") else alt.theme  # ty: ignore[unresolved-attribute]
     )
 
     # The default altair theme has some width/height defaults defined
     # which are not useful for Streamlit. Therefore, we change the theme to
     # "none" to avoid those defaults.
-    with (
-        altair_theme.enable("none")
-        if altair_theme.active == "default"
-        else nullcontext()
-    ):  # type: ignore[attr-defined,unused-ignore]
+    with alt_theme.enable("none") if alt_theme.active == "default" else nullcontext():  # ty: ignore
         with alt.data_transformers.enable("id"):  # type: ignore[attr-defined,unused-ignore]
             chart_dict = altair_chart.to_dict()
 
@@ -2083,7 +2079,6 @@ class VegaChartsMixin:
             vega_lite_proto.id = compute_and_register_element_id(
                 "arrow_vega_lite_chart",
                 user_key=key,
-                form_id=vega_lite_proto.form_id,
                 dg=self.dg,
                 vega_lite_spec=vega_lite_proto.spec,
                 # The data is either in vega_lite_proto.data.data

streamlit/elements/widgets/audio_input.py

@@ -239,7 +239,6 @@ class AudioInputMixin:
         element_id = compute_and_register_element_id(
             "audio_input",
             user_key=key,
-            form_id=current_form_id(self.dg),
             dg=self.dg,
             label=label,
             help=help,

streamlit/elements/widgets/button.py

@@ -914,8 +914,6 @@ class ButtonMixin:
         element_id = compute_and_register_element_id(
             "download_button",
             user_key=key,
-            # download_button is not allowed to be used in a form.
-            form_id=None,
             dg=self.dg,
             label=label,
             icon=icon,
@@ -1123,8 +1121,6 @@ class ButtonMixin:
         element_id = compute_and_register_element_id(
             "button",
             user_key=key,
-            # Only the
-            form_id=form_id,
             dg=self.dg,
             label=label,
             icon=icon,

streamlit/elements/widgets/button_group.py

@@ -1031,7 +1031,6 @@ class ButtonGroupMixin:
 
         check_widget_policies(self.dg, key, on_change, default_value=_default)
 
-        widget_name = "button_group"
         ctx = get_script_run_ctx()
         form_id = current_form_id(self.dg)
         formatted_options = (
@@ -1042,10 +1041,12 @@ class ButtonGroupMixin:
                 for index, _ in enumerate(indexable_options)
             ]
         )
+
         element_id = compute_and_register_element_id(
-            widget_name,
+            # The borderless style is used by st.feedback, but users expect to see
+            # "feedback" in errors
+            "feedback" if style == "borderless" else style,
             user_key=key,
-            form_id=form_id,
             dg=self.dg,
             options=formatted_options,
             default=default,
@@ -1088,7 +1089,7 @@ class ButtonGroupMixin:
         if ctx:
             save_for_app_testing(ctx, element_id, format_func)
 
-        self.dg._enqueue(widget_name, proto, layout_config=layout_config)
+        self.dg._enqueue("button_group", proto, layout_config=layout_config)
 
         return widget_state