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

streamlit/__init__.py

@@ -244,7 +244,7 @@ experimental_singleton = _experimental_singleton
 experimental_user = _UserInfoProxy()
 
 
-_EXPERIMENTAL_QUERY_PARAMS_DEPRECATE_MSG = "Refer to our [docs page](https://docs.streamlit.io/library/api-reference/utilities/st.query_params) for more information."
+_EXPERIMENTAL_QUERY_PARAMS_DEPRECATE_MSG = "Refer to our [docs page](https://docs.streamlit.io/develop/api-reference/caching-and-state/st.query_params) for more information."
 
 experimental_get_query_params = _deprecate_func_name(
     _get_query_params,

streamlit/commands/navigation.py

@@ -61,37 +61,103 @@ def navigation(
     """
     Configure the available pages in a multipage app.
 
-    Call `st.navigation` in your main script with one or more pages defined by
-    `st.Page`. `st.navigation` returns the current page which can be executed
-    using `Page.run()`.
+    Call ``st.navigation`` in your entrypoint file with one or more pages
+    defined by ``st.Page``. ``st.navigation`` returns the current page, which
+    can be executed using ``.run()`` method.
 
-    When using `st.navigation`, the main script is executed on every app rerun,
-    with the current page executed in-line using `Page.run()`. The set of
-    available pages can be updated with each rerun for dynamic navigation. In
-    this mode, the `pages/` folder is ignored.
+    When using ``st.navigation``, your entrypoint file (the file passed to
+    ``streamlit run``) acts like a router or frame of common elements around
+    each of your pages. Streamlit executes the entrypoint file with every app
+    rerun. To execute the current page, you must call the ``.run()`` method on
+    the page object returned by ``st.navigation``.
 
-    By default, `st.navigation` draws the available pages in the side
-    navigation. This behavior can be changed using the `position=` keyword
-    argument.
+    The set of available pages can be updated with each rerun for dynamic
+    navigation. By default, ``st.navigation`` draws the available pages in the
+    side navigation if there is more than one page. This behavior can be
+    changed using the ``position`` keyword argument.
+
+    As soon as any session of your app executes the ``st.navigation`` command,
+    your app will ignore the ``pages/`` directory (across all sessions).
 
     Parameters
     ----------
-    pages: list[st.Page] or dict[str, list[st.Page]]
-        A list of `st.Page` objects or a dictionary where the keys are section
-        headers and the values are lists of `st.Page` objects.
+    pages: list[StreamlitPage] or dict[str, list[StreamlitPage]]
+        The available pages for the app.
+
+        To create labeled sections or page groupings within the navigation
+        menu, ``pages`` must be a dictionary. Each key is the label of a
+        section and each value is the list of ``StreamlitPage`` objects for
+        that section.
+
+        To create a navigation menu with no sections or page groupings,
+        ``pages`` must be a list of ``StreamlitPage`` objects.
+
+        Use ``st.Page`` to create ``StreamlitPage`` objects.
 
     position: "sidebar" or "hidden"
-        The position of the navigation menu. Can be "sidebar" or "hidden".
+        The position of the navigation menu. If ``position`` is ``"sidebar"``
+        (default), the navigation widget appears at the top of the sidebar. If
+        ``position`` is ``"hidden"``, the navigation widget is not displayed.
+
+        If there is only one page in ``pages``, the navigation will be hidden
+        for any value of ``position``.
 
-    Example
+    Returns
     -------
+    StreamlitPage
+        The current page selected by the user.
+
+    Examples
+    --------
+    The following examples show possible entrypoint files, which is the file
+    you pass to ``streamlit run``. Your entrypoint file manages your app's
+    navigation and serves as a router between pages.
+
+    You can declare pages from callables or file paths.
+
+    >>> import streamlit as st
+    >>> from page_functions import page1
+    >>>
+    >>> pg = st.navigation([st.Page(page1), st.Page("page2.py")])
+    >>> pg.run()
+
+    Use a dictionary to create sections within your navigation menu.
+
     >>> import streamlit as st
-    >>> from pages import page1, page2
     >>>
-    >>>	pg = st.navigation([st.Page(page1), st.Page(page2)])
+    >>> pages = {
+    ...     "Your account" : [
+    ...         st.Page("create_account.py", title="Create your account"),
+    ...         st.Page("manage_account.py", title="Manage your account")
+    ...     ],
+    ...     "Resources" : [
+    ...         st.Page("learn.py", title="Learn about us"),
+    ...         st.Page("trial.py", title="Try it out")
+    ...     ]
+    ... }
     >>>
-    >>>	st.title("My Awesome App")
+    >>> pg = st.navigation(pages)
     >>> pg.run()
+
+    Call widget functions in your entrypoint file when you want a widget to be
+    stateful across pages. Assign keys to your common widgets and access their
+    values through Session State within your pages.
+
+    >>> import streamlit as st
+    >>>
+    >>> def page1():
+    >>>     st.write(st.session_state.foo)
+    >>>
+    >>> def page2():
+    >>>     st.write(st.session_state.bar)
+    >>>
+    >>> # Widgets shared by all the pages
+    >>> st.sidebar.selectbox("Foo", ["A", "B", "C"], key="foo")
+    >>> st.sidebar.checkbox("Bar", key="bar")
+    >>>
+    >>> pg = st.navigation(st.Page(page1), st.Page(page2))
+    >>> pg.run()
+
     """
     nav_sections = {"": pages} if isinstance(pages, list) else pages
     page_list = pages_from_nav_sections(nav_sections)

streamlit/components/v1/component_registry.py

@@ -52,25 +52,40 @@ def declare_component(
     path: str | None = None,
     url: str | None = None,
 ) -> CustomComponent:
-    """Create a custom component and register it if there is a ScriptRun context.
+    """Create a custom component and register it if there is a ``ScriptRunContext``.
 
-    The component is not registered when there is no ScriptRun context; this can happen when CustomComponents are executed as standalone commands, e.g. for testing.
+    The component is not registered when there is no ``ScriptRunContext``.
+    This can happen when a ``CustomComponent`` is executed as standalone
+    command (e.g. for testing).
+
+    To use this function, import it from the ``streamlit.components.v1``
+    module.
+
+    .. warning::
+        Using ``st.components.v1.declare_component`` directly (instead of
+        importing its module) is deprecated and will be disallowd in a later
+        version.
 
     Parameters
     ----------
-    name: str
-        A short, descriptive name for the component. Like, "slider".
+    name : str
+        A short, descriptive name for the component, like "slider".
+
     path: str or None
-        The path to serve the component's frontend files from. Either
-        `path` or `url` must be specified, but not both.
+        The path to serve the component's frontend files from. If ``path`` is
+        ``None`` (default), Streamlit will server the component from the
+        location in ``url``. Either ``path`` or ``url`` must be specified, but
+        not both.
+
     url: str or None
-        The URL that the component is served from. Either `path` or `url`
-        must be specified, but not both.
+        The URL that the component is served from. If ``url`` is ``None``
+        (default), Streamlit will server the component from the location in
+        ``path``. Either ``path`` or ``url`` must be specified, but not both.
 
     Returns
     -------
     CustomComponent
-        A CustomComponent that can be called like a function.
+        A ``CustomComponent`` that can be called like a function.
         Calling the component will create a new instance of the component
         in the Streamlit app.
 

streamlit/elements/arrow.py

@@ -95,12 +95,19 @@ class DataframeSelectionState(TypedDict, total=False):
     key and attribute notation. Selection states cannot be programmatically
     changed or set through Session State.
 
+    .. warning::
+        If a user sorts a dataframe, row selections will be reset. If your
+        users need to sort and filter the dataframe to make selections, direct
+        them to use the search function in the dataframe toolbar instead.
+
     Attributes
     ----------
     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.
+        The selected rows, identified by their integer position. The integer
+        positions match the original dataframe, even if the user sorts the
+        dataframe in their browser. For a ``pandas.DataFrame``, you can
+        retrieve data from its interger position using methods like ``.iloc[]``
+        or ``.iat[]``.
     columns : list[str]
         The selected columns, identified by their names.
 
@@ -150,8 +157,12 @@ class DataframeState(TypedDict, total=False):
 
     Attributes
     ----------
-    selection : DataframeSelectionState
-        The state of the ``on_select`` event.
+    selection : dict
+        The state of the ``on_select`` event. This attribure returns a
+        dictionary-like object that supports both key and attribute notation.
+        The attributes are described by the ``DataframeSelectionState``
+        dictionary schema.
+
 
     """
 
@@ -346,7 +357,7 @@ class ArrowMixin:
               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>`_.
+              `Column configuration <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/deck_gl_json_chart.py

@@ -66,7 +66,7 @@ class PydeckMixin:
 
         To get a token for yourself, create an account at https://mapbox.com.
         For more info on how to set config options, see
-        https://docs.streamlit.io/library/advanced-features/configuration
+        https://docs.streamlit.io/develop/api-reference/configuration/config.toml.
 
         Parameters
         ----------

streamlit/elements/dialog_decorator.py

@@ -127,9 +127,11 @@ def dialog_decorator(
     handling any side effects of that behavior.
 
     .. warning::
-        A dialog may not open another dialog. Only one dialog function may be
-        called in a script run, which means that only one dialog can be open at
-        any given time.
+        Only one dialog function may be called in a script run, which means
+        that only one dialog can be open at any given time. Since a dialog is
+        also a fragment, all fragment limitations apply. Dialogs can't contain
+        fragments, and fragments can't contain dialogs. Using dialogs in widget
+        callback functions is not supported.
 
     .. |st.experimental_fragment| replace:: ``st.experimental_fragment``
     .. _st.experimental_fragment: https://docs.streamlit.io/develop/api-reference/execution-flow/st.fragment

streamlit/elements/html.py

@@ -57,15 +57,7 @@ class HtmlMixin:
         -------
         >>> import streamlit as st
         >>>
-        >>> code = \"""
-        ... <style>
-        ...     p {
-        ...         color: red;
-        ...     }
-        ... </style>
-        ... \"""
-        >>> st.html(code)
-        >>> st.markdown("Lorem ipsum")
+        >>> st.html("<p><span style='text-decoration: line-through double red;'>Oops</span>!</p>")
 
         .. output::
            https://doc-html.streamlit.app/

streamlit/elements/iframe.py

@@ -34,18 +34,37 @@ class IframeMixin:
     ) -> DeltaGenerator:
         """Load a remote URL in an iframe.
 
+        To use this function, import it from the ``streamlit.components.v1``
+        module.
+
+        .. warning::
+            Using ``st.components.v1.iframe`` directly (instead of importing
+            its module) is deprecated and will be disallowd in a later version.
+
         Parameters
         ----------
         src : str
             The URL of the page to embed.
+
         width : int
-            The width of the frame in CSS pixels. Defaults to the app's
-            default element width.
+            The width of the iframe in CSS pixels. By default, this is the
+            app's default element width.
+
         height : int
-            The height of the frame in CSS pixels. Defaults to 150.
+            The height of the frame in CSS pixels. By default, this is ``150``.
+
         scrolling : bool
-            If True, show a scrollbar when the content is larger than the iframe.
-            Otherwise, do not show a scrollbar. Defaults to False.
+            Whether to allow scrolling in the iframe. If this ``False``
+            (default), Streamlit crops any content larger than the iframe and
+            does not show a scrollbar. If this is ``True``, Streamlit shows a
+            scrollbar when the content is larger than the iframe.
+
+        Example
+        -------
+
+        >>> import streamlit.components.v1 as components
+        >>>
+        >>> components.iframe("https://example.com", height=500)
 
         """
         iframe_proto = IFrameProto()
@@ -68,18 +87,42 @@ class IframeMixin:
     ) -> DeltaGenerator:
         """Display an HTML string in an iframe.
 
+        To use this function, import it from the ``streamlit.components.v1``
+        module.
+
+        If you want to insert HTML text into your app without an iframe, try
+        ``st.html`` instead.
+
+        .. warning::
+            Using ``st.components.v1.html`` directly (instead of importing
+            its module) is deprecated and will be disallowd in a later version.
+
         Parameters
         ----------
         html : str
             The HTML string to embed in the iframe.
+
         width : int
-            The width of the frame in CSS pixels. Defaults to the app's
-            default element width.
+            The width of the iframe in CSS pixels. By default, this is the
+            app's default element width.
+
         height : int
-            The height of the frame in CSS pixels. Defaults to 150.
+            The height of the frame in CSS pixels. By default, this is ``150``.
+
         scrolling : bool
-            If True, show a scrollbar when the content is larger than the iframe.
-            Otherwise, do not show a scrollbar. Defaults to False.
+            Whether to allow scrolling in the iframe. If this ``False``
+            (default), Streamlit crops any content larger than the iframe and
+            does not show a scrollbar. If this is ``True``, Streamlit shows a
+            scrollbar when the content is larger than the iframe.
+
+        Example
+        -------
+
+        >>> import streamlit.components.v1 as components
+        >>>
+        >>> components.html(
+        >>>     "<p><span style='text-decoration: line-through double red;'>Oops</span>!</p>"
+        >>> )
 
         """
         iframe_proto = IFrameProto()

streamlit/elements/layouts.py

@@ -164,7 +164,8 @@ class LayoutsMixin:
         Columns can only be placed inside other columns up to one level of nesting.
 
         .. warning::
-            Columns cannot be placed inside other columns in the sidebar. This is only possible in the main area of the app.
+            Columns cannot be placed inside other columns in the sidebar. This
+            is only possible in the main area of the app.
 
         Parameters
         ----------
@@ -180,10 +181,11 @@ class LayoutsMixin:
               the width of the first one, and the third one is three times that width.
 
         gap : "small", "medium", or "large"
-            The size of the gap between the columns. Defaults to "small".
+            The size of the gap between the columns. The default is ``"small"``.
 
         vertical_alignment : "top", "center", or "bottom"
-            The vertical alignment of the content inside the columns. Defaults to "top".
+            The vertical alignment of the content inside the columns. The
+            default is ``"top"``.
 
         Returns
         -------
@@ -232,6 +234,38 @@ class LayoutsMixin:
             https://doc-columns2.streamlit.app/
             height: 550px
 
+        Use ``vertical_alignment="bottom"`` to align widgets.
+
+        >>> import streamlit as st
+        >>>
+        >>> left, middle, right = st.columns(3, vertical_alignment="bottom")
+        >>>
+        >>> left.text_input("Write something")
+        >>> middle.button("Click me", use_container_width=True)
+        >>> right.checkbox("Check me")
+
+        .. output ::
+            https://doc-columns-bottom-widgets.streamlit.app/
+            height: 200px
+
+        Adjust vertical alignment to customize your grid layouts.
+
+        >>> import streamlit as st
+        >>> import numpy as np
+        >>>
+        >>> vertical_alignment = st.selectbox(
+        >>>     "Vertical alignment", ["top", "center", "bottom"], index=2
+        >>> )
+        >>>
+        >>> left, middle, right = st.columns(3, vertical_alignment=vertical_alignment)
+        >>> left.image("https://static.streamlit.io/examples/cat.jpg")
+        >>> middle.image("https://static.streamlit.io/examples/dog.jpg")
+        >>> right.image("https://static.streamlit.io/examples/owl.jpg")
+
+        .. output ::
+            https://doc-columns-vertical-alignment.streamlit.app/
+            height: 600px
+
         """
         weights = spec
         if isinstance(weights, int):
@@ -244,7 +278,7 @@ class LayoutsMixin:
             raise StreamlitAPIException(
                 "The input argument to st.columns must be either a "
                 "positive integer or a list of positive numeric weights. "
-                "See [documentation](https://docs.streamlit.io/library/api-reference/layout/st.columns) "
+                "See [documentation](https://docs.streamlit.io/develop/api-reference/layout/st.columns) "
                 "for more information."
             )
 
@@ -456,9 +490,11 @@ class LayoutsMixin:
             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``.
+
         expanded : bool
             If True, initializes the expander in "expanded" state. Defaults to
             False (collapsed).
+
         icon : str, None
             An optional emoji or icon to display next to the expander label. If ``icon``
             is ``None`` (default), no icon is displayed. If ``icon`` is a

streamlit/elements/lib/column_types.py

@@ -1038,7 +1038,7 @@ def ImageColumn(
     The cell values need to be one of:
 
     * A URL to fetch the image from. This can also be a relative URL of an image
-      deployed via `static file serving <https://docs.streamlit.io/library/advanced-features/static-file-serving>`_.
+      deployed via `static file serving <https://docs.streamlit.io/develop/concepts/configuration/serving-static-files>`_.
       Note that you can NOT use an arbitrary local image if it is not available through
       a public URL.
     * A data URL containing an SVG XML like ``data:image/svg+xml;utf8,<svg xmlns=...</svg>``.

streamlit/elements/map.py

@@ -112,7 +112,7 @@ class MapMixin:
 
         To get a token for yourself, create an account at https://mapbox.com.
         For more info on how to set config options, see
-        https://docs.streamlit.io/library/advanced-features/configuration
+        https://docs.streamlit.io/develop/api-reference/configuration/config.toml.
 
         Parameters
         ----------

streamlit/elements/markdown.py

@@ -64,15 +64,17 @@ class MarkdownMixin:
               ``:blue-background[your text here]``.
 
         unsafe_allow_html : bool
-            By default, any HTML tags found in the body will be escaped and
-            therefore treated as pure text. This behavior may be turned off by
-            setting this argument to True.
+            Whether to render HTML within ``body``. 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.
 
-            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:
+            Adding custom HTML to your app impacts safety, styling, and
+            maintainability.
 
-            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.
 
         help : str
             An optional tooltip that gets displayed next to the Markdown.
@@ -185,15 +187,17 @@ class MarkdownMixin:
               ``:blue-background[your text here]``.
 
         unsafe_allow_html : bool
-            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.
+            Whether to render HTML within ``body``. 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.
 
-            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:
+            Adding custom HTML to your app impacts safety, styling, and
+            maintainability.
 
-            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.
 
         help : str
             An optional tooltip that gets displayed next to the caption.

streamlit/elements/plotly_chart.py

@@ -184,8 +184,11 @@ class PlotlyState(TypedDict, total=False):
 
     Attributes
     ----------
-    selection : PlotlySelectionState
-        The state of the ``on_select`` event.
+    selection : dict
+        The state of the ``on_select`` event. This attribure returns a
+        dictionary-like object that supports both key and attribute notation.
+        The attributes are described by the ``PlotlySelectionState`` dictionary
+        schema.
 
     Example
     -------

streamlit/elements/toast.py

@@ -48,7 +48,7 @@ class ToastMixin:
 
         .. warning::
             ``st.toast`` is not compatible with Streamlit's `caching \
-            <https://docs.streamlit.io/library/advanced-features/caching>`_ and
+            <https://docs.streamlit.io/develop/concepts/architecture/caching>`_ and
             cannot be called within a cached function.
 
         Parameters