streamlit-data-editor-plus 0.1.0__py3-none-any.whl

streamlit/elements/metric.py

@@ -0,0 +1,529 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2026)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 __future__ import annotations
+
+from dataclasses import dataclass
+from textwrap import dedent
+from typing import TYPE_CHECKING, Any, Final, Literal, TypeAlias, cast
+
+from streamlit.dataframe_util import OptionSequence, convert_anything_to_list
+from streamlit.elements.lib.layout_utils import (
+    Height,
+    LayoutConfig,
+    Width,
+    validate_height,
+    validate_width,
+)
+from streamlit.elements.lib.policies import maybe_raise_label_warnings
+from streamlit.elements.lib.utils import (
+    LabelVisibility,
+    get_label_visibility_proto_value,
+)
+from streamlit.errors import StreamlitAPIException, StreamlitValueError
+from streamlit.proto.Metric_pb2 import Metric as MetricProto
+from streamlit.runtime.metrics_util import gather_metrics
+from streamlit.string_util import AnyNumber, clean_text, from_number
+
+if TYPE_CHECKING:
+    from streamlit.delta_generator import DeltaGenerator
+    from streamlit.elements.lib.column_types import NumberFormat
+
+
+Value: TypeAlias = AnyNumber | str | None
+Delta: TypeAlias = AnyNumber | str | None
+DeltaColor: TypeAlias = Literal[
+    "normal",
+    "inverse",
+    "off",
+    "red",
+    "orange",
+    "yellow",
+    "green",
+    "blue",
+    "violet",
+    "gray",
+    "grey",
+    "primary",
+]
+DeltaArrow: TypeAlias = Literal["auto", "up", "down", "off"]
+
+# Mapping from delta_color string values to proto enum values
+_DELTA_COLOR_TO_PROTO: Final[dict[str, MetricProto.MetricColor.ValueType]] = {
+    "red": MetricProto.MetricColor.RED,
+    "orange": MetricProto.MetricColor.ORANGE,
+    "yellow": MetricProto.MetricColor.YELLOW,
+    "green": MetricProto.MetricColor.GREEN,
+    "blue": MetricProto.MetricColor.BLUE,
+    "violet": MetricProto.MetricColor.VIOLET,
+    "gray": MetricProto.MetricColor.GRAY,
+    "grey": MetricProto.MetricColor.GRAY,
+    "primary": MetricProto.MetricColor.PRIMARY,
+}
+
+# Valid delta_color values for validation
+_VALID_DELTA_COLORS: Final[set[str]] = {
+    "normal",
+    "inverse",
+    "off",
+    *_DELTA_COLOR_TO_PROTO.keys(),
+}
+
+# Mapping from delta_arrow string values to proto enum values
+_DELTA_ARROW_TO_PROTO: Final[dict[str, MetricProto.MetricDirection.ValueType]] = {
+    "off": MetricProto.MetricDirection.NONE,
+    "up": MetricProto.MetricDirection.UP,
+    "down": MetricProto.MetricDirection.DOWN,
+}
+
+
+@dataclass(frozen=True)
+class MetricColorAndDirection:
+    color: MetricProto.MetricColor.ValueType
+    direction: MetricProto.MetricDirection.ValueType
+
+
+class MetricMixin:
+    @gather_metrics("metric")
+    def metric(
+        self,
+        label: str,
+        value: Value,
+        delta: Delta = None,
+        delta_color: DeltaColor = "normal",
+        *,
+        help: str | None = None,
+        label_visibility: LabelVisibility = "visible",
+        border: bool = False,
+        width: Width = "stretch",
+        height: Height = "content",
+        chart_data: OptionSequence[Any] | None = None,
+        chart_type: Literal["line", "bar", "area"] = "line",
+        delta_arrow: DeltaArrow = "auto",
+        format: str | NumberFormat | None = None,
+        delta_description: str | None = None,
+    ) -> DeltaGenerator:
+        r"""Display a metric in big bold font, with an optional indicator of how the metric changed.
+
+        Parameters
+        ----------
+        label : str
+            The header or title for the metric. The label can optionally
+            contain GitHub-flavored Markdown of the following types: Bold, Italics,
+            Strikethroughs, Inline Code, Links, and Images. Images display like
+            icons, with a max height equal to the font height.
+
+            Unsupported Markdown elements are unwrapped so only their children
+            (text contents) render. Display unsupported elements as literal
+            characters by backslash-escaping them. E.g.,
+            ``"1\. Not an ordered list"``.
+
+            See the ``body`` parameter of |st.markdown|_ for additional,
+            supported Markdown directives.
+
+            .. |st.markdown| replace:: ``st.markdown``
+            .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
+
+        value : int, float, decimal.Decimal, str, or None
+            Value of the metric. ``None`` is rendered as a long dash.
+
+            The value can optionally contain GitHub-flavored Markdown, subject
+            to the same limitations described in the ``label`` parameter.
+
+        delta : int, float, decimal.Decimal, str, or None
+            Amount or indicator of change in the metric. An arrow is shown next
+            to the delta, oriented according to its sign:
+
+            - If the delta is ``None`` or an empty string, no arrow is shown.
+            - If the delta is a negative number or starts with a minus sign,
+              the arrow points down and the delta is red.
+            - Otherwise, the arrow points up and the delta is green.
+
+            You can modify the display, color, and orientation of the arrow
+            using the ``delta_color`` and ``delta_arrow`` parameters.
+
+            The delta can optionally contain GitHub-flavored Markdown, subject
+            to the same limitations described in the ``label`` parameter.
+
+        delta_color : str
+            The color of the delta and chart. This can be one of the following:
+
+            - ``"normal"`` (default): The color is red when the delta is
+              negative and green otherwise.
+            - ``"inverse"``: The color is green when the delta is negative and
+              red otherwise. This is useful when a negative change is
+              considered good, like a decrease in cost.
+            - ``"off"``: The color is gray regardless of the delta.
+            - A named color from the basic palette: The chart and delta are the
+              specified color regardless of their value. This can be one of the
+              following: ``"red"``, ``"orange"``, ``"yellow"``, ``"green"``,
+              ``"blue"``, ``"violet"``, ``"gray"``/``"grey"``, or
+              ``"primary"``.
+
+        help : str or None
+            A tooltip that gets displayed next to the metric label. Streamlit
+            only displays the tooltip when ``label_visibility="visible"``. If
+            this is ``None`` (default), no tooltip is displayed.
+
+            The tooltip can optionally contain GitHub-flavored Markdown,
+            including the Markdown directives described in the ``body``
+            parameter of ``st.markdown``.
+
+        label_visibility : "visible", "hidden", or "collapsed"
+            The visibility of the label. The default is ``"visible"``. If this
+            is ``"hidden"``, Streamlit displays an empty spacer instead of the
+            label, which can help keep the widget aligned with other widgets.
+            If this is ``"collapsed"``, Streamlit displays no label or spacer.
+
+        border : bool
+            Whether to show a border around the metric container. If this is
+            ``False`` (default), no border is shown. If this is ``True``, a
+            border is shown.
+
+        height : "content", "stretch", or int
+            The height of the metric element. This can be one of the following:
+
+            - ``"content"`` (default): The height of the element matches the
+              height of its content.
+            - ``"stretch"``: The height of the element matches the height of
+              its content or the height of the parent container, whichever is
+              larger. If the element is not in a parent container, the height
+              of the element matches the height of its content.
+            - An integer specifying the height in pixels: The element has a
+              fixed height. If the content is larger than the specified
+              height, scrolling is enabled.
+
+        width : "stretch", "content", or int
+            The width of the metric element. This can be one of the following:
+
+            - ``"stretch"`` (default): The width of the element matches the
+              width of the parent container.
+            - ``"content"``: The width of the element matches the width of its
+              content, but doesn't exceed the width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the element matches the width
+              of the parent container.
+
+        chart_data : Iterable or None
+            A sequence of numeric values to display as a sparkline chart. If
+            this is ``None`` (default), no chart is displayed. The sequence can
+            be anything supported by ``st.dataframe``, including a ``list`` or
+            ``set``. If the sequence is dataframe-like, the first column will
+            be used. Each value will be cast to ``float`` internally by
+            default.
+
+            The chart uses the color of the delta indicator, which can be
+            modified using the ``delta_color`` parameter.
+
+        chart_type : "line", "bar", or "area"
+            The type of sparkline chart to display. This can be one of the
+            following:
+
+            - ``"line"`` (default): A simple sparkline.
+            - ``"area"``: A sparkline with area shading.
+            - ``"bar"``: A bar chart.
+
+        delta_arrow : "auto", "up", "down", or "off"
+            Controls the direction of the delta indicator arrow. This can be
+            one of the following strings:
+
+            - ``"auto"`` (default): The arrow direction follows the sign of
+              ``delta``.
+            - ``"up"`` or ``"down"``: The arrow is forced to point in the
+              specified direction.
+            - ``"off"``: No arrow is shown, but the delta value remains
+              visible.
+
+        format : str or None
+            A format string controlling how numbers are displayed for ``value``
+            and ``delta``. The format is only applied if the value or delta is
+            numeric. If the value or delta is a string with non-numeric
+            characters, the format is ignored. The format can be one of the
+            following values:
+
+            - ``None`` (default): No formatting is applied.
+            - ``"plain"``: Show the full number without any formatting (e.g. "1234.567").
+            - ``"localized"``: Show the number in the default locale format (e.g. "1,234.567").
+            - ``"percent"``: Show the number as a percentage (e.g. "123456.70%").
+            - ``"dollar"``: Show the number as a dollar amount (e.g. "$1,234.57").
+            - ``"euro"``: Show the number as a euro amount (e.g. "€1,234.57").
+            - ``"yen"``: Show the number as a yen amount (e.g. "¥1,235").
+            - ``"accounting"``: Show the number in an accounting format (e.g. "1,234.00").
+            - ``"bytes"``: Show the number in a byte format (e.g. "1.2KB").
+            - ``"compact"``: Show the number in a compact format (e.g. "1.2K").
+            - ``"scientific"``: Show the number in scientific notation (e.g. "1.235E3").
+            - ``"engineering"``: Show the number in engineering notation (e.g. "1.235E3").
+            - printf-style format string: Format the number with a printf
+              specifier, like ``"%d"`` to show a signed integer (e.g. "1234") or
+              ``"%.2f"`` to show a float with 2 decimal places. Use ``,`` for
+              thousand separators (e.g. ``"%,d"`` yields ``"1,234"``).
+
+        delta_description : str or None
+            A short description displayed next to the delta value, such as
+            "month over month" or "vs. last quarter". If this is ``None``
+            (default), no description is shown. The description is displayed
+            in a smaller, muted font style similar to ``st.caption``.
+
+        Examples
+        --------
+                **Example 1: Show a metric**
+
+                >>> import streamlit as st
+                >>>
+                >>> st.metric(label="Temperature", value="70 °F", delta="1.2 °F")
+
+                .. output::
+                    https://doc-metric-example1.streamlit.app/
+                    height: 210px
+
+                **Example 2: Create a row of metrics**
+
+                ``st.metric`` looks especially nice in combination with ``st.columns``.
+
+                >>> import streamlit as st
+                >>>
+                >>> col1, col2, col3 = st.columns(3)
+                >>> col1.metric("Temperature", "70 °F", "1.2 °F")
+                >>> col2.metric("Wind", "9 mph", "-8%")
+                >>> col3.metric("Humidity", "86%", "4%")
+
+                .. output::
+                    https://doc-metric-example2.streamlit.app/
+                    height: 210px
+
+                **Example 3: Modify the delta indicator**
+
+                The delta indicator color can also be inverted or turned off.
+
+                >>> import streamlit as st
+                >>>
+                >>> st.metric(
+                ...     label="Gas price", value=4, delta=-0.5, delta_color="inverse"
+                ... )
+                >>>
+                >>> st.metric(
+                ...     label="Active developers",
+                ...     value=123,
+                ...     delta=123,
+                ...     delta_color="off",
+                ... )
+
+                .. output::
+                    https://doc-metric-example3.streamlit.app/
+                    height: 320px
+
+                **Example 4: Create a grid of metric cards**
+
+                Add borders to your metrics to create a dashboard look.
+
+                >>> import streamlit as st
+                >>>
+                >>> a, b = st.columns(2)
+                >>> c, d = st.columns(2)
+                >>>
+                >>> a.metric("Temperature", "30°F", "-9°F", border=True)
+                >>> b.metric("Wind", "4 mph", "2 mph", border=True)
+                >>>
+                >>> c.metric("Humidity", "77%", "5%", border=True)
+                >>> d.metric("Pressure", "30.34 inHg", "-2 inHg", border=True)
+
+                .. output::
+                    https://doc-metric-example4.streamlit.app/
+                    height: 350px
+
+                **Example 5: Show sparklines**
+
+                To show trends over time, add sparklines.
+
+                >>> import streamlit as st
+                >>> from numpy.random import default_rng as rng
+                >>>
+                >>> changes = list(rng(4).standard_normal(20))
+                >>> data = [sum(changes[:i]) for i in range(20)]
+                >>> delta = round(data[-1], 2)
+                >>>
+                >>> row = st.container(horizontal=True)
+                >>> with row:
+                >>>     st.metric(
+                ...         "Line", 10, delta, chart_data=data, chart_type="line", border=True
+                ...     )
+                >>>     st.metric(
+                ...         "Area", 10, delta, chart_data=data, chart_type="area", border=True
+                ...     )
+                >>>     st.metric(
+                ...         "Bar", 10, delta, chart_data=data, chart_type="bar", border=True
+                ...     )
+
+                .. output::
+                    https://doc-metric-example5.streamlit.app/
+                    height: 300px
+
+        """
+        maybe_raise_label_warnings(label, label_visibility)
+
+        metric_proto = MetricProto()
+        metric_proto.body = _parse_value(value)
+        metric_proto.label = _parse_label(label)
+        metric_proto.delta = _parse_delta(delta)
+        metric_proto.show_border = border
+        if help is not None:
+            metric_proto.help = dedent(help)
+
+        color_and_direction = _determine_delta_color_and_direction(
+            cast("DeltaColor", clean_text(delta_color)), delta
+        )
+        metric_proto.color = color_and_direction.color
+        metric_proto.direction = color_and_direction.direction
+        parsed_delta_arrow = _parse_delta_arrow(
+            cast("DeltaArrow", clean_text(delta_arrow))
+        )
+
+        if parsed_delta_arrow in _DELTA_ARROW_TO_PROTO:
+            metric_proto.direction = _DELTA_ARROW_TO_PROTO[parsed_delta_arrow]
+        metric_proto.label_visibility.value = get_label_visibility_proto_value(
+            label_visibility
+        )
+
+        if chart_data is not None:
+            prepared_data: list[float] = []
+            for val in convert_anything_to_list(chart_data):
+                try:
+                    prepared_data.append(float(val))
+                except Exception as ex:  # noqa: PERF203
+                    raise StreamlitAPIException(
+                        "Only numeric values are supported for chart data sequence. The "
+                        f"value '{val}' is of type {type(val)} and "
+                        "cannot be converted to float."
+                    ) from ex
+            if len(prepared_data) > 0:
+                metric_proto.chart_data.extend(prepared_data)
+
+        metric_proto.chart_type = _parse_chart_type(chart_type)
+
+        if format is not None:
+            metric_proto.format = format
+
+        if delta_description is not None:
+            metric_proto.delta_description = delta_description
+
+        validate_height(height, allow_content=True)
+        validate_width(width, allow_content=True)
+        layout_config = LayoutConfig(width=width, height=height)
+
+        return self.dg._enqueue("metric", metric_proto, layout_config=layout_config)
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        return cast("DeltaGenerator", self)
+
+
+def _parse_chart_type(
+    chart_type: Literal["line", "bar", "area"],
+) -> MetricProto.ChartType.ValueType:
+    if chart_type == "bar":
+        return MetricProto.ChartType.BAR
+    if chart_type == "area":
+        return MetricProto.ChartType.AREA
+    # Use line as default chart:
+    return MetricProto.ChartType.LINE
+
+
+def _parse_delta_arrow(delta_arrow: DeltaArrow) -> DeltaArrow:
+    if delta_arrow not in {"auto", "up", "down", "off"}:
+        raise StreamlitValueError("delta_arrow", ["auto", "up", "down", "off"])
+    return delta_arrow
+
+
+def _parse_label(label: str) -> str:
+    if not isinstance(label, str):
+        raise TypeError(
+            f"'{label}' is of type {type(label)}, which is not an accepted type."
+            " label only accepts: str. Please convert the label to an accepted type."
+        )
+    return label
+
+
+def _parse_value(value: Value) -> str:
+    if value is None:
+        return "—"
+    if isinstance(value, str):
+        return value
+    return from_number(value)
+
+
+def _parse_delta(delta: Delta) -> str:
+    if delta is None or delta == "":
+        return ""
+    if isinstance(delta, str):
+        return dedent(delta)
+    return from_number(delta)
+
+
+def _determine_delta_color_and_direction(
+    delta_color: DeltaColor,
+    delta: Delta,
+) -> MetricColorAndDirection:
+    if delta_color not in _VALID_DELTA_COLORS:
+        raise StreamlitAPIException(
+            f"'{delta_color}' is not an accepted value. delta_color only accepts: "
+            "'normal', 'inverse', 'off', or a color name ('red', 'orange', 'yellow', "
+            "'green', 'blue', 'violet', 'gray'/'grey', 'primary')"
+        )
+
+    if delta is None or delta == "":
+        return MetricColorAndDirection(
+            color=MetricProto.MetricColor.GRAY,
+            direction=MetricProto.MetricDirection.NONE,
+        )
+
+    # Determine direction based on delta sign
+    cd_direction = (
+        MetricProto.MetricDirection.DOWN
+        if _is_negative_delta(delta)
+        else MetricProto.MetricDirection.UP
+    )
+
+    # Handle explicit color names
+    if delta_color in _DELTA_COLOR_TO_PROTO:
+        return MetricColorAndDirection(
+            color=_DELTA_COLOR_TO_PROTO[delta_color],
+            direction=cd_direction,
+        )
+
+    # Handle "normal", "inverse", "off" modes
+    is_negative = cd_direction == MetricProto.MetricDirection.DOWN
+    if delta_color == "normal":
+        cd_color = (
+            MetricProto.MetricColor.RED
+            if is_negative
+            else MetricProto.MetricColor.GREEN
+        )
+    elif delta_color == "inverse":
+        cd_color = (
+            MetricProto.MetricColor.GREEN
+            if is_negative
+            else MetricProto.MetricColor.RED
+        )
+    else:  # "off"
+        cd_color = MetricProto.MetricColor.GRAY
+
+    return MetricColorAndDirection(
+        color=cd_color,
+        direction=cd_direction,
+    )
+
+
+def _is_negative_delta(delta: Delta) -> bool:
+    return dedent(str(delta)).startswith("-")