streamlit-nightly 1.38.1.dev20240909__py2.py3-none-any.whl → 1.38.1.dev20240911__py2.py3-none-any.whl

streamlit/__init__.py

@@ -131,7 +131,7 @@ import streamlit.column_config as _column_config
 # disables implicit_reexport, where you use the respective command in the example_app.py
 # Streamlit app.
 
-from streamlit.echo import echo as echo
+from streamlit.commands.echo import echo as echo
 from streamlit.commands.logo import logo as logo
 from streamlit.commands.navigation import navigation as navigation
 from streamlit.navigation.page import Page as Page

streamlit/cli_util.py

@@ -16,6 +16,11 @@
 
 from __future__ import annotations
 
+import os
+import subprocess
+
+from streamlit import env_util, errors
+
 
 def print_to_cli(message: str, **kwargs) -> None:
     """Print a message to the terminal using click if available, else print
@@ -44,3 +49,57 @@ def style_for_cli(message: str, **kwargs) -> str:
         return click.style(message, **kwargs)
     except ImportError:
         return message
+
+
+def _open_browser_with_webbrowser(url: str) -> None:
+    import webbrowser
+
+    webbrowser.open(url)
+
+
+def _open_browser_with_command(command: str, url: str) -> None:
+    cmd_line = [command, url]
+    with open(os.devnull, "w") as devnull:
+        subprocess.Popen(cmd_line, stdout=devnull, stderr=subprocess.STDOUT)
+
+
+def open_browser(url: str) -> None:
+    """Open a web browser pointing to a given URL.
+
+    We use this function instead of Python's `webbrowser` module because this
+    way we can capture stdout/stderr to avoid polluting the terminal with the
+    browser's messages. For example, Chrome always prints things like "Created
+    new window in existing browser session", and those get on the user's way.
+
+    url : str
+        The URL. Must include the protocol.
+
+    """
+    # Treat Windows separately because:
+    # 1. /dev/null doesn't exist.
+    # 2. subprocess.Popen(['start', url]) doesn't actually pop up the
+    #    browser even though 'start url' works from the command prompt.
+    # Fun!
+    # Also, use webbrowser if we are on Linux and xdg-open is not installed.
+    #
+    # We don't use the webbrowser module on Linux and Mac because some browsers
+    # (ahem... Chrome) always print "Opening in existing browser session" to
+    # the terminal, which is spammy and annoying. So instead we start the
+    # browser ourselves and send all its output to /dev/null.
+
+    if env_util.IS_WINDOWS:
+        _open_browser_with_webbrowser(url)
+        return
+    if env_util.IS_LINUX_OR_BSD:
+        if env_util.is_executable_in_path("xdg-open"):
+            _open_browser_with_command("xdg-open", url)
+            return
+        _open_browser_with_webbrowser(url)
+        return
+    if env_util.IS_DARWIN:
+        _open_browser_with_command("open", url)
+        return
+
+    import platform
+
+    raise errors.Error(f'Cannot open browser in platform "{platform.system()}"')

streamlit/commands/experimental_query_params.py

@@ -17,16 +17,15 @@ from __future__ import annotations
 import urllib.parse as parse
 from typing import Any
 
-from streamlit import util
-from streamlit.constants import (
-    EMBED_OPTIONS_QUERY_PARAM,
-    EMBED_QUERY_PARAM,
-    EMBED_QUERY_PARAMS_KEYS,
-)
 from streamlit.errors import StreamlitAPIException
 from streamlit.proto.ForwardMsg_pb2 import ForwardMsg
 from streamlit.runtime.metrics_util import gather_metrics
 from streamlit.runtime.scriptrunner_utils.script_run_context import get_script_run_ctx
+from streamlit.runtime.state.query_params import (
+    EMBED_OPTIONS_QUERY_PARAM,
+    EMBED_QUERY_PARAM,
+    EMBED_QUERY_PARAMS_KEYS,
+)
 
 
 @gather_metrics("experimental_get_query_params")
@@ -61,7 +60,7 @@ def get_query_params() -> dict[str, list[str]]:
         return {}
     ctx.mark_experimental_query_params_used()
     # Return new query params dict, but without embed, embed_options query params
-    return util.exclude_keys_in_dict(
+    return _exclude_keys_in_dict(
         parse.parse_qs(ctx.query_string, keep_blank_values=True),
         keys_to_exclude=EMBED_QUERY_PARAMS_KEYS,
     )
@@ -107,6 +106,30 @@ def set_query_params(**query_params: Any) -> None:
     ctx.enqueue(msg)
 
 
+def _exclude_keys_in_dict(
+    d: dict[str, Any], keys_to_exclude: list[str]
+) -> dict[str, Any]:
+    """Returns new object but without keys defined in keys_to_exclude"""
+    return {
+        key: value for key, value in d.items() if key.lower() not in keys_to_exclude
+    }
+
+
+def _extract_key_query_params(
+    query_params: dict[str, list[str]], param_key: str
+) -> set[str]:
+    """Extracts key (case-insensitive) query params from Dict, and returns them as Set of str."""
+    return {
+        item.lower()
+        for sublist in [
+            [value.lower() for value in query_params[key]]
+            for key in query_params.keys()
+            if key.lower() == param_key and query_params.get(key)
+        ]
+        for item in sublist
+    }
+
+
 def _ensure_no_embed_params(
     query_params: dict[str, list[str] | str], query_string: str
 ) -> str:
@@ -114,7 +137,7 @@ def _ensure_no_embed_params(
     also makes sure old param values in query_string are preserved. Returns query_string : str.
     """
     # Get query params dict without embed, embed_options params
-    query_params_without_embed = util.exclude_keys_in_dict(
+    query_params_without_embed = _exclude_keys_in_dict(
         query_params, keys_to_exclude=EMBED_QUERY_PARAMS_KEYS
     )
     if query_params != query_params_without_embed:
@@ -126,12 +149,12 @@ def _ensure_no_embed_params(
     current_embed_params = parse.urlencode(
         {
             EMBED_QUERY_PARAM: list(
-                util.extract_key_query_params(
+                _extract_key_query_params(
                     all_current_params, param_key=EMBED_QUERY_PARAM
                 )
             ),
             EMBED_OPTIONS_QUERY_PARAM: list(
-                util.extract_key_query_params(
+                _extract_key_query_params(
                     all_current_params, param_key=EMBED_OPTIONS_QUERY_PARAM
                 )
             ),

streamlit/commands/page_config.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 
 import random
 from textwrap import dedent
-from typing import TYPE_CHECKING, Final, Literal, Mapping, Union, cast
+from typing import TYPE_CHECKING, Any, Final, Literal, Mapping, Union, cast
 
 from typing_extensions import TypeAlias
 
@@ -33,7 +33,6 @@ from streamlit.runtime.metrics_util import gather_metrics
 from streamlit.runtime.scriptrunner_utils.script_run_context import get_script_run_ctx
 from streamlit.string_util import is_emoji, validate_material_icon
 from streamlit.url_util import is_url
-from streamlit.util import lower_clean_dict_keys
 
 if TYPE_CHECKING:
     from typing_extensions import TypeGuard
@@ -80,6 +79,10 @@ ENG_EMOJIS: Final = [
 ]
 
 
+def _lower_clean_dict_keys(dict: MenuItems) -> dict[str, Any]:
+    return {str(k).lower().strip(): v for k, v in dict.items()}
+
+
 def _get_favicon_string(page_icon: PageIcon) -> str:
     """Return the string to pass to the frontend to have it show
     the given PageIcon.
@@ -251,7 +254,7 @@ def set_page_config(
     msg.page_config_changed.initial_sidebar_state = pb_sidebar_state
 
     if menu_items is not None:
-        lowercase_menu_items = cast(MenuItems, lower_clean_dict_keys(menu_items))
+        lowercase_menu_items = cast(MenuItems, _lower_clean_dict_keys(menu_items))
         validate_menu_items(lowercase_menu_items)
         menu_items_proto = msg.page_config_changed.menu_items
         set_menu_items_proto(lowercase_menu_items, menu_items_proto)

streamlit/components/v1/custom_component.py

@@ -20,7 +20,7 @@ from typing import TYPE_CHECKING, Any
 from streamlit.components.types.base_custom_component import BaseCustomComponent
 from streamlit.dataframe_util import is_dataframe_like
 from streamlit.delta_generator_singletons import get_dg_singleton_instance
-from streamlit.elements.form_utils import current_form_id
+from streamlit.elements.lib.form_utils import current_form_id
 from streamlit.elements.lib.policies import check_cache_replay_rules
 from streamlit.elements.lib.utils import compute_and_register_element_id
 from streamlit.errors import StreamlitAPIException
@@ -29,7 +29,7 @@ from streamlit.proto.Components_pb2 import SpecialArg
 from streamlit.proto.Element_pb2 import Element
 from streamlit.runtime.metrics_util import gather_metrics
 from streamlit.runtime.scriptrunner_utils.script_run_context import get_script_run_ctx
-from streamlit.runtime.state import NoValue, register_widget
+from streamlit.runtime.state import register_widget
 from streamlit.type_util import is_bytes_like, to_bytes
 
 if TYPE_CHECKING:
@@ -143,9 +143,7 @@ And if you're using Streamlit Cloud, add "pyarrow" to your requirements.txt."""
                 "Could not convert component args to JSON", ex
             )
 
-        def marshall_component(
-            dg: DeltaGenerator, element: Element
-        ) -> Any | type[NoValue]:
+        def marshall_component(dg: DeltaGenerator, element: Element) -> Any:
             element.component_instance.component_name = self.name
             element.component_instance.form_id = current_form_id(dg)
             if self.url is not None:

streamlit/config_option.py

@@ -21,8 +21,8 @@ import re
 import textwrap
 from typing import Any, Callable
 
-from streamlit import util
-from streamlit.case_converters import to_snake_case
+from streamlit.string_util import to_snake_case
+from streamlit.util import repr_
 
 
 class ConfigOption:
@@ -194,7 +194,7 @@ class ConfigOption:
         self.set_value(default_val)
 
     def __repr__(self) -> str:
-        return util.repr_(self)
+        return repr_(self)
 
     def __call__(self, get_val_func: Callable[[], Any]) -> ConfigOption:
         """Assign a function to compute the value for this option.

streamlit/delta_generator.py

@@ -55,7 +55,6 @@ from streamlit.elements.doc_string import HelpMixin
 from streamlit.elements.empty import EmptyMixin
 from streamlit.elements.exception import ExceptionMixin
 from streamlit.elements.form import FormMixin
-from streamlit.elements.form_utils import FormData, current_form_id
 from streamlit.elements.graphviz_chart import GraphvizMixin
 from streamlit.elements.heading import HeadingMixin
 from streamlit.elements.html import HtmlMixin
@@ -63,6 +62,7 @@ from streamlit.elements.iframe import IframeMixin
 from streamlit.elements.image import ImageMixin
 from streamlit.elements.json import JsonMixin
 from streamlit.elements.layouts import LayoutsMixin
+from streamlit.elements.lib.form_utils import FormData, current_form_id
 from streamlit.elements.map import MapMixin
 from streamlit.elements.markdown import MarkdownMixin
 from streamlit.elements.media import MediaMixin

streamlit/elements/arrow.py

@@ -31,7 +31,6 @@ from typing import (
 from typing_extensions import TypeAlias
 
 from streamlit import dataframe_util
-from streamlit.elements.form_utils import current_form_id
 from streamlit.elements.lib.column_config_utils import (
     INDEX_IDENTIFIER,
     ColumnConfigMappingInput,
@@ -41,6 +40,7 @@ from streamlit.elements.lib.column_config_utils import (
     update_column_config,
 )
 from streamlit.elements.lib.event_utils import AttributeDictionary
+from streamlit.elements.lib.form_utils import current_form_id
 from streamlit.elements.lib.pandas_styler_utils import marshall_styler
 from streamlit.elements.lib.policies import check_widget_policies
 from streamlit.elements.lib.utils import Key, compute_and_register_element_id, to_key

streamlit/elements/form.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 import textwrap
 from typing import TYPE_CHECKING, Literal, cast
 
-from streamlit.elements.form_utils import FormData, current_form_id, is_in_form
+from streamlit.elements.lib.form_utils import FormData, current_form_id, is_in_form
 from streamlit.elements.lib.policies import (
     check_cache_replay_rules,
     check_session_state_rules,

streamlit/elements/lib/built_in_chart_utils.py

@@ -34,7 +34,7 @@ from typing import (
 from typing_extensions import TypeAlias
 
 from streamlit import dataframe_util, type_util
-from streamlit.color_util import (
+from streamlit.elements.lib.color_util import (
     Color,
     is_color_like,
     is_color_tuple_like,
@@ -89,7 +89,6 @@ class ChartType(Enum):
 # color legends in all instances, since the "size" circles vary in size based
 # on the data, and their container is top-aligned with the color container. But
 # through trial-and-error I found this value to be a good enough middle ground.
-# See e2e/scripts/st_arrow_scatter_chart.py for some alignment tests.
 #
 # NOTE #2: In theory, we could move COLOR_LEGEND_SETTINGS into
 # ArrowVegaLiteChart/CustomTheme.tsx, but this would impact existing behavior.

streamlit/{color_util.py → elements/lib/color_util.py}

@@ -18,7 +18,7 @@ from typing import Any, Callable, Collection, Tuple, Union, cast
 
 from typing_extensions import TypeAlias
 
-from streamlit.errors import StreamlitAPIException
+from streamlit.errors import StreamlitInvalidColorError
 
 # components go from 0.0 to 1.0
 # Supported by Pillow and pretty common.
@@ -86,7 +86,7 @@ def to_css_color(color: MaybeColor) -> Color:
             c4tuple = cast(MixedRGBAColorTuple, ctuple)
             return f"rgba({c4tuple[0]}, {c4tuple[1]}, {c4tuple[2]}, {c4tuple[3]})"
 
-    raise InvalidColorException(color)
+    raise StreamlitInvalidColorError(color)
 
 
 def is_css_color_like(color: MaybeColor) -> bool:
@@ -192,18 +192,18 @@ def _to_color_tuple(
             b = color_hex[5:7]
             a = color_hex[7:9]
         else:
-            raise InvalidColorException(color)
+            raise StreamlitInvalidColorError(color)
 
         try:
             color = int(r, 16), int(g, 16), int(b, 16), int(a, 16)
         except Exception as ex:
-            raise InvalidColorException(color) from ex
+            raise StreamlitInvalidColorError(color) from ex
 
     if is_color_tuple_like(color):
         color_tuple = cast(ColorTuple, color)
         return _normalize_tuple(color_tuple, rgb_formatter, alpha_formatter)
 
-    raise InvalidColorException(color)
+    raise StreamlitInvalidColorError(color)
 
 
 def _normalize_tuple(
@@ -233,7 +233,7 @@ def _normalize_tuple(
         alpha = alpha_formatter(color_4tuple[3], color_4tuple)
         return r, g, b, alpha
 
-    raise InvalidColorException(color)
+    raise StreamlitInvalidColorError(color)
 
 
 def _int_formatter(component: float, color: MaybeColor) -> int:
@@ -247,7 +247,7 @@ def _int_formatter(component: float, color: MaybeColor) -> int:
     if isinstance(component, int):
         return min(255, max(component, 0))
 
-    raise InvalidColorException(color)
+    raise StreamlitInvalidColorError(color)
 
 
 def _float_formatter(component: float, color: MaybeColor) -> float:
@@ -261,16 +261,4 @@ def _float_formatter(component: float, color: MaybeColor) -> float:
     if isinstance(component, float):
         return min(1.0, max(component, 0.0))
 
-    raise InvalidColorException(color)
-
-
-class InvalidColorException(StreamlitAPIException):
-    def __init__(self, color, *args):
-        message = f"""This does not look like a valid color: {repr(color)}.
-
-Colors must be in one of the following formats:
-
-* Hex string with 3, 4, 6, or 8 digits. Example: `'#00ff00'`
-* List or tuple with 3 or 4 components. Example: `[1.0, 0.5, 0, 0.2]`
-            """
-        super().__init__(message, *args)
+    raise StreamlitInvalidColorError(color)

streamlit/elements/lib/options_selector_utils.py

@@ -14,18 +14,48 @@
 
 from __future__ import annotations
 
-from typing import (
-    Any,
-    Sequence,
-)
+from enum import Enum, EnumMeta
+from typing import Any, Final, Iterable, Sequence, TypeVar, overload
 
+from streamlit import config, logger
 from streamlit.dataframe_util import OptionSequence, convert_anything_to_list
 from streamlit.errors import StreamlitAPIException
+from streamlit.runtime.state.common import RegisterWidgetResult
 from streamlit.type_util import (
     T,
     check_python_comparable,
 )
 
+_LOGGER: Final = logger.get_logger(__name__)
+
+_FLOAT_EQUALITY_EPSILON: Final[float] = 0.000000000005
+_Value = TypeVar("_Value")
+
+
+def index_(iterable: Iterable[_Value], x: _Value) -> int:
+    """Return zero-based index of the first item whose value is equal to x.
+    Raises a ValueError if there is no such item.
+
+    We need a custom implementation instead of the built-in list .index() to
+    be compatible with NumPy array and Pandas Series.
+
+    Parameters
+    ----------
+    iterable : list, tuple, numpy.ndarray, pandas.Series
+    x : Any
+
+    Returns
+    -------
+    int
+    """
+    for i, value in enumerate(iterable):
+        if x == value:
+            return i
+        elif isinstance(value, float) and isinstance(x, float):
+            if abs(x - value) < _FLOAT_EQUALITY_EPSILON:
+                return i
+    raise ValueError(f"{str(x)} is not in iterable")
+
 
 def check_and_convert_to_indices(
     opt: Sequence[Any], default_values: Sequence[Any] | Any | None
@@ -58,3 +88,160 @@ def get_default_indices(
     default_indices = check_and_convert_to_indices(indexable_options, default)
     default_indices = default_indices if default_indices is not None else []
     return default_indices
+
+
+E1 = TypeVar("E1", bound=Enum)
+E2 = TypeVar("E2", bound=Enum)
+
+_ALLOWED_ENUM_COERCION_CONFIG_SETTINGS = ("off", "nameOnly", "nameAndValue")
+
+
+def _coerce_enum(from_enum_value: E1, to_enum_class: type[E2]) -> E1 | E2:
+    """Attempt to coerce an Enum value to another EnumMeta.
+
+    An Enum value of EnumMeta E1 is considered coercable to EnumType E2
+    if the EnumMeta __qualname__ match and the names of their members
+    match as well. (This is configurable in streamlist configs)
+    """
+    if not isinstance(from_enum_value, Enum):
+        raise ValueError(
+            f"Expected an Enum in the first argument. Got {type(from_enum_value)}"
+        )
+    if not isinstance(to_enum_class, EnumMeta):
+        raise ValueError(
+            f"Expected an EnumMeta/Type in the second argument. Got {type(to_enum_class)}"
+        )
+    if isinstance(from_enum_value, to_enum_class):
+        return from_enum_value  # Enum is already a member, no coersion necessary
+
+    coercion_type = config.get_option("runner.enumCoercion")
+    if coercion_type not in _ALLOWED_ENUM_COERCION_CONFIG_SETTINGS:
+        raise StreamlitAPIException(
+            "Invalid value for config option runner.enumCoercion. "
+            f"Expected one of {_ALLOWED_ENUM_COERCION_CONFIG_SETTINGS}, "
+            f"but got '{coercion_type}'."
+        )
+    if coercion_type == "off":
+        return from_enum_value  # do not attempt to coerce
+
+    # We now know this is an Enum AND the user has configured coercion enabled.
+    # Check if we do NOT meet the required conditions and log a failure message
+    # if that is the case.
+    from_enum_class = from_enum_value.__class__
+    if (
+        from_enum_class.__qualname__ != to_enum_class.__qualname__
+        or (
+            coercion_type == "nameOnly"
+            and set(to_enum_class._member_names_) != set(from_enum_class._member_names_)
+        )
+        or (
+            coercion_type == "nameAndValue"
+            and set(to_enum_class._value2member_map_)
+            != set(from_enum_class._value2member_map_)
+        )
+    ):
+        _LOGGER.debug("Failed to coerce %s to class %s", from_enum_value, to_enum_class)
+        return from_enum_value  # do not attempt to coerce
+
+    # At this point we think the Enum is coercable, and we know
+    # E1 and E2 have the same member names. We convert from E1 to E2 using _name_
+    # (since user Enum subclasses can override the .name property in 3.11)
+    _LOGGER.debug("Coerced %s to class %s", from_enum_value, to_enum_class)
+    return to_enum_class[from_enum_value._name_]
+
+
+def _extract_common_class_from_iter(iterable: Iterable[Any]) -> Any:
+    """Return the common class of all elements in a iterable if they share one.
+    Otherwise, return None."""
+    try:
+        inner_iter = iter(iterable)
+        first_class = type(next(inner_iter))
+    except StopIteration:
+        return None
+    if all(type(item) is first_class for item in inner_iter):
+        return first_class
+    return None
+
+
+@overload
+def maybe_coerce_enum(
+    register_widget_result: RegisterWidgetResult[Enum],
+    options: type[Enum],
+    opt_sequence: Sequence[Any],
+) -> RegisterWidgetResult[Enum]: ...
+
+
+@overload
+def maybe_coerce_enum(
+    register_widget_result: RegisterWidgetResult[T],
+    options: OptionSequence[T],
+    opt_sequence: Sequence[T],
+) -> RegisterWidgetResult[T]: ...
+
+
+def maybe_coerce_enum(register_widget_result, options, opt_sequence):
+    """Maybe Coerce a RegisterWidgetResult with an Enum member value to
+    RegisterWidgetResult[option] if option is an EnumType, otherwise just return
+    the original RegisterWidgetResult."""
+
+    # If the value is not a Enum, return early
+    if not isinstance(register_widget_result.value, Enum):
+        return register_widget_result
+
+    coerce_class: EnumMeta | None
+    if isinstance(options, EnumMeta):
+        coerce_class = options
+    else:
+        coerce_class = _extract_common_class_from_iter(opt_sequence)
+        if coerce_class is None:
+            return register_widget_result
+
+    return RegisterWidgetResult(
+        _coerce_enum(register_widget_result.value, coerce_class),
+        register_widget_result.value_changed,
+    )
+
+
+# slightly ugly typing because TypeVars with Generic Bounds are not supported
+# (https://github.com/python/typing/issues/548)
+@overload
+def maybe_coerce_enum_sequence(
+    register_widget_result: RegisterWidgetResult[list[T]],
+    options: OptionSequence[T],
+    opt_sequence: Sequence[T],
+) -> RegisterWidgetResult[list[T]]: ...
+
+
+@overload
+def maybe_coerce_enum_sequence(
+    register_widget_result: RegisterWidgetResult[tuple[T, T]],
+    options: OptionSequence[T],
+    opt_sequence: Sequence[T],
+) -> RegisterWidgetResult[tuple[T, T]]: ...
+
+
+def maybe_coerce_enum_sequence(register_widget_result, options, opt_sequence):
+    """Maybe Coerce a RegisterWidgetResult with a sequence of Enum members as value
+    to RegisterWidgetResult[Sequence[option]] if option is an EnumType, otherwise just return
+    the original RegisterWidgetResult."""
+
+    # If not all widget values are Enums, return early
+    if not all(isinstance(val, Enum) for val in register_widget_result.value):
+        return register_widget_result
+
+    # Extract the class to coerce
+    coerce_class: EnumMeta | None
+    if isinstance(options, EnumMeta):
+        coerce_class = options
+    else:
+        coerce_class = _extract_common_class_from_iter(opt_sequence)
+        if coerce_class is None:
+            return register_widget_result
+
+    # Return a new RegisterWidgetResult with the coerced enum values sequence
+    return RegisterWidgetResult(
+        type(register_widget_result.value)(
+            _coerce_enum(val, coerce_class) for val in register_widget_result.value
+        ),
+        register_widget_result.value_changed,
+    )

streamlit/elements/lib/policies.py

@@ -17,7 +17,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, Final, Sequence
 
 from streamlit import config, errors, logger, runtime
-from streamlit.elements.form_utils import is_in_form
+from streamlit.elements.lib.form_utils import is_in_form
 from streamlit.errors import (
     StreamlitAPIWarning,
     StreamlitFragmentWidgetsNotAllowedOutsideError,
@@ -124,11 +124,6 @@ def check_cache_replay_rules() -> None:
         exception(CachedWidgetWarning())
 
 
-_fragment_writes_widget_to_outside_error = (
-    "Fragments cannot write to elements outside of their container."
-)
-
-
 def check_fragment_path_policy(dg: DeltaGenerator):
     """Ensures that the current widget is not written outside of the
     fragment's delta path.