streamlit-nightly 1.43.2.dev20250307__py3-none-any.whl

streamlit/elements/pyplot.py

@@ -0,0 +1,194 @@
+# 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.
+
+"""Streamlit support for Matplotlib PyPlot charts."""
+
+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.proto.Image_pb2 import ImageList as ImageListProto
+from streamlit.runtime.metrics_util import gather_metrics
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+    from streamlit.delta_generator import DeltaGenerator
+
+
+class PyplotMixin:
+    @gather_metrics("pyplot")
+    def pyplot(
+        self,
+        fig: Figure | None = None,
+        clear_figure: bool | None = None,
+        use_container_width: bool = True,
+        **kwargs: Any,
+    ) -> DeltaGenerator:
+        """Display a matplotlib.pyplot figure.
+
+        .. Important::
+            You must install ``matplotlib`` to use this command.
+
+        Parameters
+        ----------
+        fig : Matplotlib Figure
+            The Matplotlib ``Figure`` object to render. See
+            https://matplotlib.org/stable/gallery/index.html for examples.
+
+            .. note::
+                When this argument isn't specified, this function will render the global
+                Matplotlib figure object. However, this feature is deprecated and
+                will be removed in a later version.
+
+        clear_figure : bool
+            If True, the figure will be cleared after being rendered.
+            If False, the figure will not be cleared after being rendered.
+            If left unspecified, we pick a default based on the value of ``fig``.
+
+            - If ``fig`` is set, defaults to ``False``.
+
+            - If ``fig`` is not set, defaults to ``True``. This simulates Jupyter's
+              approach to matplotlib rendering.
+
+        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``
+            (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.
+
+        **kwargs : any
+            Arguments to pass to Matplotlib's savefig function.
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>> import matplotlib.pyplot as plt
+        >>> import numpy as np
+        >>>
+        >>> arr = np.random.normal(1, 1, size=100)
+        >>> fig, ax = plt.subplots()
+        >>> ax.hist(arr, bins=20)
+        >>>
+        >>> st.pyplot(fig)
+
+        .. output::
+           https://doc-pyplot.streamlit.app/
+           height: 630px
+
+        Matplotlib supports several types of "backends". If you're getting an
+        error using Matplotlib with Streamlit, try setting your backend to "TkAgg"::
+
+            echo "backend: TkAgg" >> ~/.matplotlib/matplotlibrc
+
+        For more information, see https://matplotlib.org/faq/usage_faq.html.
+
+        """
+
+        if not fig:
+            show_deprecation_warning("""
+Calling `st.pyplot()` without providing a figure argument has been deprecated
+and will be removed in a later version as it requires the use of Matplotlib's
+global figure object, which is not thread-safe.
+
+To future-proof this code, you should pass in a figure as shown below:
+
+```python
+fig, ax = plt.subplots()
+ax.scatter([1, 2, 3], [1, 2, 3])
+# other plotting actions...
+st.pyplot(fig)
+```
+
+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).
+""")
+
+        image_list_proto = ImageListProto()
+        marshall(
+            self.dg._get_delta_path_str(),
+            image_list_proto,
+            fig,
+            clear_figure,
+            use_container_width,
+            **kwargs,
+        )
+        return self.dg._enqueue("imgs", image_list_proto)
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        """Get our DeltaGenerator."""
+        return cast("DeltaGenerator", self)
+
+
+def marshall(
+    coordinates: str,
+    image_list_proto: ImageListProto,
+    fig: Figure | None = None,
+    clear_figure: bool | None = True,
+    use_container_width: bool = True,
+    **kwargs: Any,
+) -> None:
+    try:
+        import matplotlib.pyplot as plt
+
+        plt.ioff()
+    except ImportError:
+        raise ImportError("pyplot() command requires matplotlib")
+
+    # You can call .savefig() on a Figure object or directly on the pyplot
+    # module, in which case you're doing it to the latest Figure.
+    if not fig:
+        if clear_figure is None:
+            clear_figure = True
+
+        fig = cast("Figure", plt)
+
+    # Normally, dpi is set to 'figure', and the figure's dpi is set to 100.
+    # So here we pick double of that to make things look good in a high
+    # DPI display.
+    options = {"bbox_inches": "tight", "dpi": 200, "format": "png"}
+
+    # If some options are passed in from kwargs then replace the values in
+    # options with the ones from kwargs
+    options = {a: kwargs.get(a, b) for a, b in options.items()}
+    # Merge options back into kwargs.
+    kwargs.update(options)
+
+    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,
+        proto_imgs=image_list_proto,
+        clamp=False,
+        channels="RGB",
+        output_format="PNG",
+    )
+
+    # Clear the figure after rendering it. This means that subsequent
+    # plt calls will be starting fresh.
+    if clear_figure:
+        fig.clf()

streamlit/elements/snow.py

@@ -0,0 +1,47 @@
+# 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.proto.Snow_pb2 import Snow as SnowProto
+from streamlit.runtime.metrics_util import gather_metrics
+
+if TYPE_CHECKING:
+    from streamlit.delta_generator import DeltaGenerator
+
+
+class SnowMixin:
+    @gather_metrics("snow")
+    def snow(self) -> DeltaGenerator:
+        """Draw celebratory snowfall.
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>>
+        >>> st.snow()
+
+        ...then watch your app and get ready for a cool celebration!
+
+        """
+        snow_proto = SnowProto()
+        snow_proto.show = True
+        return self.dg._enqueue("snow", snow_proto)
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        """Get our DeltaGenerator."""
+        return cast("DeltaGenerator", self)

streamlit/elements/spinner.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
+
+import contextlib
+import threading
+from typing import TYPE_CHECKING
+
+import streamlit as st
+from streamlit.runtime.scriptrunner import add_script_run_ctx
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+@contextlib.contextmanager
+def spinner(
+    text: str = "In progress...",
+    *,
+    show_time: bool = False,
+    _cache: bool = False,
+) -> Iterator[None]:
+    """Display a loading spinner while executing a block of code.
+
+    Parameters
+    ----------
+    text : str
+        The text to display next to the spinner. This defaults to
+        ``"In progress..."``.
+
+        The text can optionally contain GitHub-flavored Markdown. Syntax
+        information can be found at: https://github.github.com/gfm.
+
+        See the ``body`` parameter of |st.markdown|_ for additional, supported
+        Markdown directives.
+
+        .. |st.markdown| replace:: ``st.markdown``
+        .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
+
+    show_time : bool
+        Whether to show the elapsed time next to the spinner text. If this is
+        ``False`` (default), no time is displayed. If this is ``True``,
+        elapsed time is displayed with a precision of 0.1 seconds. The time
+        format is not configurable.
+
+    Example
+    -------
+    >>> import streamlit as st
+    >>> import time
+    >>>
+    >>> with st.spinner("Wait for it...", show_time=True):
+    >>>     time.sleep(5)
+    >>> st.success("Done!")
+    >>> st.button("Rerun")
+
+    .. output ::
+        https://doc-spinner.streamlit.app/
+        height: 210px
+
+    """
+    from streamlit.proto.Spinner_pb2 import Spinner as SpinnerProto
+    from streamlit.string_util import clean_text
+
+    message = st.empty()
+
+    # Set the message 0.5 seconds in the future to avoid annoying
+    # flickering if this spinner runs too quickly.
+    DELAY_SECS = 0.5
+    display_message = True
+    display_message_lock = threading.Lock()
+
+    try:
+
+        def set_message():
+            with display_message_lock:
+                if display_message:
+                    spinner_proto = SpinnerProto()
+                    spinner_proto.text = clean_text(text)
+                    spinner_proto.cache = _cache
+                    spinner_proto.show_time = show_time
+                    message._enqueue("spinner", spinner_proto)
+
+        add_script_run_ctx(threading.Timer(DELAY_SECS, set_message)).start()
+
+        # Yield control back to the context.
+        yield
+    finally:
+        if display_message_lock:
+            with display_message_lock:
+                display_message = False
+            if "chat_message" in set(message._active_dg._ancestor_block_types):
+                # Temporary stale element fix:
+                # For chat messages, we are resetting the spinner placeholder to an
+                # empty container instead of an empty placeholder (st.empty) to have
+                # it removed from the delta path. Empty containers are ignored in the
+                # frontend since they are configured with allow_empty=False. This
+                # prevents issues with stale elements caused by the spinner being
+                # rendered only in some situations (e.g. for caching).
+                message.container()
+            else:
+                message.empty()

streamlit/elements/text.py

@@ -0,0 +1,76 @@
+# 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.proto.Text_pb2 import Text as TextProto
+from streamlit.runtime.metrics_util import gather_metrics
+from streamlit.string_util import clean_text
+
+if TYPE_CHECKING:
+    from streamlit.delta_generator import DeltaGenerator
+    from streamlit.type_util import SupportsStr
+
+
+class TextMixin:
+    @gather_metrics("text")
+    def text(
+        self,
+        body: SupportsStr,
+        *,  # keyword-only arguments:
+        help: str | None = None,
+    ) -> DeltaGenerator:
+        """Write text without Markdown or HTML parsing.
+
+        For monospace text, use |st.code|_.
+
+        .. |st.code| replace:: ``st.code``
+        .. _st.code: https://docs.streamlit.io/develop/api-reference/text/st.code
+
+        Parameters
+        ----------
+        body : str
+            The string to display.
+
+        help : str or None
+            A tooltip that gets displayed next to the text. If this is ``None``
+            (default), no tooltip is displayed.
+
+            The tooltip can optionally contain GitHub-flavored Markdown,
+            including the Markdown directives described in the ``body``
+            parameter of ``st.markdown``.
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>>
+        >>> st.text("This is text\\n[and more text](that's not a Markdown link).")
+
+        .. output ::
+            https://doc-text.streamlit.app/
+            height: 220px
+
+        """
+        text_proto = TextProto()
+        text_proto.body = clean_text(body)
+        if help:
+            text_proto.help = help
+        return self.dg._enqueue("text", text_proto)
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        """Get our DeltaGenerator."""
+        return cast("DeltaGenerator", self)

streamlit/elements/toast.py

@@ -0,0 +1,98 @@
+# 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.errors import StreamlitAPIException
+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
+
+if TYPE_CHECKING:
+    from streamlit.delta_generator import DeltaGenerator
+    from streamlit.type_util import SupportsStr
+
+
+def validate_text(toast_text: SupportsStr) -> SupportsStr:
+    if str(toast_text) == "":
+        raise StreamlitAPIException(
+            "Toast body cannot be blank - please provide a message."
+        )
+    else:
+        return toast_text
+
+
+class ToastMixin:
+    @gather_metrics("toast")
+    def toast(
+        self,
+        body: SupportsStr,
+        *,  # keyword-only args:
+        icon: str | None = None,
+    ) -> DeltaGenerator:
+        """Display a short message, known as a notification "toast".
+        The toast appears in the app's bottom-right corner and disappears after four seconds.
+
+        .. warning::
+            ``st.toast`` is not compatible with Streamlit's `caching \
+            <https://docs.streamlit.io/develop/concepts/architecture/caching>`_ and
+            cannot be called within a cached function.
+
+        Parameters
+        ----------
+        body : str
+            The string to display as GitHub-flavored Markdown. Syntax
+            information can be found at: https://github.github.com/gfm.
+
+            See the ``body`` parameter of |st.markdown|_ for additional,
+            supported Markdown directives.
+
+            .. |st.markdown| replace:: ``st.markdown``
+            .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
+
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            - A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            - An icon from the Material Symbols library (rounded style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
+              font library.
+
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>>
+        >>> st.toast('Your edited image was saved!', icon='😍')
+        """
+        toast_proto = ToastProto()
+        toast_proto.body = clean_text(validate_text(body))
+        toast_proto.icon = validate_icon_or_emoji(icon)
+        return self.dg._enqueue("toast", toast_proto)
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        """Get our DeltaGenerator."""
+        return cast("DeltaGenerator", self)