streamlit-nightly 1.36.1.dev20240721__py2.py3-none-any.whl → 1.36.1.dev20240722__py2.py3-none-any.whl

streamlit/elements/toast.py

@@ -54,25 +54,14 @@ class ToastMixin:
         Parameters
         ----------
         body : str
-            The string to display as Github-flavored Markdown. Syntax
+            The string to display as GitHub-flavored Markdown. Syntax
             information can be found at: https://github.github.com/gfm.
 
-            This also supports:
+            See the ``body`` parameter of |st.markdown|_ for additional,
+            supported Markdown directives.
 
-            * Emoji shortcodes, such as ``:+1:``  and ``:sunglasses:``.
-              For a list of all supported codes,
-              see https://share.streamlit.io/streamlit/emoji-shortcodes.
-
-            * LaTeX expressions, by wrapping them in "$" or "$$" (the "$$"
-              must be on their own lines). Supported LaTeX functions are listed
-              at https://katex.org/docs/supported.html.
-
-            * Colored text and background colors for text, using the syntax
-              ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively. ``color`` must be replaced with any of the following
-              supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
-              For example, you can use ``:orange[your text here]`` or
-              ``:blue-background[your text here]``.
+            .. |st.markdown| replace:: ``st.markdown``
+            .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
 
         icon : str, None
             An optional emoji or icon to display next to the alert. If ``icon``
@@ -91,6 +80,7 @@ class ToastMixin:
               <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
               font library.
 
+
         Example
         -------
         >>> import streamlit as st

streamlit/elements/vega_charts.py

@@ -840,11 +840,16 @@ class VegaChartsMixin:
               for three lines).
 
         stack : bool, "normalize", "center", or None
-            Whether to stack the areas. If this is ``None`` (default), uses
-            Vega's default. If ``True``, stacks the areas on top of one another.
-            If ``False``, overlays the areas without stacking. If "normalize",
-            the areas are stacked and normalized to 100%. If "center", the areas
-            are stacked and shifted to center their baseline (produces steamgraph).
+            Whether to stack the areas. If this is ``None`` (default),
+            Streamlit uses Vega's default. Other values can be as follows:
+
+            - ``True``: The areas form a non-overlapping, additive stack within
+              the chart.
+            - ``False``: The areas overlap each other without stacking.
+            - ``"normalize"``: The areas are stacked and the total height is
+              normalized to 100% of the height of the chart.
+            - ``"center"``: The areas are stacked and shifted to center their
+              baseline, which creates a steamgraph.
 
         width : int or None
             Desired width of the chart expressed in pixels. If ``width`` is
@@ -904,7 +909,7 @@ class VegaChartsMixin:
            https://doc-area-chart1.streamlit.app/
            height: 440px
 
-        Finally, if your dataframe is in wide format, you can group multiple
+        If your dataframe is in wide format, you can group multiple
         columns under the y argument to show multiple series with different
         colors:
 
@@ -927,6 +932,20 @@ class VegaChartsMixin:
            https://doc-area-chart2.streamlit.app/
            height: 440px
 
+        You can adjust the stacking behavior by setting ``stack``. Create a
+        steamgraph:
+
+        >>> import streamlit as st
+        >>> from vega_datasets import data
+        >>>
+        >>> source = data.unemployment_across_industries()
+        >>>
+        >>> st.area_chart(source, x="date", y="count", color="series", stack="center")
+
+        .. output::
+           https://doc-area-chart-steamgraph.streamlit.app/
+           height: 440px
+
         """
 
         # Check that the stack parameter is valid, raise more informative error message if not
@@ -1066,12 +1085,17 @@ class VegaChartsMixin:
             horizontally.
 
         stack : bool, "normalize", "center", "layered", or None
-            Whether to stack the bars. If this is ``None`` (default), uses Vega's
-            default. If ``True``, the bars are stacked on top of each other.
-            If ``False``, the bars are displayed side by side. If "normalize",
-            the bars are stacked and normalized to 100%. If "center", the bars are
-            stacked around a central axis. If "layered", the bars are stacked on top
-            of one another.
+            Whether to stack the bars. If this is ``None`` (default),
+            Streamlit uses Vega's default. Other values can be as follows:
+
+            - ``True``: The bars form a non-overlapping, additive stack within
+              the chart.
+            - ``False``: The bars display side by side.
+            - ``"layered"``: The bars overlap each other without stacking.
+            - ``"normalize"``: The bars are stacked and the total height is
+              normalized to 100% of the height of the chart.
+            - ``"center"``: The bars are stacked and shifted to center the
+              total height around an axis.
 
         width : int or None
             Desired width of the chart expressed in pixels. If ``width`` is
@@ -1171,6 +1195,19 @@ class VegaChartsMixin:
            https://doc-bar-chart-horizontal.streamlit.app/
            height: 440px
 
+        You can unstack your bar charts.
+
+        >>> import streamlit as st
+        >>> from vega_datasets import data
+        >>>
+        >>> source = data.barley()
+        >>>
+        >>> st.bar_chart(source, x="year", y="yield", color="site", stack=False)
+
+        .. output::
+           https://doc-bar-chart-unstacked.streamlit.app/
+           height: 440px
+
         """
 
         # Check that the stack parameter is valid, raise more informative error message if not

streamlit/elements/widgets/button.py

@@ -95,50 +95,49 @@ class ButtonMixin:
         ----------
         label : str
             A short label explaining to the user what this button is for.
-            The label can optionally contain Markdown and supports the following
-            elements: Bold, Italics, Strikethroughs, Inline Code, and Emojis.
+            The label can optionally contain GitHub-flavored Markdown of the
+            following types: Bold, Italics, Strikethroughs, Inline Code, and
+            Links.
 
-            This also supports:
+            Unsupported Markdown elements are unwrapped so only their children
+            (text contents) render. Display unsupported elements as literal
+            characters by backslash-escaping them. E.g.,
+            ``"1\. Not an ordered list"``.
 
-            * Emoji shortcodes, such as ``:+1:``  and ``:sunglasses:``.
-              For a list of all supported codes,
-              see https://share.streamlit.io/streamlit/emoji-shortcodes.
+            See the ``body`` parameter of |st.markdown|_ for additional,
+            supported Markdown directives.
 
-            * LaTeX expressions, by wrapping them in "$" or "$$" (the "$$"
-              must be on their own lines). Supported LaTeX functions are listed
-              at https://katex.org/docs/supported.html.
+            .. |st.markdown| replace:: ``st.markdown``
+            .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
 
-            * Colored text and background colors for text, using the syntax
-              ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively. ``color`` must be replaced with any of the following
-              supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
-              For example, you can use ``:orange[your text here]`` or
-              ``:blue-background[your text here]``.
-
-            Unsupported elements are unwrapped so only their children (text contents) render.
-            Display unsupported elements as literal characters by
-            backslash-escaping them. E.g. ``1\. Not an ordered list``.
         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 when the button is
             hovered over.
+
         on_click : callable
             An optional callback invoked when this button is clicked.
+
         args : tuple
             An optional tuple of args to pass to the callback.
+
         kwargs : dict
             An optional dict of kwargs to pass to the callback.
+
         type : "secondary" or "primary"
             An optional string that specifies the button type. Can be "primary" for a
             button with additional emphasis or "secondary" for a normal button. Defaults
             to "secondary".
+
         disabled : bool
             An optional boolean, which 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.
             If ``use_container_width`` is ``False`` (default), Streamlit sizes
@@ -227,62 +226,64 @@ class ButtonMixin:
         ----------
         label : str
             A short label explaining to the user what this button is for.
-            The label can optionally contain Markdown and supports the following
-            elements: Bold, Italics, Strikethroughs, Inline Code, and Emojis.
+            The label can optionally contain GitHub-flavored Markdown of the
+            following types: Bold, Italics, Strikethroughs, Inline Code, and
+            Links.
 
-            This also supports:
+            Unsupported Markdown elements are unwrapped so only their children
+            (text contents) render. Display unsupported elements as literal
+            characters by backslash-escaping them. E.g.,
+            ``"1\. Not an ordered list"``.
 
-            * Emoji shortcodes, such as ``:+1:``  and ``:sunglasses:``.
-              For a list of all supported codes,
-              see https://share.streamlit.io/streamlit/emoji-shortcodes.
+            See the ``body`` parameter of |st.markdown|_ for additional,
+            supported Markdown directives.
 
-            * LaTeX expressions, by wrapping them in "$" or "$$" (the "$$"
-              must be on their own lines). Supported LaTeX functions are listed
-              at https://katex.org/docs/supported.html.
+            .. |st.markdown| replace:: ``st.markdown``
+            .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
 
-            * Colored text and background colors for text, using the syntax
-              ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively. ``color`` must be replaced with any of the following
-              supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
-              For example, you can use ``:orange[your text here]`` or
-              ``:blue-background[your text here]``.
-
-            Unsupported elements are unwrapped so only their children (text contents)
-            render. Display unsupported elements as literal characters by
-            backslash-escaping them. E.g. ``1\. Not an ordered list``.
         data : str or bytes or file
             The contents of the file to be downloaded. See example below for
             caching techniques to avoid recomputing this data unnecessarily.
+
         file_name: str
             An optional string to use as the name of the file to be downloaded,
             such as 'my_file.csv'. If not specified, the name will be
             automatically generated.
+
         mime : str or None
             The MIME type of the data. If None, defaults to "text/plain"
             (if data is of type *str* or is a textual *file*) or
             "application/octet-stream" (if data is of type *bytes* or is a
             binary *file*).
+
         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 when the button is
             hovered over.
+
         on_click : callable
             An optional callback invoked when this button is clicked.
+
         args : tuple
             An optional tuple of args to pass to the callback.
+
         kwargs : dict
             An optional dict of kwargs to pass to the callback.
+
         type : "secondary" or "primary"
             An optional string that specifies the button type. Can be "primary" for a
             button with additional emphasis or "secondary" for a normal button. Defaults
             to "secondary".
+
         disabled : bool
             An optional boolean, which 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.
             If ``use_container_width`` is ``False`` (default), Streamlit sizes
@@ -394,41 +395,37 @@ class ButtonMixin:
         ----------
         label : str
             A short label explaining to the user what this button is for.
-            The label can optionally contain Markdown and supports the following
-            elements: Bold, Italics, Strikethroughs, Inline Code, and Emojis.
-
-            This also supports:
+            The label can optionally contain GitHub-flavored Markdown of the
+            following types: Bold, Italics, Strikethroughs, Inline Code, and
+            Links.
 
-            * Emoji shortcodes, such as ``:+1:``  and ``:sunglasses:``.
-              For a list of all supported codes,
-              see https://share.streamlit.io/streamlit/emoji-shortcodes.
+            Unsupported Markdown elements are unwrapped so only their children
+            (text contents) render. Display unsupported elements as literal
+            characters by backslash-escaping them. E.g.,
+            ``"1\. Not an ordered list"``.
 
-            * LaTeX expressions, by wrapping them in "$" or "$$" (the "$$"
-              must be on their own lines). Supported LaTeX functions are listed
-              at https://katex.org/docs/supported.html.
+            See the ``body`` parameter of |st.markdown|_ for additional,
+            supported Markdown directives.
 
-            * Colored text and background colors for text, using the syntax
-              ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively. ``color`` must be replaced with any of the following
-              supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
-              For example, you can use ``:orange[your text here]`` or
-              ``:blue-background[your text here]``.
+            .. |st.markdown| replace:: ``st.markdown``
+            .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
 
-            Unsupported elements are unwrapped so only their children (text contents)
-            render. Display unsupported elements as literal characters by
-            backslash-escaping them. E.g. ``1\. Not an ordered list``.
         url : str
             The url to be opened on user click
+
         help : str
             An optional tooltip that gets displayed when the button is
             hovered over.
+
         type : "secondary" or "primary"
             An optional string that specifies the button type. Can be "primary" for a
             button with additional emphasis or "secondary" for a normal button. Defaults
             to "secondary".
+
         disabled : bool
             An optional boolean, which 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.
             If ``use_container_width`` is ``False`` (default), Streamlit sizes
@@ -492,32 +489,25 @@ class ButtonMixin:
             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://").
+
         label : str
             The label for the page link. Labels are required for external pages.
-            Labels can optionally contain Markdown and supports the following
-            elements: Bold, Italics, Strikethroughs, Inline Code, and Emojis.
-
-            This also supports:
-
-            * Emoji shortcodes, such as ``:+1:``  and ``:sunglasses:``.
-              For a list of all supported codes,
-              see https://share.streamlit.io/streamlit/emoji-shortcodes.
-
-            * LaTeX expressions, by wrapping them in "$" or "$$" (the "$$"
-              must be on their own lines). Supported LaTeX functions are listed
-              at https://katex.org/docs/supported.html.
-
-            * Colored text and background colors for text, using the syntax
-              ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively. ``color`` must be replaced with any of the following
-              supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
-              For example, you can use ``:orange[your text here]`` or
-              ``:blue-background[your text here]``.
-
-            Unsupported elements are unwrapped so only their children (text contents)
-            render. Display unsupported elements as literal characters by
-            backslash-escaping them. E.g. ``1\. Not an ordered list``.
-        icon : str, None
+            The label can optionally contain GitHub-flavored Markdown of the
+            following types: Bold, Italics, Strikethroughs, Inline Code, and
+            Links.
+
+            Unsupported Markdown elements are unwrapped so only their children
+            (text contents) render. Display unsupported elements as literal
+            characters by backslash-escaping them. E.g.,
+            ``"1\. Not an ordered list"``.
+
+            See the ``body`` parameter of |st.markdown|_ for additional,
+            supported Markdown directives.
+
+            .. |st.markdown| replace:: ``st.markdown``
+            .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
+
+        icon : str or None
             An optional emoji or icon to display next to the button label. If ``icon``
             is ``None`` (default), no icon is displayed. If ``icon`` is a
             string, the following options are valid:
@@ -533,12 +523,15 @@ class ButtonMixin:
               Thumb Up icon. Find additional icons in the `Material Symbols \
               <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
               font library.
+
         help : str
             An optional tooltip that gets displayed when the link is
             hovered over.
+
         disabled : bool
             An optional boolean, which 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.
             The default is ``True`` for page links in the sidebar and ``False``

streamlit/elements/widgets/button_group.py

@@ -181,57 +181,85 @@ class ButtonGroupMixin:
     ) -> int | None:
         """Display a feedback widget.
 
-        This is useful to collect user feedback, especially in chat-based apps.
+        A feedback widget is an icon-based button group available in three
+        styles, as described in ``options``. It is commonly used in chat and AI
+        apps to allow users to rate responses.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         options: "thumbs", "faces", or "stars"
-            The feedback options displayed to the user. The options are:
-            - "thumbs" (default): displays a row of thumbs-up and thumbs-down buttons.
-            - "faces": displays a row of five buttons with facial expressions, each
-                depicting increasing satisfaction from left to right.
-            - "stars": displays a row of star icons typically used for ratings.
+            The feedback options displayed to the user. ``options`` can be one
+            of the following:
+
+            - ``"thumbs"`` (default): Streamlit displays a thumb-up and
+              thumb-down button group.
+            - ``"faces"``: Streamlit displays a row of five buttons with
+              facial expressions depicting increasing satisfaction from left to
+              right.
+            - ``"stars"``: Streamlit displays a row of star icons, allowing the
+              user to select a rating from one to five stars.
+
         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.
+
         disabled : bool
-            An optional boolean, which disables the multiselect widget if set
+            An optional boolean, which disables the feedback widget if set
             to True. The default is False. This argument can only be supplied
             by keyword.
+
         on_change : callable
-            An optional callback invoked when this multiselect's value changes.
+            An optional callback invoked when this feedback widget's value
+            changes.
+
         args : tuple
             An optional tuple of args to pass to the callback.
+
         kwargs : dict
             An optional dict of kwargs to pass to the callback.
 
         Returns
         -------
-        An integer indicating the user's selection, where 0 is the lowest
-        feedback and higher values indicate more positive feedback.
-        If no option was selected, returns None.
-            - For "thumbs": a return value of 0 is for thumbs-down and 1 for thumbs-up.
-            - For "faces" and "stars":
-                values range from 0 (least satisfied) to 4 (most satisfied).
+        int or None
+            An integer indicating the user's selection, where ``0`` is the
+            lowest feedback. Higher values indicate more positive feedback.
+            If no option was selected, the widget returns ``None``.
 
+            - For ``options="thumbs"``, a return value of ``0`` indicates
+              thumbs-down, and ``1`` indicates thumbs-up.
+            - For ``options="faces"`` and ``options="stars"``, return values
+              range from ``0`` (least satisfied) to ``4`` (most satisfied).
 
         Examples
         --------
-        Example 1: Display a feedback widget with stars and show the selected sentiment
+        Display a feedback widget with stars, and show the selected sentiment:
 
         >>> import streamlit as st
-        >>> sentiment_mapping: = [0.0, 0.25, 0.5, 0.75, 1.0]
+        >>>
+        >>> sentiment_mapping = ["one", "two", "three", "four", "five"]
         >>> selected = st.feedback("stars")
-        >>> st.write(f"You selected: {sentiment_mapping[selected]}")
+        >>> if selected is not None:
+        >>>     st.markdown(f"You selected {sentiment_mapping[selected]} star(s).")
+
+        .. output ::
+            https://doc-feedback-stars.streamlit.app/
+            height: 350px
 
-        Example 2: Display a feedback widget with thumbs and show the selected sentiment
+        Display a feedback widget with thumbs, and show the selected sentiment:
 
         >>> import streamlit as st
-        >>> sentiment_mapping: = [0.0, 1.0]
+        >>>
+        >>> sentiment_mapping = [":material/thumb_down:", ":material/thumb_up:"]
         >>> selected = st.feedback("thumbs")
-        >>> st.write(f"You selected: {sentiment_mapping[selected]}")
+        >>> if selected is not None:
+        >>>     st.markdown(f"You selected: {sentiment_mapping[selected]}")
+
+        .. output ::
+            https://doc-feedback-thumbs.streamlit.app/
+            height: 350px
+
         """
 
         if not isinstance(options, list) and options not in get_args(_FeedbackOptions):

streamlit/elements/widgets/camera_input.py

@@ -102,34 +102,25 @@ class CameraInputMixin:
         ----------
         label : str
             A short label explaining to the user what this widget is used for.
-            The label can optionally contain Markdown and supports the following
-            elements: Bold, Italics, Strikethroughs, Inline Code, Emojis, and Links.
+            The label can optionally contain GitHub-flavored Markdown of the
+            following types: Bold, Italics, Strikethroughs, Inline Code, and
+            Links.
 
-            This also supports:
+            Unsupported Markdown elements are unwrapped so only their children
+            (text contents) render. Display unsupported elements as literal
+            characters by backslash-escaping them. E.g.,
+            ``"1\. Not an ordered list"``.
 
-            * Emoji shortcodes, such as ``:+1:``  and ``:sunglasses:``.
-              For a list of all supported codes,
-              see https://share.streamlit.io/streamlit/emoji-shortcodes.
-
-            * LaTeX expressions, by wrapping them in "$" or "$$" (the "$$"
-              must be on their own lines). Supported LaTeX functions are listed
-              at https://katex.org/docs/supported.html.
-
-            * Colored text and background colors for text, using the syntax
-              ``:color[text to be colored]`` and ``:color-background[text to be colored]``,
-              respectively. ``color`` must be replaced with any of the following
-              supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
-              For example, you can use ``:orange[your text here]`` or
-              ``:blue-background[your text here]``.
-
-            Unsupported elements are unwrapped so only their children (text contents) render.
-            Display unsupported elements as literal characters by
-            backslash-escaping them. E.g. ``1\. Not an ordered list``.
+            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.
 
+            .. |st.markdown| replace:: ``st.markdown``
+            .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
+
         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