streamlit 1.49.1__py3-none-any.whl → 1.51.0__py3-none-any.whl

streamlit/elements/lib/built_in_chart_utils.py

@@ -19,16 +19,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from datetime import date
 from enum import Enum
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Final,
-    Literal,
-    TypedDict,
-    cast,
-)
-
-from typing_extensions import TypeAlias
+from typing import TYPE_CHECKING, Any, Final, Literal, TypeAlias, TypedDict, cast
 
 from streamlit import dataframe_util, type_util
 from streamlit.elements.lib.color_util import (
@@ -47,6 +38,10 @@ if TYPE_CHECKING:
     import pandas as pd
 
     from streamlit.dataframe_util import Data
+    from streamlit.elements.lib.layout_utils import (
+        Height,
+        Width,
+    )
 
 VegaLiteType: TypeAlias = Literal["quantitative", "ordinal", "temporal", "nominal"]
 ChartStackType: TypeAlias = Literal["normalize", "center", "layered"]
@@ -59,6 +54,7 @@ class PrepDataColumns(TypedDict):
     y_column_list: list[str]
     color_column: str | None
     size_column: str | None
+    sort_column: str | None
 
 
 @dataclass
@@ -73,13 +69,14 @@ class AddRowsMetadata:
     columns: PrepDataColumns
     # Chart styling properties
     color: str | Color | list[Color] | None = None
-    width: int | None = None
-    height: int | None = None
-    use_container_width: bool = True
+    width: Width | None = None
+    height: Height | None = None
+    use_container_width: bool | None = None
     # Only applicable for bar & area charts
     stack: bool | ChartStackType | None = None
     # Only applicable for bar charts
     horizontal: bool = False
+    sort: bool | str = False
 
 
 class ChartType(Enum):
@@ -151,13 +148,14 @@ def generate_chart(
     y_axis_label: str | None = None,
     color_from_user: str | Color | list[Color] | None = None,
     size_from_user: str | float | None = None,
-    width: int | None = None,
-    height: int | None = None,
-    use_container_width: bool = True,
+    width: Width | None = None,
+    height: Height | None = None,
+    use_container_width: bool | None = None,
     # Bar & Area charts only:
     stack: bool | ChartStackType | None = None,
     # Bar charts only:
     horizontal: bool = False,
+    sort_from_user: bool | str = False,
 ) -> tuple[alt.Chart | alt.LayerChart, AddRowsMetadata]:
     """Function to use the chart's type, data columns and indices to figure out the
     chart's spec.
@@ -181,6 +179,8 @@ def generate_chart(
     # Get name of column to use for size, or constant value to use. Any/both could
     #  be None.
     size_column, size_value = _parse_generic_column(df, size_from_user)
+    # Get name of column to use for sort.
+    sort_column = _parse_sort_column(df, sort_from_user)
 
     # Store some info so we can use it in add_rows.
     add_rows_metadata = AddRowsMetadata(
@@ -194,6 +194,7 @@ def generate_chart(
             "y_column_list": y_column_list,
             "color_column": color_column,
             "size_column": size_column,
+            "sort_column": sort_column,
         },
         # Chart styling properties
         color=color_from_user,
@@ -202,13 +203,13 @@ def generate_chart(
         use_container_width=use_container_width,
         stack=stack,
         horizontal=horizontal,
+        sort=sort_from_user,
     )
 
     # At this point, all foo_column variables are either None/empty or contain actual
     # columns that are guaranteed to exist.
-
-    df, x_column, y_column, color_column, size_column = _prep_data(
-        df, x_column, y_column_list, color_column, size_column
+    df, x_column, y_column, color_column, size_column, sort_column = _prep_data(
+        df, x_column, y_column_list, color_column, size_column, sort_column
     )
 
     # At this point, x_column is only None if user did not provide one AND df is empty.
@@ -224,14 +225,18 @@ def generate_chart(
         x_axis_label,
         y_axis_label,
         stack,
+        sort_from_user,
     )
 
+    chart_width = width if isinstance(width, int) else None
+    chart_height = height if isinstance(height, int) else None
+
     # Create a Chart with x and y encodings.
     chart = alt.Chart(
         data=df,
         mark=chart_type.value["mark_type"],
-        width=width or 0,
-        height=height or 0,
+        width=chart_width or 0,
+        height=chart_height or 0,
     ).encode(
         x=x_encoding,
         y=y_encoding,
@@ -281,7 +286,7 @@ def generate_chart(
         and is_altair_version_5_or_greater
     ):
         return _add_improved_hover_tooltips(
-            chart, x_column, width, height
+            chart, x_column, chart_width, chart_height
         ).interactive(), add_rows_metadata
 
     return chart.interactive(), add_rows_metadata
@@ -359,6 +364,7 @@ def prep_chart_data_for_add_rows(
         y_column_list=add_rows_metadata.columns["y_column_list"],
         color_column=add_rows_metadata.columns["color_column"],
         size_column=add_rows_metadata.columns["size_column"],
+        sort_column=add_rows_metadata.columns["sort_column"],
     )
 
     return out_data, add_rows_metadata
@@ -437,7 +443,8 @@ def _prep_data(
     y_column_list: list[str],
     color_column: str | None,
     size_column: str | None,
-) -> tuple[pd.DataFrame, str | None, str | None, str | None, str | None]:
+    sort_column: str | None = None,
+) -> tuple[pd.DataFrame, str | None, str | None, str | None, str | None, str | None]:
     """Prepares the data for charting. This is also used in add_rows.
 
     Returns the prepared dataframe and the new names of the x column (taking the index
@@ -450,7 +457,7 @@ def _prep_data(
 
     # Drop columns we're not using.
     selected_data = _drop_unused_columns(
-        df, x_column, color_column, size_column, *y_column_list
+        df, x_column, color_column, size_column, sort_column, *y_column_list
     )
 
     # Maybe convert color to Vega colors.
@@ -462,17 +469,18 @@ def _prep_data(
         y_column_list,
         color_column,
         size_column,
+        sort_column,
     ) = _convert_col_names_to_str_in_place(
-        selected_data, x_column, y_column_list, color_column, size_column
+        selected_data, x_column, y_column_list, color_column, size_column, sort_column
     )
 
     # Maybe melt data from wide format into long format.
     melted_data, y_column, color_column = _maybe_melt(
-        selected_data, x_column, y_column_list, color_column, size_column
+        selected_data, x_column, y_column_list, color_column, size_column, sort_column
     )
 
     # Return the data, but also the new names to use for x, y, and color.
-    return melted_data, x_column, y_column, color_column, size_column
+    return melted_data, x_column, y_column, color_column, size_column, sort_column
 
 
 def _last_index_for_melted_dataframes(
@@ -505,7 +513,7 @@ def _is_date_column(df: pd.DataFrame, name: str | None) -> bool:
     if column.size == 0:
         return False
 
-    return isinstance(column.iloc[0], date)
+    return isinstance(column.iat[0], date)
 
 
 def _melt_data(
@@ -636,7 +644,7 @@ def _maybe_convert_color_column_in_place(
     if color_column is None or len(df[color_column]) == 0:
         return
 
-    first_color_datum = df[color_column].iloc[0]
+    first_color_datum = df[color_column].iat[0]
 
     if is_hex_color_like(first_color_datum):
         # Hex is already CSS-valid.
@@ -657,7 +665,8 @@ def _convert_col_names_to_str_in_place(
     y_column_list: list[str],
     color_column: str | None,
     size_column: str | None,
-) -> tuple[str | None, list[str], str | None, str | None]:
+    sort_column: str | None,
+) -> tuple[str | None, list[str], str | None, str | None, str | None]:
     """Converts column names to strings, since Vega-Lite does not accept ints, etc."""
     import pandas as pd
 
@@ -670,6 +679,7 @@ def _convert_col_names_to_str_in_place(
         [str(c) for c in y_column_list],
         None if color_column is None else str(color_column),
         None if size_column is None else str(size_column),
+        None if sort_column is None else str(sort_column),
     )
 
 
@@ -703,6 +713,17 @@ def _parse_x_column(df: pd.DataFrame, x_from_user: str | None) -> str | None:
     )
 
 
+def _parse_sort_column(df: pd.DataFrame, sort_from_user: bool | str) -> str | None:
+    if sort_from_user is False or sort_from_user is True:
+        return None
+
+    sort_column = sort_from_user.removeprefix("-")
+    if sort_column not in df.columns:
+        raise StreamlitColumnNotFoundError(df, sort_column)
+
+    return sort_column
+
+
 def _parse_y_columns(
     df: pd.DataFrame,
     y_from_user: str | Sequence[str] | None,
@@ -790,6 +811,7 @@ def _maybe_melt(
     y_column_list: list[str],
     color_column: str | None,
     size_column: str | None,
+    sort_column: str | None,
 ) -> tuple[pd.DataFrame, str | None, str | None]:
     """If multiple columns are set for y, melt the dataframe into long format."""
     y_column: str | None
@@ -806,6 +828,8 @@ def _maybe_melt(
         columns_to_leave_alone = [x_column]
         if size_column:
             columns_to_leave_alone.append(size_column)
+        if sort_column:
+            columns_to_leave_alone.append(sort_column)
 
         df = _melt_data(
             df=df,
@@ -828,8 +852,10 @@ def _get_axis_encodings(
     x_axis_label: str | None,
     y_axis_label: str | None,
     stack: bool | ChartStackType | None,
+    sort_from_user: bool | str,
 ) -> tuple[alt.X, alt.Y]:
     stack_encoding: alt.X | alt.Y
+    sort_encoding: alt.X | alt.Y
     if chart_type == ChartType.HORIZONTAL_BAR:
         # Handle horizontal bar chart - switches x and y data:
         x_encoding = _get_x_encoding(
@@ -839,6 +865,7 @@ def _get_axis_encodings(
             df, x_column, x_from_user, y_axis_label, chart_type
         )
         stack_encoding = x_encoding
+        sort_encoding = y_encoding
     else:
         x_encoding = _get_x_encoding(
             df, x_column, x_from_user, x_axis_label, chart_type
@@ -847,10 +874,15 @@ def _get_axis_encodings(
             df, y_column, y_from_user, y_axis_label, chart_type
         )
         stack_encoding = y_encoding
+        sort_encoding = x_encoding
 
     # Handle stacking - only relevant for bar & area charts
     _update_encoding_with_stack(stack, stack_encoding)
 
+    # Handle sorting - only relevant for bar charts
+    if chart_type in (ChartType.VERTICAL_BAR, ChartType.HORIZONTAL_BAR):
+        _update_encoding_with_sort(sort_from_user, sort_encoding)
+
     return x_encoding, y_encoding
 
 
@@ -957,6 +989,38 @@ def _update_encoding_with_stack(
     encoding["stack"] = stack
 
 
+def _update_encoding_with_sort(
+    sort_from_user: bool | str,
+    encoding: alt.X | alt.Y,
+) -> None:
+    """Apply sort to the given encoding in-place.
+
+    - If sort is False: disable Altair's default sorting on the bar's categorical axis
+        (i.e., set to None).
+    - If sort is True: use Altair's default sorting.
+    - If sort is a column name (optionally starting with '-') set a SortField with the correct order.
+
+    Note: Column validation should be done before calling this function.
+    """
+    import altair as alt
+
+    if sort_from_user is False:
+        # Disable Altair's default sorting
+        encoding["sort"] = None
+    elif sort_from_user is True:
+        # Use Altair's default sorting
+        pass
+    else:
+        # String: sort by column name (optional '-' prefix for descending)
+        sort_order: Literal["ascending", "descending"]
+        if sort_from_user.startswith("-"):
+            sort_order = "descending"
+        else:
+            sort_order = "ascending"
+        sort_field = sort_from_user.removeprefix("-")
+        encoding["sort"] = alt.SortField(field=sort_field, order=sort_order)
+
+
 def _get_color_encoding(
     df: pd.DataFrame,
     color_value: Color | None,
@@ -1022,7 +1086,7 @@ def _get_color_encoding(
 
         # If the 0th element in the color column looks like a color, we'll use the color
         # column's values as the colors in our chart.
-        elif len(df[color_column]) and is_color_like(df[color_column].iloc[0]):
+        elif len(df[color_column]) and is_color_like(df[color_column].iat[0]):
             color_range = [to_css_color(c) for c in df[color_column].unique()]
             color_enc["scale"] = alt.Scale(range=color_range)
             # Don't show the color legend, because it will just show text with the

streamlit/elements/lib/color_util.py

@@ -14,10 +14,8 @@
 
 from __future__ import annotations
 
-from collections.abc import Collection
-from typing import Any, Callable, Union, cast
-
-from typing_extensions import TypeAlias
+from collections.abc import Callable, Collection
+from typing import Any, TypeAlias, cast
 
 from streamlit.errors import StreamlitInvalidColorError
 
@@ -35,26 +33,18 @@ IntRGBAColorTuple: TypeAlias = tuple[int, int, int, int]
 # CSS uses these.
 MixedRGBAColorTuple: TypeAlias = tuple[int, int, int, float]
 
-Color4Tuple: TypeAlias = Union[
-    FloatRGBAColorTuple,
-    IntRGBAColorTuple,
-    MixedRGBAColorTuple,
-]
+Color4Tuple: TypeAlias = FloatRGBAColorTuple | IntRGBAColorTuple | MixedRGBAColorTuple
 
-Color3Tuple: TypeAlias = Union[
-    FloatRGBColorTuple,
-    IntRGBColorTuple,
-]
+Color3Tuple: TypeAlias = FloatRGBColorTuple | IntRGBColorTuple
 
-ColorTuple: TypeAlias = Union[Color4Tuple, Color3Tuple]
+ColorTuple: TypeAlias = Color4Tuple | Color3Tuple
 
-IntColorTuple = Union[IntRGBColorTuple, IntRGBAColorTuple]
-CSSColorStr = Union[IntRGBAColorTuple, MixedRGBAColorTuple]
+IntColorTuple: TypeAlias = IntRGBColorTuple | IntRGBAColorTuple
 
 ColorStr: TypeAlias = str
 
-Color: TypeAlias = Union[ColorTuple, ColorStr]
-MaybeColor: TypeAlias = Union[str, Collection[Any]]
+Color: TypeAlias = ColorTuple | ColorStr
+MaybeColor: TypeAlias = str | Collection[Any]
 
 
 def to_int_color_tuple(color: MaybeColor) -> IntColorTuple:

streamlit/elements/lib/column_config_utils.py

@@ -18,9 +18,7 @@ import copy
 import json
 from collections.abc import Mapping
 from enum import Enum
-from typing import TYPE_CHECKING, Final, Literal, Union
-
-from typing_extensions import TypeAlias
+from typing import TYPE_CHECKING, Final, Literal, TypeAlias
 
 from streamlit.dataframe_util import DataFormat
 from streamlit.elements.lib.column_types import ColumnConfig, ColumnType
@@ -109,6 +107,11 @@ _EDITING_COMPATIBILITY_MAPPING: Final[dict[ColumnType, list[ColumnDataKind]]] =
         ColumnDataKind.STRING,
         ColumnDataKind.EMPTY,
     ],
+    "multiselect": [
+        ColumnDataKind.LIST,
+        ColumnDataKind.STRING,
+        ColumnDataKind.EMPTY,
+    ],
 }
 
 
@@ -400,16 +403,14 @@ def determine_dataframe_schema(
 
 
 # A mapping of column names/IDs to column configs.
-ColumnConfigMapping: TypeAlias = dict[
-    Union[IndexIdentifierType, str, int], ColumnConfig
-]
+ColumnConfigMapping: TypeAlias = dict[IndexIdentifierType | str | int, ColumnConfig]
 ColumnConfigMappingInput: TypeAlias = Mapping[
     # TODO(lukasmasuch): This should also use int here to
     # correctly type the support for positional index. However,
     # allowing int here leads mypy to complain about simple dict[str, ...]
     # as input -> which seems like a mypy bug.
-    Union[IndexIdentifierType, str],
-    Union[ColumnConfig, None, str],
+    IndexIdentifierType | str,
+    ColumnConfig | None | str,
 ]