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

streamlit/elements/graphviz_chart.py

@@ -0,0 +1,150 @@
+# 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 support for GraphViz charts."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Union, cast
+
+from typing_extensions import TypeAlias
+
+from streamlit import type_util
+from streamlit.errors import StreamlitAPIException
+from streamlit.proto.GraphVizChart_pb2 import GraphVizChart as GraphVizChartProto
+from streamlit.runtime.metrics_util import gather_metrics
+from streamlit.util import calc_md5
+
+if TYPE_CHECKING:
+    import graphviz
+
+    from streamlit.delta_generator import DeltaGenerator
+
+FigureOrDot: TypeAlias = Union[
+    "graphviz.Graph", "graphviz.Digraph", "graphviz.Source", str
+]
+
+
+class GraphvizMixin:
+    @gather_metrics("graphviz_chart")
+    def graphviz_chart(
+        self,
+        figure_or_dot: FigureOrDot,
+        use_container_width: bool = False,
+    ) -> DeltaGenerator:
+        """Display a graph using the dagre-d3 library.
+
+        Parameters
+        ----------
+        figure_or_dot : graphviz.dot.Graph, graphviz.dot.Digraph, graphviz.sources.Source, str
+            The Graphlib graph object or dot string to display
+
+        use_container_width : bool
+            Whether to override the figure's native width with the width of
+            the parent container. If ``use_container_width`` is ``False``
+            (default), Streamlit sets the width of the chart to fit its contents
+            according to the plotting library, up to the width of the parent
+            container. If ``use_container_width`` is ``True``, Streamlit sets
+            the width of the figure to match the width of the parent container.
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>> import graphviz
+        >>>
+        >>> # Create a graphlib graph object
+        >>> graph = graphviz.Digraph()
+        >>> graph.edge("run", "intr")
+        >>> graph.edge("intr", "runbl")
+        >>> graph.edge("runbl", "run")
+        >>> graph.edge("run", "kernel")
+        >>> graph.edge("kernel", "zombie")
+        >>> graph.edge("kernel", "sleep")
+        >>> graph.edge("kernel", "runmem")
+        >>> graph.edge("sleep", "swap")
+        >>> graph.edge("swap", "runswap")
+        >>> graph.edge("runswap", "new")
+        >>> graph.edge("runswap", "runmem")
+        >>> graph.edge("new", "runmem")
+        >>> graph.edge("sleep", "runmem")
+        >>>
+        >>> st.graphviz_chart(graph)
+
+        Or you can render the chart from the graph using GraphViz's Dot
+        language:
+
+        >>> st.graphviz_chart('''
+            digraph {
+                run -> intr
+                intr -> runbl
+                runbl -> run
+                run -> kernel
+                kernel -> zombie
+                kernel -> sleep
+                kernel -> runmem
+                sleep -> swap
+                swap -> runswap
+                runswap -> new
+                runswap -> runmem
+                new -> runmem
+                sleep -> runmem
+            }
+        ''')
+
+        .. output::
+           https://doc-graphviz-chart.streamlit.app/
+           height: 600px
+
+        """
+        # Generate element ID from delta path
+        delta_path = self.dg._get_delta_path_str()
+        element_id = calc_md5(delta_path.encode())
+
+        graphviz_chart_proto = GraphVizChartProto()
+
+        marshall(graphviz_chart_proto, figure_or_dot, use_container_width, element_id)
+        return self.dg._enqueue("graphviz_chart", graphviz_chart_proto)
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        """Get our DeltaGenerator."""
+        return cast("DeltaGenerator", self)
+
+
+def marshall(
+    proto: GraphVizChartProto,
+    figure_or_dot: FigureOrDot,
+    use_container_width: bool,
+    element_id: str,
+) -> None:
+    """Construct a GraphViz chart object.
+
+    See DeltaGenerator.graphviz_chart for docs.
+    """
+
+    if type_util.is_graphviz_chart(figure_or_dot):
+        dot = figure_or_dot.source
+        engine = figure_or_dot.engine
+    elif isinstance(figure_or_dot, str):
+        dot = figure_or_dot
+        engine = "dot"
+    else:
+        raise StreamlitAPIException(
+            "Unhandled type for graphviz chart: %s" % type(figure_or_dot)
+        )
+
+    proto.spec = dot
+    proto.engine = engine
+    proto.use_container_width = use_container_width
+    proto.element_id = element_id

streamlit/elements/heading.py

@@ -0,0 +1,302 @@
+# 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 enum import Enum
+from typing import TYPE_CHECKING, Literal, Union, cast
+
+from typing_extensions import TypeAlias
+
+from streamlit.errors import StreamlitAPIException
+from streamlit.proto.Heading_pb2 import Heading as HeadingProto
+from streamlit.runtime.metrics_util import gather_metrics
+from streamlit.string_util import clean_text
+
+if TYPE_CHECKING:
+    from streamlit.delta_generator import DeltaGenerator
+    from streamlit.type_util import SupportsStr
+
+
+class HeadingProtoTag(Enum):
+    TITLE_TAG = "h1"
+    HEADER_TAG = "h2"
+    SUBHEADER_TAG = "h3"
+
+
+Anchor: TypeAlias = Union[str, Literal[False], None]
+Divider: TypeAlias = Union[bool, str, None]
+
+
+class HeadingMixin:
+    @gather_metrics("header")
+    def header(
+        self,
+        body: SupportsStr,
+        anchor: Anchor = None,
+        *,  # keyword-only arguments:
+        help: str | None = None,
+        divider: Divider = False,
+    ) -> DeltaGenerator:
+        """Display text in header formatting.
+
+        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
+
+        anchor : str or False
+            The anchor name of the header that can be accessed with #anchor
+            in the URL. If omitted, it generates an anchor using the body.
+            If False, the anchor is not shown in the UI.
+
+        help : str or None
+            A tooltip that gets displayed next to the header. 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``.
+
+        divider : bool or “blue”, “green”, “orange”, “red”, “violet”, “gray”/"grey", or “rainbow”
+            Shows a colored divider below the header. If True, successive
+            headers will cycle through divider colors. That is, the first
+            header will have a blue line, the second header will have a
+            green line, and so on. If a string, the color can be set to one of
+            the following: blue, green, orange, red, violet, gray/grey, or
+            rainbow.
+
+        Examples
+        --------
+        >>> import streamlit as st
+        >>>
+        >>> st.header("_Streamlit_ is :blue[cool] :sunglasses:")
+        >>> st.header("This is a header with a divider", divider="gray")
+        >>> st.header("These headers have rotating dividers", divider=True)
+        >>> st.header("One", divider=True)
+        >>> st.header("Two", divider=True)
+        >>> st.header("Three", divider=True)
+        >>> st.header("Four", divider=True)
+
+        .. output::
+           https://doc-header.streamlit.app/
+           height: 600px
+
+        """
+        return self.dg._enqueue(
+            "heading",
+            HeadingMixin._create_heading_proto(
+                tag=HeadingProtoTag.HEADER_TAG,
+                body=body,
+                anchor=anchor,
+                help=help,
+                divider=divider,
+            ),
+        )
+
+    @gather_metrics("subheader")
+    def subheader(
+        self,
+        body: SupportsStr,
+        anchor: Anchor = None,
+        *,  # keyword-only arguments:
+        help: str | None = None,
+        divider: Divider = False,
+    ) -> DeltaGenerator:
+        """Display text in subheader formatting.
+
+        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
+
+        anchor : str or False
+            The anchor name of the header that can be accessed with #anchor
+            in the URL. If omitted, it generates an anchor using the body.
+            If False, the anchor is not shown in the UI.
+
+        help : str or None
+            A tooltip that gets displayed next to the subheader. 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``.
+
+        divider : bool or “blue”, “green”, “orange”, “red”, “violet”, “gray”/"grey", or “rainbow”
+            Shows a colored divider below the header. If True, successive
+            headers will cycle through divider colors. That is, the first
+            header will have a blue line, the second header will have a
+            green line, and so on. If a string, the color can be set to one of
+            the following: blue, green, orange, red, violet, gray/grey, or
+            rainbow.
+
+        Examples
+        --------
+        >>> import streamlit as st
+        >>>
+        >>> st.subheader("_Streamlit_ is :blue[cool] :sunglasses:")
+        >>> st.subheader("This is a subheader with a divider", divider="gray")
+        >>> st.subheader("These subheaders have rotating dividers", divider=True)
+        >>> st.subheader("One", divider=True)
+        >>> st.subheader("Two", divider=True)
+        >>> st.subheader("Three", divider=True)
+        >>> st.subheader("Four", divider=True)
+
+        .. output::
+           https://doc-subheader.streamlit.app/
+           height: 500px
+
+        """
+        return self.dg._enqueue(
+            "heading",
+            HeadingMixin._create_heading_proto(
+                tag=HeadingProtoTag.SUBHEADER_TAG,
+                body=body,
+                anchor=anchor,
+                help=help,
+                divider=divider,
+            ),
+        )
+
+    @gather_metrics("title")
+    def title(
+        self,
+        body: SupportsStr,
+        anchor: Anchor = None,
+        *,  # keyword-only arguments:
+        help: str | None = None,
+    ) -> DeltaGenerator:
+        """Display text in title formatting.
+
+        Each document should have a single `st.title()`, although this is not
+        enforced.
+
+        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
+
+        anchor : str or False
+            The anchor name of the header that can be accessed with #anchor
+            in the URL. If omitted, it generates an anchor using the body.
+            If False, the anchor is not shown in the UI.
+
+        help : str or None
+            A tooltip that gets displayed next to the title. 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``.
+
+        Examples
+        --------
+        >>> import streamlit as st
+        >>>
+        >>> st.title("This is a title")
+        >>> st.title("_Streamlit_ is :blue[cool] :sunglasses:")
+
+        .. output::
+           https://doc-title.streamlit.app/
+           height: 220px
+
+        """
+        return self.dg._enqueue(
+            "heading",
+            HeadingMixin._create_heading_proto(
+                tag=HeadingProtoTag.TITLE_TAG, body=body, anchor=anchor, help=help
+            ),
+        )
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        """Get our DeltaGenerator."""
+        return cast("DeltaGenerator", self)
+
+    @staticmethod
+    def _handle_divider_color(divider: Divider) -> str:
+        if divider is True:
+            return "auto"
+        valid_colors = [
+            "blue",
+            "green",
+            "orange",
+            "red",
+            "violet",
+            "gray",
+            "grey",
+            "rainbow",
+        ]
+        if divider in valid_colors:
+            return cast(str, divider)
+        else:
+            raise StreamlitAPIException(
+                f"Divider parameter has invalid value: `{divider}`. Please choose from: {', '.join(valid_colors)}."
+            )
+
+    @staticmethod
+    def _create_heading_proto(
+        tag: HeadingProtoTag,
+        body: SupportsStr,
+        anchor: Anchor = None,
+        help: str | None = None,
+        divider: Divider = False,
+    ) -> HeadingProto:
+        proto = HeadingProto()
+        proto.tag = tag.value
+        proto.body = clean_text(body)
+        if divider:
+            proto.divider = HeadingMixin._handle_divider_color(divider)
+        if anchor is not None:
+            if anchor is False:
+                proto.hide_anchor = True
+            elif isinstance(anchor, str):
+                proto.anchor = anchor
+            elif anchor is True:  # type: ignore
+                raise StreamlitAPIException(
+                    "Anchor parameter has invalid value: %s. "
+                    "Supported values: None, any string or False" % anchor
+                )
+            else:
+                raise StreamlitAPIException(
+                    "Anchor parameter has invalid type: %s. "
+                    "Supported values: None, any string or False"
+                    % type(anchor).__name__
+                )
+
+        if help:
+            proto.help = help
+        return proto

streamlit/elements/html.py

@@ -0,0 +1,105 @@
+# 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
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+
+from streamlit.proto.Html_pb2 import Html as HtmlProto
+from streamlit.runtime.metrics_util import gather_metrics
+from streamlit.string_util import clean_text
+from streamlit.type_util import SupportsReprHtml, SupportsStr, has_callable_attr
+
+if TYPE_CHECKING:
+    from streamlit.delta_generator import DeltaGenerator
+
+
+class HtmlMixin:
+    @gather_metrics("html")
+    def html(
+        self,
+        body: str | Path | SupportsStr | SupportsReprHtml,
+    ) -> DeltaGenerator:
+        """Insert HTML into your app.
+
+        Adding custom HTML to your app impacts safety, styling, and
+        maintainability. We sanitize HTML with `DOMPurify
+        <https://github.com/cure53/DOMPurify>`_, but inserting HTML remains a
+        developer risk. Passing untrusted code to ``st.html`` or dynamically
+        loading external code can increase the risk of vulnerabilities in your
+        app.
+
+        ``st.html`` content is **not** iframed. Executing JavaScript is not
+        supported at this time.
+
+        Parameters
+        ----------
+        body : any
+            The HTML code to insert. This can be one of the following:
+
+            - A string of HTML code.
+            - A path to a local file with HTML code. The path can be a ``str``
+              or ``Path`` object. Paths can be absolute or relative to the
+              working directory (where you execute ``streamlit run``).
+            - Any object. If ``body`` is not a string or path, Streamlit will
+              convert the object to a string. ``body._repr_html_()`` takes
+              precedence over ``str(body)`` when available.
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>>
+        >>> st.html(
+        ...     "<p><span style='text-decoration: line-through double red;'>Oops</span>!</p>"
+        ... )
+
+        .. output::
+           https://doc-html.streamlit.app/
+           height: 300px
+
+        """
+        html_proto = HtmlProto()
+
+        # If body supports _repr_html_, use that.
+        if has_callable_attr(body, "_repr_html_"):
+            html_proto.body = cast(SupportsReprHtml, body)._repr_html_()
+
+        # Check if the body is a file path. May include filesystem lookup.
+        elif isinstance(body, Path) or _is_file(body):
+            with open(cast(str, body), encoding="utf-8") as f:
+                html_proto.body = f.read()
+
+        # OK, let's just try converting to string and hope for the best.
+        else:
+            html_proto.body = clean_text(cast(SupportsStr, body))
+
+        return self.dg._enqueue("html", html_proto)
+
+    @property
+    def dg(self) -> DeltaGenerator:
+        """Get our DeltaGenerator."""
+        return cast("DeltaGenerator", self)
+
+
+def _is_file(obj: Any) -> bool:
+    """Checks if obj is a file, and doesn't throw if not.
+
+    The "not throwing" part is important!
+    """
+    try:
+        return os.path.isfile(obj)
+    except TypeError:
+        return False