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

streamlit/elements/media.py

@@ -23,7 +23,6 @@ from typing import TYPE_CHECKING, Final, Union, cast
 from typing_extensions import TypeAlias
 
 from streamlit import runtime, type_util, url_util
-from streamlit.elements.lib.form_utils import current_form_id
 from streamlit.elements.lib.layout_utils import WidthWithoutContent, validate_width
 from streamlit.elements.lib.subtitle_utils import process_subtitle_data
 from streamlit.elements.lib.utils import compute_and_register_element_id
@@ -210,6 +209,7 @@ class MediaMixin:
             )
         coordinates = self.dg._get_delta_path_str()
         marshall_audio(
+            self.dg,
             coordinates,
             audio_proto,
             data,
@@ -219,7 +219,6 @@ class MediaMixin:
             end_time,
             loop,
             autoplay,
-            form_id=current_form_id(self.dg),
             width=width,
         )
         return self.dg._enqueue("audio", audio_proto)
@@ -389,6 +388,7 @@ class MediaMixin:
         video_proto = VideoProto()
         coordinates = self.dg._get_delta_path_str()
         marshall_video(
+            self.dg,
             coordinates,
             video_proto,
             data,
@@ -399,7 +399,6 @@ class MediaMixin:
             loop,
             autoplay,
             muted,
-            form_id=current_form_id(self.dg),
             width=width,
         )
         return self.dg._enqueue("video", video_proto)
@@ -500,6 +499,7 @@ def _marshall_av_media(
 
 
 def marshall_video(
+    dg: DeltaGenerator,
     coordinates: str,
     proto: VideoProto,
     data: MediaData,
@@ -510,7 +510,6 @@ def marshall_video(
     loop: bool = False,
     autoplay: bool = False,
     muted: bool = False,
-    form_id: str | None = None,
     width: WidthWithoutContent = "stretch",
 ) -> None:
     """Marshalls a video proto, using url processors as needed.
@@ -555,9 +554,6 @@ def marshall_video(
     muted: bool
         Whether the video should play with the audio silenced. This can be used to
         enable autoplay without user interaction. Defaults to False.
-    form_id: str | None
-        The ID of the form that this element is placed in. Provide None if
-        the element is not placed in a form.
     width: int or "stretch"
         The width of the video player. This can be one of the following:
         - An int: The width in pixels, e.g. 200 for a width of 200 pixels.
@@ -643,7 +639,7 @@ def marshall_video(
             "video",
             # video does not yet allow setting a user-defined key
             user_key=None,
-            form_id=form_id,
+            dg=dg,
             url=proto.url,
             mimetype=mimetype,
             start_time=start_time,
@@ -763,6 +759,7 @@ def _maybe_convert_to_wav_bytes(data: MediaData, sample_rate: int | None) -> Med
 
 
 def marshall_audio(
+    dg: DeltaGenerator,
     coordinates: str,
     proto: AudioProto,
     data: MediaData,
@@ -772,7 +769,6 @@ def marshall_audio(
     end_time: int | None = None,
     loop: bool = False,
     autoplay: bool = False,
-    form_id: str | None = None,
     width: WidthWithoutContent = "stretch",
 ) -> None:
     """Marshalls an audio proto, using data and url processors as needed.
@@ -800,9 +796,6 @@ def marshall_audio(
     autoplay : bool
         Whether the audio should start playing automatically.
         Browsers will not autoplay audio files if the user has not interacted with the page yet.
-    form_id: str | None
-        The ID of the form that this element is placed in. Provide None if
-        the element is not placed in a form.
     width: int or "stretch"
         The width of the audio player. This can be one of the following:
         - An int: The width in pixels, e.g. 200 for a width of 200 pixels.
@@ -838,7 +831,7 @@ def marshall_audio(
         proto.id = compute_and_register_element_id(
             "audio",
             user_key=None,
-            form_id=form_id,
+            dg=dg,
             url=proto.url,
             mimetype=mimetype,
             start_time=start_time,

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",