streamlit-nightly 1.52.3.dev20260113__py3-none-any.whl → 1.53.1.dev20260114__py3-none-any.whl

streamlit/elements/metric.py

@@ -108,11 +108,6 @@ class MetricMixin:
     ) -> DeltaGenerator:
         r"""Display a metric in big bold font, with an optional indicator of how the metric changed.
 
-        Tip: If you want to display a large number, it may be a good idea to
-        shorten it using packages like `millify <https://github.com/azaitsev/millify>`_
-        or `numerize <https://github.com/davidsa03/numerize>`_. E.g. ``1234`` can be
-        displayed as ``1.2k`` using ``st.metric("Short number", millify(1234))``.
-
         Parameters
         ----------
         label : str
@@ -135,35 +130,38 @@ class MetricMixin:
         value : int, float, decimal.Decimal, str, or None
             Value of the metric. ``None`` is rendered as a long dash.
 
-            The value can optionally contain GitHub-flavored Markdown,
-            including the Markdown directives described in the ``body``
-            parameter of ``st.markdown``.
+            The value can optionally contain GitHub-flavored Markdown, subject
+            to the same limitations described in the ``label`` parameter.
 
         delta : int, float, decimal.Decimal, str, or None
-            Indicator of how the metric changed, rendered with an arrow below
-            the metric. If delta is negative (int/float) or starts with a minus
-            sign (str), the arrow points down and the text is red; else the
-            arrow points up and the text is green. If None (default), no delta
-            indicator is shown.
+            Amount or indicator of change in the metric. An arrow is shown next
+            to the delta, oriented according to its sign:
 
-            The delta can optionally contain GitHub-flavored Markdown
-            including the Markdown directives described in the ``body``
-            parameter of ``st.markdown``.
+            - If the delta is ``None`` or an empty string, no arrow is shown.
+            - If the delta is a negative number or starts with a minus sign,
+              the arrow points down and the delta is red.
+            - Otherwise, the arrow points up and the delta is green.
+
+            You can modify the display, color, and orientation of the arrow
+            using the ``delta_color`` and ``delta_arrow`` parameters.
+
+            The delta can optionally contain GitHub-flavored Markdown, subject
+            to the same limitations described in the ``label`` parameter.
 
         delta_color : str
-            The color of the delta indicator. This can be one of the following:
-
-            - ``"normal"`` (default): The delta indicator is green when
-                positive and red when negative.
-            - ``"inverse"``: The delta indicator is red when positive and
-                green when negative. This is useful when a negative change is
-                considered good, e.g. if cost decreased.
-            - ``"off"``: The delta indicator is shown in gray regardless of
-                its value.
-            - A named color from the basic palette: ``"red"``, ``"orange"``,
-                ``"yellow"``, ``"green"``, ``"blue"``, ``"violet"``,
-                ``"gray"``/``"grey"``, or ``"primary"``. The delta indicator
-                and chart uses that color regardless of its value.
+            The color of the delta and chart. This can be one of the following:
+
+            - ``"normal"`` (default): The color is red when the delta is
+              negative and green otherwise.
+            - ``"inverse"``: The color is green when the delta is negative and
+              red otherwise. This is useful when a negative change is
+              considered good, like a decrease in cost.
+            - ``"off"``: The color is gray regardless of the delta.
+            - A named color from the basic palette: The chart and delta are the
+              specified color regardless of their value. This can be one of the
+              following: ``"red"``, ``"orange"``, ``"yellow"``, ``"green"``,
+              ``"blue"``, ``"violet"``, ``"gray"``/``"grey"``, or
+              ``"primary"``.
 
         help : str or None
             A tooltip that gets displayed next to the metric label. Streamlit
@@ -189,26 +187,26 @@ class MetricMixin:
             The height of the metric element. This can be one of the following:
 
             - ``"content"`` (default): The height of the element matches the
-                height of its content.
+              height of its content.
             - ``"stretch"``: The height of the element matches the height of
-                its content or the height of the parent container, whichever is
-                larger. If the element is not in a parent container, the height
-                of the element matches the height of its content.
+              its content or the height of the parent container, whichever is
+              larger. If the element is not in a parent container, the height
+              of the element matches the height of its content.
             - An integer specifying the height in pixels: The element has a
-                fixed height. If the content is larger than the specified
-                height, scrolling is enabled.
+              fixed height. If the content is larger than the specified
+              height, scrolling is enabled.
 
         width : "stretch", "content", or int
             The width of the metric element. This can be one of the following:
 
             - ``"stretch"`` (default): The width of the element matches the
-                width of the parent container.
+              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.
+              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.
+              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.
 
         chart_data : Iterable or None
             A sequence of numeric values to display as a sparkline chart. If
@@ -218,6 +216,9 @@ class MetricMixin:
             be used. Each value will be cast to ``float`` internally by
             default.
 
+            The chart uses the color of the delta indicator, which can be
+            modified using the ``delta_color`` parameter.
+
         chart_type : "line", "bar", or "area"
             The type of sparkline chart to display. This can be one of the
             following:
@@ -231,18 +232,18 @@ class MetricMixin:
             one of the following strings:
 
             - ``"auto"`` (default): The arrow direction follows the sign of
-                ``delta``.
+              ``delta``.
             - ``"up"`` or ``"down"``: The arrow is forced to point in the
-                specified direction.
+              specified direction.
             - ``"off"``: No arrow is shown, but the delta value remains
-                visible.
+              visible.
 
         format : str or None
             A format string controlling how numbers are displayed for ``value``
             and ``delta``. The format is only applied if the value or delta is
-            numeric (int, float, or decimal.Decimal). If the value or delta is
-            a string with non-numeric characters, the format is ignored.
-            This can be one of the following values:
+            numeric. If the value or delta is a string with non-numeric
+            characters, the format is ignored. The format can be one of the
+            following values:
 
             - ``None`` (default): No formatting is applied.
             - ``"plain"``: Show the full number without any formatting (e.g. "1234.567").
@@ -257,8 +258,8 @@ class MetricMixin:
             - ``"scientific"``: Show the number in scientific notation (e.g. "1.235E3").
             - ``"engineering"``: Show the number in engineering notation (e.g. "1.235E3").
             - printf-style format string: Format the number with a printf
-            specifier, like ``"%d"`` to show a signed integer (e.g. "1234") or
-            ``"%.2f"`` to show a float with 2 decimal places.
+              specifier, like ``"%d"`` to show a signed integer (e.g. "1234") or
+              ``"%.2f"`` to show a float with 2 decimal places.
 
         Examples
         --------

streamlit/elements/widgets/button.py

@@ -223,8 +223,8 @@ class ButtonMixin:
             - ``"spinner"``: Displays a spinner as an icon.
 
         icon_position : "left" or "right"
-            The position of the icon relative to the button label. Defaults to
-            ``"left"``.
+            The position of the icon relative to the button label. This
+            defaults to ``"left"``.
 
         disabled : bool
             An optional boolean that disables the button if set to ``True``.
@@ -539,8 +539,8 @@ class ButtonMixin:
             - ``"spinner"``: Displays a spinner as an icon.
 
         icon_position : "left" or "right"
-            The position of the icon relative to the button label. Defaults to
-            ``"left"``.
+            The position of the icon relative to the button label. This
+            defaults to ``"left"``.
 
         disabled : bool
             An optional boolean that disables the download button if set to
@@ -847,8 +847,8 @@ class ButtonMixin:
             - ``"spinner"``: Displays a spinner as an icon.
 
         icon_position : "left" or "right"
-            The position of the icon relative to the button label. Defaults to
-            ``"left"``.
+            The position of the icon relative to the button label. This
+            defaults to ``"left"``.
 
         disabled : bool
             An optional boolean that disables the link button if set to
@@ -990,7 +990,7 @@ class ButtonMixin:
             .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown
 
         icon : str or None
-            An optional emoji or icon to display next to the button label. If
+            An optional emoji or icon to display next to the link label. If
             ``icon`` is ``None`` (default), the icon is inferred from the
             ``StreamlitPage`` object or no icon is displayed. If ``icon`` is a
             string, the following options are valid:
@@ -1010,8 +1010,8 @@ class ButtonMixin:
             - ``"spinner"``: Displays a spinner as an icon.
 
         icon_position : "left" or "right"
-            The position of the icon relative to the page link label. Defaults
-            to ``"left"``.
+            The position of the icon relative to the link label. This
+            defaults to ``"left"``.
 
         help : str or None
             A tooltip that gets displayed when the link is hovered over. If

streamlit/elements/widgets/chat.py

@@ -633,16 +633,12 @@ class ChatMixin:
             ``None`` (default), there will be no maximum.
 
         max_upload_size : int or None
-            The maximum allowed size of each uploaded file for this chat input,
-            in megabytes.
+            The maximum allowed size of each uploaded file in megabytes.
 
-            When set to a positive integer, this per-widget limit takes
-            precedence over the global ``server.maxUploadSize`` configuration
-            option.
-
-            When this is ``None`` (default), the chat input falls back to
-            ``server.maxUploadSize`` for its file size limit. For more
-            information on how to set config options, see |config.toml|_.
+            If this is ``None`` (default), the maximum file size is set by the
+            ``server.maxUploadSize`` configuration option in your
+            ``config.toml`` file. If this is an integer, it must be positive
+            and will override the ``server.maxUploadSize`` configuration option.
 
         accept_file : bool, "multiple", or "directory"
             Whether the chat input should accept files. This can be one of the

streamlit/elements/widgets/data_editor.py

@@ -792,10 +792,10 @@ class DataEditorMixin:
             first index column.
 
         num_rows : "fixed", "dynamic", "add", or "delete"
-            Specifies if the user can add and delete rows in the data editor.
+            Specifies if the user can add and/or delete rows in the data editor.
 
-            - ``"fixed"`` (default): The user cannot add or delete rows.
-            - ``"dynamic"``: The user can add and delete rows, but column
+            - ``"fixed"`` (default): The user can't add or delete rows.
+            - ``"dynamic"``: The user can add and delete rows, and column
               sorting is disabled.
             - ``"add"``: The user can only add rows (no deleting), and column
               sorting is disabled.

streamlit/elements/widgets/file_uploader.py

@@ -266,9 +266,12 @@ class FileUploaderMixin:
         width: WidthWithoutContent = "stretch",
     ) -> UploadedFile | list[UploadedFile] | None:
         r"""Display a file uploader widget.
+
         By default, uploaded files are limited to 200 MB each. You can
-        configure this using the ``server.maxUploadSize`` config option. For
-        more information on how to set config options, see |config.toml|_.
+        configure this globally using the ``server.maxUploadSize`` configuration
+        option. For more information on how to set configuration options, see
+        |config.toml|_. Additionally, you can set a per-widget limit using the
+        ``max_upload_size`` parameter.
 
         .. |config.toml| replace:: ``config.toml``
         .. _config.toml: https://docs.streamlit.io/develop/api-reference/configuration/config.toml
@@ -315,16 +318,12 @@ class FileUploaderMixin:
                 part of the app developer's responsibility.
 
         max_upload_size : int or None
-            The maximum allowed size of each uploaded file for this uploader,
-            in megabytes.
-
-            When set to a positive integer, this per-widget limit takes
-            precedence over the global ``server.maxUploadSize`` configuration
-            option.
+            The maximum allowed size of each uploaded file in megabytes.
 
-            When this is ``None`` (default), the uploader falls back to
-            ``server.maxUploadSize`` for its file size limit. For more
-            information on how to set config options, see |config.toml|_.
+            If this is ``None`` (default), the maximum file size is set by the
+            ``server.maxUploadSize`` configuration option in your
+            ``config.toml`` file. If this is an integer, it must be positive
+            and will override the ``server.maxUploadSize`` configuration option.
 
         accept_multiple_files : bool or "directory"
             Whether to accept more than one file in a submission. This can be one

streamlit/elements/widgets/select_slider.py

@@ -200,6 +200,10 @@ class SelectSliderMixin:
             ``options`` is dataframe-like, the first column will be used. Each
             label will be cast to ``str`` internally by default.
 
+            Each item in the iterable can optionally contain GitHub-flavored
+            Markdown, subject to the same limitations described in the
+            ``label`` parameter.
+
         value : a supported type or a tuple/list of supported types or None
             The value of the slider when it first renders. If a tuple/list
             of two values is passed here, then a range slider with those lower

streamlit/runtime/caching/cache_data_api.py

@@ -465,6 +465,11 @@ class CacheDataAPI:
     ) -> CachedFunc[P, R] | Callable[[Callable[P, R]], CachedFunc[P, R]]:
         """Decorator to cache functions that return data (e.g. dataframe transforms, database queries, ML inference).
 
+        Cached objects can be global or session-scoped. Global cached data is
+        available across all users, sessions, and reruns. Session-scoped cached
+        data is only available in the current session and removed when the
+        session disconnects.
+
         Cached objects are stored in "pickled" form, which means that the return
         value of a cached function must be pickleable. Each caller of the cached
         function gets its own copy of the cached data.
@@ -472,20 +477,17 @@ class CacheDataAPI:
         You can clear a function's cache with ``func.clear()`` or clear the entire
         cache with ``st.cache_data.clear()``.
 
-        A function's arguments must be hashable to cache it. If you have an
-        unhashable argument (like a database connection) or an argument you
-        want to exclude from caching, use an underscore prefix in the argument
-        name. In this case, Streamlit will return a cached value when all other
-        arguments match a previous function call. Alternatively, you can
-        declare custom hashing functions with ``hash_funcs``.
-
-        Cached values are available to all users of your app. If you need to
-        save results that should only be accessible within a session, use
-        `Session State
-        <https://docs.streamlit.io/develop/concepts/architecture/session-state>`_
-        instead. Within each user session, an ``@st.cache_data``-decorated
-        function returns a *copy* of the cached return value (if the value is
-        already cached). To cache shared global resources (singletons), use
+        A function's arguments must be hashable to cache it. Streamlit makes a
+        best effort to hash a variety of objects, but the fallback hashing method
+        requires that the argument be pickleable, also. If you have an unhashable
+        argument (like a database connection) or an argument you want to exclude
+        from caching, use an underscore prefix in the argument name. In this case,
+        Streamlit will return a cached value when all other arguments match a
+        previous function call. Alternatively, you can declare custom hashing
+        functions with ``hash_funcs``.
+
+        Objects cached by ``st.cache_data`` are returned as copies. To cache a
+        shared resource or something you want to mutate in place, use
         ``st.cache_resource`` instead. To learn more about caching, see
         `Caching overview
         <https://docs.streamlit.io/develop/concepts/architecture/caching>`_.
@@ -544,13 +546,15 @@ class CacheDataAPI:
             of how this can be used.
 
         scope : "global" or "session"
-            The scope for the resource. If "global", cache globally. If "session",
-            cache in the session.
-
-            Session-scoped cache entries will be expired when a user's session is
-            disconnected. Note that disconnected sessions can reconnect - so it is
-            possible for the cache to populate multiple times in a single session for
-            the same key.
+            The scope for the data cache. If this is ``"global"`` (default),
+            the data is cached globally. If this is ``"session"``, the data is
+            removed from the cache when the session disconnects.
+
+            Because a session-scoped cache is cleared when a session disconnects,
+            an unstable network connection can cause the cache to populate
+            multiple times in a single session. If this is a problem, you might
+            consider adjusting the ``server.websocketPingInterval``
+            configuration option.
 
         Example
         -------

streamlit/runtime/caching/cache_resource_api.py

@@ -362,33 +362,30 @@ class CacheResourceAPI:
         on_release: OnRelease | None = None,
         scope: CacheScope = "global",
     ) -> CachedFunc[P, R] | Callable[[Callable[P, R]], CachedFunc[P, R]]:
-        """Decorator to cache functions that return global resources (e.g. database connections, ML models).
+        """Decorator to cache functions that return resource objects (e.g. database connections, ML models).
 
-        Cached objects are shared across all users, sessions, and reruns. They
-        must be thread-safe because they can be accessed from multiple threads
-        concurrently. If thread safety is an issue, consider using ``st.session_state``
-        to store resources per session instead.
+        Cached objects can be global or session-scoped. Global resources are
+        shared across all users, sessions, and reruns. Session-scoped resources are
+        scoped to the current session and are removed when the session disconnects.
+        Global resources must be thread-safe. If thread safety is an issue,
+        consider using a session-scoped cache or storing the resource in
+        ``st.session_state`` instead.
 
         You can clear a function's cache with ``func.clear()`` or clear the entire
         cache with ``st.cache_resource.clear()``.
 
-        A function's arguments must be hashable to cache it. If you have an
-        unhashable argument (like a database connection) or an argument you
-        want to exclude from caching, use an underscore prefix in the argument
-        name. In this case, Streamlit will return a cached value when all other
-        arguments match a previous function call. Alternatively, you can
-        declare custom hashing functions with ``hash_funcs``.
-
-        Cached values are available to all users of your app. If you need to
-        save results that should only be accessible within a session, use
-        `Session State
-        <https://docs.streamlit.io/develop/concepts/architecture/session-state>`_
-        instead. Within each user session, an ``@st.cache_resource``-decorated
-        function returns the cached instance of the return value (if the value
-        is already cached). Therefore, objects cached by ``st.cache_resource``
-        act like singletons and can mutate. To cache data and return copies,
-        use ``st.cache_data`` instead. To learn more about caching, see
-        `Caching overview
+        A function's arguments must be hashable to cache it. Streamlit makes a
+        best effort to hash a variety of objects, but the fallback hashing method
+        requires that the argument be pickleable, also. If you have an unhashable
+        argument (like a database connection) or an argument you want to exclude
+        from caching, use an underscore prefix in the argument name. In this case,
+        Streamlit will return a cached value when all other arguments match a
+        previous function call. Alternatively, you can declare custom hashing
+        functions with ``hash_funcs``.
+
+        Objects cached by ``st.cache_resource`` act like singletons and can
+        mutate. To cache data and return copies, use ``st.cache_data`` instead.
+        To learn more about caching, see `Caching overview
         <https://docs.streamlit.io/develop/concepts/architecture/caching>`_.
 
         .. warning::
@@ -410,7 +407,8 @@ class CacheResourceAPI:
             function's source code.
 
         ttl : float, timedelta, str, or None
-            The maximum time to keep an entry in the cache. Can be one of:
+            The maximum age of a returned entry from the cache. This can be one
+            of the following values:
 
             - ``None`` if cache entries should never expire (default).
             - A number specifying the time in seconds.
@@ -459,30 +457,40 @@ class CacheResourceAPI:
             of how this can be used.
 
         on_release : callable or None
-            If set, a function to call when a cache entry is removed from the cache.
+            A function to call when an entry is removed from the cache.
             The removed item will be provided to the function as an argument.
 
-            This is only useful for caches which will remove entries normally: Those
-            with ``max_entries`` or ``ttl`` settings. Note that TTL expiration does not
-            happen on all reads - so ``ttl`` should not be used to guarantee timely
-            cleanup, only cleanup when expired resources are accessed. Also note that
-            expiration can happen on any app render or load, so care should be taken
-            to ensure that ``on_release`` functions are thread-safe and do not rely on
-            session state.
+            This is only useful for caches that remove entries normally.
+            Most commonly, this is used session-scoped caches to release
+            per-session resources. This can also be used with ``max_entries``
+            or ``ttl`` settings.
 
-            This will NOT be called when an app is shut down.
+            TTL expiration only happens when expired resources are accessed.
+            Therefore, don't rely on TTL expiration to guarantee timely cleanup.
+            Also, expiration can happen on any script run. Ensure that
+            ``on_release`` functions are thread-safe and don't rely on session
+            state.
+
+            The ``on_release`` function isn't guaranteed to be called when an
+            app is shut down.
 
         scope : "global" or "session"
-            The scope for the resource. If "global", cache globally. If "session",
-            cache in the session.
+            The scope for the resource cache. If this is ``"global"`` (default),
+            the resource is cached globally. If this is ``"session"``, the
+            resource is removed from the cache when the session disconnects.
 
-            Session-scoped cache entries will be expired when a user's session is
-            disconnected. Note that disconnected sessions can reconnect - so it is
-            possible for the cache to populate multiple times in a single session for
-            the same key.
+            Because a session-scoped cache is cleared when a session disconnects,
+            an unstable network connection can cause the cache to populate
+            multiple times in a single session. If this is a problem, you might
+            consider adjusting the ``server.websocketPingInterval``
+            configuration option.
 
         Example
         -------
+        **Example 1: Global cache**
+
+        By default, an ``@st.cache_resource``-decorated function uses a global cache.
+
         >>> import streamlit as st
         >>>
         >>> @st.cache_resource
@@ -501,7 +509,22 @@ class CacheResourceAPI:
         >>> s3 = get_database_session(SESSION_URL_2)
         >>> # This is a different URL, so the function executes.
 
-        By default, all parameters to a cache_resource function must be hashable.
+        **Example 2: Session-scoped cache**
+
+        By passing ``scope="session"``, an ``@st.cache_resource``-decorated function
+        uses a session-scoped cache. You can also use ``on_release`` to clean up
+        resources when they are no longer needed.
+
+        >>> import streamlit as st
+        >>>
+        >>> @st.cache_resource(scope="session", on_release=lambda sess: sess.close())
+        ... def get_database_session(url):
+        ...     # Create a database session object that points to the URL.
+        ...     return session
+
+        **Example 3: Unhashable arguments**
+
+        By default, all parameters to a cached function must be hashable.
         Any parameter whose name begins with ``_`` will not be hashed. You can use
         this as an "escape hatch" for parameters that are not hashable:
 
@@ -521,7 +544,9 @@ class CacheResourceAPI:
         >>> # value - even though the _sessionmaker parameter was different
         >>> # in both calls.
 
-        A cache_resource function's cache can be procedurally cleared:
+        **Example 4: Clearing a cache**
+
+        A cached function's cache can be procedurally cleared:
 
         >>> import streamlit as st
         >>>
@@ -530,12 +555,14 @@ class CacheResourceAPI:
         ...     # Create a database connection object that points to the URL.
         ...     return connection
         >>>
-        >>> fetch_and_clean_data.clear(_sessionmaker, "https://streamlit.io/")
+        >>> get_database_session.clear(_sessionmaker, "https://streamlit.io/")
         >>> # Clear the cached entry for the arguments provided.
         >>>
         >>> get_database_session.clear()
         >>> # Clear all cached entries for this function.
 
+        **Example 5: Custom hashing**
+
         To override the default hashing behavior, pass a custom hash function.
         You can do that by mapping a type (e.g. ``Person``) to a hash
         function (``str``) like this:
@@ -562,6 +589,7 @@ class CacheResourceAPI:
         >>> @st.cache_resource(hash_funcs={"__main__.Person": str})
         ... def get_person_name(person: Person):
         ...     return person.name
+
         """
 
         if scope not in ("global", "session"):