streamlit-nightly 1.38.1.dev20240926__py2.py3-none-any.whl → 1.38.1.dev20240928__py2.py3-none-any.whl

streamlit/commands/logo.py

@@ -58,27 +58,35 @@ def logo(
         sidebar. If ``icon_image`` is also provided, then Streamlit will only
         display ``image`` in the sidebar.
 
-        Streamlit scales the image to a height of 24 pixels and a maximum
-        width of 240 pixels. Use images with an aspect ratio of 10:1 or less to
-        avoid distortion.
+        Streamlit scales the image to a max height set by ``size`` and a max
+        width to fit within the sidebar.
     size: "small", "medium", or "large"
         The size of the image displayed in the upper-left corner of the app and its
-        sidebar. The default is ``"medium"``.
+        sidebar. The possible values are as follows:
+
+        - ``"small"``: 20px max height
+        - ``"medium"`` (default): 24px max height
+        - ``"large"``: 32px max height
+
     link : str or None
         The external URL to open when a user clicks on the logo. The URL must
         start with "\\http://" or "\\https://". If ``link`` is ``None`` (default),
         the logo will not include a hyperlink.
     icon_image: Anything supported by st.image or None
-        An alternate image to replace ``image`` in the upper-left corner of the
-        app's main body. If ``icon_image`` is ``None`` (default), Streamlit
-        will render ``image`` in the upper-left corner of the app and its
-        sidebar. Otherwise, Streamlit will render ``icon_image`` in the
-        upper-left corner of the app and ``image`` in the upper-left corner
-        of the sidebar.
-
-        Streamlit scales the image to a height of 24 pixels and a maximum
-        width of 240 pixels. Use images with an aspect ratio of 10:1 or less to
-        avoid distortion.
+        An optional, typically smaller image to replace ``image`` in the
+        upper-left corner when the sidebar is closed. If ``icon_image`` is
+        ``None`` (default), Streamlit will always display ``image`` in the
+        upper-left corner, regardless of whether the sidebar is open or closed.
+        Otherwise, Streamlit will render ``icon_image`` in the upper-left
+        corner of the app when the sidebar is closed.
+
+        Streamlit scales the image to a max height set by ``size`` and a max
+        width to fit within the sidebar. If the sidebar is closed, the max
+        width is retained from when it was last open.
+
+        For best results, pass a wide or horizontal image to ``image`` and a
+        square image to ``icon_image``. Or, pass a square image to ``image``
+        and leave ``icon_image=None``.
 
     Examples
     --------

streamlit/commands/navigation.py

@@ -82,7 +82,7 @@ def navigation(
 
     Parameters
     ----------
-    pages: list[StreamlitPage] or dict[str, list[StreamlitPage]]
+    pages : list[StreamlitPage] or dict[str, list[StreamlitPage]]
         The available pages for the app.
 
         To create labeled sections or page groupings within the navigation
@@ -95,7 +95,7 @@ def navigation(
 
         Use ``st.Page`` to create ``StreamlitPage`` objects.
 
-    position: "sidebar" or "hidden"
+    position : "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.
@@ -103,11 +103,16 @@ def navigation(
         If there is only one page in ``pages``, the navigation will be hidden
         for any value of ``position``.
 
-    expanded: bool
-        Whether the navigation menu should be expanded. If ``True``,
-        the navigation menu will always be expanded. If ``False``, the
-        navigation menu will be collapsed and will include a button
-        to view more options.
+    expanded : bool
+        Whether the navigation menu should be expanded. If this is ``False``
+        (default), the navigation menu will be collapsed and will include a
+        button to view more options when there are too many pages to display.
+        If this is ``True``, the navigation menu will always be expanded; no
+        button to collapse the menu will be displayed.
+
+        If ``st.navigation`` changes from ``expanded=True`` to
+        ``expanded=False`` on a rerun, the menu will stay expanded and a
+        collapse button will be displayed.
 
     Returns
     -------

streamlit/components/v1/component_registry.py

@@ -73,13 +73,13 @@ def declare_component(
 
     path: str or None
         The path to serve the component's frontend files from. If ``path`` is
-        ``None`` (default), Streamlit will server the component from the
+        ``None`` (default), Streamlit will serve 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. If ``url`` is ``None``
-        (default), Streamlit will server the component from the location in
+        (default), Streamlit will serve the component from the location in
         ``path``. Either ``path`` or ``url`` must be specified, but not both.
 
     Returns

streamlit/components/v1/custom_component.py

@@ -194,12 +194,12 @@ And if you're using Streamlit Cloud, add "pyarrow" to your requirements.txt."""
                 return ui_value
 
             component_state = register_widget(
-                element_type="component_instance",
-                element_proto=element.component_instance,
+                element.component_instance.id,
                 deserializer=deserialize_component,
                 serializer=lambda x: x,
                 ctx=ctx,
                 on_change_handler=on_change,
+                value_type="json_value",
             )
             widget_value = component_state.value
 

streamlit/config.py

@@ -91,24 +91,38 @@ def set_option(key: str, value: Any, where_defined: str = _USER_DEFINED) -> None
 
 
 def set_user_option(key: str, value: Any) -> None:
-    """Set config option.
+    """Set a configuration option.
 
-    Currently, only the following config options can be set within the script itself:
-        * client.caching
+    Currently, only ``client`` configuration options can be set within the
+    script itself:
 
-    Calling with any other options will raise StreamlitAPIException.
+        - ``client.showErrorDetails``
+        - ``client.showSidebarNavigation``
+        - ``client.toolbarMode``
 
-    Run `streamlit config show` in the terminal to see all available options.
+    Calling ``st.set_option`` with any other option will raise a
+    ``StreamlitAPIException``. When changing a configuration option in a
+    running app, you may need to trigger a rerun after changing the option to
+    see the effects.
+
+    Run ``streamlit config show`` in a terminal to see all available options.
 
     Parameters
     ----------
     key : str
         The config option key of the form "section.optionName". To see all
-        available options, run `streamlit config show` on a terminal.
+        available options, run ``streamlit config show`` in a terminal.
 
     value
         The new value to assign to this config option.
 
+    Example
+    -------
+
+    >>> import streamlit as st
+    >>>
+    >>> st.set_option("client.showErrorDetails", True)
+
     """
     try:
         opt = _config_options_template[key]
@@ -124,15 +138,23 @@ def set_user_option(key: str, value: Any) -> None:
 
 
 def get_option(key: str) -> Any:
-    """Return the current value of a given Streamlit config option.
+    """Return the current value of a given Streamlit configuration option.
 
-    Run `streamlit config show` in the terminal to see all available options.
+    Run ``streamlit config show`` in a terminal to see all available options.
 
     Parameters
     ----------
     key : str
         The config option key of the form "section.optionName". To see all
-        available options, run `streamlit config show` on a terminal.
+        available options, run ``streamlit config show`` in a terminal.
+
+    Example
+    -------
+
+    >>> import streamlit as st
+    >>>
+    >>> color = st.get_option("theme.primaryColor")
+
     """
     with _config_lock:
         config_options = get_config_options()

streamlit/elements/arrow.py

@@ -78,7 +78,7 @@ class DataframeSelectionState(TypedDict, total=False):
     """
     The schema for the dataframe selection state.
 
-    The selection state is stored in a dictionary-like object that suports both
+    The selection state is stored in a dictionary-like object that supports both
     key and attribute notation. Selection states cannot be programmatically
     changed or set through Session State.
 
@@ -136,7 +136,7 @@ class DataframeState(TypedDict, total=False):
     """
     The schema for the dataframe event state.
 
-    The event state is stored in a dictionary-like object that suports both
+    The event state is stored in a dictionary-like object that supports both
     key and attribute notation. Event states cannot be programmatically
     changed or set through Session State.
 
@@ -145,7 +145,7 @@ class DataframeState(TypedDict, total=False):
     Attributes
     ----------
     selection : dict
-        The state of the ``on_select`` event. This attribure returns a
+        The state of the ``on_select`` event. This attribute returns a
         dictionary-like object that supports both key and attribute notation.
         The attributes are described by the ``DataframeSelectionState``
         dictionary schema.
@@ -295,7 +295,7 @@ class ArrowMixin:
             - ``snowflake.snowpark.dataframe.DataFrame``,
               ``snowflake.snowpark.table.Table``
 
-            If a dataype is not recognized, Streamlit will convert the object
+            If a data type is not recognized, Streamlit will convert the object
             to a ``pandas.DataFrame`` or ``pyarrow.Table`` using a
             ``.to_pandas()`` or ``.to_arrow()`` method, respectively, if
             available.
@@ -304,7 +304,9 @@ class ArrowMixin:
             underlying ``pandas.DataFrame``. Streamlit supports custom cell
             values and colors. It does not support some of the more exotic
             styling options, like bar charts, hovering, and captions. For
-            these styling options, use column configuration instead.
+            these styling options, use column configuration instead. Text and
+            number formatting from ``column_config`` always takes precedence
+            over text and number formatting from ``pandas.Styler``.
 
             Collection-like objects include all Python-native ``Collection``
             types, such as ``dict``, ``list``, and ``set``.
@@ -417,9 +419,9 @@ class ArrowMixin:
         Returns
         -------
         element or dict
-            If ``on_select`` is ``"ignore"`` (default), this method returns an
+            If ``on_select`` is ``"ignore"`` (default), this command returns an
             internal placeholder for the dataframe element that can be used
-            with the ``.add_rows()`` method. Otherwise, this method returns a
+            with the ``.add_rows()`` method. Otherwise, this command returns a
             dictionary-like object that supports both key and attribute
             notation. The attributes are described by the ``DataframeState``
             dictionary schema.
@@ -581,12 +583,12 @@ class ArrowMixin:
 
             serde = DataframeSelectionSerde()
             widget_state = register_widget(
-                "dataframe",
-                proto,
+                proto.id,
                 on_change_handler=on_select if callable(on_select) else None,
                 deserializer=serde.deserialize,
                 serializer=serde.serialize,
                 ctx=ctx,
+                value_type="string_value",
             )
             self.dg._enqueue("arrow_data_frame", proto)
             return cast(DataframeState, widget_state.value)

streamlit/elements/deck_gl_json_chart.py

@@ -101,17 +101,106 @@ def parse_selection_mode(
 
 
 class PydeckSelectionState(TypedDict, total=False):
-    """
-    The schema for the PyDeck Layer Selection State
+    r"""
+    The schema for the PyDeck chart selection state.
+
+    The selection state is stored in a dictionary-like object that supports
+    both key and attribute notation. Selection states cannot be
+    programmatically changed or set through Session State.
+
+    You must define ``id`` in ``pydeck.Layer`` to ensure statefulness when
+    using selections with ``st.pydeck_chart``.
 
     Attributes
     ----------
     indices : dict[str, list[int]]
-        Dictionary where keys are the layer id and values are lists of indices
-        of selected objects.
+        A dictionary of selected objects by layer. Each key in the dictionary
+        is a layer id, and each value is a list of object indices within that
+        layer.
     objects : dict[str, list[dict[str, Any]]]
-        Dictionary where keys are the layer id and values are lists of metadata
-        objects for the selected items.
+        A dictionary of object attributes by layer. Each key in the dictionary
+        is a layer id, and each value is a list of metadata dictionaries for
+        the selected objects in that layer.
+
+    Examples
+    --------
+    The following example has multi-object selection enabled. The chart
+    displays US state capitals by population (2023 US Census estimate). You
+    can access this `data
+    <https://github.com/streamlit/docs/blob/main/python/api-examples-source/data/capitals.csv>`_
+    from GitHub.
+
+    >>> import streamlit as st
+    >>> import pydeck
+    >>> import pandas as pd
+    >>>
+    >>> capitals = pd.read_csv(
+    ...     "capitals.csv",
+    ...     header=0,
+    ...     names=[
+    ...         "Capital",
+    ...         "State",
+    ...         "Abbreviation",
+    ...         "Latitude",
+    ...         "Longitude",
+    ...         "Population",
+    ...     ],
+    ... )
+    >>> capitals["size"] = capitals.Population / 10
+    >>>
+    >>> point_layer = pydeck.Layer(
+    ...     "ScatterplotLayer",
+    ...     data=capitals,
+    ...     id="capital-cities",
+    ...     get_position=["Longitude", "Latitude"],
+    ...     get_color="[255, 75, 75]",
+    ...     pickable=True,
+    ...     auto_highlight=True,
+    ...     get_radius="size",
+    ... )
+    >>>
+    >>> view_state = pydeck.ViewState(
+    ...     latitude=40, longitude=-117, controller=True, zoom=2.4, pitch=30
+    ... )
+    >>>
+    >>> chart = pydeck.Deck(
+    ...     point_layer,
+    ...     initial_view_state=view_state,
+    ...     tooltip={"text": "{Capital}, {Abbreviation}\nPopulation: {Population}"},
+    ... )
+    >>>
+    >>> event = st.pydeck_chart(chart, on_select="rerun", selection_mode="multi-object")
+    >>>
+    >>> event.selection
+
+    .. output ::
+        https://doc-pydeck-event-state-selections.streamlit.app/
+        height: 700px
+
+    This is an example of the selection state when selecting a single object
+    from a layer with id, ``"captial-cities"``:
+
+    >>> {
+    >>>   "indices":{
+    >>>     "capital-cities":[
+    >>>       2
+    >>>     ]
+    >>>   },
+    >>>   "objects":{
+    >>>     "capital-cities":[
+    >>>       {
+    >>>         "Abbreviation":" AZ"
+    >>>         "Capital":"Phoenix"
+    >>>         "Latitude":33.448457
+    >>>         "Longitude":-112.073844
+    >>>         "Population":1650070
+    >>>         "State":" Arizona"
+    >>>         "size":165007.0
+    >>>       }
+    >>>     ]
+    >>>   }
+    >>> }
+
     """
 
     indices: dict[str, list[int]]
@@ -120,12 +209,22 @@ class PydeckSelectionState(TypedDict, total=False):
 
 class PydeckState(TypedDict, total=False):
     """
-    The schema for the PyDeck State
+    The schema for the PyDeck event state.
+
+    The event state is stored in a dictionary-like object that supports both
+    key and attribute notation. Event states cannot be programmatically changed
+    or set through Session State.
+
+    Only selection events are supported at this time.
 
     Attributes
     ----------
-    selection : PydeckSelectionState
-        The selection state of the PyDeck layers.
+    selection : dict
+        The state of the ``on_select`` event. This attribute returns a
+        dictionary-like object that supports both key and attribute notation.
+        The attributes are described by the ``PydeckSelectionState``
+        dictionary schema.
+
     """
 
     selection: PydeckSelectionState
@@ -251,28 +350,30 @@ class PydeckMixin:
             ``None`` (default), Streamlit sets the height of the chart to fit
             its contents according to the plotting library.
         on_select : "ignore" or "rerun" or callable
-            How the chart should respond to user selection events. This controls
-            whether or not the dataframe behaves like an input widget.
+            How the figure should respond to user selection events. This controls
+            whether or not the chart behaves like an input widget.
             ``on_select`` can be one of the following:
 
             - ``"ignore"`` (default): Streamlit will not react to any selection
-              events in the dataframe. The dataframe will not behave like an
+              events in the chart. The figure will not behave like an
               input widget.
-            - ``"rerun"``: Rerun the script when a selection is made.
-            - callable: A Python callable that will be called when a selection
-                is made. The callable will be passed the selection state as a
-                dictionary.
-
-            If ``on_select`` is not ``"ignore"``, ensure that the layers given
-            to the ``pydeck_obj`` have stable IDs so that selection state can be
-            maintained across reruns.
+            - ``"rerun"``: Streamlit will rerun the app when the user selects
+              data in the chart. In this case, ``st.pydeck_chart`` will return
+              the selection data as a dictionary.
+            - A ``callable``: Streamlit will rerun the app and execute the callable
+              as a callback function before the rest of the app. In this case,
+              ``st.pydeck_chart`` will return the selection data as a
+              dictionary.
+
+            If ``on_select`` is not ``"ignore"``, all layers must have a
+            declared ``id`` to keep the chart stateful across reruns.
         selection_mode : "single-object" or "multi-object"
-            The types of selections Streamlit should allow. This can be one of
-            the following:
+            The selection mode of the chart. This can be one of the following:
 
             - ``"single-object"`` (default): Only one object can be selected at
               a time.
             - ``"multi-object"``: Multiple objects can be selected at a time.
+
         key : str
             An optional string to use for giving this element a stable
             identity. If ``key`` is ``None`` (default), this element's identity
@@ -282,6 +383,15 @@ class PydeckMixin:
             Streamlit will register the key in Session State to store the
             selection state. The selection state is read-only.
 
+        Returns
+        -------
+        element or dict
+            If ``on_select`` is ``"ignore"`` (default), this command returns an
+            internal placeholder for the chart element. Otherwise, this method
+            returns a dictionary-like object that supports both key and
+            attribute notation. The attributes are described by the
+            ``PydeckState`` dictionary schema.
+
         Example
         -------
         Here's a chart using a HexagonLayer and a ScatterplotLayer. It uses either the
@@ -399,12 +509,12 @@ class PydeckMixin:
             serde = PydeckSelectionSerde()
 
             widget_state = register_widget(
-                "deck_gl_json_chart",
-                pydeck_proto,
+                pydeck_proto.id,
                 ctx=ctx,
                 deserializer=serde.deserialize,
                 on_change_handler=on_select if callable(on_select) else None,
                 serializer=serde.serialize,
+                value_type="string_value",
             )
 
             self.dg._enqueue("deck_gl_json_chart", pydeck_proto)

streamlit/elements/empty.py

@@ -39,37 +39,62 @@ class EmptyMixin:
 
         Examples
         --------
-        Overwriting elements in-place using ``with`` notation:
+        Inside a ``with st.empty():`` block, each displayed element will
+        replace the previous one.
 
         >>> import streamlit as st
         >>> import time
         >>>
         >>> with st.empty():
-        ...     for seconds in range(60):
+        ...     for seconds in range(10):
         ...         st.write(f"⏳ {seconds} seconds have passed")
         ...         time.sleep(1)
-        ...     st.write("✔️ 1 minute over!")
+        ...     st.write(":material/check: 10 seconds over!")
+        ... st.button("Rerun")
 
-        Replacing several elements, then clearing them:
+        .. output::
+           https://doc-empty.streamlit.app/
+           height: 220px
+
+        You can use an ``st.empty`` to replace multiple elements in
+        succession. Use ``st.container`` inside ``st.empty`` to display (and
+        later replace) a group of elements.
 
         >>> import streamlit as st
+        >>> import time
         >>>
-        >>> placeholder = st.empty()
+        >>> st.button("Start over")
         >>>
-        >>> # Replace the placeholder with some text:
-        >>> placeholder.text("Hello")
+        >>> placeholder = st.empty()
+        >>> placeholder.markdown("Hello")
+        >>> time.sleep(1)
         >>>
-        >>> # Replace the text with a chart:
-        >>> placeholder.line_chart({"data": [1, 5, 2, 6]})
+        >>> placeholder.progress(0, "Wait for it...")
+        >>> time.sleep(1)
+        >>> placeholder.progress(50, "Wait for it...")
+        >>> time.sleep(1)
+        >>> placeholder.progress(100, "Wait for it...")
+        >>> time.sleep(1)
         >>>
-        >>> # Replace the chart with several elements:
         >>> with placeholder.container():
-        ...     st.write("This is one element")
-        ...     st.write("This is another")
+        ...     st.line_chart({"data": [1, 5, 2, 6]})
+        ...     time.sleep(1)
+        ...     st.markdown("3...")
+        ...     time.sleep(1)
+        ...     st.markdown("2...")
+        ...     time.sleep(1)
+        ...     st.markdown("1...")
+        ...     time.sleep(1)
+        >>>
+        >>> placeholder.markdown("Poof!")
+        >>> time.sleep(1)
         >>>
-        >>> # Clear all those elements:
         >>> placeholder.empty()
 
+        .. output::
+           https://doc-empty-placeholder.streamlit.app/
+           height: 600px
+
         """
         empty_proto = EmptyProto()
         return self.dg._enqueue("empty", empty_proto)

streamlit/elements/form.py

@@ -100,7 +100,19 @@ class FormMixin:
             will not be reset to their defaults on form submission.)
         enter_to_submit : bool
             Whether to submit the form when a user presses Enter while
-            interacting with a widget inside the form. Defaults to True.
+            interacting with a widget inside the form.
+
+            If this is ``True`` (default), pressing Enter while interacting
+            with a form widget is equivalent to clicking the first
+            ``st.form_submit_button`` in the form.
+
+            If this is ``False``, the user must click an
+            ``st.form_submit_button`` to submit the form.
+
+            If the first ``st.form_submit_button`` in the form is disabled,
+            the form will override submission behavior with
+            ``enter_to_submit=False``.
+
         border : bool
             Whether to show a border around the form. Defaults to True.
 
@@ -193,13 +205,13 @@ class FormMixin:
         """Display a form submit button.
 
         When this button is clicked, all widget values inside the form will be
-        sent to Streamlit in a batch.
+        sent from the user's browser to your Streamlit server in a batch.
 
-        Every form must have a form_submit_button. A form_submit_button
-        cannot exist outside a form.
+        Every form must have at least one ``st.form_submit_button``. An
+        ``st.form_submit_button`` cannot exist outside of a form.
 
-        For more information about forms, check out our
-        `blog post <https://blog.streamlit.io/introducing-submit-button-and-forms/>`_.
+        For more information about forms, check out our `docs
+        <https://docs.streamlit.io/develop/concepts/architecture/forms>`_.
 
         Parameters
         ----------
@@ -236,8 +248,14 @@ class FormMixin:
               <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
               font library.
         disabled : bool
-            An optional boolean, which disables the button if set to True. The
-            default is False.
+            Whether to disable the button. If this is ``False`` (default), the
+            user can interact with the button. If this is ``True``, the button
+            is grayed-out and can't be clicked.
+
+            If the first ``st.form_submit_button`` in the form is disabled,
+            the form will override submission behavior with
+            ``enter_to_submit=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