streamlit-nightly 1.25.1.dev20230817__py2.py3-none-any.whl → 1.25.1.dev20230819__py2.py3-none-any.whl

streamlit/elements/dataframe_selector.py

@@ -273,32 +273,32 @@ class DataFrameSelectorMixin:
             The color to use for different lines in this chart. This argument
             can only be supplied by keyword.
 
-            For a line chart with just 1 line, this can be:
+            For a line chart with just one line, this can be:
 
             * None, to use the default color.
             * A hex string like "#ffaa00" or "#ffaa0088".
-            * An RGB or RGBA tuple with the red, green, #04f, and alpha
+            * An RGB or RGBA tuple with the red, green, blue, and alpha
               components specified as ints from 0 to 255 or floats from 0.0 to
               1.0.
 
             For a line chart with multiple lines, where the dataframe is in
-            long format (that is, y is None or just 1 column), this can be:
+            long format (that is, y is None or just one column), this can be:
 
             * None, to use the default colors.
             * The name of a column in the dataset. Data points will be grouped
               into lines of the same color based on the value of this column.
-              In addition, if the values in this column in one of the color
+              In addition, if the values in this column match one of the color
               formats above (hex string or color tuple), then that color will
               be used.
 
               For example: if the dataset has 1000 rows, but this column can
-              only contains the values "adult", "child", "baby",
-              then those 1000 datapoints will be grouped into 3 lines, whose
+              only contains the values "adult", "child", "baby", then
+              those 1000 datapoints will be grouped into three lines, whose
               colors will be automatically selected from the default palette.
 
               But, if for the same 1000-row dataset, this column contained
               the values "#ffaa00", "#f0f", "#0000ff", then then those 1000
-              datapoints would still be grouped into 3 lines, but their
+              datapoints would still be grouped into three lines, but their
               colors would be "#ffaa00", "#f0f", "#0000ff" this time around.
 
             For a line chart with multiple lines, where the dataframe is in
@@ -307,10 +307,8 @@ class DataFrameSelectorMixin:
             * None, to use the default colors.
             * A list of string colors or color tuples to be used for each of
               the lines in the chart. This list should have the same length
-              as the number of y values.
-
-              For example, for a chart with have 3 lines this argument can
-              be set to ``color=["#fd0", "#f0f", "#04f"]``.
+              as the number of y values (e.g. ``color=["#fd0", "#f0f", "#04f"]``
+              for three lines).
 
         width : int
             The chart width in pixels. If 0, selects the width automatically.
@@ -334,43 +332,61 @@ class DataFrameSelectorMixin:
         >>> chart_data = pd.DataFrame(
         ...     np.random.randn(20, 3),
         ...     columns=['a', 'b', 'c'])
-        ...
+        >>>
         >>> st.line_chart(chart_data)
 
         .. output::
            https://doc-line-chart.streamlit.app/
-           height: 400px
+           height: 440px
 
         You can also choose different columns to use for x and y, as well as set
         the color dynamically based on a 3rd column (assuming your dataframe is in
         long format):
 
-        >>> chart_data = pd.DataFrame(
-        ...     np.random.randn(20, 4),
-        ...     columns=['col1', 'col2', 'col3'])
-        ...
+        >>> import streamlit as st
+        >>> import pandas as pd
+        >>> import numpy as np
+        >>>
+        >>> chart_data = pd.DataFrame({
+        ...     'col1' : np.random.randn(20),
+        ...     'col2' : np.random.randn(20),
+        ...     'col3' : np.random.choice(['A','B','C'], 20)
+        ... })
+        >>>
         >>> st.line_chart(
         ...     chart_data,
-        ...     x='col1',
-        ...     y='col2',
-        ...     color='col3',
+        ...     x = 'col1',
+        ...     y = 'col2',
+        ...     color = 'col3'
         ... )
 
+        .. output::
+           https://doc-line-chart1.streamlit.app/
+           height: 440px
+
         Finally, if your dataframe is in wide format, you can group multiple
         columns under the y argument to show multiple lines with different
         colors:
 
+        >>> import streamlit as st
+        >>> import pandas as pd
+        >>> import numpy as np
+        >>>
         >>> chart_data = pd.DataFrame(
-        ...     np.random.randn(20, 4),
-        ...     columns=['col1', 'col2', 'col3'])
-        ...
+        ...     np.random.randn(20, 3),
+        ...     columns = ['col1', 'col2', 'col3'])
+        >>>
         >>> st.line_chart(
         ...     chart_data,
-        ...     x='col1',
-        ...     y=['col2', 'col3'],
-        ...     color=['red', 'black'],  # Optional
+        ...     x = 'col1',
+        ...     y = ['col2', 'col3'],
+        ...     color = ['#FF0000', '#0000FF']  # Optional
         ... )
 
+        .. output::
+           https://doc-line-chart2.streamlit.app/
+           height: 440px
+
         """
         if _use_arrow():
             return self.dg._arrow_line_chart(
@@ -439,17 +455,17 @@ class DataFrameSelectorMixin:
 
             * None, to use the default color.
             * A hex string like "#ffaa00" or "#ffaa0088".
-            * An RGB or RGBA tuple with the red, green, #04f, and alpha
+            * An RGB or RGBA tuple with the red, green, blue, and alpha
               components specified as ints from 0 to 255 or floats from 0.0 to
               1.0.
 
             For an area chart with multiple series, where the dataframe is in
-            long format (that is, y is None or just 1 column), this can be:
+            long format (that is, y is None or just one column), this can be:
 
             * None, to use the default colors.
             * The name of a column in the dataset. Data points will be grouped
               into series of the same color based on the value of this column.
-              In addition, if the values in this column in one of the color
+              In addition, if the values in this column match one of the color
               formats above (hex string or color tuple), then that color will
               be used.
 
@@ -469,10 +485,8 @@ class DataFrameSelectorMixin:
             * None, to use the default colors.
             * A list of string colors or color tuples to be used for each of
               the series in the chart. This list should have the same length
-              as the number of y values.
-
-              For example, for a chart with have 3 series this argument can
-              be set to ``color=["#fd0", "#f0f", "#04f"]``.
+              as the number of y values (e.g. ``color=["#fd0", "#f0f", "#04f"]``
+              for three lines).
 
         width : int
             The chart width in pixels. If 0, selects the width automatically.
@@ -495,44 +509,62 @@ class DataFrameSelectorMixin:
         >>>
         >>> chart_data = pd.DataFrame(
         ...     np.random.randn(20, 3),
-        ...     columns=['a', 'b', 'c'])
-        ...
+        ...     columns = ['a', 'b', 'c'])
+        >>>
         >>> st.area_chart(chart_data)
 
         .. output::
            https://doc-area-chart.streamlit.app/
-           height: 400px
+           height: 440px
 
         You can also choose different columns to use for x and y, as well as set
         the color dynamically based on a 3rd column (assuming your dataframe is in
         long format):
 
-        >>> chart_data = pd.DataFrame(
-        ...     np.random.randn(20, 4),
-        ...     columns=['col1', 'col2', 'col3'])
-        ...
+        >>> import streamlit as st
+        >>> import pandas as pd
+        >>> import numpy as np
+        >>>
+        >>> chart_data = pd.DataFrame({
+        ...     'col1' : np.random.randn(20),
+        ...     'col2' : np.random.randn(20),
+        ...     'col3' : np.random.choice(['A', 'B', 'C'], 20)
+        ... })
+        >>>
         >>> st.area_chart(
         ...     chart_data,
-        ...     x='col1',
-        ...     y='col2',
-        ...     color='col3',
+        ...     x = 'col1',
+        ...     y = 'col2',
+        ...     color = 'col3'
         ... )
 
+        .. output::
+           https://doc-area-chart1.streamlit.app/
+           height: 440px
+
         Finally, if your dataframe is in wide format, you can group multiple
         columns under the y argument to show multiple series with different
         colors:
 
+        >>> import streamlit as st
+        >>> import pandas as pd
+        >>> import numpy as np
+        >>>
         >>> chart_data = pd.DataFrame(
-        ...     np.random.randn(20, 4),
+        ...     np.random.randn(20, 3),
         ...     columns=['col1', 'col2', 'col3'])
         ...
         >>> st.area_chart(
         ...     chart_data,
         ...     x='col1',
         ...     y=['col2', 'col3'],
-        ...     color=['red', 'black'],  # Optional
+        ...     color=['#FF0000','#0000FF']  # Optional
         ... )
 
+        .. output::
+           https://doc-area-chart2.streamlit.app/
+           height: 440px
+
         """
         if _use_arrow():
             return self.dg._arrow_area_chart(
@@ -601,17 +633,17 @@ class DataFrameSelectorMixin:
 
             * None, to use the default color.
             * A hex string like "#ffaa00" or "#ffaa0088".
-            * An RGB or RGBA tuple with the red, green, #04f, and alpha
+            * An RGB or RGBA tuple with the red, green, blue, and alpha
               components specified as ints from 0 to 255 or floats from 0.0 to
               1.0.
 
             For a bar chart with multiple series, where the dataframe is in
-            long format (that is, y is None or just 1 column), this can be:
+            long format (that is, y is None or just one column), this can be:
 
             * None, to use the default colors.
             * The name of a column in the dataset. Data points will be grouped
               into series of the same color based on the value of this column.
-              In addition, if the values in this column in one of the color
+              In addition, if the values in this column match one of the color
               formats above (hex string or color tuple), then that color will
               be used.
 
@@ -631,10 +663,8 @@ class DataFrameSelectorMixin:
             * None, to use the default colors.
             * A list of string colors or color tuples to be used for each of
               the series in the chart. This list should have the same length
-              as the number of y values.
-
-              For example, for a chart with have 3 series this argument can
-              be set to ``color=["#fd0", "#f0f", "#04f"]``.
+              as the number of y values (e.g. ``color=["#fd0", "#f0f", "#04f"]``
+              for three lines).
 
         width : int
             The chart width in pixels. If 0, selects the width automatically.
@@ -663,38 +693,56 @@ class DataFrameSelectorMixin:
 
         .. output::
            https://doc-bar-chart.streamlit.app/
-           height: 400px
+           height: 440px
 
         You can also choose different columns to use for x and y, as well as set
         the color dynamically based on a 3rd column (assuming your dataframe is in
         long format):
 
-        >>> chart_data = pd.DataFrame(
-        ...     np.random.randn(20, 4),
-        ...     columns=['col1', 'col2', 'col3'])
-        ...
+        >>> import streamlit as st
+        >>> import pandas as pd
+        >>> import numpy as np
+        >>>
+        >>> chart_data = pd.DataFrame({
+        ...     'col1' : np.random.randn(20),
+        ...     'col2' : np.random.randn(20),
+        ...     'col3' : np.random.choice(['A','B','C'],20)
+        ... })
+        >>>
         >>> st.bar_chart(
         ...     chart_data,
         ...     x='col1',
         ...     y='col2',
-        ...     color='col3',
+        ...     color='col3'
         ... )
 
+        .. output::
+           https://doc-bar-chart1.streamlit.app/
+           height: 440px
+
         Finally, if your dataframe is in wide format, you can group multiple
         columns under the y argument to show multiple series with different
         colors:
 
+        >>> import streamlit as st
+        >>> import pandas as pd
+        >>> import numpy as np
+        >>>
         >>> chart_data = pd.DataFrame(
-        ...     np.random.randn(20, 4),
+        ...     np.random.randn(20, 3),
         ...     columns=['col1', 'col2', 'col3'])
         ...
         >>> st.bar_chart(
         ...     chart_data,
         ...     x='col1',
         ...     y=['col2', 'col3'],
-        ...     color=['red', 'black'],  # Optional
+        ...     color=['#FF0000','#0000FF']  # Optional
         ... )
 
+        .. output::
+           https://doc-bar-chart2.streamlit.app/
+           height: 440px
+
         """
 
         if _use_arrow():

streamlit/elements/heading.py

@@ -78,18 +78,23 @@ class HeadingMixin:
             An optional tooltip that gets displayed next to the header.
 
         divider : bool or “blue”, “green”, “orange”, “red”, “violet”, “gray”/"grey", or “rainbow”
-            Shows a colored divider below the header. If True, will cycle through
-            colors for subsequent headers, i.e. the first header with divider=True
-            will have a blue line, the second one will have a green line, etc.
-            If string, can set one of the following colors: blue, green, orange,
-            red, violet, gray/grey, or rainbow.
+            Shows a colored divider below the header. If True, successive
+            headers will cycle through divider colors. That is, the first
+            header will have a blue line, the second header will have a
+            green line, and so on. If a string, the color can be set to one of
+            the following: blue, green, orange, red, violet, gray/grey, or
+            rainbow.
 
         Examples
         --------
         >>> import streamlit as st
         >>>
-        >>> st.header('This is a header')
-        >>> st.header('A header with _italics_ :blue[colors] and emojis :sunglasses:')
+        >>> st.header('This is a header with a divider', divider='rainbow')
+        >>> st.header('_Streamlit_ is :blue[cool] :sunglasses:')
+
+        .. output::
+           https://doc-header.streamlit.app/
+           height: 220px
 
         """
         return self.dg._enqueue(
@@ -143,18 +148,23 @@ class HeadingMixin:
             An optional tooltip that gets displayed next to the subheader.
 
         divider : bool or “blue”, “green”, “orange”, “red”, “violet”, “gray”/"grey", or “rainbow”
-            Shows a colored divider below the header. If True, will cycle through
-            colors for subsequent headers, i.e. the first header with divider=True
-            will have a blue line, the second one will have a green line, etc.
-            If string, can set one of the following colors: blue, green, orange,
-            red, violet, gray/grey, or rainbow.
+            Shows a colored divider below the header. If True, successive
+            headers will cycle through divider colors. That is, the first
+            header will have a blue line, the second header will have a
+            green line, and so on. If a string, the color can be set to one of
+            the following: blue, green, orange, red, violet, gray/grey, or
+            rainbow.
 
         Examples
         --------
         >>> import streamlit as st
         >>>
-        >>> st.subheader('This is a subheader')
-        >>> st.subheader('A subheader with _italics_ :blue[colors] and emojis :sunglasses:')
+        >>> st.subheader('This is a subheader with a divider', divider='rainbow')
+        >>> st.subheader('_Streamlit_ is :blue[cool] :sunglasses:')
+
+        .. output::
+           https://doc-subheader.streamlit.app/
+           height: 220px
 
         """
         return self.dg._enqueue(
@@ -214,7 +224,11 @@ class HeadingMixin:
         >>> import streamlit as st
         >>>
         >>> st.title('This is a title')
-        >>> st.title('A title with _italics_ :blue[colors] and emojis :sunglasses:')
+        >>> st.title('_Streamlit_ is :blue[cool] :sunglasses:')
+
+        .. output::
+           https://doc-title.streamlit.app/
+           height: 220px
 
         """
         return self.dg._enqueue(

streamlit/elements/layouts.py

@@ -11,7 +11,10 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-from typing import TYPE_CHECKING, List, Optional, Sequence, Union, cast
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Literal, Optional, Sequence, Union, cast
 
 from streamlit.errors import StreamlitAPIException
 from streamlit.proto.Block_pb2 import Block as BlockProto
@@ -19,6 +22,7 @@ from streamlit.runtime.metrics_util import gather_metrics
 
 if TYPE_CHECKING:
     from streamlit.delta_generator import DeltaGenerator
+    from streamlit.elements.lib.mutable_status_container import StatusContainer
 
 SpecType = Union[int, Sequence[Union[int, float]]]
 
@@ -402,11 +406,133 @@ class LayoutsMixin:
         expandable_proto.label = label
 
         block_proto = BlockProto()
-        block_proto.allow_empty = True
+        block_proto.allow_empty = False
         block_proto.expandable.CopyFrom(expandable_proto)
 
         return self.dg._block(block_proto=block_proto)
 
+    @gather_metrics("status")
+    def status(
+        self,
+        label: str,
+        *,
+        expanded: bool = False,
+        state: Literal["running", "complete", "error"] = "running",
+    ) -> "StatusContainer":
+        """Insert a status container to display output from long-running tasks.
+
+        Inserts a container into your app that is typically used to show the status and
+        details of a process or task. The container can hold multiple elements and can
+        be expanded or collapsed by the user similar to ``st.expander``.
+        When collapsed, all that is visible is the status icon and label.
+
+        The label, state, and expanded state can all be updated by calling ``.update()``
+        on the returned object. To add elements to the returned container, you can
+        use "with" notation (preferred) or just call methods directly on the returned
+        object.
+
+        By default, ``st.status()`` initializes in the "running" state. When called using
+        "with" notation, it automatically updates to the "complete" state at the end
+        of the "with" block. See examples below for more details.
+
+        Parameters
+        ----------
+
+        label : str
+            The initial label of the status container. The label can optionally
+            contain Markdown and supports the following elements: Bold,
+            Italics, Strikethroughs, Inline Code, Emojis, and Links.
+
+            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, using the syntax ``:color[text to be colored]``,
+              where ``color`` needs to be replaced with any of the following
+              supported colors: blue, green, orange, red, violet, gray/grey, rainbow.
+
+            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 status container in "expanded" state. Defaults to
+            False (collapsed).
+
+        state : "running", "complete", or "error"
+            The initial state of the status container which determines which icon is
+            shown:
+
+            * ``running`` (default): A spinner icon is shown.
+
+            * ``complete``: A checkmark icon is shown.
+
+            * ``error``: An error icon is shown.
+
+        Returns
+        -------
+
+        StatusContainer
+            A mutable status container that can hold multiple elements. The label, state,
+            and expanded state can be updated after creation via ``.update()``.
+
+        Examples
+        --------
+
+        You can use `with` notation to insert any element into an status container:
+
+        >>> import time
+        >>> import streamlit as st
+        >>>
+        >>> with st.status("Downloading data..."):
+        ...     st.write("Searching for data...")
+        ...     time.sleep(2)
+        ...     st.write("Found URL.")
+        ...     time.sleep(1)
+        ...     st.write("Downloading data...")
+        ...     time.sleep(1)
+        >>>
+        >>> st.button('Rerun')
+
+        .. output ::
+            https://doc-status.streamlit.app/
+            height: 300px
+
+        You can also use `.update()` on the container to change the label, state,
+        or expanded state:
+
+        >>> import time
+        >>> import streamlit as st
+        >>>
+        >>> with st.status("Downloading data...", expanded=True) as status:
+        ...     st.write("Searching for data...")
+        ...     time.sleep(2)
+        ...     st.write("Found URL.")
+        ...     time.sleep(1)
+        ...     st.write("Downloading data...")
+        ...     time.sleep(1)
+        ...     status.update(label="Download complete!", state="complete", expanded=False)
+        >>>
+        >>> st.button('Rerun')
+
+        .. output ::
+            https://doc-status-update.streamlit.app/
+            height: 300px
+
+        """
+        # We need to import StatusContainer here to avoid a circular import
+        from streamlit.elements.lib.mutable_status_container import StatusContainer
+
+        return StatusContainer._create(
+            self.dg, label=label, expanded=expanded, state=state
+        )
+
     @property
     def dg(self) -> "DeltaGenerator":
         """Get our DeltaGenerator."""