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

streamlit/elements/widgets/data_editor.py

@@ -22,6 +22,7 @@ from typing import (
     Any,
     Final,
     Literal,
+    TypeAlias,
     TypedDict,
     TypeVar,
     Union,
@@ -29,7 +30,7 @@ from typing import (
     overload,
 )
 
-from typing_extensions import TypeAlias
+from typing_extensions import Required
 
 from streamlit import dataframe_util
 from streamlit import logger as _logger
@@ -52,6 +53,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 (
+    Height,
     LayoutConfig,
     Width,
     validate_height,
@@ -89,26 +91,19 @@ _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],
 )
 
 
 # All data types supported by the data editor.
 DataTypes: TypeAlias = Union[
     "pd.DataFrame",
-    "pd.Series",
-    "pd.Index",
+    "pd.Series[Any]",
+    "pd.Index[Any]",
     "Styler",
     "pa.Table",
     "np.ndarray[Any, np.dtype[np.float64]]",
@@ -138,9 +133,9 @@ class EditingState(TypedDict, total=False):
         the deleted row.
     """
 
-    edited_rows: dict[int, dict[str, str | int | float | bool | None]]
-    added_rows: list[dict[str, str | int | float | bool | None]]
-    deleted_rows: list[int]
+    edited_rows: Required[dict[int, dict[str, str | int | float | bool | None]]]
+    added_rows: Required[list[dict[str, str | int | float | bool | None]]]
+    deleted_rows: Required[list[int]]
 
 
 @dataclass
@@ -148,30 +143,32 @@ class DataEditorSerde:
     """DataEditorSerde is used to serialize and deserialize the data editor state."""
 
     def deserialize(self, ui_value: str | None) -> EditingState:
-        data_editor_state: EditingState = (
+        data_editor_state: EditingState = cast(
+            "EditingState",
             {
                 "edited_rows": {},
                 "added_rows": [],
                 "deleted_rows": [],
             }
             if ui_value is None
-            else json.loads(ui_value)
+            else json.loads(ui_value),
         )
 
         # Make sure that all editing state keys are present:
         if "edited_rows" not in data_editor_state:
-            data_editor_state["edited_rows"] = {}
+            data_editor_state["edited_rows"] = {}  # type: ignore[unreachable]
 
         if "deleted_rows" not in data_editor_state:
-            data_editor_state["deleted_rows"] = []
+            data_editor_state["deleted_rows"] = []  # type: ignore[unreachable]
 
         if "added_rows" not in data_editor_state:
-            data_editor_state["added_rows"] = []
+            data_editor_state["added_rows"] = []  # type: ignore[unreachable]
 
         # 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
 
@@ -204,7 +201,7 @@ def _parse_value(
     import pandas as pd
 
     try:
-        if column_data_kind == ColumnDataKind.LIST:
+        if column_data_kind in (ColumnDataKind.LIST, ColumnDataKind.EMPTY):
             return list(value) if is_list_like(value) else [value]  # ty: ignore
 
         if column_data_kind == ColumnDataKind.STRING:
@@ -215,7 +212,7 @@ def _parse_value(
         # This isn't expected to happen.
         if isinstance(value, list):
             raise TypeError(  # noqa: TRY301
-                "List values are only supported by list and string columns."
+                "List values are only supported by list, string and empty columns."
             )
 
         if column_data_kind == ColumnDataKind.INTEGER:
@@ -241,10 +238,10 @@ 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
+            if pd.isna(datetime_value):
+                return None  # type: ignore[unreachable]
 
             if column_data_kind == ColumnDataKind.DATETIME:
                 return datetime_value
@@ -301,7 +298,7 @@ def _apply_cell_edits(
                 )
             else:
                 col_pos = df.columns.get_loc(col_name)
-                df.iat[row_pos, col_pos] = _parse_value(
+                df.iat[row_pos, col_pos] = _parse_value(  # type: ignore
                     value, dataframe_schema[col_name]
                 )
 
@@ -326,6 +323,20 @@ def _parse_added_row(
     return index_value, new_row
 
 
+def _assign_row_values(
+    df: pd.DataFrame,
+    row_label: Any,
+    row_values: list[Any],
+) -> None:
+    """Assign values to a dataframe row via a mapping.
+
+    This avoids numpy attempting to coerce nested sequences (e.g. lists) into
+    multi-dimensional arrays when a column legitimately stores list values.
+    """
+
+    df.loc[row_label] = dict(zip(df.columns, row_values, strict=True))
+
+
 def _apply_row_additions(
     df: pd.DataFrame,
     added_rows: list[dict[str, Any]],
@@ -382,13 +393,13 @@ def _apply_row_additions(
             # already exists. In the future, it would be better to
             # require users to provide unique non-None values for the index with
             # some kind of visual indications.
-            df.loc[index_value, :] = new_row
+            _assign_row_values(df, index_value, new_row)
             continue
 
         if index_stop is not None and index_step is not None:
             # Case 2: Range or integer index that can be auto incremented.
             # Add row using the next value in the sequence
-            df.loc[index_stop, :] = new_row
+            _assign_row_values(df, index_stop, new_row)
             # Increment to the next range index value
             index_stop += index_step
             continue
@@ -448,7 +459,7 @@ def _apply_dataframe_edits(
         _apply_row_additions(df, data_editor_state["added_rows"], dataframe_schema)
 
 
-def _is_supported_index(df_index: pd.Index) -> bool:
+def _is_supported_index(df_index: pd.Index[Any]) -> bool:
     """Check if the index is supported by the data editor component.
 
     Parameters
@@ -564,7 +575,7 @@ def _check_type_compatibilities(
     indices = [(INDEX_IDENTIFIER, data_df.index)]
 
     for column in indices + list(data_df.items()):
-        column_name, _ = column
+        column_name = str(column[0])
         column_data_kind = dataframe_schema[column_name]
 
         # TODO(lukasmasuch): support column config via numerical index here?
@@ -602,7 +613,7 @@ class DataEditorMixin:
         data: EditableData,
         *,
         width: Width = "stretch",
-        height: int | Literal["auto"] = "auto",
+        height: Height | Literal["auto"] = "auto",
         use_container_width: bool | None = None,
         hide_index: bool | None = None,
         column_order: Iterable[str] | None = None,
@@ -614,6 +625,7 @@ class DataEditorMixin:
         args: WidgetArgs | None = None,
         kwargs: WidgetKwargs | None = None,
         row_height: int | None = None,
+        placeholder: str | None = None,
     ) -> EditableData:
         pass
 
@@ -623,7 +635,7 @@ class DataEditorMixin:
         data: Any,
         *,
         width: Width = "stretch",
-        height: int | Literal["auto"] = "auto",
+        height: Height | Literal["auto"] = "auto",
         use_container_width: bool | None = None,
         hide_index: bool | None = None,
         column_order: Iterable[str] | None = None,
@@ -635,6 +647,7 @@ class DataEditorMixin:
         args: WidgetArgs | None = None,
         kwargs: WidgetKwargs | None = None,
         row_height: int | None = None,
+        placeholder: str | None = None,
     ) -> pd.DataFrame:
         pass
 
@@ -644,7 +657,7 @@ class DataEditorMixin:
         data: DataTypes,
         *,
         width: Width = "stretch",
-        height: int | Literal["auto"] = "auto",
+        height: Height | Literal["auto"] = "auto",
         use_container_width: bool | None = None,
         hide_index: bool | None = None,
         column_order: Iterable[str] | None = None,
@@ -656,6 +669,7 @@ class DataEditorMixin:
         args: WidgetArgs | None = None,
         kwargs: WidgetKwargs | None = None,
         row_height: int | None = None,
+        placeholder: str | None = None,
     ) -> DataTypes:
         """Display a data editor widget.
 
@@ -670,6 +684,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 +710,26 @@ class DataEditorMixin:
               the parent container, the width of the editor matches the width
               of the parent container.
 
-        height : int or "auto"
+        height : "auto", "content", "stretch", or int
             The height of the data editor. This can be one of the following:
 
             - ``"auto"`` (default): Streamlit sets the height to show at most
               ten rows.
+            - ``"content"``: The height of the editor matches the height of
+              its content. The height is capped at 10,000 pixels to prevent
+              performance issues with very large dataframes.
+            - ``"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
@@ -798,6 +825,12 @@ class DataEditorMixin:
             is ``None`` (default), Streamlit will use a default row height,
             which fits one line of text.
 
+        placeholder : str or None
+            The text that should be shown for missing values. If this is
+            ``None`` (default), missing values are displayed as "None". To
+            leave a cell empty, use an empty string (``""``). Other common
+            values are ``"null"``, ``"NaN"`` and ``"-"``.
+
         Returns
         -------
         pandas.DataFrame, pandas.Series, pyarrow.Table, numpy.ndarray, list, set, tuple, or dict.
@@ -903,8 +936,8 @@ class DataEditorMixin:
         validate_width(width, allow_content=True)
         validate_height(
             height,
-            allow_content=False,
-            allow_stretch=False,
+            allow_content=True,
+            allow_stretch=True,
             additional_allowed=["auto"],
         )
 
@@ -967,10 +1000,10 @@ class DataEditorMixin:
         for column_name, column_data in data_df.items():
             if dataframe_util.is_colum_type_arrow_incompatible(column_data):
                 update_column_config(
-                    column_config_mapping, column_name, {"disabled": True}
+                    column_config_mapping, str(column_name), {"disabled": True}
                 )
                 # Convert incompatible type to string
-                data_df[column_name] = column_data.astype("string")
+                data_df[cast("Any", column_name)] = column_data.astype("string")
 
         apply_data_specific_configs(column_config_mapping, data_format)
 
@@ -985,6 +1018,13 @@ class DataEditorMixin:
             update_column_config(
                 column_config_mapping, INDEX_IDENTIFIER, {"required": True}
             )
+            if num_rows == "dynamic" and hide_index is True:
+                _LOGGER.warning(
+                    "Setting `hide_index=True` in data editor with a non-range index will not have any effect "
+                    "when `num_rows='dynamic'`. It is required for the user to fill in index values for "
+                    "adding new rows. To hide the index, make sure to set the DataFrame "
+                    "index to a range index."
+                )
 
         if hide_index is None and has_range_index and num_rows == "dynamic":
             # Temporary workaround:
@@ -1038,6 +1078,7 @@ class DataEditorMixin:
             column_config_mapping=str(column_config_mapping),
             num_rows=num_rows,
             row_height=row_height,
+            placeholder=placeholder,
         )
 
         proto = ArrowProto()
@@ -1049,6 +1090,9 @@ class DataEditorMixin:
         if column_order:
             proto.column_order[:] = column_order
 
+        if placeholder is not None:
+            proto.placeholder = placeholder
+
         # Only set disabled to true if it is actually true
         # It can also be a list of columns, which should result in false here.
         proto.disabled = disabled is True

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,7 +483,10 @@ class FileUploaderMixin:
         element_id = compute_and_register_element_id(
             "file_uploader",
             user_key=key,
-            key_as_main_identity=False,
+            # Treat the provided key as the main identity; only include
+            # changes to the type and accept_multiple_files parameters in
+            # the identity computation as those can invalidate the current value.
+            key_as_main_identity={"type", "accept_multiple_files"},
             dg=self.dg,
             label=label,
             type=type,

streamlit/elements/widgets/multiselect.py

@@ -19,7 +19,6 @@ from textwrap import dedent
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
     Generic,
     Literal,
     TypeVar,
@@ -64,7 +63,7 @@ from streamlit.type_util import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
 
     from streamlit.dataframe_util import OptionSequence
     from streamlit.delta_generator import DeltaGenerator
@@ -370,7 +369,9 @@ class MultiSelectMixin:
         Returns
         -------
         list
-            A list with the selected options
+            A list of the selected options.
+
+            The list contains copies of the selected options, not the originals.
 
         Examples
         --------

streamlit/elements/widgets/number_input.py

@@ -17,9 +17,7 @@ from __future__ import annotations
 import numbers
 from dataclasses import dataclass
 from textwrap import dedent
-from typing import TYPE_CHECKING, Literal, TypeVar, Union, cast, overload
-
-from typing_extensions import TypeAlias
+from typing import TYPE_CHECKING, Literal, TypeAlias, TypeVar, cast, overload
 
 from streamlit.elements.lib.form_utils import current_form_id
 from streamlit.elements.lib.js_number import JSNumber, JSNumberBoundsException
@@ -62,7 +60,7 @@ if TYPE_CHECKING:
     from streamlit.delta_generator import DeltaGenerator
 
 
-Number: TypeAlias = Union[int, float]
+Number: TypeAlias = int | float
 IntOrNone = TypeVar("IntOrNone", int, None)
 FloatOrNone = TypeVar("FloatOrNone", float, None)
 
@@ -355,6 +353,8 @@ class NumberInputMixin:
               <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
               font library.
 
+            - ``"spinner"``: Displays a spinner as an icon.
+
         width : "stretch" or int
             The width of the number input widget. This can be one of the
             following:

streamlit/elements/widgets/radio.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from textwrap import dedent
-from typing import TYPE_CHECKING, Any, Callable, Generic, TypeVar, cast, overload
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast, overload
 
 from typing_extensions import Never
 
@@ -56,7 +56,7 @@ from streamlit.type_util import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
 
     from streamlit.delta_generator import DeltaGenerator
 
@@ -272,6 +272,8 @@ class RadioMixin:
         any
             The selected option or ``None`` if no option is selected.
 
+            This is a copy of the selected option, not the original.
+
         Example
         -------
         >>> import streamlit as st
@@ -369,7 +371,12 @@ class RadioMixin:
         element_id = compute_and_register_element_id(
             "radio",
             user_key=key,
-            key_as_main_identity=False,
+            # Treat provided key as the main widget identity. Only include the
+            # following parameters in the identity computation since they can
+            # invalidate the current selection mapping.
+            # Changes to format_func also invalidate the current selection,
+            # but this is already handled via the `options` parameter below:
+            key_as_main_identity={"options"},
             dg=self.dg,
             label=label,
             options=[str(format_func(option)) for option in opt],

streamlit/elements/widgets/select_slider.py

@@ -19,15 +19,13 @@ from textwrap import dedent
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
     Generic,
+    TypeGuard,
     TypeVar,
     cast,
     overload,
 )
 
-from typing_extensions import TypeGuard
-
 from streamlit.dataframe_util import OptionSequence, convert_anything_to_list
 from streamlit.elements.lib.form_utils import current_form_id
 from streamlit.elements.lib.layout_utils import LayoutConfig, validate_width
@@ -61,7 +59,7 @@ from streamlit.runtime.state import (
 from streamlit.type_util import check_python_comparable
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
 
     from streamlit.delta_generator import DeltaGenerator
     from streamlit.elements.lib.layout_utils import WidthWithoutContent
@@ -264,6 +262,8 @@ class SelectSliderMixin:
             The current value of the slider widget. The return type will match
             the data type of the value parameter.
 
+            This contains copies of the selected options, not the originals.
+
         Examples
         --------
         >>> import streamlit as st
@@ -377,7 +377,10 @@ class SelectSliderMixin:
         element_id = compute_and_register_element_id(
             "select_slider",
             user_key=key,
-            key_as_main_identity=False,
+            # Treat the provided key as the main identity; only include
+            # changes to the options (and implicitly their formatting) in the
+            # identity computation as those can invalidate the current value.
+            key_as_main_identity={"options", "format_func"},
             dg=self.dg,
             label=label,
             options=[str(format_func(option)) for option in opt],

streamlit/elements/widgets/selectbox.py

@@ -17,7 +17,6 @@ from textwrap import dedent
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
     Generic,
     Literal,
     TypeVar,
@@ -67,7 +66,7 @@ from streamlit.type_util import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
 
     from streamlit.delta_generator import DeltaGenerator
 
@@ -404,6 +403,8 @@ class SelectboxMixin:
         any
             The selected option or ``None`` if no option is selected.
 
+            This is a copy of the selected option, not the original.
+
         Examples
         --------
         **Example 1: Use a basic selectbox widget**
@@ -544,7 +545,9 @@ class SelectboxMixin:
             # Treat the provided key as the main identity. Only include
             # the options and accept_new_options in the identity computation
             # as those can invalidate the current selection.
-            key_as_main_identity={"options", "accept_new_options", "format_func"},
+            # Changes to format_func also invalidate the current selection,
+            # but this is already handled via the `options` parameter below:
+            key_as_main_identity={"options", "accept_new_options"},
             dg=self.dg,
             label=label,
             options=formatted_options,