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

streamlit/elements/widgets/audio_input.py

@@ -16,9 +16,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from textwrap import dedent
-from typing import TYPE_CHECKING, Union, cast
-
-from typing_extensions import TypeAlias
+from typing import TYPE_CHECKING, TypeAlias, cast
 
 from streamlit.elements.lib.file_uploader_utils import enforce_filename_restriction
 from streamlit.elements.lib.form_utils import current_form_id
@@ -53,7 +51,7 @@ if TYPE_CHECKING:
     from streamlit.delta_generator import DeltaGenerator
     from streamlit.elements.lib.layout_utils import WidthWithoutContent
 
-SomeUploadedAudioFile: TypeAlias = Union[UploadedFile, DeletedFile, None]
+SomeUploadedAudioFile: TypeAlias = UploadedFile | DeletedFile | None
 
 # Allowed sample rates for audio recording
 ALLOWED_SAMPLE_RATES = {8000, 11025, 16000, 22050, 24000, 32000, 44100, 48000}
@@ -131,13 +129,14 @@ class AudioInputMixin:
             .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
 
         sample_rate : int or None
-            The target sample rate for the audio recording in Hz.
-            This defaults to 16000 Hz, which is optimal for speech recognition.
+            The target sample rate for the audio recording in Hz. This
+            defaults to ``16000``, which is optimal for speech recognition.
 
-            The following sample rates are supported: 8000, 11025, 16000,
-            22050, 24000, 32000, 44100, or 48000. If this is ``None``, the
-            widget uses the browser's default sample rate (typically 44100 or
-            48000 Hz).
+            The following values are supported: ``8000`` (telephone quality),
+            ``11025``, ``16000`` (speech-recognition quality), ``22050``,
+            ``24000``, ``32000``, ``44100``, ``48000`` (high-quality), or
+            ``None``. If this is ``None``, the widget uses the browser's
+            default sample rate (typically 44100 or 48000 Hz).
 
         key : str or int
             An optional string or integer to use as the unique key for the widget.
@@ -282,11 +281,13 @@ class AudioInputMixin:
         element_id = compute_and_register_element_id(
             "audio_input",
             user_key=key,
-            key_as_main_identity=False,
+            # Treat the provided key as the main identity.
+            key_as_main_identity=True,
             dg=self.dg,
             label=label,
             help=help,
             width=width,
+            sample_rate=sample_rate,
         )
 
         audio_input_proto = AudioInputProto()

streamlit/elements/widgets/button.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 
 import io
 import os
+from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
 from textwrap import dedent
@@ -25,16 +26,15 @@ from typing import (
     Final,
     Literal,
     TextIO,
-    Union,
+    TypeAlias,
     cast,
 )
 
-from typing_extensions import TypeAlias
-
 from streamlit import runtime
 from streamlit.elements.lib.form_utils import current_form_id, is_in_form
 from streamlit.elements.lib.layout_utils import LayoutConfig, Width, validate_width
 from streamlit.elements.lib.policies import check_widget_policies
+from streamlit.elements.lib.shortcut_utils import normalize_shortcut
 from streamlit.elements.lib.utils import (
     Key,
     compute_and_register_element_id,
@@ -52,6 +52,7 @@ from streamlit.proto.Button_pb2 import Button as ButtonProto
 from streamlit.proto.DownloadButton_pb2 import DownloadButton as DownloadButtonProto
 from streamlit.proto.LinkButton_pb2 import LinkButton as LinkButtonProto
 from streamlit.proto.PageLink_pb2 import PageLink as PageLinkProto
+from streamlit.runtime.download_data_util import convert_data_to_bytes_and_infer_mime
 from streamlit.runtime.metrics_util import gather_metrics
 from streamlit.runtime.pages_manager import PagesManager
 from streamlit.runtime.scriptrunner import ScriptRunContext, get_script_run_ctx
@@ -61,12 +62,14 @@ from streamlit.runtime.state import (
     WidgetKwargs,
     register_widget,
 )
+from streamlit.runtime.state.query_params import process_query_params
 from streamlit.string_util import validate_icon_or_emoji
 from streamlit.url_util import is_url
 from streamlit.util import in_sidebar
 
 if TYPE_CHECKING:
     from streamlit.delta_generator import DeltaGenerator
+    from streamlit.runtime.state.query_params import QueryParamsInput
 
 FORM_DOCS_INFO: Final = """
 
@@ -74,7 +77,14 @@ For more information, refer to the
 [documentation for forms](https://docs.streamlit.io/develop/api-reference/execution-flow/st.form).
 """
 
-DownloadButtonDataType: TypeAlias = Union[str, bytes, TextIO, BinaryIO, io.RawIOBase]
+DownloadButtonDataType: TypeAlias = (
+    str
+    | bytes
+    | TextIO
+    | BinaryIO
+    | io.RawIOBase
+    | Callable[[], str | bytes | TextIO | BinaryIO | io.RawIOBase]
+)
 
 
 @dataclass
@@ -102,6 +112,7 @@ class ButtonMixin:
         disabled: bool = False,
         use_container_width: bool | None = None,
         width: Width = "content",
+        shortcut: str | None = None,
     ) -> bool:
         r"""Display a button widget.
 
@@ -175,6 +186,8 @@ class ButtonMixin:
               <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
               font library.
 
+            - ``"spinner"``: Displays a spinner as an icon.
+
         disabled : bool
             An optional boolean that disables the button if set to ``True``.
             The default is ``False``.
@@ -207,6 +220,33 @@ class ButtonMixin:
               the parent container, the width of the button matches the width
               of the parent container.
 
+        shortcut : str or None
+            An optional keyboard shortcut that triggers the button. This can be
+            one of the following strings:
+
+            - A single alphanumeric key like ``"K"`` or ``"4"``.
+            - A function key like ``"F11"``.
+            - A special key like ``"Enter"``, ``"Esc"``, or ``"Tab"``.
+            - Any of the above combined with modifiers. For example, you can use
+              ``"Ctrl+K"`` or ``"Cmd+Shift+O"``.
+
+            .. important::
+                The keys ``"C"`` and ``"R"`` are reserved and can't be used,
+                even with modifiers. Punctuation keys like ``"."`` and ``","``
+                aren't currently supported.
+
+            The following special keys are supported: Backspace, Delete, Down,
+            End, Enter, Esc, Home, Left, PageDown, PageUp, Right, Space, Tab,
+            and Up.
+
+            The following modifiers are supported: Alt, Ctrl, Cmd, Meta, Mod,
+            Option, Shift.
+
+            - Ctrl, Cmd, Meta, and Mod are interchangeable and will display to
+              the user to match their platform.
+            - Option and Alt are interchangeable and will display to the user
+              to match their platform.
+
         Returns
         -------
         bool
@@ -251,6 +291,25 @@ class ButtonMixin:
            https://doc-button-icons.streamlit.app/
            height: 220px
 
+        **Example 3: Use keyboard shortcuts**
+
+        The following example shows how to use keyboard shortcuts to trigger a
+        button. If you use any of the platform-dependent modifiers (Ctrl, Cmd,
+        or Mod), they are interpreted interchangeably and always displayed to
+        the user to match their platform.
+
+        >>> import streamlit as st
+        >>>
+        >>> with st.container(horizontal=True, horizontal_alignment="distribute"):
+        >>>     "`A`" if st.button("A", shortcut="A") else "` `"
+        >>>     "`S`" if st.button("S", shortcut="Ctrl+S") else "` `"
+        >>>     "`D`" if st.button("D", shortcut="Cmd+Shift+D") else "` `"
+        >>>     "`F`" if st.button("F", shortcut="Mod+Alt+Shift+F") else "` `"
+
+        .. output::
+           https://doc-button-shortcuts.streamlit.app/
+           height: 220px
+
         """
         key = to_key(key)
         ctx = get_script_run_ctx()
@@ -278,6 +337,7 @@ class ButtonMixin:
             icon=icon,
             ctx=ctx,
             width=width,
+            shortcut=shortcut,
         )
 
     @gather_metrics("download_button")
@@ -298,15 +358,18 @@ class ButtonMixin:
         disabled: bool = False,
         use_container_width: bool | None = None,
         width: Width = "content",
+        shortcut: str | None = None,
     ) -> bool:
         r"""Display a download button widget.
 
         This is useful when you would like to provide a way for your users
         to download a file directly from your app.
 
-        Note that the data to be downloaded is stored in-memory while the
-        user is connected, so it's a good idea to keep file sizes under a
-        couple hundred megabytes to conserve memory.
+        If you pass the data directly to the ``data`` parameter, then the data
+        is stored in-memory while the user is connected. It's a good idea to
+        keep file sizes under a couple hundred megabytes to conserve memory or
+        use deferred data generation by passing a callable to the ``data``
+        parameter.
 
         If you want to prevent your app from rerunning when a user clicks the
         download button, wrap the download button in a `fragment
@@ -332,10 +395,22 @@ class ButtonMixin:
             .. |st.markdown| replace:: ``st.markdown``
             .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
 
-        data : str, bytes, or file
-            The contents of the file to be downloaded.
+        data : str, bytes, file-like, or callable
+            The contents of the file to be downloaded or a callable that
+            returns the contents of the file.
+
+            File contents can be a string, bytes, or file-like object.
+            File-like objects include ``io.BytesIO``, ``io.StringIO``, or any
+            class that implements the abstract base class ``io.RawIOBase``.
 
-            To prevent unncecessary recomputation, use caching when converting
+            If a callable is passed, it is executed when the user clicks
+            the download button and runs on a separate thread from the
+            resulting script rerun. This deferred generation is helpful for
+            large files to avoid blocking the page script. The callable can't
+            accept any arguments. If any Streamlit commands are executed inside
+            the callable, they will be ignored.
+
+            To prevent unnecessary recomputation, use caching when converting
             your data for download. For more information, see the Example 1
             below.
 
@@ -419,6 +494,8 @@ class ButtonMixin:
               <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
               font library.
 
+            - ``"spinner"``: Displays a spinner as an icon.
+
         disabled : bool
             An optional boolean that disables the download button if set to
             ``True``. The default is ``False``.
@@ -451,6 +528,27 @@ class ButtonMixin:
               the parent container, the width of the button matches the width
               of the parent container.
 
+        shortcut : str or None
+            An optional keyboard shortcut that triggers the button. This can be
+            one of the following strings:
+
+            - A single alphanumeric key like ``"K"`` or ``"4"``.
+            - A function key like ``"F11"``.
+            - A special key like ``"Enter"``, ``"Esc"``, or ``"Tab"``.
+            - Any of the above combined with modifiers. For example, you can use
+              ``"Ctrl+K"`` or ``"Cmd+Shift+O"``.
+
+            .. important::
+                The keys ``"C"`` and ``"R"`` are reserved and can't be used,
+                even with modifiers. Punctuation keys like ``"."`` and ``","``
+                aren't currently supported.
+
+            For a list of supported keys and modifiers, see the documentation
+            for |st.button|_.
+
+            .. |st.button| replace:: ``st.button``
+            .. _st.button: https://docs.streamlit.io/develop/api-reference/widgets/st.button
+
         Returns
         -------
         bool
@@ -561,6 +659,31 @@ class ButtonMixin:
            https://doc-download-button-file.streamlit.app/
            height: 200px
 
+        **Example 4: Generate the data on-click with a callable**
+
+        Pass a callable to ``data`` to generate the bytes lazily when the user
+        clicks the button. Streamlit commands inside this callable are ignored.
+        The callable can't accept any arguments and must return a file-like
+        object.
+
+        >>> import streamlit as st
+        >>> import time
+        >>>
+        >>> def make_report():
+        >>>     time.sleep(1)
+        >>>     return "col1,col2\n1,2\n3,4".encode("utf-8")
+        >>>
+        >>> st.download_button(
+        ...     label="Download report",
+        ...     data=make_report,
+        ...     file_name="report.csv",
+        ...     mime="text/csv",
+        ... )
+
+        .. output::
+           https://doc-download-button-deferred.streamlit.app/
+           height: 200px
+
         """
         ctx = get_script_run_ctx()
 
@@ -588,6 +711,7 @@ class ButtonMixin:
             disabled=disabled,
             ctx=ctx,
             width=width,
+            shortcut=shortcut,
         )
 
     @gather_metrics("link_button")
@@ -602,6 +726,7 @@ class ButtonMixin:
         disabled: bool = False,
         use_container_width: bool | None = None,
         width: Width = "content",
+        shortcut: str | None = None,
     ) -> DeltaGenerator:
         r"""Display a link button element.
 
@@ -667,6 +792,8 @@ class ButtonMixin:
               <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
               font library.
 
+            - ``"spinner"``: Displays a spinner as an icon.
+
         disabled : bool
             An optional boolean that disables the link button if set to
             ``True``. The default is ``False``.
@@ -699,6 +826,27 @@ class ButtonMixin:
               the parent container, the width of the button matches the width
               of the parent container.
 
+        shortcut : str or None
+            An optional keyboard shortcut that triggers the button. This can be
+            one of the following strings:
+
+            - A single alphanumeric key like ``"K"`` or ``"4"``.
+            - A function key like ``"F11"``.
+            - A special key like ``"Enter"``, ``"Esc"``, or ``"Tab"``.
+            - Any of the above combined with modifiers. For example, you can use
+              ``"Ctrl+K"`` or ``"Cmd+Shift+O"``.
+
+            .. important::
+                The keys ``"C"`` and ``"R"`` are reserved and can't be used,
+                even with modifiers. Punctuation keys like ``"."`` and ``","``
+                aren't currently supported.
+
+            For a list of supported keys and modifiers, see the documentation
+            for |st.button|_.
+
+            .. |st.button| replace:: ``st.button``
+            .. _st.button: https://docs.streamlit.io/develop/api-reference/widgets/st.button
+
         Example
         -------
         >>> import streamlit as st
@@ -728,6 +876,7 @@ class ButtonMixin:
             type=type,
             icon=icon,
             width=width,
+            shortcut=shortcut,
         )
 
     @gather_metrics("page_link")
@@ -741,6 +890,7 @@ class ButtonMixin:
         disabled: bool = False,
         use_container_width: bool | None = None,
         width: Width = "content",
+        query_params: QueryParamsInput | None = None,
     ) -> DeltaGenerator:
         r"""Display a link to another page in a multipage app or to an external page.
 
@@ -795,6 +945,8 @@ class ButtonMixin:
               <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
               font library.
 
+            - ``"spinner"``: Displays a spinner as an icon.
+
         help : str or None
             A tooltip that gets displayed when the link is hovered over. If
             this is ``None`` (default), no tooltip is displayed.
@@ -831,15 +983,27 @@ class ButtonMixin:
               the parent container, the width of the button matches the width
               of the parent container.
 
+        query_params : dict, list of tuples, or None
+            Query parameters to apply when navigating to the target page.
+            This can be a dictionary or an iterable of key-value tuples. Values can
+            be strings or iterables of strings (for repeated keys). When this is
+            ``None`` (default), all non-embed query parameters are cleared during
+            navigation.
+
         Example
         -------
-        Consider the following example given this file structure:
+        **Example 1: Basic usage**
 
-        >>> your-repository/
-        >>> ├── pages/
-        >>> │   ├── page_1.py
-        >>> │   └── page_2.py
-        >>> └── your_app.py
+        The following example shows how to create page links in a multipage app
+        that uses the ``pages/`` directory:
+
+        .. code-block:: text
+
+            your-repository/
+            ├── pages/
+            │   ├── page_1.py
+            │   └── page_2.py
+            └── your_app.py
 
         >>> import streamlit as st
         >>>
@@ -856,10 +1020,34 @@ class ButtonMixin:
         .. |client.showSidebarNavigation| replace:: ``client.showSidebarNavigation``
         .. _client.showSidebarNavigation: https://docs.streamlit.io/develop/api-reference/configuration/config.toml#client
 
-        .. output ::
+        .. output::
             https://doc-page-link.streamlit.app/
             height: 350px
 
+        **Example 2: Passing query parameters**
+
+        The following example shows how to pass query parameters when creating a
+        page link in a multipage app:
+
+        .. code-block:: text
+
+            your-repository/
+            ├── page_2.py
+            └── your_app.py
+
+        >>> import streamlit as st
+        >>>
+        >>> def page_1():
+        >>>     st.title("Page 1")
+        >>>     st.page_link("page_2.py", query_params={"utm_source": "page_1"})
+        >>>
+        >>> pg = st.navigation([page_1, "page_2.py"])
+        >>> pg.run()
+
+        .. output::
+            https://doc-page-link-query-params.streamlit.app/
+            height: 350px
+
         """
         if use_container_width is not None:
             width = "stretch" if use_container_width else "content"
@@ -875,6 +1063,7 @@ class ButtonMixin:
             help=help,
             disabled=disabled,
             width=width,
+            query_params=query_params,
         )
 
     def _download_button(
@@ -894,6 +1083,7 @@ class ButtonMixin:
         disabled: bool = False,
         ctx: ScriptRunContext | None = None,
         width: Width = "content",
+        shortcut: str | None = None,
     ) -> bool:
         key = to_key(key)
 
@@ -903,6 +1093,10 @@ class ButtonMixin:
             else cast("WidgetCallback", on_click)
         )
 
+        normalized_shortcut: str | None = None
+        if shortcut is not None:
+            normalized_shortcut = normalize_shortcut(shortcut)
+
         check_widget_policies(
             self.dg,
             key,
@@ -923,6 +1117,7 @@ class ButtonMixin:
             help=help,
             type=type,
             width=width,
+            shortcut=normalized_shortcut,
         )
 
         if is_in_form(self.dg):
@@ -951,6 +1146,9 @@ class ButtonMixin:
         else:
             download_button_proto.ignore_rerun = False
 
+        if normalized_shortcut is not None:
+            download_button_proto.shortcut = normalized_shortcut
+
         serde = ButtonSerde()
 
         button_state = register_widget(
@@ -981,8 +1179,30 @@ class ButtonMixin:
         icon: str | None = None,
         disabled: bool = False,
         width: Width = "content",
+        shortcut: str | None = None,
     ) -> DeltaGenerator:
         link_button_proto = LinkButtonProto()
+        normalized_shortcut: str | None = None
+        if shortcut is not None:
+            normalized_shortcut = normalize_shortcut(shortcut)
+
+        if normalized_shortcut is not None:
+            # We only register the element ID if a shortcut is provide.
+            # The ID is required to correctly register and handle the shortcut
+            # on the client side.
+            link_button_proto.id = compute_and_register_element_id(
+                "link_button",
+                user_key=None,
+                key_as_main_identity=False,
+                dg=self.dg,
+                label=label,
+                icon=icon,
+                url=url,
+                help=help,
+                type=type,
+                width=width,
+                shortcut=normalized_shortcut,
+            )
         link_button_proto.label = label
         link_button_proto.url = url
         link_button_proto.type = type
@@ -994,6 +1214,9 @@ class ButtonMixin:
         if icon is not None:
             link_button_proto.icon = validate_icon_or_emoji(icon)
 
+        if normalized_shortcut is not None:
+            link_button_proto.shortcut = normalized_shortcut
+
         validate_width(width, allow_content=True)
         layout_config = LayoutConfig(width=width)
         return self.dg._enqueue(
@@ -1009,8 +1232,12 @@ class ButtonMixin:
         help: str | None = None,
         disabled: bool = False,
         width: Width = "content",
+        query_params: QueryParamsInput | None = None,
     ) -> DeltaGenerator:
         page_link_proto = PageLinkProto()
+        if query_params:
+            page_link_proto.query_string = process_query_params(query_params)
+
         validate_width(width, allow_content=True)
 
         ctx = get_script_run_ctx()
@@ -1105,9 +1332,14 @@ class ButtonMixin:
         disabled: bool = False,
         ctx: ScriptRunContext | None = None,
         width: Width = "content",
+        shortcut: str | None = None,
     ) -> bool:
         key = to_key(key)
 
+        normalized_shortcut: str | None = None
+        if shortcut is not None:
+            normalized_shortcut = normalize_shortcut(shortcut)
+
         check_widget_policies(
             self.dg,
             key,
@@ -1130,6 +1362,7 @@ class ButtonMixin:
             is_form_submitter=is_form_submitter,
             type=type,
             width=width,
+            shortcut=normalized_shortcut,
         )
 
         # It doesn't make sense to create a button inside a form (except
@@ -1162,6 +1395,9 @@ class ButtonMixin:
         if icon is not None:
             button_proto.icon = validate_icon_or_emoji(icon)
 
+        if normalized_shortcut is not None:
+            button_proto.shortcut = normalized_shortcut
+
         serde = ButtonSerde()
 
         button_state = register_widget(
@@ -1197,32 +1433,33 @@ def marshall_file(
     mimetype: str | None,
     file_name: str | None = None,
 ) -> None:
-    data_as_bytes: bytes
-    if isinstance(data, str):
-        data_as_bytes = data.encode()
-        mimetype = mimetype or "text/plain"
-    elif isinstance(data, io.TextIOWrapper):
-        string_data = data.read()
-        data_as_bytes = string_data.encode()
-        mimetype = mimetype or "text/plain"
-    # Assume bytes; try methods until we run out.
-    elif isinstance(data, bytes):
-        data_as_bytes = data
-        mimetype = mimetype or "application/octet-stream"
-    elif isinstance(data, io.BytesIO):
-        data.seek(0)
-        data_as_bytes = data.getvalue()
-        mimetype = mimetype or "application/octet-stream"
-    elif isinstance(data, io.BufferedReader):
-        data.seek(0)
-        data_as_bytes = data.read()
-        mimetype = mimetype or "application/octet-stream"
-    elif isinstance(data, io.RawIOBase):
-        data.seek(0)
-        data_as_bytes = data.read() or b""
-        mimetype = mimetype or "application/octet-stream"
-    else:
-        raise StreamlitAPIException(f"Invalid binary data format: {type(data)}")
+    # Check if data is a callable (for deferred downloads)
+    if callable(data):
+        if not runtime.exists():
+            # When running in "raw mode", we can't access the MediaFileManager.
+            proto_download_button.url = ""
+            return
+
+        # Register the callable for deferred execution
+        file_id = runtime.get_instance().media_file_mgr.add_deferred(
+            data,
+            mimetype,
+            coordinates,
+            file_name=file_name,
+        )
+        proto_download_button.deferred_file_id = file_id
+        proto_download_button.url = ""  # No URL yet, will be generated on click
+        return
+
+    # Existing logic for non-callable data
+    data_as_bytes, inferred_mime_type = convert_data_to_bytes_and_infer_mime(
+        data,
+        unsupported_error=StreamlitAPIException(
+            f"Invalid binary data format: {type(data)}"
+        ),
+    )
+    if mimetype is None:
+        mimetype = inferred_mime_type
 
     if runtime.exists():
         file_url = runtime.get_instance().media_file_mgr.add(