streamlit-nightly 1.35.1.dev20240613__py2.py3-none-any.whl → 1.35.1.dev20240614__py2.py3-none-any.whl

streamlit/elements/vega_charts.py

@@ -113,11 +113,13 @@ class VegaLiteState(TypedDict, total=False):
 
     Attributes
     ----------
-    selection : AttributeDictionary
-        The state of the ``on_select`` event. The name of each selection
-        parameter becomes an attribute in the ``selection`` attribute
-        dictionary. The format of the data within each attribute is determined
-        by the selection parameter definition within Vega-Lite.
+    selection : dict
+        The state of the ``on_select`` event. This attribure returns a
+        dictionary-like object that supports both key and attribute notation.
+        The name of each Vega-Lite selection parameter becomes an attribute in
+        the ``selection`` dictionary. The format of the data within each
+        attribute is determined by the selection parameter definition within
+        Vega-Lite.
 
     Examples
     --------
@@ -584,23 +586,32 @@ class VegaChartsMixin:
 
         Parameters
         ----------
-        data : pandas.DataFrame, pandas.Styler, pyarrow.Table, numpy.ndarray, pyspark.sql.DataFrame, snowflake.snowpark.dataframe.DataFrame, snowflake.snowpark.table.Table, Iterable, dict or None
+        data : pandas.DataFrame, pandas.Styler, pyarrow.Table, numpy.ndarray, \
+            pyspark.sql.DataFrame, snowflake.snowpark.dataframe.DataFrame, \
+            snowflake.snowpark.table.Table, Iterable, dict or None
             Data to be plotted.
 
         x : str or None
-            Column name to use for the x-axis. If None, uses the data index for the x-axis.
+            Column name or key associated to the x-axis data. If ``x`` is
+            ``None`` (default), Streamlit uses the data index for the x-axis
+            values.
 
         y : str, Sequence of str, or None
-            Column name(s) to use for the y-axis. If a Sequence of strings,
-            draws several series on the same chart by melting your wide-format
-            table into a long-format table behind the scenes. If None, draws
-            the data of all remaining columns as data series.
+            Column name(s) or key(s) associated to the y-axis data. If this is
+            ``None`` (default), Streamlit draws the data of all remaining
+            columns as data series. If this is a ``Sequence`` of strings,
+            Streamlit draws several series on the same chart by melting your
+            wide-format table into a long-format table behind the scenes.
 
         x_label : str or None
-            The label for the x-axis. If None, either the column name specified in x will be used, or no label will be displayed.
+            The label for the x-axis. If this is ``None`` (default), Streamlit
+            will use the column name specified in ``x`` if available, or else
+            no label will be displayed.
 
         y_label : str or None
-            The label for the y-axis. If None, either the column name specified in y will be used, or no label will be displayed.
+            The label for the y-axis. If this is ``None`` (default), Streamlit
+            will use the column name(s) specified in ``y`` if available, or
+            else no label will be displayed.
 
         color : str, tuple, Sequence of str, Sequence of tuple, or None
             The color to use for different lines in this chart.
@@ -768,23 +779,32 @@ class VegaChartsMixin:
 
         Parameters
         ----------
-        data : pandas.DataFrame, pandas.Styler, pyarrow.Table, numpy.ndarray, pyspark.sql.DataFrame, snowflake.snowpark.dataframe.DataFrame, snowflake.snowpark.table.Table, Iterable, or dict
+        data : pandas.DataFrame, pandas.Styler, pyarrow.Table, numpy.ndarray, \
+            pyspark.sql.DataFrame, snowflake.snowpark.dataframe.DataFrame, \
+            snowflake.snowpark.table.Table, Iterable, or dict
             Data to be plotted.
 
         x : str or None
-            Column name to use for the x-axis. If None, uses the data index for the x-axis.
+            Column name or key associated to the x-axis data. If ``x`` is
+            ``None`` (default), Streamlit uses the data index for the x-axis
+            values.
 
         y : str, Sequence of str, or None
-            Column name(s) to use for the y-axis. If a Sequence of strings,
-            draws several series on the same chart by melting your wide-format
-            table into a long-format table behind the scenes. If None, draws
-            the data of all remaining columns as data series.
+            Column name(s) or key(s) associated to the y-axis data. If this is
+            ``None`` (default), Streamlit draws the data of all remaining
+            columns as data series. If this is a ``Sequence`` of strings,
+            Streamlit draws several series on the same chart by melting your
+            wide-format table into a long-format table behind the scenes.
 
         x_label : str or None
-            The label for the x-axis. If None, either the column name specified in x will be used, or no label will be displayed.
+            The label for the x-axis. If this is ``None`` (default), Streamlit
+            will use the column name specified in ``x`` if available, or else
+            no label will be displayed.
 
         y_label : str or None
-            The label for the y-axis. If None, either the column name specified in y will be used, or no label will be displayed.
+            The label for the y-axis. If this is ``None`` (default), Streamlit
+            will use the column name(s) specified in ``y`` if available, or
+            else no label will be displayed.
 
         color : str, tuple, Sequence of str, Sequence of tuple, or None
             The color to use for different series in this chart.
@@ -953,23 +973,32 @@ class VegaChartsMixin:
 
         Parameters
         ----------
-        data : pandas.DataFrame, pandas.Styler, pyarrow.Table, numpy.ndarray, pyspark.sql.DataFrame, snowflake.snowpark.dataframe.DataFrame, snowflake.snowpark.table.Table, Iterable, or dict
+        data : pandas.DataFrame, pandas.Styler, pyarrow.Table, numpy.ndarray, \
+            pyspark.sql.DataFrame, snowflake.snowpark.dataframe.DataFrame, \
+            snowflake.snowpark.table.Table, Iterable, or dict
             Data to be plotted.
 
         x : str or None
-            Column name to use for the x-axis. If None, uses the data index for the x-axis.
+            Column name or key associated to the x-axis data. If ``x`` is
+            ``None`` (default), Streamlit uses the data index for the x-axis
+            values.
 
         y : str, Sequence of str, or None
-            Column name(s) to use for the y-axis. If a Sequence of strings,
-            draws several series on the same chart by melting your wide-format
-            table into a long-format table behind the scenes. If None, draws
-            the data of all remaining columns as data series.
+            Column name(s) or key(s) associated to the y-axis data. If this is
+            ``None`` (default), Streamlit draws the data of all remaining
+            columns as data series. If this is a ``Sequence`` of strings,
+            Streamlit draws several series on the same chart by melting your
+            wide-format table into a long-format table behind the scenes.
 
         x_label : str or None
-            The label for the x-axis. If None, either the column name specified in x will be used, or no label will be displayed.
+            The label for the x-axis. If this is ``None`` (default), Streamlit
+            will use the column name specified in ``x`` if available, or else
+            no label will be displayed.
 
         y_label : str or None
-            The label for the y-axis. If None, either the column name specified in y will be used, or no label will be displayed.
+            The label for the y-axis. If this is ``None`` (default), Streamlit
+            will use the column name(s) specified in ``y`` if available, or
+            else no label will be displayed.
 
         color : str, tuple, Sequence of str, Sequence of tuple, or None
             The color to use for different series in this chart.
@@ -1012,9 +1041,10 @@ class VegaChartsMixin:
               for three lines).
 
         horizontal : bool
-            Determines the orientation of the chart:
-            * True: Displays the chart horizontally, with the x-axis and y-axis swapped.
-            * False: Displays the chart vertically (default).
+            Whether to make the bars horizontal. If this is ``False``
+            (default), the bars display vertically. If this is ``True``,
+            Streamlit swaps the x-axis and y-axis and the bars display
+            horizontally.
 
         width : int or None
             Desired width of the chart expressed in pixels. If ``width`` is
@@ -1074,7 +1104,7 @@ class VegaChartsMixin:
            https://doc-bar-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:
 
@@ -1094,6 +1124,19 @@ class VegaChartsMixin:
            https://doc-bar-chart2.streamlit.app/
            height: 440px
 
+        You can rotate your bar charts to display horizontally.
+
+        >>> import streamlit as st
+        >>> from vega_datasets import data
+        >>>
+        >>> source = data.barley()
+        >>>
+        >>> st.bar_chart(source, x="variety", y="yield", color="site", horizontal=True)
+
+        .. output::
+           https://doc-bar-chart-horizontal.streamlit.app/
+           height: 440px
+
         """
 
         bar_chart_type = (
@@ -1149,23 +1192,32 @@ class VegaChartsMixin:
 
         Parameters
         ----------
-        data : pandas.DataFrame, pandas.Styler, pyarrow.Table, numpy.ndarray, pyspark.sql.DataFrame, snowflake.snowpark.dataframe.DataFrame, snowflake.snowpark.table.Table, Iterable, dict or None
+        data : pandas.DataFrame, pandas.Styler, pyarrow.Table, numpy.ndarray, \
+            pyspark.sql.DataFrame, snowflake.snowpark.dataframe.DataFrame, \
+            snowflake.snowpark.table.Table, Iterable, dict or None
             Data to be plotted.
 
         x : str or None
-            Column name to use for the x-axis. If None, uses the data index for the x-axis.
+            Column name or key associated to the x-axis data. If ``x`` is
+            ``None`` (default), Streamlit uses the data index for the x-axis
+            values.
 
         y : str, Sequence of str, or None
-            Column name(s) to use for the y-axis. If a Sequence of strings,
-            draws several series on the same chart by melting your wide-format
-            table into a long-format table behind the scenes. If None, draws
-            the data of all remaining columns as data series.
+            Column name(s) or key(s) associated to the y-axis data. If this is
+            ``None`` (default), Streamlit draws the data of all remaining
+            columns as data series. If this is a ``Sequence`` of strings,
+            Streamlit draws several series on the same chart by melting your
+            wide-format table into a long-format table behind the scenes.
 
         x_label : str or None
-            The label for the x-axis. If None, either the column name specified in x will be used, or no label will be displayed.
+            The label for the x-axis. If this is ``None`` (default), Streamlit
+            will use the column name specified in ``x`` if available, or else
+            no label will be displayed.
 
         y_label : str or None
-            The label for the y-axis. If None, either the column name specified in y will be used, or no label will be displayed.
+            The label for the y-axis. If this is ``None`` (default), Streamlit
+            will use the column name(s) specified in ``y`` if available, or
+            else no label will be displayed.
 
         color : str, tuple, Sequence of str, Sequence of tuple, or None
             The color of the circles representing each datapoint.

streamlit/elements/widgets/button.py

@@ -56,7 +56,7 @@ if TYPE_CHECKING:
 FORM_DOCS_INFO: Final = """
 
 For more information, refer to the
-[documentation for forms](https://docs.streamlit.io/library/api-reference/control-flow/st.form).
+[documentation for forms](https://docs.streamlit.io/develop/api-reference/execution-flow/st.form).
 """
 
 DownloadButtonDataType: TypeAlias = Union[str, bytes, TextIO, BinaryIO, io.RawIOBase]
@@ -216,6 +216,10 @@ class ButtonMixin:
         user is connected, so it's a good idea to keep file sizes under a
         couple hundred megabytes to conserve memory.
 
+        If you want to prevent your app from rerunning when a user clicks the
+        download button, wrap the download button in a `fragment
+        <https://docs.streamlit.io/develop/concepts/architecture/fragments>`_.
+
         Parameters
         ----------
         label : str
@@ -560,8 +564,7 @@ class ButtonMixin:
         navigation menus for your apps!
 
         .. |client.showSidebarNavigation| replace:: ``client.showSidebarNavigation``
-        .. _client.showSidebarNavigation: https://docs.streamlit.io/library\
-            /advanced-features/configuration#client
+        .. _client.showSidebarNavigation: https://docs.streamlit.io/develop/api-reference/configuration/config.toml#client
 
         .. output ::
             https://doc-page-link.streamlit.app/

streamlit/elements/widgets/data_editor.py

@@ -669,7 +669,7 @@ class DataEditorMixin:
             * 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>`_.
+              and config options `here <https://docs.streamlit.io/develop/api-reference/data/st.column_config>`_.
 
             To configure the index column(s), use ``_index`` as the column name.
 

streamlit/elements/widgets/file_uploader.py

@@ -242,7 +242,7 @@ class FileUploaderMixin:
         By default, uploaded files are limited to 200MB. You can configure
         this using the ``server.maxUploadSize`` config option. For more info
         on how to set config options, see
-        https://docs.streamlit.io/library/advanced-features/configuration#set-configuration-options
+        https://docs.streamlit.io/develop/api-reference/configuration/config.toml
 
         Parameters
         ----------

streamlit/elements/write.py

@@ -86,7 +86,7 @@ class WriteMixin:
         Example
         -------
         You can pass an OpenAI stream as shown in our tutorial, `Build a \
-        basic LLM chat app <https://docs.streamlit.io/knowledge-base/tutorials\
+        basic LLM chat app <https://docs.streamlit.io/develop/tutorials/llms\
         /build-conversational-apps#build-a-chatgpt-like-app>`_. Alternatively,
         you can pass a generic generator function as input:
 
@@ -272,17 +272,18 @@ class WriteMixin:
             - write(obj)            : Prints str(obj) if otherwise unknown.
 
         unsafe_allow_html : bool
-            This is a keyword-only argument that defaults to False.
+            Whether to render HTML within ``*args``. This only applies to
+            strings or objects falling back on ``_repr_html_()``. If this is
+            ``False`` (default), any HTML tags found in ``body`` will be
+            escaped and therefore treated as raw text. If this is ``True``, any
+            HTML expressions within ``body`` will be rendered.
 
-            By default, any HTML tags found in strings will be escaped and
-            therefore treated as pure text. This behavior may be turned off by
-            setting this argument to True.
+            Adding custom HTML to your app impacts safety, styling, and
+            maintainability.
 
-            That said, *we strongly advise against it*. It is hard to write secure
-            HTML, so by using this argument you may be compromising your users'
-            security. For more information, see:
-
-            https://github.com/streamlit/streamlit/issues/152
+            .. note::
+                If you only want to insert HTML or CSS without Markdown text,
+                we recommend using ``st.html`` instead.
 
         **kwargs : any
             Keyword arguments. Not used.

streamlit/hello/Mapping_Demo.py

@@ -108,7 +108,7 @@ st.markdown("# Mapping Demo")
 st.sidebar.header("Mapping Demo")
 st.write(
     """This demo shows how to use
-[`st.pydeck_chart`](https://docs.streamlit.io/library/api-reference/charts/st.pydeck_chart)
+[`st.pydeck_chart`](https://docs.streamlit.io/develop/api-reference/charts/st.pydeck_chart)
 to display geospatial data."""
 )
 

streamlit/navigation/page.py

@@ -35,30 +35,41 @@ def Page(
     url_path: str | None = None,
     default: bool = False,
 ):
-    """Configure a page in `st.navigation` in a multipage app.
+    """Configure a page for ``st.navigation`` in a multipage app.
 
-    The Page object is passed to `st.navigation` and returned when the user
-    navigates to that page. Call `Page.run()` on the returned Page in your
-    main script to execute the page code.
+    Call ``st.Page`` to initialize a ``StreamlitPage`` object, and pass it to
+    ``st.navigation`` to declare a page in your app.
 
-    Page code can be specified by file path of the page (relative to the main
-    script) or by passing a Callable such as a function.
+    When a user navigates to a page, ``st.navigation`` returns the selected
+    ``StreamlitPage`` object. Call ``StreamlitPage.run()`` on the returned page
+    to execute the page. You can only run the page returned by
+    ``st.navigation``, and you can only run it once per app rerun.
+
+    A page can be defined by a Python file or ``Callable``.
 
     Parameters
     ----------
 
-    page: str or Path or callable
-        The path to the script file or a callable that defines the page.
-        The path must be relative to the main script.
+    page: str, Path, or callable
+        The page source as a ``Callable`` or path to a Python file. If the page
+        source is defined by a Python file, the path can be a string or
+        ``pathlib.Path`` object, but must be declared relative to the
+        entrypoint file. If the page source is defined by a ``Callable``, the
+        ``Callable`` can't accept arguments.
 
     title: str or None
-        The title of the page. If None, the title will be inferred from the
-        page path or callable name.
+        The title of the page. If this is ``None`` (default), the page title
+        (in the browser tab) and label (in the navigation menu) will be
+        inferred from the filename or callable name in ``page``. For more
+        information, see `Overview of multipage apps
+        <https://docs.streamlit.io/st.page.automatic-page-labels>`_.
 
     icon: str or None
-        An optional emoji or icon to display next to the alert. If ``icon``
-        is ``None`` (default), no icon is displayed. If ``icon`` is a
-        string, the following options are valid:
+        An optional emoji or icon to display next to the page title and label.
+        If ``icon`` is ``None`` (default), no icon is displayed next to the
+        page label in the navigation menu, and a Streamlit icon is displayed
+        next to the title (in the browser tab). If ``icon`` is a string, the
+        following options are valid:
 
         * A single-character emoji. For example, you can set ``icon="🚨"``
             or ``icon="🔥"``. Emoji short codes are not supported.
@@ -73,14 +84,27 @@ def Page(
             font library.
 
     url_path: str or None
-        The URL pathname associated with a page. If None, the URL pathname will be
-        inferred from the file name, callable name. The default page will have
-        a url_path of "" to indicate the root url and ignore the value of url_path
+        The page's URL pathname, which is the path relative to the app's root
+        URL. If this is ``None`` (default), the URL pathname will be inferred
+        from the filename or callable name in ``page``. For more information,
+        see `Overview of multipage apps
+        <https://docs.streamlit.io/st.page.automatic-page-urls>`_.
+
+        The default page will have a pathname of ``""``, indicating the root
+        URL of the app. If you set ``default=True``, ``url_path`` is ignored.
 
     default: bool
         Whether this page is the default page to be shown when the app is
-        loaded. Only one page can be marked default. If no default page is
-        provided, the first page will be the default page.
+        loaded. If ``default`` is ``False`` (default), the page will have a
+        nonempty URL pathname. However, if no default page is passed to
+        ``st.navigation`` and this is the first page, this page will become the
+        default page. If ``default`` is ``True``, then the page will have
+        an empty pathname and ``url_path`` will be ignored.
+
+    Returns
+    -------
+    StreamlitPage
+        The page object associated to the given script.
 
     Example
     -------
@@ -88,6 +112,7 @@ def Page(
     >>>
     >>> def page2():
     >>>     st.title("Second page")
+    >>>
     >>> pg = st.navigation([
     >>>	    st.Page("page1.py", title="First page", icon="🔥"),
     >>>	    st.Page(page2, title="Second page", icon=":material/favorite:"),
@@ -100,6 +125,39 @@ def Page(
 
 
 class StreamlitPage:
+    """A page within a multipage Streamlit app.
+
+    Use ``st.Page`` to initialize a ``StreamlitPage`` object.
+
+    Attributes
+    ----------
+    icon : str
+        The icon of the page.
+
+        If no icon was declared in ``st.Page``, this property returns ``""``.
+
+    title : str
+        The title of the page.
+
+        Unless declared otherwise in ``st.Page``, the page title is inferred
+        from the filename or callable name. For more information, see
+        `Overview of multipage apps
+        <https://docs.streamlit.io/st.page.automatic-page-labels>`_.
+
+    url_path : str
+        The page's URL pathname, which is the path relative to the app's root
+        URL.
+
+        Unless declared otherwise in ``st.Page``, the URL pathname is inferred
+        from the filename or callable name. For more information, see
+        `Overview of multipage apps
+        <https://docs.streamlit.io/st.page.automatic-page-urls>`_.
+
+        The default page will always have a ``url_path`` of ``""`` to indicate
+        the root URL (e.g. homepage).
+
+    """
+
     def __init__(
         self,
         page: str | Path | Callable[[], None],
@@ -161,17 +219,47 @@ class StreamlitPage:
 
     @property
     def title(self) -> str:
+        """The title of the page.
+
+        Unless declared otherwise in ``st.Page``, the page title is inferred
+        from the filename or callable name. For more information, see
+        `Overview of multipage apps
+        <https://docs.streamlit.io/st.page.automatic-page-labels>`_.
+        """
         return self._title
 
     @property
     def icon(self) -> str:
+        """The icon of the page.
+
+        If no icon was declared in ``st.Page``, this property returns ``""``.
+        """
         return self._icon
 
     @property
     def url_path(self) -> str:
+        """The page's URL pathname, which is the path relative to the app's \
+        root URL.
+
+        Unless declared otherwise in ``st.Page``, the URL pathname is inferred
+        from the filename or callable name. For more information, see
+        `Overview of multipage apps
+        <https://docs.streamlit.io/st.page.automatic-page-urls>`_.
+
+        The default page will always have a ``url_path`` of ``""`` to indicate
+        the root URL (e.g. homepage).
+        """
         return "" if self._default else self._url_path
 
     def run(self) -> None:
+        """Execute the page.
+
+        When a page is returned by ``st.navigation``, use the ``.run()`` method
+        within your entrypoint file to render the page. You can only call this
+        method on the page returned by ``st.navigation``. You can only call
+        this method once per run of your entrypoint file.
+
+        """
         if not self._can_be_called:
             raise StreamlitAPIException(
                 "This page cannot be called directly. Only the page returned from st.navigation can be called once."

streamlit/runtime/caching/cache_data_api.py

@@ -414,7 +414,7 @@ class CacheDataAPI:
         cache with ``st.cache_data.clear()``.
 
         To cache global resources, use ``st.cache_resource`` instead. Learn more
-        about caching at https://docs.streamlit.io/library/advanced-features/caching.
+        about caching at https://docs.streamlit.io/develop/concepts/architecture/caching.
 
         Parameters
         ----------
@@ -456,9 +456,6 @@ class CacheDataAPI:
             Setting this parameter to True may lead to excessive memory use since the
             widget value is treated as an additional input parameter to the cache.
 
-            .. note::
-                This parameter is deprecated and will be removed in a future release.
-
         hash_funcs : dict or None
             Mapping of types or fully qualified names to hash functions.
             This is used to override the behavior of the hasher inside Streamlit's
@@ -467,6 +464,10 @@ class CacheDataAPI:
             the provided function to generate a hash for it. See below for an example
             of how this can be used.
 
+        .. deprecated::
+            ``experimental_allow_widgets`` is deprecated and will be removed in
+            a later version.
+
         Example
         -------
         >>> import streamlit as st

streamlit/runtime/caching/cache_errors.py

@@ -23,7 +23,7 @@ from streamlit.runtime.caching.cache_type import CacheType, get_decorator_api_na
 if TYPE_CHECKING:
     from types import FunctionType
 
-CACHE_DOCS_URL = "https://docs.streamlit.io/library/advanced-features/caching"
+CACHE_DOCS_URL = "https://docs.streamlit.io/develop/concepts/architecture/caching"
 
 
 def get_cached_func_name_md(func: Any) -> str:

streamlit/runtime/caching/cache_resource_api.py

@@ -284,7 +284,7 @@ class CacheResourceAPI:
         cache with ``st.cache_resource.clear()``.
 
         To cache data, use ``st.cache_data`` instead. Learn more about caching at
-        https://docs.streamlit.io/library/advanced-features/caching.
+        https://docs.streamlit.io/develop/concepts/architecture/caching.
 
         Parameters
         ----------
@@ -328,9 +328,6 @@ class CacheResourceAPI:
             Setting this parameter to True may lead to excessive memory use since the
             widget value is treated as an additional input parameter to the cache.
 
-            .. note::
-                This parameter is deprecated and will be removed in a future release.
-
         hash_funcs : dict or None
             Mapping of types or fully qualified names to hash functions.
             This is used to override the behavior of the hasher inside Streamlit's
@@ -339,6 +336,10 @@ class CacheResourceAPI:
             the provided function to generate a hash for it. See below for an example
             of how this can be used.
 
+        .. deprecated::
+            ``experimental_allow_widgets`` is deprecated and will be removed in
+            a later version.
+
         Example
         -------
         >>> import streamlit as st

streamlit/runtime/caching/legacy_cache_api.py

@@ -41,29 +41,30 @@ def cache(
     max_entries: int | None = None,
     ttl: float | None = None,
 ):
-    """Function decorator to memoize function executions.
+    """Legacy caching decorator (deprecated).
+
+    Legacy caching with ``st.cache`` has been removed from Streamlit. This is
+    now an alias for ``st.cache_data`` and ``st.cache_resource``.
 
     Parameters
     ----------
     func : callable
-        The function to cache. Streamlit hashes the function and dependent code.
+        The function to cache. Streamlit hashes the function's source code.
 
     persist : bool
         Whether to persist the cache on disk.
 
     allow_output_mutation : bool
-        Streamlit shows a warning when return values are mutated, as that
-        can have unintended consequences. This is done by hashing the return value internally.
-
-        If you know what you're doing and would like to override this warning, set this to True.
+        Whether to use ``st.cache_data`` or ``st.cache_resource``. If this is
+        ``False`` (default), the arguments are passed to ``st.cache_data``. If
+        this is ``True``, the arguments are passed to ``st.cache_resource``.
 
     show_spinner : bool
-        Enable the spinner. Default is True to show a spinner when there is
-        a cache miss.
+        Enable the spinner. Default is ``True`` to show a spinner when there is
+        a "cache miss" and the cached data is being created.
 
     suppress_st_warning : bool
-        Suppress warnings about calling Streamlit commands from within
-        the cached function.
+        This is not used.
 
     hash_funcs : dict or None
         Mapping of types or fully qualified names to hash functions. This is used to override
@@ -73,9 +74,9 @@ def cache(
         for an example of how this can be used.
 
     max_entries : int or None
-        The maximum number of entries to keep in the cache, or None
+        The maximum number of entries to keep in the cache, or ``None``
         for an unbounded cache. (When a new entry is added to a full cache,
-        the oldest cached entry will be removed.) The default is None.
+        the oldest cached entry will be removed.) The default is ``None``.
 
     ttl : float or None
         The maximum number of seconds to keep an entry in the cache, or