streamlit 1.49.1__py3-none-any.whl → 1.51.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
@@ -35,6 +33,7 @@ from streamlit.elements.lib.utils import (
     to_key,
 )
 from streamlit.elements.widgets.file_uploader import _get_upload_files
+from streamlit.errors import StreamlitAPIException
 from streamlit.proto.AudioInput_pb2 import AudioInput as AudioInputProto
 from streamlit.proto.Common_pb2 import FileUploaderState as FileUploaderStateProto
 from streamlit.proto.Common_pb2 import UploadedFileInfo as UploadedFileInfoProto
@@ -52,7 +51,10 @@ 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}
 
 
 @dataclass
@@ -90,6 +92,7 @@ class AudioInputMixin:
         self,
         label: str,
         *,
+        sample_rate: int | None = 16000,
         key: Key | None = None,
         help: str | None = None,
         on_change: WidgetCallback | None = None,
@@ -125,6 +128,15 @@ class AudioInputMixin:
             .. |st.markdown| replace:: ``st.markdown``
             .. _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 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).
+
         key : str or int
             An optional string or integer to use as the unique key for the widget.
             If this is omitted, a key will be generated for the widget
@@ -185,6 +197,10 @@ class AudioInputMixin:
 
         Examples
         --------
+        *Example 1:* Record a voice message and play it back.*
+
+        The default sample rate of 16000 Hz is optimal for speech recognition.
+
         >>> import streamlit as st
         >>>
         >>> audio_value = st.audio_input("Record a voice message")
@@ -196,10 +212,34 @@ class AudioInputMixin:
            https://doc-audio-input.streamlit.app/
            height: 260px
 
+        *Example 2:* Record high-fidelity audio and play it back.*
+
+        Higher sample rates can create higher-quality, larger audio files. This
+        might require a nicer microphone to fully appreciate the difference.
+
+        >>> import streamlit as st
+        >>>
+        >>> audio_value = st.audio_input("Record high quality audio", sample_rate=48000)
+        >>>
+        >>> if audio_value:
+        ...     st.audio(audio_value)
+
+        .. output::
+           https://doc-audio-input-high-rate.streamlit.app/
+           height: 260px
+
         """
+        # Validate sample_rate parameter
+        if sample_rate is not None and sample_rate not in ALLOWED_SAMPLE_RATES:
+            raise StreamlitAPIException(
+                f"Invalid sample_rate: {sample_rate}. "
+                f"Must be one of {sorted(ALLOWED_SAMPLE_RATES)} Hz, or None for browser default."
+            )
+
         ctx = get_script_run_ctx()
         return self._audio_input(
             label=label,
+            sample_rate=sample_rate,
             key=key,
             help=help,
             on_change=on_change,
@@ -214,6 +254,7 @@ class AudioInputMixin:
     def _audio_input(
         self,
         label: str,
+        sample_rate: int | None = 16000,
         key: Key | None = None,
         help: str | None = None,
         on_change: WidgetCallback | None = None,
@@ -239,10 +280,13 @@ class AudioInputMixin:
         element_id = compute_and_register_element_id(
             "audio_input",
             user_key=key,
+            # 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()
@@ -254,6 +298,10 @@ class AudioInputMixin:
             label_visibility
         )
 
+        # Set sample_rate in protobuf if specified
+        if sample_rate is not None:
+            audio_input_proto.sample_rate = sample_rate
+
         if label and help is not None:
             audio_input_proto.help = dedent(help)
 

streamlit/elements/widgets/button.py

@@ -25,12 +25,10 @@ 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
@@ -74,7 +72,7 @@ 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
 
 
 @dataclass
@@ -188,6 +186,12 @@ class ButtonMixin:
             In both cases, if the contents of the button are wider than the
             parent container, the contents will line wrap.
 
+            .. 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"``.
+
         width : "content", "stretch", or int
             The width of the button. This can be one of the following:
 
@@ -201,12 +205,6 @@ class ButtonMixin:
               the parent container, the width of the button matches the width
               of the parent container.
 
-        .. deprecated::
-            ``use_container_width`` is deprecated and will be removed in a
-            future release. For ``use_container_width=True``, use
-            ``width="stretch"``. For ``use_container_width=False``, use
-            ``width="content"``.
-
         Returns
         -------
         bool
@@ -432,6 +430,12 @@ class ButtonMixin:
             In both cases, if the contents of the button are wider than the
             parent container, the contents will line wrap.
 
+            .. 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"``.
+
         width : "content", "stretch", or int
             The width of the download button. This can be one of the following:
 
@@ -445,12 +449,6 @@ class ButtonMixin:
               the parent container, the width of the button matches the width
               of the parent container.
 
-        .. deprecated::
-            ``use_container_width`` is deprecated and will be removed in a
-            future release. For ``use_container_width=True``, use
-            ``width="stretch"``. For ``use_container_width=False``, use
-            ``width="content"``.
-
         Returns
         -------
         bool
@@ -680,6 +678,12 @@ class ButtonMixin:
             In both cases, if the contents of the button are wider than the
             parent container, the contents will line wrap.
 
+            .. 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"``.
+
         width : "content", "stretch", or int
             The width of the link button. This can be one of the following:
 
@@ -693,12 +697,6 @@ class ButtonMixin:
               the parent container, the width of the button matches the width
               of the parent container.
 
-        .. deprecated::
-            ``use_container_width`` is deprecated and will be removed in a
-            future release. For ``use_container_width=True``, use
-            ``width="stretch"``. For ``use_container_width=False``, use
-            ``width="content"``.
-
         Example
         -------
         >>> import streamlit as st
@@ -812,6 +810,12 @@ class ButtonMixin:
             The default is ``True`` for page links in the sidebar and ``False``
             for those in the main app.
 
+            .. 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"``.
+
         width : "content", "stretch", or int
             The width of the page-link button. This can be one of the following:
 
@@ -825,12 +829,6 @@ class ButtonMixin:
               the parent container, the width of the button matches the width
               of the parent container.
 
-        .. deprecated::
-            ``use_container_width`` is deprecated and will be removed in a
-            future release. For ``use_container_width=True``, use
-            ``width="stretch"``. For ``use_container_width=False``, use
-            ``width="content"``.
-
         Example
         -------
         Consider the following example given this file structure:
@@ -914,6 +912,7 @@ class ButtonMixin:
         element_id = compute_and_register_element_id(
             "download_button",
             user_key=key,
+            key_as_main_identity=True,
             dg=self.dg,
             label=label,
             icon=icon,
@@ -1119,8 +1118,9 @@ class ButtonMixin:
         # Only the form submitter button needs a form ID at the moment.
         form_id = current_form_id(self.dg) if is_form_submitter else ""
         element_id = compute_and_register_element_id(
-            "button",
+            "form_submit_button" if is_form_submitter else "button",
             user_key=key,
+            key_as_main_identity=True,
             dg=self.dg,
             label=label,
             icon=icon,

streamlit/elements/widgets/button_group.py

@@ -14,22 +14,20 @@
 
 from __future__ import annotations
 
-from collections.abc import Sequence
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
     Final,
     Generic,
     Literal,
+    TypeAlias,
     TypeVar,
     cast,
     overload,
 )
 
-from typing_extensions import TypeAlias
-
 from streamlit.elements.lib.form_utils import current_form_id
 from streamlit.elements.lib.layout_utils import (
     LayoutConfig,
@@ -276,6 +274,7 @@ class ButtonGroupMixin:
         options: Literal["thumbs"] = ...,
         *,
         key: Key | None = None,
+        default: int | None = None,
         disabled: bool = False,
         on_change: WidgetCallback | None = None,
         args: WidgetArgs | None = None,
@@ -288,6 +287,7 @@ class ButtonGroupMixin:
         options: Literal["faces", "stars"] = ...,
         *,
         key: Key | None = None,
+        default: int | None = None,
         disabled: bool = False,
         on_change: WidgetCallback | None = None,
         args: WidgetArgs | None = None,
@@ -300,6 +300,7 @@ class ButtonGroupMixin:
         options: Literal["thumbs", "faces", "stars"] = "thumbs",
         *,
         key: Key | None = None,
+        default: int | None = None,
         disabled: bool = False,
         on_change: WidgetCallback | None = None,
         args: WidgetArgs | None = None,
@@ -331,6 +332,14 @@ class ButtonGroupMixin:
             If this is omitted, a key will be generated for the widget
             based on its content. No two widgets may have the same key.
 
+        default : int or None
+            Default feedback value. This must be consistent with the feedback
+            type in ``options``:
+
+            - 0 or 1 if ``options="thumbs"``.
+            - Between 0 and 4, inclusive, if ``options="faces"`` or
+              ``options="stars"``.
+
         disabled : bool
             An optional boolean that disables the feedback widget if set
             to ``True``. The default is ``False``.
@@ -407,7 +416,17 @@ class ButtonGroupMixin:
                 f"The argument passed was '{options}'."
             )
         transformed_options, options_indices = get_mapped_options(options)
-        serde = _SingleSelectSerde[int](options_indices)
+
+        if default is not None and (default < 0 or default >= len(transformed_options)):
+            raise StreamlitAPIException(
+                f"The default value in '{options}' must be a number between 0 and {len(transformed_options) - 1}."
+                f" The passed default value is {default}"
+            )
+
+        _default: list[int] | None = (
+            [options_indices[default]] if default is not None else None
+        )
+        serde = _SingleSelectSerde[int](options_indices, default_value=_default)
 
         selection_visualization = ButtonGroupProto.SelectionVisualization.ONLY_SELECTED
         if options == "stars":
@@ -417,7 +436,7 @@ class ButtonGroupMixin:
 
         sentiment = self._button_group(
             transformed_options,
-            default=None,
+            default=_default,
             key=key,
             selection_mode="single",
             disabled=disabled,
@@ -597,6 +616,8 @@ class ButtonGroupMixin:
             options or an empty list. If the ``selection_mode`` is
             ``"single"``, this is a selected option or ``None``.
 
+            This contains copies of the selected options, not the originals.
+
         Examples
         --------
         **Example 1: Multi-select pills**
@@ -824,6 +845,8 @@ class ButtonGroupMixin:
             options or an empty list. If the ``selection_mode`` is
             ``"single"``, this is a selected option or ``None``.
 
+            This contains copies of the selected options, not the originals.
+
         Examples
         --------
         **Example 1: Multi-select segmented control**
@@ -1047,6 +1070,10 @@ class ButtonGroupMixin:
             # "feedback" in errors
             "feedback" if style == "borderless" else style,
             user_key=key,
+            # Treat the provided key as the main identity for segmented_control, pills and feedback,
+            # and only include kwargs that can invalidate the current selection.
+            # We whitelist the formatted options and the click mode (single vs multi).
+            key_as_main_identity={"options", "click_mode"},
             dg=self.dg,
             options=formatted_options,
             default=default,

streamlit/elements/widgets/camera_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
@@ -52,7 +50,7 @@ if TYPE_CHECKING:
     from streamlit.delta_generator import DeltaGenerator
     from streamlit.elements.lib.layout_utils import WidthWithoutContent
 
-SomeUploadedSnapshotFile: TypeAlias = Union[UploadedFile, DeletedFile, None]
+SomeUploadedSnapshotFile: TypeAlias = UploadedFile | DeletedFile | None
 
 
 @dataclass
@@ -234,6 +232,7 @@ class CameraInputMixin:
         element_id = compute_and_register_element_id(
             "camera_input",
             user_key=key,
+            key_as_main_identity=False,
             dg=self.dg,
             label=label,
             help=help,

streamlit/elements/widgets/chat.py

@@ -624,6 +624,13 @@ class ChatMixin:
         element_id = compute_and_register_element_id(
             "chat_input",
             user_key=key,
+            # Treat the provided key as the main identity. Only include
+            # properties that can invalidate the current widget state
+            # when changed. For chat_input, those are:
+            # - accept_file: Changes whether files can be attached (and how)
+            # - file_type: Restricts the accepted file types
+            # - max_chars: Changes the maximum allowed characters for the input
+            key_as_main_identity={"accept_file", "file_type", "max_chars"},
             dg=self.dg,
             placeholder=placeholder,
             max_chars=max_chars,

streamlit/elements/widgets/checkbox.py

@@ -342,6 +342,7 @@ class CheckboxMixin:
         element_id = compute_and_register_element_id(
             "toggle" if type == CheckboxProto.StyleType.TOGGLE else "checkbox",
             user_key=key,
+            key_as_main_identity=True,
             dg=self.dg,
             label=label,
             value=bool(value),

streamlit/elements/widgets/color_picker.py

@@ -219,6 +219,7 @@ class ColorPickerMixin:
         element_id = compute_and_register_element_id(
             "color_picker",
             user_key=key,
+            key_as_main_identity=True,
             dg=self.dg,
             label=label,
             value=str(value),

streamlit/elements/widgets/data_editor.py

@@ -22,6 +22,7 @@ from typing import (
     Any,
     Final,
     Literal,
+    TypeAlias,
     TypedDict,
     TypeVar,
     Union,
@@ -29,8 +30,6 @@ from typing import (
     overload,
 )
 
-from typing_extensions import TypeAlias
-
 from streamlit import dataframe_util
 from streamlit import logger as _logger
 from streamlit.deprecation_util import (
@@ -52,6 +51,7 @@ from streamlit.elements.lib.column_config_utils import (
 )
 from streamlit.elements.lib.form_utils import current_form_id
 from streamlit.elements.lib.layout_utils import (
+    HeightWithoutContent,
     LayoutConfig,
     Width,
     validate_height,
@@ -89,18 +89,11 @@ _LOGGER: Final = _logger.get_logger(__name__)
 # formats will be returned with the same type when used with data_editor.
 EditableData = TypeVar(
     "EditableData",
-    bound=Union[
-        dataframe_util.DataFrameGenericAlias[Any],  # covers DataFrame and Series
-        tuple[Any],
-        list[Any],
-        set[Any],
-        dict[str, Any],
-        # TODO(lukasmasuch): Add support for np.ndarray
-        # but it is not possible with np.ndarray.
-        # NDArray[Any] works, but is only available in numpy>1.20.
-        # TODO(lukasmasuch): Add support for pa.Table typing
-        # pa.Table does not work since it is a C-based class resulting in Any
-    ],
+    bound=dataframe_util.DataFrameGenericAlias[Any]
+    | tuple[Any]
+    | list[Any]
+    | set[Any]
+    | dict[str, Any],
 )
 
 
@@ -171,7 +164,8 @@ class DataEditorSerde:
         # Convert the keys (numerical row positions) to integers.
         # The keys are strings because they are serialized to JSON.
         data_editor_state["edited_rows"] = {
-            int(k): v for k, v in data_editor_state["edited_rows"].items()
+            int(k): v
+            for k, v in data_editor_state["edited_rows"].items()  # ty: ignore[possibly-missing-attribute]
         }
         return data_editor_state
 
@@ -241,7 +235,7 @@ def _parse_value(
             ColumnDataKind.DATE,
             ColumnDataKind.TIME,
         ]:
-            datetime_value = pd.Timestamp(value)
+            datetime_value = pd.Timestamp(value)  # ty: ignore
 
             if datetime_value is pd.NaT:
                 return None
@@ -602,7 +596,7 @@ class DataEditorMixin:
         data: EditableData,
         *,
         width: Width = "stretch",
-        height: int | Literal["auto"] = "auto",
+        height: HeightWithoutContent | Literal["auto"] = "auto",
         use_container_width: bool | None = None,
         hide_index: bool | None = None,
         column_order: Iterable[str] | None = None,
@@ -623,7 +617,7 @@ class DataEditorMixin:
         data: Any,
         *,
         width: Width = "stretch",
-        height: int | Literal["auto"] = "auto",
+        height: HeightWithoutContent | Literal["auto"] = "auto",
         use_container_width: bool | None = None,
         hide_index: bool | None = None,
         column_order: Iterable[str] | None = None,
@@ -644,7 +638,7 @@ class DataEditorMixin:
         data: DataTypes,
         *,
         width: Width = "stretch",
-        height: int | Literal["auto"] = "auto",
+        height: HeightWithoutContent | Literal["auto"] = "auto",
         use_container_width: bool | None = None,
         hide_index: bool | None = None,
         column_order: Iterable[str] | None = None,
@@ -670,6 +664,9 @@ class DataEditorMixin:
                 - Styles from ``pandas.Styler`` will only be applied to non-editable columns.
                 - Text and number formatting from ``column_config`` always takes
                   precedence over text and number formatting from ``pandas.Styler``.
+                - If your dataframe starts with an empty column, you should set
+                  the column datatype in the underlying dataframe to ensure your
+                  intended datatype, especially for integers versus floats.
                 - Mixing data types within a column can make the column uneditable.
                 - Additionally, the following data types are not yet supported for editing:
                   ``complex``, ``tuple``, ``bytes``, ``bytearray``,
@@ -693,16 +690,23 @@ class DataEditorMixin:
               the parent container, the width of the editor matches the width
               of the parent container.
 
-        height : int or "auto"
-            The height of the data editor. This can be one of the following:
+        height : int, "auto", or "stretch"
+            The height of the editor. This can be one of the following:
 
             - ``"auto"`` (default): Streamlit sets the height to show at most
               ten rows.
+            - ``"stretch"``: The height of the editor expands to fill the
+              available vertical space in its parent container. When multiple
+              elements with stretch height are in the same container, they
+              share the available vertical space evenly. The editor will
+              maintain a minimum height to display up to three rows, but
+              otherwise won't exceed the available height in its parent
+              container.
             - An integer specifying the height in pixels: The editor has a
               fixed height.
 
-            Vertical scrolling within the data editor is enabled when the
-            height does not accommodate all rows.
+            Vertical scrolling within the editor is enabled when the height
+            does not accommodate all rows.
 
         use_container_width : bool
             Whether to override ``width`` with the width of the parent
@@ -711,6 +715,11 @@ class DataEditorMixin:
             this is ``False``, Streamlit sets the data editor's width according
             to ``width``.
 
+            .. deprecated::
+                ``use_container_width`` is deprecated and will be removed in a
+                future release. For ``use_container_width=True``, use
+                ``width="stretch"``.
+
         hide_index : bool or None
             Whether to hide the index column(s). If ``hide_index`` is ``None``
             (default), the visibility of index columns is automatically
@@ -793,11 +802,6 @@ class DataEditorMixin:
             is ``None`` (default), Streamlit will use a default row height,
             which fits one line of text.
 
-        .. deprecated::
-            ``use_container_width`` is deprecated and will be removed in a
-            future release. For ``use_container_width=True``, use
-            ``width="stretch"``.
-
         Returns
         -------
         pandas.DataFrame, pandas.Series, pyarrow.Table, numpy.ndarray, list, set, tuple, or dict.
@@ -904,7 +908,7 @@ class DataEditorMixin:
         validate_height(
             height,
             allow_content=False,
-            allow_stretch=False,
+            allow_stretch=True,
             additional_allowed=["auto"],
         )
 
@@ -1028,6 +1032,7 @@ class DataEditorMixin:
         element_id = compute_and_register_element_id(
             "data_editor",
             user_key=key,
+            key_as_main_identity=False,
             dg=self.dg,
             data=arrow_bytes,
             width=width,

streamlit/elements/widgets/file_uploader.py

@@ -16,9 +16,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from textwrap import dedent
-from typing import TYPE_CHECKING, Literal, Union, cast, overload
-
-from typing_extensions import TypeAlias
+from typing import TYPE_CHECKING, Literal, TypeAlias, cast, overload
 
 from streamlit import config
 from streamlit.elements.lib.file_uploader_utils import (
@@ -60,18 +58,15 @@ if TYPE_CHECKING:
 
     from streamlit.delta_generator import DeltaGenerator
 
-SomeUploadedFiles: TypeAlias = Union[
-    UploadedFile,
-    DeletedFile,
-    list[Union[UploadedFile, DeletedFile]],
-    None,
-]
+SomeUploadedFiles: TypeAlias = (
+    UploadedFile | DeletedFile | list[UploadedFile | DeletedFile] | None
+)
 
 # Type alias for accept_multiple_files parameter.
 # If True, multiple files can be uploaded.
 # If False, only a single file can be uploaded.
 # If set to the literal "directory", users can upload an entire directory (folder) of files.
-AcceptMultipleFiles: TypeAlias = Union[bool, Literal["directory"]]
+AcceptMultipleFiles: TypeAlias = bool | Literal["directory"]
 
 
 def _get_upload_files(
@@ -488,6 +483,7 @@ class FileUploaderMixin:
         element_id = compute_and_register_element_id(
             "file_uploader",
             user_key=key,
+            key_as_main_identity=False,
             dg=self.dg,
             label=label,
             type=type,