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

streamlit/elements/exception.py

@@ -0,0 +1,331 @@
+# 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 os
+import traceback
+from typing import TYPE_CHECKING, Callable, Final, TypeVar, cast
+
+from streamlit import config
+from streamlit.errors import (
+    MarkdownFormattedException,
+    StreamlitAPIWarning,
+)
+from streamlit.logger import get_logger
+from streamlit.proto.Exception_pb2 import Exception as ExceptionProto
+from streamlit.runtime.metrics_util import gather_metrics
+from streamlit.runtime.scriptrunner_utils.script_run_context import get_script_run_ctx
+
+if TYPE_CHECKING:
+    from streamlit.delta_generator import DeltaGenerator
+
+_LOGGER: Final = get_logger(__name__)
+
+# When client.showErrorDetails is False, we show a generic warning in the
+# frontend when we encounter an uncaught app exception.
+_GENERIC_UNCAUGHT_EXCEPTION_TEXT: Final = "This app has encountered an error. The original error message is redacted to prevent data leaks.  Full error details have been recorded in the logs (if you're on Streamlit Cloud, click on 'Manage app' in the lower right of your app)."
+
+
+class ExceptionMixin:
+    @gather_metrics("exception")
+    def exception(self, exception: BaseException) -> DeltaGenerator:
+        """Display an exception.
+
+        Parameters
+        ----------
+        exception : Exception
+            The exception to display.
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>>
+        >>> e = RuntimeError("This is an exception of type RuntimeError")
+        >>> st.exception(e)
+
+        """
+        return _exception(self.dg, exception)
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        """Get our DeltaGenerator."""
+        return cast("DeltaGenerator", self)
+
+
+# TODO(lawilby): confirm whether we want to track metrics here with lukasmasuch.
+@gather_metrics("exception")
+def _exception(
+    dg: DeltaGenerator,
+    exception: BaseException,
+    is_uncaught_app_exception: bool = False,
+) -> DeltaGenerator:
+    exception_proto = ExceptionProto()
+    marshall(exception_proto, exception, is_uncaught_app_exception)
+    return dg._enqueue("exception", exception_proto)
+
+
+def marshall(
+    exception_proto: ExceptionProto,
+    exception: BaseException,
+    is_uncaught_app_exception: bool = False,
+) -> None:
+    """Marshalls an Exception.proto message.
+
+    Parameters
+    ----------
+    exception_proto : Exception.proto
+        The Exception protobuf to fill out.
+
+    exception : BaseException
+        The exception whose data we're extracting.
+
+    is_uncaught_app_exception: bool
+        The exception originates from an uncaught error during script execution.
+    """
+    is_markdown_exception = isinstance(exception, MarkdownFormattedException)
+
+    # Some exceptions (like UserHashError) have an alternate_name attribute so
+    # we can pretend to the user that the exception is called something else.
+    if getattr(exception, "alternate_name", None) is not None:
+        exception_proto.type = exception.alternate_name  # type: ignore[attr-defined]
+    else:
+        exception_proto.type = type(exception).__name__
+
+    stack_trace = _get_stack_trace_str_list(exception)
+
+    exception_proto.stack_trace.extend(stack_trace)
+    exception_proto.is_warning = isinstance(exception, Warning)
+
+    try:
+        if isinstance(exception, SyntaxError):
+            # SyntaxErrors have additional fields (filename, text, lineno,
+            # offset) that we can use for a nicely-formatted message telling
+            # the user what to fix.
+            exception_proto.message = _format_syntax_error_message(exception)
+        else:
+            exception_proto.message = str(exception).strip()
+            exception_proto.message_is_markdown = is_markdown_exception
+
+    except Exception as str_exception:
+        # Sometimes the exception's __str__/__unicode__ method itself
+        # raises an error.
+        exception_proto.message = ""
+        _LOGGER.warning(
+            """
+
+Streamlit was unable to parse the data from an exception in the user's script.
+This is usually due to a bug in the Exception object itself. Here is some info
+about that Exception object, so you can report a bug to the original author:
+
+Exception type:
+  %s
+
+Problem:
+  %s
+
+Traceback:
+%s
+
+        """,
+            type(exception).__name__,
+            str_exception,
+            "\n".join(_get_stack_trace_str_list(str_exception)),
+        )
+
+    if is_uncaught_app_exception:
+        show_error_details = config.get_option("client.showErrorDetails")
+
+        show_message = (
+            show_error_details == config.ShowErrorDetailsConfigOptions.FULL
+            or config.ShowErrorDetailsConfigOptions.is_true_variation(
+                show_error_details
+            )
+        )
+        # False is a legacy config option still in-use in community cloud. It is equivalent
+        # to "stacktrace".
+        show_trace = (
+            show_message
+            or show_error_details == config.ShowErrorDetailsConfigOptions.STACKTRACE
+            or config.ShowErrorDetailsConfigOptions.is_false_variation(
+                show_error_details
+            )
+        )
+        show_type = (
+            show_trace
+            or show_error_details == config.ShowErrorDetailsConfigOptions.TYPE
+        )
+
+        if not show_message:
+            exception_proto.message = _GENERIC_UNCAUGHT_EXCEPTION_TEXT
+        if not show_type:
+            exception_proto.ClearField("type")
+        else:
+            type_str = str(type(exception))
+            exception_proto.type = type_str.replace("<class '", "").replace("'>", "")
+        if not show_trace:
+            exception_proto.ClearField("stack_trace")
+
+
+def _format_syntax_error_message(exception: SyntaxError) -> str:
+    """Returns a nicely formatted SyntaxError message that emulates
+    what the Python interpreter outputs, e.g.:
+
+    > File "raven.py", line 3
+    >   st.write('Hello world!!'))
+    >                            ^
+    > SyntaxError: invalid syntax
+
+    """
+    if exception.text:
+        if exception.offset is not None:
+            caret_indent = " " * max(exception.offset - 1, 0)
+        else:
+            caret_indent = ""
+
+        return (
+            'File "%(filename)s", line %(lineno)s\n'
+            "  %(text)s\n"
+            "  %(caret_indent)s^\n"
+            "%(errname)s: %(msg)s"
+            % {
+                "filename": exception.filename,
+                "lineno": exception.lineno,
+                "text": exception.text.rstrip(),
+                "caret_indent": caret_indent,
+                "errname": type(exception).__name__,
+                "msg": exception.msg,
+            }
+        )
+    # If a few edge cases, SyntaxErrors don't have all these nice fields. So we
+    # have a fall back here.
+    # Example edge case error message: encoding declaration in Unicode string
+    return str(exception)
+
+
+def _get_stack_trace_str_list(exception: BaseException) -> list[str]:
+    """Get the stack trace for the given exception.
+
+    Parameters
+    ----------
+    exception : BaseException
+        The exception to extract the traceback from
+
+    Returns
+    -------
+    tuple of two string lists
+        The exception traceback as two lists of strings. The first represents the part
+        of the stack trace the users don't typically want to see, containing internal
+        Streamlit code. The second is whatever comes after the Streamlit stack trace,
+        which is usually what the user wants.
+
+    """
+    extracted_traceback: traceback.StackSummary | None = None
+    if isinstance(exception, StreamlitAPIWarning):
+        extracted_traceback = exception.tacked_on_stack
+    elif hasattr(exception, "__traceback__"):
+        extracted_traceback = traceback.extract_tb(exception.__traceback__)
+
+    # Format the extracted traceback and add it to the protobuf element.
+    if extracted_traceback is None:
+        trace_str_list = [
+            "Cannot extract the stack trace for this exception. "
+            "Try calling exception() within the `catch` block."
+        ]
+    else:
+        internal_frames, external_frames = _split_internal_streamlit_frames(
+            extracted_traceback
+        )
+
+        if external_frames:
+            trace_str_list = traceback.format_list(external_frames)
+        else:
+            trace_str_list = traceback.format_list(internal_frames)
+
+        trace_str_list = [item.strip() for item in trace_str_list]
+
+    return trace_str_list
+
+
+def _is_in_package(file: str, package_path: str) -> bool:
+    """True if the given file is part of package_path."""
+    try:
+        common_prefix = os.path.commonprefix([os.path.realpath(file), package_path])
+    except ValueError:
+        # Raised if paths are on different drives.
+        return False
+
+    return common_prefix == package_path
+
+
+def _split_internal_streamlit_frames(
+    extracted_tb: traceback.StackSummary,
+) -> tuple[list[traceback.FrameSummary], list[traceback.FrameSummary]]:
+    """Split the traceback into a Streamlit-internal part and an external part.
+
+    The internal part is everything up to (but excluding) the first frame belonging to
+    the user's code. The external part is everything else.
+
+    So if the stack looks like this:
+
+        1. Streamlit frame
+        2. Pandas frame
+        3. Altair frame
+        4. Streamlit frame
+        5. User frame
+        6. User frame
+        7. Streamlit frame
+        8. Matplotlib frame
+
+    ...then this should return 1-4 as the internal traceback and 5-8 as the external.
+
+    (Note that something like the example above is extremely unlikely to happen since
+    it's not like Altair is calling Streamlit code, but you get the idea.)
+    """
+
+    ctx = get_script_run_ctx()
+
+    if not ctx:
+        return [], list(extracted_tb)
+
+    package_path = os.path.join(os.path.realpath(str(ctx.main_script_parent)), "")
+
+    return _split_list(
+        extracted_tb,
+        split_point=lambda tb: _is_in_package(tb.filename, package_path),
+    )
+
+
+T = TypeVar("T")
+
+
+def _split_list(
+    orig_list: list[T], split_point: Callable[[T], bool]
+) -> tuple[list[T], list[T]]:
+    before: list[T] = []
+    after: list[T] = []
+
+    saw_split_point = False
+
+    for item in orig_list:
+        if not saw_split_point:
+            if split_point(item):
+                saw_split_point = True
+
+        if saw_split_point:
+            after.append(item)
+        else:
+            before.append(item)
+
+    return before, after

streamlit/elements/form.py

@@ -0,0 +1,354 @@
+# 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 textwrap
+from typing import TYPE_CHECKING, Literal, cast
+
+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,
+)
+from streamlit.errors import StreamlitAPIException
+from streamlit.proto import Block_pb2
+from streamlit.runtime.metrics_util import gather_metrics
+from streamlit.runtime.scriptrunner import ScriptRunContext, get_script_run_ctx
+
+if TYPE_CHECKING:
+    from streamlit.delta_generator import DeltaGenerator
+    from streamlit.runtime.state import WidgetArgs, WidgetCallback, WidgetKwargs
+
+
+def _build_duplicate_form_message(user_key: str | None = None) -> str:
+    if user_key is not None:
+        message = textwrap.dedent(
+            f"""
+            There are multiple identical forms with `key='{user_key}'`.
+
+            To fix this, please make sure that the `key` argument is unique for
+            each `st.form` you create.
+            """
+        )
+    else:
+        message = textwrap.dedent(
+            """
+            There are multiple identical forms with the same generated key.
+
+            When a form is created, it's assigned an internal key based on
+            its structure. Multiple forms with an identical structure will
+            result in the same internal key, which causes this error.
+
+            To fix this error, please pass a unique `key` argument to
+            `st.form`.
+            """
+        )
+
+    return message.strip("\n")
+
+
+class FormMixin:
+    @gather_metrics("form")
+    def form(
+        self,
+        key: str,
+        clear_on_submit: bool = False,
+        *,
+        enter_to_submit: bool = True,
+        border: bool = True,
+    ) -> DeltaGenerator:
+        """Create a form that batches elements together with a "Submit" button.
+
+        A form is a container that visually groups other elements and
+        widgets together, and contains a Submit button. When the form's
+        Submit button is pressed, all widget values inside the form will be
+        sent to Streamlit in a batch.
+
+        To add elements to a form object, you can use ``with`` notation
+        (preferred) or just call methods directly on the form. See
+        examples below.
+
+        Forms have a few constraints:
+
+        - Every form must contain a ``st.form_submit_button``.
+        - ``st.button`` and ``st.download_button`` cannot be added to a form.
+        - Forms can appear anywhere in your app (sidebar, columns, etc),
+          but they cannot be embedded inside other forms.
+        - Within a form, the only widget that can have a callback function is
+          ``st.form_submit_button``.
+
+        Parameters
+        ----------
+        key : str
+            A string that identifies the form. Each form must have its own
+            key. (This key is not displayed to the user in the interface.)
+        clear_on_submit : bool
+            If True, all widgets inside the form will be reset to their default
+            values after the user presses the Submit button. Defaults to False.
+            (Note that Custom Components are unaffected by this flag, and
+            will not be reset to their defaults on form submission.)
+        enter_to_submit : bool
+            Whether to submit the form when a user presses Enter while
+            interacting with a widget inside the form.
+
+            If this is ``True`` (default), pressing Enter while interacting
+            with a form widget is equivalent to clicking the first
+            ``st.form_submit_button`` in the form.
+
+            If this is ``False``, the user must click an
+            ``st.form_submit_button`` to submit the form.
+
+            If the first ``st.form_submit_button`` in the form is disabled,
+            the form will override submission behavior with
+            ``enter_to_submit=False``.
+
+        border : bool
+            Whether to show a border around the form. Defaults to True.
+
+            .. note::
+                Not showing a border can be confusing to viewers since interacting with a
+                widget in the form will do nothing. You should only remove the border if
+                there's another border (e.g. because of an expander) or the form is small
+                (e.g. just a text input and a submit button).
+
+        Examples
+        --------
+        Inserting elements using ``with`` notation:
+
+        >>> import streamlit as st
+        >>>
+        >>> with st.form("my_form"):
+        ...     st.write("Inside the form")
+        ...     slider_val = st.slider("Form slider")
+        ...     checkbox_val = st.checkbox("Form checkbox")
+        ...
+        ...     # Every form must have a submit button.
+        ...     submitted = st.form_submit_button("Submit")
+        ...     if submitted:
+        ...         st.write("slider", slider_val, "checkbox", checkbox_val)
+        >>> st.write("Outside the form")
+
+        .. output::
+           https://doc-form1.streamlit.app/
+           height: 425px
+
+        Inserting elements out of order:
+
+        >>> import streamlit as st
+        >>>
+        >>> form = st.form("my_form")
+        >>> form.slider("Inside the form")
+        >>> st.slider("Outside the form")
+        >>>
+        >>> # Now add a submit button to the form:
+        >>> form.form_submit_button("Submit")
+
+        .. output::
+           https://doc-form2.streamlit.app/
+           height: 375px
+
+        """
+        if is_in_form(self.dg):
+            raise StreamlitAPIException("Forms cannot be nested in other forms.")
+
+        check_cache_replay_rules()
+        check_session_state_rules(default_value=None, key=key, writes_allowed=False)
+
+        # A form is uniquely identified by its key.
+        form_id = key
+
+        ctx = get_script_run_ctx()
+        if ctx is not None:
+            new_form_id = form_id not in ctx.form_ids_this_run
+            if new_form_id:
+                ctx.form_ids_this_run.add(form_id)
+            else:
+                raise StreamlitAPIException(_build_duplicate_form_message(key))
+
+        block_proto = Block_pb2.Block()
+        block_proto.form.form_id = form_id
+        block_proto.form.clear_on_submit = clear_on_submit
+        block_proto.form.enter_to_submit = enter_to_submit
+        block_proto.form.border = border
+        block_dg = self.dg._block(block_proto)
+
+        # Attach the form's button info to the newly-created block's
+        # DeltaGenerator.
+        block_dg._form_data = FormData(form_id)
+        return block_dg
+
+    @gather_metrics("form_submit_button")
+    def form_submit_button(
+        self,
+        label: str = "Submit",
+        help: str | None = None,
+        on_click: WidgetCallback | None = None,
+        args: WidgetArgs | None = None,
+        kwargs: WidgetKwargs | None = None,
+        *,  # keyword-only arguments:
+        type: Literal["primary", "secondary", "tertiary"] = "secondary",
+        icon: str | None = None,
+        disabled: bool = False,
+        use_container_width: bool = False,
+    ) -> bool:
+        """Display a form submit button.
+
+        When this button is clicked, all widget values inside the form will be
+        sent from the user's browser to your Streamlit server in a batch.
+
+        Every form must have at least one ``st.form_submit_button``. An
+        ``st.form_submit_button`` cannot exist outside of a form.
+
+        For more information about forms, check out our `docs
+        <https://docs.streamlit.io/develop/concepts/architecture/forms>`_.
+
+        Parameters
+        ----------
+        label : str
+            A short label explaining to the user what this button is for. This
+            defaults to ``"Submit"``. 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
+        help : str or None
+            A tooltip that gets displayed when the button is hovered over. 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``.
+        on_click : callable
+            An optional callback invoked when this button is clicked.
+        args : tuple
+            An optional tuple of args to pass to the callback.
+        kwargs : dict
+            An optional dict of kwargs to pass to the callback.
+        type : "primary", "secondary", or "tertiary"
+            An optional string that specifies the button type. This can be one
+            of the following:
+
+            - ``"primary"``: The button's background is the app's primary color
+              for additional emphasis.
+            - ``"secondary"`` (default): The button's background coordinates
+              with the app's background color for normal emphasis.
+            - ``"tertiary"``: The button is plain text without a border or
+              background for subtly.
+
+        icon : str or None
+            An optional emoji or icon to display next to the button label. 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.
+        disabled : bool
+            Whether to disable the button. If this is ``False`` (default), the
+            user can interact with the button. If this is ``True``, the button
+            is grayed-out and can't be clicked.
+
+            If the first ``st.form_submit_button`` in the form is disabled,
+            the form will override submission behavior with
+            ``enter_to_submit=False``.
+
+        use_container_width : bool
+            Whether to expand the button's width to fill its parent container.
+            If ``use_container_width`` is ``False`` (default), Streamlit sizes
+            the button to fit its contents. If ``use_container_width`` is
+            ``True``, the width of the button matches its parent container.
+
+            In both cases, if the contents of the button are wider than the
+            parent container, the contents will line wrap.
+
+        Returns
+        -------
+        bool
+            True if the button was clicked.
+        """
+        ctx = get_script_run_ctx()
+
+        # Checks whether the entered button type is one of the allowed options
+        if type not in ["primary", "secondary", "tertiary"]:
+            raise StreamlitAPIException(
+                'The type argument to st.form_submit_button must be "primary", "secondary", or "tertiary". \n'
+                f'The argument passed was "{type}".'
+            )
+
+        return self._form_submit_button(
+            label=label,
+            help=help,
+            on_click=on_click,
+            args=args,
+            kwargs=kwargs,
+            type=type,
+            icon=icon,
+            disabled=disabled,
+            use_container_width=use_container_width,
+            ctx=ctx,
+        )
+
+    def _form_submit_button(
+        self,
+        label: str = "Submit",
+        help: str | None = None,
+        on_click: WidgetCallback | None = None,
+        args: WidgetArgs | None = None,
+        kwargs: WidgetKwargs | None = None,
+        *,  # keyword-only arguments:
+        type: Literal["primary", "secondary", "tertiary"] = "secondary",
+        icon: str | None = None,
+        disabled: bool = False,
+        use_container_width: bool = False,
+        ctx: ScriptRunContext | None = None,
+    ) -> bool:
+        form_id = current_form_id(self.dg)
+        submit_button_key = f"FormSubmitter:{form_id}-{label}"
+        return self.dg._button(
+            label=label,
+            key=submit_button_key,
+            help=help,
+            is_form_submitter=True,
+            on_click=on_click,
+            args=args,
+            kwargs=kwargs,
+            type=type,
+            icon=icon,
+            disabled=disabled,
+            use_container_width=use_container_width,
+            ctx=ctx,
+        )
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        """Get our DeltaGenerator."""
+        return cast("DeltaGenerator", self)