streamlit-nightly 1.34.1.dev20240521__py2.py3-none-any.whl → 1.35.1.dev20240523__py2.py3-none-any.whl

streamlit/commands/logo.py

@@ -41,25 +41,73 @@ def logo(
     icon_image: AtomicImage | None = None,
 ) -> None:
     """
-    Renders logos in the main and sidebar sections of the page
+    Renders a logo in the upper-left corner of your app and its sidebar.
+
+    If ``st.logo`` is called multiple times within a page, Streamlit will
+    render the image passed in the last call. For the most consistent results,
+    call ``st.logo`` early in your page script and choose an image that works
+    well in both light and dark mode. Avoid empty margins around your image.
+
+    If your logo does not work well for both light and dark mode, consider
+    setting the theme and hiding the settings menu from users with the
+    `configuration option <https://docs.streamlit.io/develop/api-reference/configuration/config.toml>`_
+    ``client.toolbarMode="minimal"``.
 
     Parameters
     ----------
-    image: Anything supported by st.image or str
-        The app logo to be displayed in the top left corner of the sidebar of your app
-        (as well as the main section if icon_image param is not provided).
+    image: Anything supported by st.image
+        The image to display in the upper-left corner of your app and its
+        sidebar. If ``icon_image`` is also provided, then Streamlit will only
+        display ``image`` in the sidebar.
+
+        Streamlit scales the image to a height of 24 pixels and a maximum
+        width of 240 pixels. Use images with an aspect ratio of 10:1 or less to
+        avoid distortion.
     link : str or None
-        The external url to be opened when a user clicks on the logo (must start with
-        http:// or https://)
-    icon_image: numpy.ndarray, BytesIO, str, or None
-        The app logo to be displayed in the top left corner of the main section of your
-        app.
-
-    Example
-    -------
+        The external URL to open when a user clicks on the logo. The URL must
+        start with "\\http://" or "\\https://". If ``link`` is ``None`` (default),
+        the logo will not include a hyperlink.
+    icon_image: Anything supported by st.image or None
+        An alternate image to replace ``image`` in the upper-left corner of the
+        app's main body. If ``icon_image`` is ``None`` (default), Streamlit
+        will render ``image`` in the upper-left corner of the app and its
+        sidebar. Otherwise, Streamlit will render ``icon_image`` in the
+        upper-left corner of the app and ``image`` in the upper-left corner
+        of the sidebar.
+
+        Streamlit scales the image to a height of 24 pixels and a maximum
+        width of 240 pixels. Use images with an aspect ratio of 10:1 or less to
+        avoid distortion.
+
+    Examples
+    --------
+    A common design practice is to use a wider logo in the sidebar, and a
+    smaller, icon-styled logo in your app's main body.
+
     >>> import streamlit as st
     >>>
-    >>> st.logo(streamlit_full, link="https://streamlit.io/gallery", icon_image=streamlit_small)
+    >>> st.logo(LOGO_URL_LARGE, link="https://streamlit.io/gallery", icon_image=LOGO_URL_SMALL)
+
+    Try switching logos around in the following example:
+
+    >>> import streamlit as st
+    >>>
+    >>> HORIZONTAL_RED = "images/horizontal_red.png"
+    >>> ICON_RED = "images/icon_red.png"
+    >>> HORIZONTAL_BLUE = "images/horizontal_blue.png"
+    >>> ICON_BLUE = "images/icon_blue.png"
+    >>>
+    >>> options = [HORIZONTAL_RED, ICON_RED, HORIZONTAL_BLUE, ICON_BLUE]
+    >>> sidebar_logo = st.selectbox("Sidebar logo", options, 0)
+    >>> main_body_logo = st.selectbox("Main body logo", options, 1)
+    >>>
+    >>> st.logo(sidebar_logo, icon_image=main_body_logo)
+    >>> st.sidebar.markdown("Hi!")
+
+    .. output::
+        https://doc-logo.streamlit.app/
+        height: 300px
+
     """
 
     ctx = get_script_run_ctx()

streamlit/components/types/base_custom_component.py

@@ -16,11 +16,14 @@ from __future__ import annotations
 
 import os
 from abc import ABC, abstractmethod
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from streamlit import util
 from streamlit.errors import StreamlitAPIException
 
+if TYPE_CHECKING:
+    from streamlit.runtime.state.common import WidgetCallback
+
 
 class MarshallComponentException(StreamlitAPIException):
     """Class for exceptions generated during custom component marshalling."""
@@ -56,10 +59,17 @@ class BaseCustomComponent(ABC):
         *args,
         default: Any = None,
         key: str | None = None,
+        on_change: WidgetCallback | None = None,
         **kwargs,
     ) -> Any:
         """An alias for create_instance."""
-        return self.create_instance(*args, default=default, key=key, **kwargs)
+        return self.create_instance(
+            *args,
+            default=default,
+            key=key,
+            on_change=on_change,
+            **kwargs,
+        )
 
     @property
     def abspath(self) -> str | None:
@@ -102,6 +112,7 @@ class BaseCustomComponent(ABC):
         *args,
         default: Any = None,
         key: str | None = None,
+        on_change: WidgetCallback | None = None,
         **kwargs,
     ) -> Any:
         """Create a new instance of the component.
@@ -118,6 +129,8 @@ class BaseCustomComponent(ABC):
         key: str or None
             If not None, this is the user key we use to generate the
             component's "widget ID".
+        on_change: WidgetCallback or None
+            An optional callback invoked when the widget's value changes. No arguments are passed to it.
         **kwargs
             Keyword args to pass to the component.
 

streamlit/components/v1/custom_component.py

@@ -33,6 +33,7 @@ from streamlit.type_util import to_bytes
 
 if TYPE_CHECKING:
     from streamlit.delta_generator import DeltaGenerator
+    from streamlit.runtime.state.common import WidgetCallback
 
 
 class MarshallComponentException(StreamlitAPIException):
@@ -49,10 +50,17 @@ class CustomComponent(BaseCustomComponent):
         *args,
         default: Any = None,
         key: str | None = None,
+        on_change: WidgetCallback | None = None,
         **kwargs,
     ) -> Any:
         """An alias for create_instance."""
-        return self.create_instance(*args, default=default, key=key, **kwargs)
+        return self.create_instance(
+            *args,
+            default=default,
+            key=key,
+            on_change=on_change,
+            **kwargs,
+        )
 
     @gather_metrics("create_instance")
     def create_instance(
@@ -60,6 +68,7 @@ class CustomComponent(BaseCustomComponent):
         *args,
         default: Any = None,
         key: str | None = None,
+        on_change: WidgetCallback | None = None,
         **kwargs,
     ) -> Any:
         """Create a new instance of the component.
@@ -76,6 +85,8 @@ class CustomComponent(BaseCustomComponent):
         key: str or None
             If not None, this is the user key we use to generate the
             component's "widget ID".
+        on_change: WidgetCallback or None
+            An optional callback invoked when the widget's value changes. No arguments are passed to it.
         **kwargs
             Keyword args to pass to the component.
 
@@ -195,6 +206,7 @@ And if you're using Streamlit Cloud, add "pyarrow" to your requirements.txt."""
                 deserializer=deserialize_component,
                 serializer=lambda x: x,
                 ctx=ctx,
+                on_change_handler=on_change,
             )
             widget_value = component_state.value
 

streamlit/config.py

@@ -342,6 +342,14 @@ _create_option(
     replaced_by="logger.level",
 )
 
+_create_option(
+    "global.e2eTest",
+    description="Are we in an e2e (playwright) test? Set automatically when our e2e tests are running.",
+    visibility="hidden",
+    default_val=False,
+    type_=bool,
+)
+
 _create_option(
     "global.unitTest",
     description="Are we in a unit test?",

streamlit/elements/arrow.py

@@ -85,14 +85,49 @@ _SELECTION_MODES: Final[set[SelectionMode]] = {
 
 class DataframeSelectionState(TypedDict, total=False):
     """
-    A dictionary representing the current selection state of the dataframe.
+    The schema for the dataframe selection state.
+
+    The selection state is stored in a dictionary-like object that suports both
+    key and attribute notation. Selection states cannot be programmatically
+    changed or set through Session State.
 
     Attributes
     ----------
-    rows
-        The selected rows (numerical indices).
-    columns
-        The selected columns (column names).
+    rows : list[int]
+        The selected rows, identified by their positional index. The positional
+        indices match the original dataframe, even if the user sorts the
+        dataframe in their browser.
+    columns : list[str]
+        The selected columns, identified by their names.
+
+    Example
+    -------
+    The following example has multi-row and multi-column selections enabled.
+    Try selecting some rows. To select multiple columns, hold ``Ctrl`` while
+    selecting columns. Hold ``Shift`` to select a range of columns.
+
+    >>> import streamlit as st
+    >>> import pandas as pd
+    >>> import numpy as np
+    >>>
+    >>> if "df" not in st.session_state:
+    >>>     st.session_state.df = pd.DataFrame(
+    ...         np.random.randn(12, 5), columns=["a", "b", "c", "d", "e"]
+    ...     )
+    >>>
+    >>> event = st.dataframe(
+    ...     st.session_state.df,
+    ...     key="data",
+    ...     on_select="rerun",
+    ...     selection_mode=["multi-row", "multi-column"],
+    ... )
+    >>>
+    >>> event.selection
+
+    .. output::
+        https://doc-dataframe-events-selection-state.streamlit.app
+        height: 600px
+
     """
 
     rows: list[int]
@@ -101,12 +136,19 @@ class DataframeSelectionState(TypedDict, total=False):
 
 class DataframeState(TypedDict, total=False):
     """
-    A dictionary representing the current state of the dataframe.
+    The schema for the dataframe event state.
+
+    The event state is stored in a dictionary-like object that suports both
+    key and attribute notation. Event states cannot be programmatically
+    changed or set through Session State.
+
+    Only selection events are supported at this time.
 
     Attributes
     ----------
     selection : DataframeSelectionState
-        The state of the `on_select` event.
+        The state of the ``on_select`` event.
+
     """
 
     selection: DataframeSelectionState
@@ -234,75 +276,128 @@ class ArrowMixin:
 
         Parameters
         ----------
-        data : pandas.DataFrame, pandas.Series, pandas.Styler, pandas.Index, pyarrow.Table, numpy.ndarray, pyspark.sql.DataFrame, snowflake.snowpark.dataframe.DataFrame, snowflake.snowpark.table.Table, Iterable, dict, or None
+        data : pandas.DataFrame, pandas.Series, pandas.Styler, pandas.Index, \
+            pyarrow.Table, numpy.ndarray, pyspark.sql.DataFrame, snowflake.snowpark.dataframe.DataFrame, \
+            snowflake.snowpark.table.Table, Iterable, dict, or None
             The data to display.
 
-            If 'data' is a pandas.Styler, it will be used to style its
-            underlying DataFrame. Streamlit supports custom cell
+            If ``data`` is a ``pandas.Styler``, it will be used to style its
+            underlying ``pandas.DataFrame``. Streamlit supports custom cell
             values and colors. It does not support some of the more exotic
             pandas styling features, like bar charts, hovering, and captions.
 
         width : int or None
-            Desired width of the dataframe expressed in pixels. If None, the width
-            will be automatically calculated based on the column content.
+            Desired width of the dataframe expressed in pixels. If ``width`` is
+            ``None`` (default), Streamlit sets the dataframe width to fit its
+            contents up to the width of the parent container. If ``width`` is
+            greater than the width of the parent container, Streamlit sets the
+            dataframe width to match the width of the parent container.
 
         height : int or None
-            Desired height of the dataframe expressed in pixels. If None, a
-            default height is used.
+            Desired height of the dataframe expressed in pixels. If ``height``
+            is ``None`` (default), Streamlit sets the height to show at most
+            ten rows. Vertical scrolling within the dataframe element is
+            enabled when the height does not accomodate all rows.
 
         use_container_width : bool
-            If True, set the dataframe width to the width of the parent container.
-            This takes precedence over the width argument.
+            Whether to override ``width`` with the width of the parent
+            container. If ``use_container_width`` is ``False`` (default),
+            Streamlit sets the dataframe's width according to ``width``. If
+            ``use_container_width`` is ``True``, Streamlit sets the width of
+            the dataframe to match the width of the parent container.
 
         hide_index : bool or None
-            Whether to hide the index column(s). If None (default), the visibility of
-            index columns is automatically determined based on the data.
+            Whether to hide the index column(s). If ``hide_index`` is ``None``
+            (default), the visibility of index columns is automatically
+            determined based on the data.
 
         column_order : Iterable of str or None
-            Specifies the display order of columns. This also affects which columns are
-            visible. For example, ``column_order=("col2", "col1")`` will display 'col2'
-            first, followed by 'col1', and will hide all other non-index columns. If
-            None (default), the order is inherited from the original data structure.
+            The ordered list of columns to display. If ``column_order`` is
+            ``None`` (default), Streamlit displays all columns in the order
+            inherited from the underlying data structure. If ``column_order``
+            is a list, the indicated columns will display in the order they
+            appear within the list. Columns may be omitted or repeated within
+            the list.
+
+            For example, ``column_order=("col2", "col1")`` will display
+            ``"col2"`` first, followed by ``"col1"``, and will hide all other
+            non-index columns.
 
         column_config : dict or None
-            Configures how columns are displayed, e.g. their title, visibility, type, or
-            format. This needs to be a dictionary where each key is a column name and
-            the value is one of:
+            Configuration to customize how columns display. If ``column_config``
+            is ``None`` (default), columns are styled based on the underlying
+            data type of each column.
+
+            Column configuration can modify column names, visibility, type,
+            width, or format, among other things. ``column_config`` must be a
+            dictionary where each key is a column name and the associated value
+            is one of the following:
 
-            * ``None`` to hide the column.
+            * ``None``: Streamlit hides the column.
 
-            * A string to set the display label of the column.
+            * A string: Streamlit changes the display label of the column to
+              the given string.
 
-            * One of the column types defined under ``st.column_config``, e.g.
-              ``st.column_config.NumberColumn("Dollar values”, format=”$ %d")`` to show
-              a column as dollar amounts. See more info on the available column types
-              and config options `here <https://docs.streamlit.io/library/api-reference/data/st.column_config>`_.
+            * A column type within ``st.column_config``: Streamlit applies the
+              defined configuration to the column. For example, use
+              ``st.column_config.NumberColumn("Dollar values”, format=”$ %d")``
+              to change the displayed name of the column to "Dollar values"
+              and add a "$" prefix in each cell. For more info on the
+              available column types and config options, see
+              `Column configuration <https://docs.streamlit.io/library/api-reference/data/st.column_config>`_.
 
             To configure the index column(s), use ``_index`` as the column name.
 
         key : str
-            An optional string to use as the unique key for this element when used in combination
-            with ```on_select```. If this is omitted, a key will be generated for the widget based
-            on its content. Multiple widgets of the same type may not share the same key.
+            An optional string to use for giving this element a stable
+            identity. If ``key`` is ``None`` (default), this element's identity
+            will be determined based on the values of the other parameters.
+
+            Additionally, if selections are activated and ``key`` is provided,
+            Streamlit will register the key in Session State to store the
+            selection state. The selection state is read-only.
 
         on_select : "ignore" or "rerun" or callable
-            Controls the behavior in response to selection events on the table. Can be one of:
+            How the dataframe should respond to user selection events. This
+            controls whether or not the dataframe behaves like an input widget.
+            ``on_select`` can be one of the following:
+
+            - ``"ignore"`` (default): Streamlit will not react to any selection
+              events in the dataframe. The dataframe will not behave like an
+              input widget.
+
+            - ``"rerun"``: Streamlit will rerun the app when the user selects
+              rows or columns in the dataframe. In this case, ``st.dataframe``
+              will return the selection data as a dictionary.
 
-            - "ignore" (default): Streamlit will not react to any selection events in the chart.
-            - "rerun": Streamlit will rerun the app when the user selects rows or columns in the table.
-              In this case, ```st.dataframe``` will return the selection data as a dictionary.
-            - callable: If a callable is provided, Streamlit will rerun and execute the callable as a
-              callback function before the rest of the app. The selection data can be retrieved through
-              session state by setting the key parameter.
+            - A ``callable``: Streamlit will rerun the app and execute the
+              ``callable`` as a callback function before the rest of the app.
+              In this case, ``st.dataframe`` will return the selection data
+              as a dictionary.
 
-        selection_mode : "single-row", "multi-row", single-column", "multi-column", or an iterable of these
-            The selection mode of the table. Can be one of:
+        selection_mode : "single-row", "multi-row", single-column", \
+            "multi-column", or Iterable of these
+            The types of selections Streamlit should allow. This can be one of
+            the following:
 
             - "multi-row" (default): Multiple rows can be selected at a time.
             - "single-row": Only one row can be selected at a time.
             - "multi-column": Multiple columns can be selected at a time.
             - "single-column": Only one column can be selected at a time.
-            - An iterable of the above options: The table will allow selection based on the modes specified.
+            - An ``Iterable`` of the above options: The table will allow
+              selection based on the modes specified.
+
+            When column selections are enabled, column sorting is disabled.
+
+        Returns
+        -------
+        element or dict
+            If ``on_select`` is ``"ignore"`` (default), this method returns an
+            internal placeholder for the dataframe element that can be used
+            with the ``.add_rows()`` method. Otherwise, this method returns a
+            dictionary-like object that supports both key and attribute
+            notation. The attributes are described by the ``DataframeState``
+            dictionary schema.
 
         Examples
         --------
@@ -316,7 +411,7 @@ class ArrowMixin:
 
         .. output::
            https://doc-dataframe.streamlit.app/
-           height: 410px
+           height: 500px
 
         You can also pass a Pandas Styler object to change the style of
         the rendered DataFrame:
@@ -331,7 +426,7 @@ class ArrowMixin:
 
         .. output::
            https://doc-dataframe1.streamlit.app/
-           height: 410px
+           height: 500px
 
         Or you can customize the dataframe via ``column_config``, ``hide_index``, or ``column_order``:
 

streamlit/elements/bokeh_chart.py

@@ -43,11 +43,11 @@ class BokehMixin:
         """Display an interactive Bokeh chart.
 
         Bokeh is a charting library for Python. The arguments to this function
-        closely follow the ones for Bokeh's `show` function. You can find
+        closely follow the ones for Bokeh's ``show`` function. You can find
         more about Bokeh at https://bokeh.pydata.org.
 
-        To show Bokeh charts in Streamlit, call `st.bokeh_chart`
-        wherever you would call Bokeh's `show`.
+        To show Bokeh charts in Streamlit, call ``st.bokeh_chart``
+        wherever you would call Bokeh's ``show``.
 
         Parameters
         ----------
@@ -55,8 +55,12 @@ class BokehMixin:
             A Bokeh figure to plot.
 
         use_container_width : bool
-            If True, set the chart width to the column width. This takes
-            precedence over Bokeh's native `width` value.
+            Whether to override the figure's native width with the width of
+            the parent container. If ``use_container_width`` is ``False``
+            (default), Streamlit sets the width of the chart to fit its contents
+            according to the plotting library, up to the width of the parent
+            container. If ``use_container_width`` is ``True``, Streamlit sets
+            the width of the figure to match the width of the parent container.
 
         Example
         -------

streamlit/elements/deck_gl_json_chart.py

@@ -73,6 +73,12 @@ class PydeckMixin:
         pydeck_obj: pydeck.Deck or None
             Object specifying the PyDeck chart to draw.
         use_container_width: bool
+            Whether to override the figure's native width with the width of
+            the parent container. If ``use_container_width`` is ``False``
+            (default), Streamlit sets the width of the chart to fit its contents
+            according to the plotting library, up to the width of the parent
+            container. If ``use_container_width`` is ``True``, Streamlit sets
+            the width of the figure to match the width of the parent container.
 
         Example
         -------

streamlit/elements/dialog_decorator.py

@@ -86,13 +86,13 @@ def dialog_decorator(title: str, *, width: DialogWidth = "small") -> Callable[[F
 # The user is supposed to call it like @st.dialog("my_title") , which makes 'title' a positional arg, hence
 # this 'trick'. The overload is required to have a good type hint for the decorated function args.
 @overload
-def dialog_decorator(title: F | None, *, width: DialogWidth = "small") -> F:
+def dialog_decorator(title: F, *, width: DialogWidth = "small") -> F:
     ...
 
 
 @gather_metrics("experimental_dialog")
 def dialog_decorator(
-    title: F | None | str = "", *, width: DialogWidth = "small"
+    title: F | str, *, width: DialogWidth = "small"
 ) -> F | Callable[[F], F]:
     """Function decorator to create a modal dialog.
 
@@ -173,13 +173,7 @@ def dialog_decorator(
     """
 
     func_or_title = title
-    if func_or_title is None:
-        # Support passing the params via function decorator
-        def wrapper(f: F) -> F:
-            return _dialog_decorator(non_optional_func=f, title="", width=width)
-
-        return wrapper
-    elif type(func_or_title) is str:
+    if type(func_or_title) is str:
         # Support passing the params via function decorator
         def wrapper(f: F) -> F:
             title: str = func_or_title

streamlit/elements/graphviz_chart.py

@@ -50,8 +50,12 @@ class GraphvizMixin:
             The Graphlib graph object or dot string to display
 
         use_container_width : bool
-            If True, set the chart width to the column width. This takes
-            precedence over the figure's native `width` value.
+            Whether to override the figure's native width with the width of
+            the parent container. If ``use_container_width`` is ``False``
+            (default), Streamlit sets the width of the chart to fit its contents
+            according to the plotting library, up to the width of the parent
+            container. If ``use_container_width`` is ``True``, Streamlit sets
+            the width of the figure to match the width of the parent container.
 
         Example
         -------

streamlit/elements/lib/built_in_chart_utils.py

@@ -118,8 +118,8 @@ def generate_chart(
     y_from_user: str | Sequence[str] | None = None,
     color_from_user: str | Color | list[Color] | None = None,
     size_from_user: str | float | None = None,
-    width: int = 0,
-    height: int = 0,
+    width: int | None = None,
+    height: int | None = None,
 ) -> tuple[alt.Chart, AddRowsMetadata]:
     """Function to use the chart's type, data columns and indices to figure out the chart's spec."""
     import altair as alt
@@ -167,8 +167,8 @@ def generate_chart(
     chart = alt.Chart(
         data=df,
         mark=chart_type.value["mark_type"],
-        width=width,
-        height=height,
+        width=width or 0,
+        height=height or 0,
     ).encode(
         x=_get_x_encoding(df, x_column, x_from_user, chart_type),
         y=_get_y_encoding(df, y_column, y_from_user),

streamlit/elements/map.py

@@ -166,8 +166,12 @@ class MapMixin:
             https://wiki.openstreetmap.org/wiki/Zoom_levels.
 
         use_container_width: bool
-            If True, set the chart width to the column width. This takes
-            precedence over the width argument.
+            Whether to override the map's native width with the width of
+            the parent container. If ``use_container_width`` is ``False``
+            (default), Streamlit sets the width of the chart to fit its contents
+            according to the plotting library, up to the width of the parent
+            container. If ``use_container_width`` is ``True``, Streamlit sets
+            the width of the map to match the width of the parent container.
 
         Examples
         --------