streamlit-nightly 1.43.2.dev20250307__py3-none-any.whl

streamlit/delta_generator_singletons.py

@@ -0,0 +1,204 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2025)
+#
+# 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.
+
+"""
+The main purpose of this module (right now at least) is to avoid a dependency
+cycle between streamlit.delta_generator and some elements.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from typing import TYPE_CHECKING, Callable, Generic, TypeVar
+
+from streamlit.proto.RootContainer_pb2 import RootContainer as _RootContainer
+
+if TYPE_CHECKING:
+    from streamlit.delta_generator import DeltaGenerator
+    from streamlit.elements.lib.dialog import Dialog
+    from streamlit.elements.lib.mutable_status_container import StatusContainer
+
+
+class DeltaGeneratorSingleton:
+    """Used to initialize the DeltaGenerator classes and store them as singletons.
+    This module allows us to avoid circular imports between DeltaGenerator and elements,
+    because elemens can import this singleton module instead of DeltaGenerator directly.
+    """
+
+    _instance: DeltaGeneratorSingleton | None = None
+
+    @classmethod
+    def instance(cls) -> DeltaGeneratorSingleton:
+        """Return the singleton DeltaGeneratorSingleton instance. Raise an Error if the
+        DeltaGeneratorSingleton hasn't been created yet.
+        """
+        if cls._instance is None:
+            raise RuntimeError("DeltaGeneratorSingleton hasn't been created!")
+        return cls._instance
+
+    def __init__(
+        self,
+        delta_generator_cls: type[DeltaGenerator],
+        status_container_cls: type[StatusContainer],
+        dialog_container_cls: type[Dialog],
+    ):
+        """Registers and initializes all delta-generator classes.
+
+        Parameters
+        ----------
+
+        delta_generator_cls : type[DeltaGenerator]
+            The main DeltaGenerator class.
+        status_container_cls : type[StatusContainer]
+            The delta-generator class that is used as return value for `st.status`.
+        dialog_container_cls : type[Dialog]
+            The delta-generator class used is used as return value for `st.dialog`.
+
+        Raises
+        ------
+        RuntimeError
+            If the DeltaGeneratorSingleton instance already exists.
+        """
+        if DeltaGeneratorSingleton._instance is not None:
+            raise RuntimeError("DeltaGeneratorSingleton instance already exists!")
+        DeltaGeneratorSingleton._instance = self
+
+        self._main_dg = delta_generator_cls(root_container=_RootContainer.MAIN)
+        self._sidebar_dg = delta_generator_cls(
+            root_container=_RootContainer.SIDEBAR, parent=self._main_dg
+        )
+        self._event_dg = delta_generator_cls(
+            root_container=_RootContainer.EVENT, parent=self._main_dg
+        )
+        self._bottom_dg = delta_generator_cls(
+            root_container=_RootContainer.BOTTOM, parent=self._main_dg
+        )
+        self._status_container_cls = status_container_cls
+        self._dialog_container_cls = dialog_container_cls
+
+    @property
+    def main_dg(self) -> DeltaGenerator:
+        return self._main_dg
+
+    @property
+    def sidebar_dg(self) -> DeltaGenerator:
+        return self._sidebar_dg
+
+    @property
+    def event_dg(self) -> DeltaGenerator:
+        return self._event_dg
+
+    @property
+    def bottom_dg(self) -> DeltaGenerator:
+        return self._bottom_dg
+
+    @property
+    def status_container_cls(
+        self,
+    ) -> type[StatusContainer]:
+        """Stub for StatusContainer. Since StatusContainer inherits from DeltaGenerator,
+        this is used to avoid circular imports.
+        """
+        return self._status_container_cls
+
+    @property
+    def dialog_container_cls(self) -> type[Dialog]:
+        """Stub for Dialog. Since Dialog inherits from DeltaGenerator,
+        this is used to avoid circular imports.
+        """
+        return self._dialog_container_cls
+
+
+def get_dg_singleton_instance() -> DeltaGeneratorSingleton:
+    """Return the DeltaGeneratorSingleton instance. Raise an Error if the
+    DeltaGeneratorSingleton hasn't been created yet.
+    """
+    return DeltaGeneratorSingleton.instance()
+
+
+_T = TypeVar("_T")
+
+
+class ContextVarWithLazyDefault(Generic[_T]):
+    """The dg_stack tracks the currently active DeltaGenerator, and is pushed to when
+    a DeltaGenerator is entered via a `with` block. This is implemented as a ContextVar
+    so that different threads or async tasks can have their own stacks.
+
+    We have a wrapper around it because ContextVar default cannot be a function, but
+    the default dg (main_dg) might not exist yet when this module is imported.
+    """
+
+    def __init__(self, name: str, *, default: Callable[[], _T]):
+        self._name = name
+        self._default = default
+        self._context_var: ContextVar[_T] | None = None
+
+    def _init_context_var(self) -> None:
+        self._context_var = ContextVar(self._name, default=self._default())  # noqa: B039
+
+    def get(self) -> _T:
+        if self._context_var is None:
+            self._init_context_var()
+        return self._context_var.get()  # type: ignore[union-attr]
+
+    def set(self, value: _T) -> Token[_T]:
+        if self._context_var is None:
+            self._init_context_var()
+        return self._context_var.set(value)  # type: ignore[union-attr]
+
+    def reset(self, token: Token[_T]) -> None:
+        if self._context_var is None:
+            self._init_context_var()
+        self._context_var.reset(token)  # type: ignore[union-attr]
+
+    def __hash__(self) -> int:
+        if self._context_var is None:
+            self._init_context_var()
+        return self._context_var.__hash__()
+
+
+# we don't use the default factory here because `main_dg` is not initialized when this
+# module is imported. This is why we have our own ContextVar wrapper.
+context_dg_stack: ContextVarWithLazyDefault[tuple[DeltaGenerator, ...]] = (
+    ContextVarWithLazyDefault(
+        "context_dg_stack", default=lambda: (get_dg_singleton_instance().main_dg,)
+    )
+)
+
+
+def get_default_dg_stack_value() -> tuple[DeltaGenerator, ...]:
+    """Get the default dg_stack value with which the dg_stack should
+    be initialized and reset if needed."""
+    instance = get_dg_singleton_instance()
+    if instance._main_dg is None:
+        raise RuntimeError("main_dg is not set")
+
+    return (instance._main_dg,)
+
+
+def get_last_dg_added_to_context_stack() -> DeltaGenerator | None:
+    """Get the last added DeltaGenerator of the stack in the current context.
+
+    Returns None if the stack has only one element or is empty for whatever reason.
+    """
+    current_stack = context_dg_stack.get()
+    # If set to "> 0" and thus return the only delta generator in the stack -
+    # which logically makes more sense -, some unit tests fail.
+    # It looks like the reason is that they create their own main delta generator
+    # but do not populate the dg_stack correctly. However, to be on the safe-side,
+    # we keep the logic but leave the comment as shared knowledge for whoever will look
+    # into this in the future.
+    if len(current_stack) > 1:
+        return current_stack[-1]
+    return None

streamlit/deprecation_util.py

@@ -0,0 +1,209 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2025)
+#
+# 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
+
+import functools
+from typing import Any, Callable, Final, TypeVar, cast
+
+import streamlit
+from streamlit import config
+from streamlit.logger import get_logger
+
+_LOGGER: Final = get_logger(__name__)
+
+TFunc = TypeVar("TFunc", bound=Callable[..., Any])
+TObj = TypeVar("TObj", bound=object)
+
+
+def _should_show_deprecation_warning_in_browser() -> bool:
+    """True if we should print deprecation warnings to the browser."""
+    return bool(config.get_option("client.showErrorDetails"))
+
+
+def show_deprecation_warning(message: str) -> None:
+    """Show a deprecation warning message."""
+    if _should_show_deprecation_warning_in_browser():
+        streamlit.warning(message)
+
+    # We always log deprecation warnings
+    _LOGGER.warning(message)
+
+
+def make_deprecated_name_warning(
+    old_name: str,
+    new_name: str,
+    removal_date: str,
+    extra_message: str | None = None,
+    include_st_prefix: bool = True,
+) -> str:
+    if include_st_prefix:
+        old_name = f"st.{old_name}"
+        new_name = f"st.{new_name}"
+
+    return (
+        f"Please replace `{old_name}` with `{new_name}`.\n\n"
+        f"`{old_name}` will be removed after {removal_date}."
+        + (f"\n\n{extra_message}" if extra_message else "")
+    )
+
+
+def deprecate_func_name(
+    func: TFunc,
+    old_name: str,
+    removal_date: str,
+    extra_message: str | None = None,
+    name_override: str | None = None,
+) -> TFunc:
+    """Wrap an `st` function whose name has changed.
+
+    Wrapped functions will run as normal, but will also show an st.warning
+    saying that the old name will be removed after removal_date.
+
+    (We generally set `removal_date` to 3 months from the deprecation date.)
+
+    Parameters
+    ----------
+    func
+        The `st.` function whose name has changed.
+
+    old_name
+        The function's deprecated name within __init__.py.
+
+    removal_date
+        A date like "2020-01-01", indicating the last day we'll guarantee
+        support for the deprecated name.
+
+    extra_message
+        An optional extra message to show in the deprecation warning.
+
+    name_override
+        An optional name to use in place of func.__name__.
+    """
+
+    @functools.wraps(func)
+    def wrapped_func(*args, **kwargs):
+        result = func(*args, **kwargs)
+        show_deprecation_warning(
+            make_deprecated_name_warning(
+                old_name, name_override or func.__name__, removal_date, extra_message
+            )
+        )
+        return result
+
+    # Update the wrapped func's name & docstring so st.help does the right thing
+    wrapped_func.__name__ = old_name
+    wrapped_func.__doc__ = func.__doc__
+    return cast(TFunc, wrapped_func)
+
+
+def deprecate_obj_name(
+    obj: TObj,
+    old_name: str,
+    new_name: str,
+    removal_date: str,
+    include_st_prefix: bool = True,
+) -> TObj:
+    """Wrap an `st` object whose name has changed.
+
+    Wrapped objects will behave as normal, but will also show an st.warning
+    saying that the old name will be removed after `removal_date`.
+
+    (We generally set `removal_date` to 3 months from the deprecation date.)
+
+    Parameters
+    ----------
+    obj
+        The `st.` object whose name has changed.
+
+    old_name
+        The object's deprecated name within __init__.py.
+
+    new_name
+        The object's new name within __init__.py.
+
+    removal_date
+        A date like "2020-01-01", indicating the last day we'll guarantee
+        support for the deprecated name.
+
+    include_st_prefix
+        If False, does not prefix each of the object names in the deprecation
+        essage with `st.*`. Defaults to True.
+    """
+
+    return _create_deprecated_obj_wrapper(
+        obj,
+        lambda: show_deprecation_warning(
+            make_deprecated_name_warning(
+                old_name, new_name, removal_date, include_st_prefix=include_st_prefix
+            )
+        ),
+    )
+
+
+def _create_deprecated_obj_wrapper(obj: TObj, show_warning: Callable[[], Any]) -> TObj:
+    """Create a wrapper for an object that has been deprecated. The first
+    time one of the object's properties or functions is accessed, the
+    given `show_warning` callback will be called.
+    """
+    has_shown_warning = False
+
+    def maybe_show_warning() -> None:
+        # Call `show_warning` if it hasn't already been called once.
+        nonlocal has_shown_warning
+        if not has_shown_warning:
+            has_shown_warning = True
+            show_warning()
+
+    class Wrapper:
+        def __init__(self):
+            # Override all the Wrapped object's magic functions
+            for name in Wrapper._get_magic_functions(obj.__class__):
+                setattr(
+                    self.__class__,
+                    name,
+                    property(self._make_magic_function_proxy(name)),
+                )
+
+        def __getattr__(self, attr):
+            # We handle __getattr__ separately from our other magic
+            # functions. The wrapped class may not actually implement it,
+            # but we still need to implement it to call all its normal
+            # functions.
+            if attr in self.__dict__:
+                return getattr(self, attr)
+
+            maybe_show_warning()
+            return getattr(obj, attr)
+
+        @staticmethod
+        def _get_magic_functions(cls) -> list[str]:
+            # ignore the handful of magic functions we cannot override without
+            # breaking the Wrapper.
+            ignore = ("__class__", "__dict__", "__getattribute__", "__getattr__")
+            return [
+                name
+                for name in dir(cls)
+                if name not in ignore and name.startswith("__")
+            ]
+
+        @staticmethod
+        def _make_magic_function_proxy(name):
+            def proxy(self, *args):
+                maybe_show_warning()
+                return getattr(obj, name)
+
+            return proxy
+
+    return cast(TObj, Wrapper())

streamlit/development.py

@@ -0,0 +1,21 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2025)
+#
+# 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.
+
+"""Variables for dev purposes.
+
+The main purpose of this module (right now at least) is to avoid a dependency
+cycle between streamlit.config and streamlit.logger.
+"""
+
+is_development_mode = False

streamlit/elements/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2025)
+#
+# 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.

streamlit/elements/alert.py

@@ -0,0 +1,234 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2025)
+#
+# 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 typing import TYPE_CHECKING, cast
+
+from streamlit.proto.Alert_pb2 import Alert as AlertProto
+from streamlit.runtime.metrics_util import gather_metrics
+from streamlit.string_util import clean_text, validate_icon_or_emoji
+
+if TYPE_CHECKING:
+    from streamlit.delta_generator import DeltaGenerator
+    from streamlit.type_util import SupportsStr
+
+
+class AlertMixin:
+    @gather_metrics("error")
+    def error(
+        self,
+        body: SupportsStr,
+        *,  # keyword-only args:
+        icon: str | None = None,
+    ) -> DeltaGenerator:
+        """Display error message.
+
+        Parameters
+        ----------
+        body : str
+            The text to display as GitHub-flavored Markdown. Syntax
+            information can be found at: https://github.github.com/gfm.
+
+            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
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            - A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            - An icon from the Material Symbols library (rounded style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
+              font library.
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>>
+        >>> st.error('This is an error', icon="🚨")
+
+        """
+        alert_proto = AlertProto()
+
+        alert_proto.icon = validate_icon_or_emoji(icon)
+        alert_proto.body = clean_text(body)
+        alert_proto.format = AlertProto.ERROR
+        return self.dg._enqueue("alert", alert_proto)
+
+    @gather_metrics("warning")
+    def warning(
+        self,
+        body: SupportsStr,
+        *,  # keyword-only args:
+        icon: str | None = None,
+    ) -> DeltaGenerator:
+        """Display warning message.
+
+        Parameters
+        ----------
+        body : str
+            The text to display as GitHub-flavored Markdown. Syntax
+            information can be found at: https://github.github.com/gfm.
+
+            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
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            - A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            - An icon from the Material Symbols library (rounded style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
+              font library.
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>>
+        >>> st.warning('This is a warning', icon="⚠️")
+
+        """
+        alert_proto = AlertProto()
+        alert_proto.body = clean_text(body)
+        alert_proto.icon = validate_icon_or_emoji(icon)
+        alert_proto.format = AlertProto.WARNING
+        return self.dg._enqueue("alert", alert_proto)
+
+    @gather_metrics("info")
+    def info(
+        self,
+        body: SupportsStr,
+        *,  # keyword-only args:
+        icon: str | None = None,
+    ) -> DeltaGenerator:
+        """Display an informational message.
+
+        Parameters
+        ----------
+        body : str
+            The text to display as GitHub-flavored Markdown. Syntax
+            information can be found at: https://github.github.com/gfm.
+
+            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
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            - A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            - An icon from the Material Symbols library (rounded style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
+              font library.
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>>
+        >>> st.info('This is a purely informational message', icon="ℹ️")
+
+        """
+
+        alert_proto = AlertProto()
+        alert_proto.body = clean_text(body)
+        alert_proto.icon = validate_icon_or_emoji(icon)
+        alert_proto.format = AlertProto.INFO
+        return self.dg._enqueue("alert", alert_proto)
+
+    @gather_metrics("success")
+    def success(
+        self,
+        body: SupportsStr,
+        *,  # keyword-only args:
+        icon: str | None = None,
+    ) -> DeltaGenerator:
+        """Display a success message.
+
+        Parameters
+        ----------
+        body : str
+            The text to display as GitHub-flavored Markdown. Syntax
+            information can be found at: https://github.github.com/gfm.
+
+            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
+        icon : str, None
+            An optional emoji or icon to display next to the alert. If ``icon``
+            is ``None`` (default), no icon is displayed. If ``icon`` is a
+            string, the following options are valid:
+
+            - A single-character emoji. For example, you can set ``icon="🚨"``
+              or ``icon="🔥"``. Emoji short codes are not supported.
+
+            - An icon from the Material Symbols library (rounded style) in the
+              format ``":material/icon_name:"`` where "icon_name" is the name
+              of the icon in snake case.
+
+              For example, ``icon=":material/thumb_up:"`` will display the
+              Thumb Up icon. Find additional icons in the `Material Symbols \
+              <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
+              font library.
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>>
+        >>> st.success('This is a success message!', icon="✅")
+
+        """
+        alert_proto = AlertProto()
+        alert_proto.body = clean_text(body)
+        alert_proto.icon = validate_icon_or_emoji(icon)
+        alert_proto.format = AlertProto.SUCCESS
+        return self.dg._enqueue("alert", alert_proto)
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        """Get our DeltaGenerator."""
+        return cast("DeltaGenerator", self)