streamlit 1.45.0__py3-none-any.whl → 1.46.0__py3-none-any.whl

streamlit/elements/doc_string.py

@@ -24,17 +24,19 @@ import types
 from typing import TYPE_CHECKING, Any, Final, cast
 
 import streamlit
+from streamlit.elements.lib.layout_utils import LayoutConfig, validate_width
 from streamlit.proto.DocString_pb2 import DocString as DocStringProto
 from streamlit.proto.DocString_pb2 import Member as MemberProto
 from streamlit.runtime.metrics_util import gather_metrics
 from streamlit.runtime.scriptrunner.script_runner import (
-    __file__ as SCRIPTRUNNER_FILENAME,
+    __file__ as SCRIPTRUNNER_FILENAME,  # noqa: N812
 )
 from streamlit.runtime.secrets import Secrets
 from streamlit.string_util import is_mem_address_str
 
 if TYPE_CHECKING:
     from streamlit.delta_generator import DeltaGenerator
+    from streamlit.elements.lib.layout_utils import WidthWithoutContent
 
 
 CONFUSING_STREAMLIT_SIG_PREFIXES: Final = ("(element, ",)
@@ -42,7 +44,9 @@ CONFUSING_STREAMLIT_SIG_PREFIXES: Final = ("(element, ",)
 
 class HelpMixin:
     @gather_metrics("help")
-    def help(self, obj: Any = streamlit) -> DeltaGenerator:
+    def help(
+        self, obj: Any = streamlit, *, width: WidthWithoutContent = "stretch"
+    ) -> DeltaGenerator:
         """Display help and other information for a given object.
 
         Depending on the type of object that is passed in, this displays the
@@ -54,6 +58,15 @@ class HelpMixin:
         obj : any
             The object whose information should be displayed. If left
             unspecified, this call will display help for Streamlit itself.
+        width : "stretch" or int
+            The width of the help element. This can be one of the following:
+
+            - ``"stretch"`` (default): The width of the element matches the
+              width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the element matches the width
+              of the parent container.
 
         Example
         -------
@@ -115,8 +128,14 @@ class HelpMixin:
             height: 700px
         """
         doc_string_proto = DocStringProto()
+
+        validate_width(width, allow_content=False)
+        layout_config = LayoutConfig(width=width)
         _marshall(doc_string_proto, obj)
-        return self.dg._enqueue("doc_string", doc_string_proto)
+
+        return self.dg._enqueue(
+            "doc_string", doc_string_proto, layout_config=layout_config
+        )
 
     @property
     def dg(self) -> DeltaGenerator:
@@ -147,38 +166,30 @@ def _marshall(doc_string_proto: DocStringProto, obj: Any) -> None:
     doc_string_proto.members.extend(_get_members(obj))
 
 
-def _get_name(obj):
+def _get_name(obj: object) -> str | None:
     # Try to get the fully-qualified name of the object.
-    # For example:
-    #   st.help(bar.Baz(123))
-    #
-    #   The name is bar.Baz
+    # For example: st.help(bar.Baz(123))
+    #    The name is bar.Baz
     name = getattr(obj, "__qualname__", None)
     if name:
-        return name
+        return cast("str", name)
 
     # Try to get the name of the object.
-    # For example:
-    #   st.help(bar.Baz(123))
-    #
+    # For example: st.help(bar.Baz(123))
     #   The name is Baz
-    return getattr(obj, "__name__", None)
+    return cast("str | None", getattr(obj, "__name__", None))
 
 
-def _get_module(obj):
+def _get_module(obj: object) -> str | None:
     return getattr(obj, "__module__", None)
 
 
-def _get_signature(obj):
+def _get_signature(obj: object) -> str | None:
     if not inspect.isclass(obj) and not callable(obj):
         return None
 
     sig = ""
 
-    # TODO: Can we replace below with this?
-    # with contextlib.suppress(ValueError):
-    #     sig = str(inspect.signature(obj))
-
     try:
         sig = str(inspect.signature(obj))
     except ValueError:
@@ -202,7 +213,7 @@ def _get_signature(obj):
     return sig
 
 
-def _get_docstring(obj):
+def _get_docstring(obj: object) -> str | None:
     doc_string = inspect.getdoc(obj)
 
     # Sometimes an object has no docstring, but the object's type does.
@@ -226,7 +237,7 @@ def _get_docstring(obj):
     return None
 
 
-def _get_variable_name():
+def _get_variable_name() -> str | None:
     """Try to get the name of the variable in the current line, as set by the user.
 
     For example:
@@ -243,25 +254,25 @@ def _get_variable_name():
     return _get_variable_name_from_code_str(code)
 
 
-def _get_variable_name_from_code_str(code):
+def _get_variable_name_from_code_str(code: str) -> str | None:
     tree = ast.parse(code)
 
     # Example:
     #
-    # tree = Module(
-    #   body=[
-    #     Expr(
-    #       value=Call(
-    #         args=[
-    #           Name(id='the variable name')
-    #         ],
-    #         keywords=[
-    #           ???
-    #         ],
-    #       )
-    #     )
-    #   ]
-    # )
+    # > tree = Module(
+    # >   body=[
+    # >     Expr(
+    # >       value=Call(
+    # >         args=[
+    # >           Name(id='the variable name')
+    # >         ],
+    # >         keywords=[
+    # >           ???
+    # >         ],
+    # >       )
+    # >     )
+    # >   ]
+    # > )
 
     # Check if this is an magic call (i.e. it's not st.help or st.write).
     # If that's the case, just clean it up and return it.
@@ -270,9 +281,7 @@ def _get_variable_name_from_code_str(code):
     ):
         # A common pattern is to add "," at the end of a magic command to make it print.
         # This removes that final ",", so it looks nicer.
-        code = code.removesuffix(",")
-
-        return code
+        return code.removesuffix(",")
 
     arg_node = _get_stcommand_arg(tree)
 
@@ -282,7 +291,7 @@ def _get_variable_name_from_code_str(code):
 
     # If walrus, get name.
     # E.g. st.help(foo := 123) should give you "foo".
-    elif type(arg_node) is ast.NamedExpr:
+    if type(arg_node) is ast.NamedExpr:
         # This next "if" will always be true, but need to add this for the type-checking test to
         # pass.
         if type(arg_node.target) is ast.Name:
@@ -316,7 +325,7 @@ def _get_variable_name_from_code_str(code):
 _NEWLINES = re.compile(r"[\n\r]+")
 
 
-def _get_current_line_of_code_as_str():
+def _get_current_line_of_code_as_str() -> str | None:
     scriptrunner_frame = _get_scriptrunner_frame()
 
     if scriptrunner_frame is None:
@@ -339,7 +348,7 @@ def _get_current_line_of_code_as_str():
     return re.sub(_NEWLINES, "", code_as_string.strip())
 
 
-def _get_scriptrunner_frame():
+def _get_scriptrunner_frame() -> inspect.FrameInfo | None:
     prev_frame = None
     scriptrunner_frame = None
 
@@ -362,7 +371,7 @@ def _get_scriptrunner_frame():
     return scriptrunner_frame
 
 
-def _is_stcommand(tree, command_name):
+def _is_stcommand(tree: Any, command_name: str) -> bool:
     """Checks whether the AST in tree is a call for command_name."""
     root_node = tree.body[0].value
 
@@ -378,25 +387,25 @@ def _is_stcommand(tree, command_name):
     )
 
 
-def _get_stcommand_arg(tree):
+def _get_stcommand_arg(tree: ast.Module) -> ast.expr | None:
     """Gets the argument node for the st command in tree (AST)."""
 
-    root_node = tree.body[0].value
+    root_node = tree.body[0].value  # type: ignore
 
     if root_node.args:
-        return root_node.args[0]
+        return cast("ast.expr", root_node.args[0])
 
     return None
 
 
-def _get_type_as_str(obj):
+def _get_type_as_str(obj: object) -> str:
     if inspect.isclass(obj):
         return "class"
 
     return str(type(obj).__name__)
 
 
-def _get_first_line(text):
+def _get_first_line(text: str) -> str:
     if not text:
         return ""
 
@@ -404,7 +413,7 @@ def _get_first_line(text):
     return left
 
 
-def _get_weight(value):
+def _get_weight(value: Any) -> int:
     if inspect.ismodule(value):
         return 3
     if inspect.isclass(value):
@@ -414,7 +423,7 @@ def _get_weight(value):
     return 0
 
 
-def _get_value(obj, var_name):
+def _get_value(obj: object, var_name: str | None) -> str | None:
     obj_value = _get_human_readable_value(obj)
 
     if obj_value is not None:
@@ -436,10 +445,7 @@ def _get_value(obj, var_name):
     sig = _get_signature(name_obj) or ""
 
     if name:
-        if module:
-            obj_value = f"{module}.{name}{sig}"
-        else:
-            obj_value = f"{name}{sig}"
+        obj_value = f"{module}.{name}{sig}" if module else f"{name}{sig}"
 
     if obj_value == var_name:
         # No need to repeat the same info.
@@ -449,7 +455,7 @@ def _get_value(obj, var_name):
     return obj_value
 
 
-def _get_human_readable_value(value):
+def _get_human_readable_value(value: Any) -> str | None:
     if isinstance(value, Secrets):
         # Don't want to read secrets.toml because that will show a warning if there's no
         # secrets.toml file.
@@ -472,12 +478,12 @@ def _get_human_readable_value(value):
     return _shorten(value_str)
 
 
-def _shorten(s, length=300):
+def _shorten(s: str, length: int = 300) -> str:
     s = s.strip()
     return s[:length] + "..." if len(s) > length else s
 
 
-def _is_computed_property(obj, attr_name):
+def _is_computed_property(obj: object, attr_name: str) -> bool:
     obj_class = getattr(obj, "__class__", None)
 
     if not obj_class:
@@ -498,7 +504,7 @@ def _is_computed_property(obj, attr_name):
     return False
 
 
-def _get_members(obj):
+def _get_members(obj: object) -> list[MemberProto]:
     members_for_sorting = []
 
     for attr_name in dir(obj):

streamlit/elements/exception.py

@@ -38,7 +38,11 @@ _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)."
+_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:
@@ -56,13 +60,15 @@ class ExceptionMixin:
         ----------
         exception : Exception
             The exception to display.
-        width : int or "stretch"
-            The desired width of the exception expressed in pixels. If this is
-            ``"stretch"`` (default), Streamlit sets the width of the exception
-            to match the width of the parent container. Otherwise, this must be
-            an integer. If the specified width is greater than the width of the
-            parent container, Streamlit sets the width of the exception to
-            match the width of the parent container.
+        width : "stretch" or int
+            The width of the exception element. This can be one of the following:
+
+            - ``"stretch"`` (default): The width of the element matches the
+              width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the element matches the width
+              of the parent container.
 
         Example
         -------
@@ -228,24 +234,15 @@ def _format_syntax_error_message(exception: SyntaxError) -> str:
 
     """
     if exception.text:
-        if exception.offset is not None:
-            caret_indent = " " * max(exception.offset - 1, 0)
-        else:
-            caret_indent = ""
+        caret_indent = (
+            " " * max(exception.offset - 1, 0) if exception.offset is not None else ""
+        )
 
         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,
-            }
+            f'File "{exception.filename}", line {exception.lineno}\n'
+            f"  {exception.text.rstrip()}\n"
+            f"  {caret_indent}^\n"
+            f"{type(exception).__name__}: {exception.msg}"
         )
     # If a few edge cases, SyntaxErrors don't have all these nice fields. So we
     # have a fall back here.
@@ -358,9 +355,8 @@ def _split_list(
     saw_split_point = False
 
     for item in orig_list:
-        if not saw_split_point:
-            if split_point(item):
-                saw_split_point = True
+        if not saw_split_point and split_point(item):
+            saw_split_point = True
 
         if saw_split_point:
             after.append(item)

streamlit/elements/form.py

@@ -17,6 +17,13 @@ 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.layout_utils import (
+    Width,
+    get_height_config,
+    get_width_config,
+    validate_height,
+    validate_width,
+)
 from streamlit.elements.lib.policies import (
     check_cache_replay_rules,
     check_session_state_rules,
@@ -67,6 +74,8 @@ class FormMixin:
         *,
         enter_to_submit: bool = True,
         border: bool = True,
+        width: Width = "stretch",
+        height: int | Literal["content"] = "content",
     ) -> DeltaGenerator:
         """Create a form that batches elements together with a "Submit" button.
 
@@ -122,6 +131,34 @@ class FormMixin:
                 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).
 
+        width : "stretch", "content", or int
+            The width of the form container. This can be one of the following:
+
+            - ``"stretch"`` (default): The width of the container matches the
+              width of the parent container.
+            - ``"content"``: The width of the container matches the width of its
+              content, but doesn't exceed the width of the parent container.
+            - An integer specifying the width in pixels: The container has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the container matches the width
+              of the parent container.
+
+        height : "content" or int
+            The height of the form container. This can be one of the following:
+
+            - ``"content"`` (default): The height of the container matches the
+              height of its content.
+            - An integer specifying the height in pixels: The container has a
+              fixed height. If the content is larger than the specified
+              height, scrolling is enabled.
+
+            .. note::
+                Use scrolling containers sparingly. If you use scrolling
+                containers, avoid heights that exceed 500 pixels. Otherwise,
+                the scroll surface of the container might cover the majority of
+                the screen on mobile devices, which makes it hard to scroll the
+                rest of the app.
+
         Examples
         --------
         Inserting elements using ``with`` notation:
@@ -181,6 +218,10 @@ class FormMixin:
         block_proto.form.clear_on_submit = clear_on_submit
         block_proto.form.enter_to_submit = enter_to_submit
         block_proto.form.border = border
+        validate_width(width, allow_content=True)
+        block_proto.width_config.CopyFrom(get_width_config(width))
+        validate_height(height, allow_content=True)
+        block_proto.height_config.CopyFrom(get_height_config(height))
         block_dg = self.dg._block(block_proto)
 
         # Attach the form's button info to the newly-created block's

streamlit/elements/graphviz_chart.py

@@ -141,7 +141,7 @@ def marshall(
         engine = "dot"
     else:
         raise StreamlitAPIException(
-            "Unhandled type for graphviz chart: %s" % type(figure_or_dot)
+            f"Unhandled type for graphviz chart: {type(figure_or_dot)}"
         )
 
     proto.spec = dot

streamlit/elements/heading.py

@@ -19,6 +19,7 @@ from typing import TYPE_CHECKING, Literal, Union, cast
 
 from typing_extensions import TypeAlias
 
+from streamlit.elements.lib.layout_utils import LayoutConfig, validate_width
 from streamlit.errors import StreamlitAPIException
 from streamlit.proto.Heading_pb2 import Heading as HeadingProto
 from streamlit.runtime.metrics_util import gather_metrics
@@ -26,6 +27,7 @@ from streamlit.string_util import clean_text
 
 if TYPE_CHECKING:
     from streamlit.delta_generator import DeltaGenerator
+    from streamlit.elements.lib.layout_utils import Width
     from streamlit.type_util import SupportsStr
 
 
@@ -48,6 +50,7 @@ class HeadingMixin:
         *,  # keyword-only arguments:
         help: str | None = None,
         divider: Divider = False,
+        width: Width = "stretch",
     ) -> DeltaGenerator:
         """Display text in header formatting.
 
@@ -76,7 +79,7 @@ class HeadingMixin:
             including the Markdown directives described in the ``body``
             parameter of ``st.markdown``.
 
-        divider : bool or “blue”, “green”, “orange”, “red”, “violet”, “gray”/"grey", or “rainbow”
+        divider : bool, “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
@@ -84,6 +87,18 @@ class HeadingMixin:
             the following: blue, green, orange, red, violet, gray/grey, or
             rainbow.
 
+        width : "stretch", "content", or int
+            The width of the header element. This can be one of the following:
+
+            - ``"stretch"`` (default): The width of the element matches the
+              width of the parent container.
+            - ``"content"``: The width of the element matches the width of its
+              content, but doesn't exceed the width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the element matches the width
+              of the parent container.
+
         Examples
         --------
         >>> import streamlit as st
@@ -101,6 +116,9 @@ class HeadingMixin:
            height: 600px
 
         """
+        validate_width(width, allow_content=True)
+        layout_config = LayoutConfig(width=width)
+
         return self.dg._enqueue(
             "heading",
             HeadingMixin._create_heading_proto(
@@ -110,6 +128,7 @@ class HeadingMixin:
                 help=help,
                 divider=divider,
             ),
+            layout_config=layout_config,
         )
 
     @gather_metrics("subheader")
@@ -120,6 +139,7 @@ class HeadingMixin:
         *,  # keyword-only arguments:
         help: str | None = None,
         divider: Divider = False,
+        width: Width = "stretch",
     ) -> DeltaGenerator:
         """Display text in subheader formatting.
 
@@ -156,6 +176,18 @@ class HeadingMixin:
             the following: blue, green, orange, red, violet, gray/grey, or
             rainbow.
 
+        width : "stretch", "content", or int
+            The width of the subheader element. This can be one of the following:
+
+            - ``"stretch"`` (default): The width of the element matches the
+              width of the parent container.
+            - ``"content"``: The width of the element matches the width of its
+              content, but doesn't exceed the width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the element matches the width
+              of the parent container.
+
         Examples
         --------
         >>> import streamlit as st
@@ -173,6 +205,9 @@ class HeadingMixin:
            height: 500px
 
         """
+        validate_width(width, allow_content=True)
+        layout_config = LayoutConfig(width=width)
+
         return self.dg._enqueue(
             "heading",
             HeadingMixin._create_heading_proto(
@@ -182,6 +217,7 @@ class HeadingMixin:
                 help=help,
                 divider=divider,
             ),
+            layout_config=layout_config,
         )
 
     @gather_metrics("title")
@@ -191,6 +227,7 @@ class HeadingMixin:
         anchor: Anchor = None,
         *,  # keyword-only arguments:
         help: str | None = None,
+        width: Width = "stretch",
     ) -> DeltaGenerator:
         """Display text in title formatting.
 
@@ -222,6 +259,18 @@ class HeadingMixin:
             including the Markdown directives described in the ``body``
             parameter of ``st.markdown``.
 
+        width : "stretch", "content", or int
+            The width of the title element. This can be one of the following:
+
+            - ``"stretch"`` (default): The width of the element matches the
+              width of the parent container.
+            - ``"content"``: The width of the element matches the width of its
+              content, but doesn't exceed the width of the parent container.
+            - An integer specifying the width in pixels: The element has a
+              fixed width. If the specified width is greater than the width of
+              the parent container, the width of the element matches the width
+              of the parent container.
+
         Examples
         --------
         >>> import streamlit as st
@@ -234,11 +283,15 @@ class HeadingMixin:
            height: 220px
 
         """
+        validate_width(width, allow_content=True)
+        layout_config = LayoutConfig(width=width)
+
         return self.dg._enqueue(
             "heading",
             HeadingMixin._create_heading_proto(
                 tag=HeadingProtoTag.TITLE_TAG, body=body, anchor=anchor, help=help
             ),
+            layout_config=layout_config,
         )
 
     @property
@@ -262,10 +315,9 @@ class HeadingMixin:
         ]
         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)}."
-            )
+        raise StreamlitAPIException(
+            f"Divider parameter has invalid value: `{divider}`. Please choose from: {', '.join(valid_colors)}."
+        )
 
     @staticmethod
     def _create_heading_proto(
@@ -287,14 +339,13 @@ class HeadingMixin:
                 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
+                    f"Anchor parameter has invalid value: {anchor}. "
+                    "Supported values: None, any string or False"
                 )
             else:
                 raise StreamlitAPIException(
-                    "Anchor parameter has invalid type: %s. "
+                    f"Anchor parameter has invalid type: {type(anchor).__name__}. "
                     "Supported values: None, any string or False"
-                    % type(anchor).__name__
                 )
 
         if help:

streamlit/elements/html.py

@@ -113,10 +113,9 @@ class HtmlMixin:
             # If true, there are only style tags - send html to the event container
             html_proto.body = html_content
             return self._event_dg._enqueue("html", html_proto)
-        else:
-            # Otherwise, send the html to the main container as normal
-            html_proto.body = html_content
-            return self.dg._enqueue("html", html_proto)
+        # Otherwise, send the html to the main container as normal
+        html_proto.body = html_content
+        return self.dg._enqueue("html", html_proto)
 
     @property
     def dg(self) -> DeltaGenerator: