streamlit-nightly 1.39.1.dev20241031__py2.py3-none-any.whl → 1.39.1.dev20241102__py2.py3-none-any.whl

streamlit/elements/widgets/button.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 import io
 import os
 from dataclasses import dataclass
+from pathlib import Path
 from textwrap import dedent
 from typing import (
     TYPE_CHECKING,
@@ -105,8 +106,9 @@ class ButtonMixin:
         label : str
             A short label explaining to the user what this button is for.
             The label can optionally contain GitHub-flavored Markdown of the
-            following types: Bold, Italics, Strikethroughs, Inline Code, and
-            Links.
+            following types: Bold, Italics, Strikethroughs, Inline Code, Links,
+            and Images. Images display like icons, with a max height equal to
+            the font height.
 
             Unsupported Markdown elements are unwrapped so only their children
             (text contents) render. Display unsupported elements as literal
@@ -159,8 +161,8 @@ class ButtonMixin:
               font library.
 
         disabled : bool
-            An optional boolean, which disables the button if set to True. The
-            default is False.
+            An optional boolean that disables the button if set to ``True``.
+            The default is ``False``.
 
         use_container_width : bool
             Whether to expand the button's width to fill its parent container.
@@ -270,8 +272,9 @@ class ButtonMixin:
         label : str
             A short label explaining to the user what this button is for.
             The label can optionally contain GitHub-flavored Markdown of the
-            following types: Bold, Italics, Strikethroughs, Inline Code, and
-            Links.
+            following types: Bold, Italics, Strikethroughs, Inline Code, Links,
+            and Images. Images display like icons, with a max height equal to
+            the font height.
 
             Unsupported Markdown elements are unwrapped so only their children
             (text contents) render. Display unsupported elements as literal
@@ -340,8 +343,8 @@ class ButtonMixin:
               font library.
 
         disabled : bool
-            An optional boolean, which disables the download button if set to
-            True. The default is False.
+            An optional boolean that disables the download button if set to
+            ``True``. The default is ``False``.
 
         use_container_width : bool
             Whether to expand the button's width to fill its parent container.
@@ -457,8 +460,9 @@ class ButtonMixin:
         label : str
             A short label explaining to the user what this button is for.
             The label can optionally contain GitHub-flavored Markdown of the
-            following types: Bold, Italics, Strikethroughs, Inline Code, and
-            Links.
+            following types: Bold, Italics, Strikethroughs, Inline Code, Links,
+            and Images. Images display like icons, with a max height equal to
+            the font height.
 
             Unsupported Markdown elements are unwrapped so only their children
             (text contents) render. Display unsupported elements as literal
@@ -501,8 +505,8 @@ class ButtonMixin:
               font library.
 
         disabled : bool
-            An optional boolean, which disables the link button if set to
-            True. The default is False.
+            An optional boolean that disables the link button if set to
+            ``True``. The default is ``False``.
 
         use_container_width : bool
             Whether to expand the button's width to fill its parent container.
@@ -544,7 +548,7 @@ class ButtonMixin:
     @gather_metrics("page_link")
     def page_link(
         self,
-        page: str | StreamlitPage,
+        page: str | Path | StreamlitPage,
         *,
         label: str | None = None,
         icon: str | None = None,
@@ -564,7 +568,7 @@ class ButtonMixin:
 
         Parameters
         ----------
-        page : str or st.Page
+        page : str, Path, or st.Page
             The file path (relative to the main script) or an st.Page indicating
             the page to switch to. Alternatively, this can be the URL to an
             external page (must start with "http://" or "https://").
@@ -572,8 +576,9 @@ class ButtonMixin:
         label : str
             The label for the page link. Labels are required for external pages.
             The label can optionally contain GitHub-flavored Markdown of the
-            following types: Bold, Italics, Strikethroughs, Inline Code, and
-            Links.
+            following types: Bold, Italics, Strikethroughs, Inline Code, Links,
+            and Images. Images display like icons, with a max height equal to
+            the font height.
 
             Unsupported Markdown elements are unwrapped so only their children
             (text contents) render. Display unsupported elements as literal
@@ -608,8 +613,8 @@ class ButtonMixin:
             hovered over.
 
         disabled : bool
-            An optional boolean, which disables the page link if set to
-            ``True``. The default is ``False``.
+            An optional boolean that disables the page link if set to ``True``.
+            The default is ``False``.
 
         use_container_width : bool
             Whether to expand the link's width to fill its parent container.
@@ -764,7 +769,7 @@ class ButtonMixin:
 
     def _page_link(
         self,
-        page: str | StreamlitPage,
+        page: str | Path | StreamlitPage,
         *,  # keyword-only arguments:
         label: str | None = None,
         icon: str | None = None,
@@ -793,6 +798,10 @@ class ButtonMixin:
             if label is None:
                 page_link_proto.label = page.title
         else:
+            # Convert Path to string if necessary
+            if isinstance(page, Path):
+                page = str(page)
+
             # Handle external links:
             if is_url(page):
                 if label is None or label == "":

streamlit/elements/widgets/button_group.py

@@ -300,9 +300,8 @@ class ButtonGroupMixin:
             based on its content. No two widgets may have the same key.
 
         disabled : bool
-            An optional boolean, which disables the feedback widget if set
-            to True. The default is False. This argument can only be supplied
-            by keyword.
+            An optional boolean that disables the feedback widget if set
+            to ``True``. The default is ``False``.
 
         on_change : callable
             An optional callback invoked when this feedback widget's value
@@ -440,16 +439,18 @@ class ButtonGroupMixin:
     ) -> list[V] | V | None:
         r"""Display a pills widget.
 
-        A pills widget is similar to a single- or multiselect widget where the passed
-        ``options`` are visually shown as pills-button.
+        A pills widget is similar to a ``st.selectbox`` or ``st.multiselect``
+        where the ``options`` are displayed as pill-buttons instead of a
+        drop-down list.
 
         Parameters
         ----------
-        label : str
+        label: str
             A short label explaining to the user what this widget is for.
             The label can optionally contain GitHub-flavored Markdown of the
-            following types: Bold, Italics, Strikethroughs, Inline Code, and
-            Links.
+            following types: Bold, Italics, Strikethroughs, Inline Code, Links,
+            and Images. Images display like icons, with a max height equal to
+            the font height.
 
             Unsupported Markdown elements are unwrapped so only their children
             (text contents) render. Display unsupported elements as literal
@@ -459,106 +460,116 @@ class ButtonGroupMixin:
             See the ``body`` parameter of |st.markdown|_ for additional,
             supported Markdown directives.
 
-            For accessibility reasons, you should never set an empty label (label="")
-            but hide it with label_visibility if needed. In the future, we may disallow
-            empty labels by raising an exception.
+            For accessibility reasons, you should never set an empty label, but
+            you can hide it with ``label_visibility`` if needed. In the future,
+            we may disallow empty labels by raising an exception.
 
             .. |st.markdown| replace:: ``st.markdown``
             .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
 
-        selection_mode: "single" or "multi"
-            The selection mode for the widget. If "single", only one option can be
-            selected. If "multi", multiple options can be selected.
-
         options: Iterable of V
             Labels for the select options in an ``Iterable``. This can be a
             ``list``, ``set``, or anything supported by ``st.dataframe``. If
             ``options`` is dataframe-like, the first column will be used. Each
             label will be cast to ``str`` internally by default.
 
+        selection_mode: "single" or "multi"
+            The selection mode for the widget. If this is ``"single"``
+            (default), only one option can be selected. If this is ``"multi"``,
+            multiple options can be selected.
+
         default: Iterable of V, V, or None
-            List of default value or a single value. If the ``selection_mode``
-            is "single", only a single value is allowed to be passed.
+            The value of the widget when it first renders. If the
+            ``selection_mode`` is ``multi``, this can be a list of values, a
+            single value, or ``None``. If the ``selection_mode`` is
+            ``"single"``, this can be a single value or ``None``.
 
-        format_func : function
+        format_func: function
             Function to modify the display of the options. It receives
             the raw option as an argument and should output the label to be
             shown for that option. This has no impact on the return value of
             the command.
 
-        key : str or int
+        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
             based on its content. Multiple widgets of the same type may
             not share the same key.
 
-        help : str
-            An optional tooltip that gets displayed next to the multiselect.
+        help: str
+            An optional tooltip that gets displayed next to the widget label.
+            Streamlit only displays the tooltip when
+            ``label_visibility="visible"``.
 
-        on_change : callable
-            An optional callback invoked when this feedback widget's value
-            changes.
+        on_change: callable
+            An optional callback invoked when this widget's value changes.
 
-        args : tuple
+        args: tuple
             An optional tuple of args to pass to the callback.
 
-        kwargs : dict
+        kwargs: dict
             An optional dict of kwargs to pass to the callback.
 
-        disabled : bool
-            An optional boolean, which disables the widget if set
-            to True. The default is False. This argument can only be supplied
-            by keyword.
+        disabled: bool
+            An optional boolean that disables the widget if set to ``True``.
+            The default is ``False``.
 
-        label_visibility : "visible", "hidden", or "collapsed"
-            The visibility of the label. If "hidden", the label doesn't show but there
-            is still empty space for it above the widget (equivalent to label="").
-            If "collapsed", both the label and the space are removed. Default is
-            "visible".
+        label_visibility: "visible", "hidden", or "collapsed"
+            The visibility of the label. The default is ``"visible"``. If this
+            is ``"hidden"``, Streamlit displays an empty spacer instead of the
+            label, which can help keep the widget alligned with other widgets.
+            If this is ``"collapsed"``, Streamlit displays no label or spacer.
 
         Returns
         -------
-        list of V or V or None
-            A list of selected options or an empty list if the ``selection_mode`` is
-            "multi".
-            If the "selection_mode" is "single", the return value is the selected option
-            or None.
+        list of V, V, or None
+            If the ``selection_mode`` is ``multi``, this is a list of selected
+            options or an empty list. If the ``selection_mode`` is
+            ``"single"``, this is a selected option or ``None``.
 
         Examples
         --------
-        Display a pills widget with multi select, and show the option:
+
+        **Example 1: Multi-select pills**
+
+        Display a multi-select pills widget, and show the selection:
 
         >>> import streamlit as st
         >>>
-        >>> options = ["one", "two", "three", "four", "five"]
-        >>> selection = st.pills(label="Numbered pills",
-                                options, selection_mode="multi")
-        >>> st.markdown(f"You selected option: '{selection}'.")
+        >>> options = ["North", "East", "South", "West"]
+        >>> selection = st.pills("Directions", options, selection_mode="multi")
+        >>> st.markdown(f"Your selected options: {selection}.")
 
-        .. output ::
-            TBD
+        .. output::
+           https://doc-pills-multi.streamlit.app/
+           height: 200px
 
+        **Example 2: Single-select pills with icons**
 
-        Display a pills widget that renders icons-only:
+        Display a single-select pills widget with icons:
 
         >>> import streamlit as st
         >>>
-        >>> option_to_icon_map = {
-        >>>     0: ":material/add:",
-        >>>     1: ":material/zoom_in:",
-        >>>     2: ":material/zoom_out:",
-        >>>     3: ":material/zoom_out_map:",
-        >>> }
+        >>> option_map = {
+        ...     0: ":material/add:",
+        ...     1: ":material/zoom_in:",
+        ...     2: ":material/zoom_out:",
+        ...     3: ":material/zoom_out_map:",
+        ... }
         >>> selection = st.pills(
-        >>>     "Icon-only pills",
-        >>>     options=option_to_icon_map.keys(),
-        >>>     format_func=lambda option: option_to_icon_map[option],
-        >>>     selection_mode="single",
-        >>> )
-        >>> st.write(f"Single selection: {selection}")
-
-        .. output ::
-            TBD
+        ...     "Tool",
+        ...     options=option_map.keys(),
+        ...     format_func=lambda option: option_map[option],
+        ...     selection_mode="single",
+        ... )
+        >>> st.write(
+        ...     "Your selected option: "
+        ...     f"{None if selection is None else option_map[selection]}"
+        ... )
+
+        .. output::
+           https://doc-pills-single.streamlit.app/
+           height: 200px
 
         """
         return self._internal_button_group(
@@ -631,16 +642,17 @@ class ButtonGroupMixin:
     ) -> list[V] | V | None:
         r"""Display a segmented control widget.
 
-        A segmented control widget is a linear set of segments where each of the passed
-        ``options`` functions as a button.
+        A segmented control widget is a linear set of segments where each of
+        the passed ``options`` functions like a toggle button.
 
         Parameters
         ----------
         label : str
             A short label explaining to the user what this widget is for.
             The label can optionally contain GitHub-flavored Markdown of the
-            following types: Bold, Italics, Strikethroughs, Inline Code, and
-            Links.
+            following types: Bold, Italics, Strikethroughs, Inline Code, Links,
+            and Images. Images display like icons, with a max height equal to
+            the font height.
 
             Unsupported Markdown elements are unwrapped so only their children
             (text contents) render. Display unsupported elements as literal
@@ -650,106 +662,119 @@ class ButtonGroupMixin:
             See the ``body`` parameter of |st.markdown|_ for additional,
             supported Markdown directives.
 
-            For accessibility reasons, you should never set an empty label (label="")
-            but hide it with label_visibility if needed. In the future, we may disallow
-            empty labels by raising an exception.
+            For accessibility reasons, you should never set an empty label, but
+            you can hide it with ``label_visibility`` if needed. In the future,
+            we may disallow empty labels by raising an exception.
 
             .. |st.markdown| replace:: ``st.markdown``
             .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
 
-        selection_mode: "single" or "multi"
-            The selection mode for the widget. If "single", only one option can be
-            selected. If "multi", multiple options can be selected.
-
         options: Iterable of V
             Labels for the select options in an ``Iterable``. This can be a
             ``list``, ``set``, or anything supported by ``st.dataframe``. If
             ``options`` is dataframe-like, the first column will be used. Each
             label will be cast to ``str`` internally by default.
 
+        selection_mode: "single" or "multi"
+            The selection mode for the widget. If this is ``"single"``
+            (default), only one option can be selected. If this is ``"multi"``,
+            multiple options can be selected.
+
         default: Iterable of V, V, or None
-            List of default value or a single value. If the ``selection_mode``
-            is "single", only a single value is allowed to be passed.
+            The value of the widget when it first renders. If the
+            ``selection_mode`` is ``multi``, this can be a list of values, a
+            single value, or ``None``. If the ``selection_mode`` is
+            ``"single"``, this can be a single value or ``None``.
 
-        format_func : function
+        format_func: function
             Function to modify the display of the options. It receives
             the raw option as an argument and should output the label to be
             shown for that option. This has no impact on the return value of
             the command.
 
-        key : str or int
+        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
             based on its content. Multiple widgets of the same type may
             not share the same key.
 
-        help : str
-            An optional tooltip that gets displayed next to the multiselect.
+        help: str
+            An optional tooltip that gets displayed next to the widget label.
+            Streamlit only displays the tooltip when
+            ``label_visibility="visible"``.
 
-        on_change : callable
-            An optional callback invoked when this feedback widget's value
-            changes.
+        on_change: callable
+            An optional callback invoked when this widget's value changes.
 
-        args : tuple
+        args: tuple
             An optional tuple of args to pass to the callback.
 
-        kwargs : dict
+        kwargs: dict
             An optional dict of kwargs to pass to the callback.
 
-        disabled : bool
-            An optional boolean, which disables the widget if set
-            to True. The default is False. This argument can only be supplied
-            by keyword.
+        disabled: bool
+            An optional boolean that disables the widget if set to ``True``.
+            The default is ``False``.
 
-        label_visibility : "visible", "hidden", or "collapsed"
-            The visibility of the label. If "hidden", the label doesn't show but there
-            is still empty space for it above the widget (equivalent to label="").
-            If "collapsed", both the label and the space are removed. Default is
-            "visible".
+        label_visibility: "visible", "hidden", or "collapsed"
+            The visibility of the label. The default is ``"visible"``. If this
+            is ``"hidden"``, Streamlit displays an empty spacer instead of the
+            label, which can help keep the widget alligned with other widgets.
+            If this is ``"collapsed"``, Streamlit displays no label or spacer.
 
         Returns
         -------
-        list of V or V or None
-            A list of selected options or an empty list if the ``selection_mode`` is
-            "multi".
-            If the "selection_mode" is "single", the return value is the selected option
-            or None.
+        list of V, V, or None
+            If the ``selection_mode`` is ``multi``, this is a list of selected
+            options or an empty list. If the ``selection_mode`` is
+            ``"single"``, this is a selected option or ``None``.
 
         Examples
         --------
-        Display a segmented control widget with multi select, and show the option:
+
+        **Example 1: Multi-select segmented control**
+
+        Display a multi-select segmented control widget, and show the
+        selection:
 
         >>> import streamlit as st
         >>>
         >>> options = ["North", "East", "South", "West"]
-        >>> selection = st.segmented_control(label="Directions",
-                                options, selection_mode="multi")
-        >>> st.markdown(f"You selected options: '{selection}'.")
+        >>> selection = st.segmented_control(
+        ...     "Directions", options, selection_mode="multi"
+        ... )
+        >>> st.markdown(f"Your selected options: {selection}.")
 
-        .. output ::
-            TBD
+        .. output::
+           https://doc-segmented-control-multi.streamlit.app/
+           height: 200px
 
+        **Example 2: Single-select segmented control with icons**
 
-        Display a segmented control widget that renders icons-only:
+        Display a single-select segmented control widget with icons:
 
         >>> import streamlit as st
         >>>
-        >>> option_to_icon_map = {
-        >>>     0: ":material/add:",
-        >>>     1: ":material/zoom_in:",
-        >>>     2: ":material/zoom_out:",
-        >>>     3: ":material/zoom_out_map:",
-        >>> }
+        >>> option_map = {
+        ...     0: ":material/add:",
+        ...     1: ":material/zoom_in:",
+        ...     2: ":material/zoom_out:",
+        ...     3: ":material/zoom_out_map:",
+        ... }
         >>> selection = st.segmented_control(
-        >>>     "Icon-only segmented control",
-        >>>     options=option_to_icon_map.keys(),
-        >>>     format_func=lambda option: option_to_icon_map[option],
-        >>>     selection_mode="single",
-        >>> )
-        >>> st.write(f"Single selection: {selection}")
-
-        .. output ::
-            TBD
+        ...     "Tool",
+        ...     options=option_map.keys(),
+        ...     format_func=lambda option: option_map[option],
+        ...     selection_mode="single",
+        ... )
+        >>> st.write(
+        ...     "Your selected option: "
+        ...     f"{None if selection is None else option_map[selection]}"
+        ... )
+
+        .. output::
+           https://doc-segmented-control-single.streamlit.app/
+           height: 200px
 
         """
         return self._internal_button_group(

streamlit/elements/widgets/camera_input.py

@@ -103,8 +103,9 @@ class CameraInputMixin:
         label : str
             A short label explaining to the user what this widget is used for.
             The label can optionally contain GitHub-flavored Markdown of the
-            following types: Bold, Italics, Strikethroughs, Inline Code, and
-            Links.
+            following types: Bold, Italics, Strikethroughs, Inline Code, Links,
+            and Images. Images display like icons, with a max height equal to
+            the font height.
 
             Unsupported Markdown elements are unwrapped so only their children
             (text contents) render. Display unsupported elements as literal
@@ -114,9 +115,9 @@ class CameraInputMixin:
             See the ``body`` parameter of |st.markdown|_ for additional,
             supported Markdown directives.
 
-            For accessibility reasons, you should never set an empty label (label="")
-            but hide it with label_visibility if needed. In the future, we may disallow
-            empty labels by raising an exception.
+            For accessibility reasons, you should never set an empty label, but
+            you can hide it with ``label_visibility`` if needed. In the future,
+            we may disallow empty labels by raising an exception.
 
             .. |st.markdown| replace:: ``st.markdown``
             .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
@@ -140,13 +141,14 @@ class CameraInputMixin:
             An optional dict of kwargs to pass to the callback.
 
         disabled : bool
-            An optional boolean, which disables the camera input if set to
-            True. Default is False.
+            An optional boolean that disables the camera input if set to
+            ``True``. Default is ``False``.
+
         label_visibility : "visible", "hidden", or "collapsed"
-            The visibility of the label. If "hidden", the label doesn't show but there
-            is still empty space for it above the widget (equivalent to label="").
-            If "collapsed", both the label and the space are removed. Default is
-            "visible".
+            The visibility of the label. The default is ``"visible"``. If this
+            is ``"hidden"``, Streamlit displays an empty spacer instead of the
+            label, which can help keep the widget alligned with other widgets.
+            If this is ``"collapsed"``, Streamlit displays no label or spacer.
 
         Returns
         -------

streamlit/elements/widgets/chat.py

@@ -20,8 +20,8 @@ from typing import TYPE_CHECKING, Literal, cast
 
 from streamlit import runtime
 from streamlit.delta_generator_singletons import get_dg_singleton_instance
-from streamlit.elements.image import AtomicImage, WidthBehaviour, image_to_url
 from streamlit.elements.lib.form_utils import is_in_form
+from streamlit.elements.lib.image_utils import AtomicImage, WidthBehavior, image_to_url
 from streamlit.elements.lib.policies import check_widget_policies
 from streamlit.elements.lib.utils import (
     Key,
@@ -96,7 +96,7 @@ def _process_avatar_input(
         try:
             return AvatarType.IMAGE, image_to_url(
                 avatar,
-                width=WidthBehaviour.ORIGINAL,
+                width=WidthBehavior.ORIGINAL,
                 clamp=False,
                 channels="RGB",
                 output_format="auto",