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

streamlit/config_option.py

@@ -0,0 +1,311 @@
+# 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.
+
+"""Class to store a key-value pair for the config system."""
+
+from __future__ import annotations
+
+import datetime
+import re
+import textwrap
+from typing import Any, Callable
+
+from streamlit.string_util import to_snake_case
+from streamlit.util import repr_
+
+
+class ConfigOption:
+    '''Stores a Streamlit configuration option.
+
+    A configuration option, like 'browser.serverPort', which indicates which port
+    to use when connecting to the proxy. There are two ways to create a
+    ConfigOption:
+
+    Simple ConfigOptions are created as follows:
+
+        ConfigOption('browser.serverPort',
+            description = 'Connect to the proxy at this port.',
+            default_val = 8501)
+
+    More complex config options resolve their values at runtime as follows:
+
+        @ConfigOption('browser.serverPort')
+        def _proxy_port():
+            """Connect to the proxy at this port.
+
+            Defaults to 8501.
+            """
+            return 8501
+
+    NOTE: For complex config options, the function is called each time the
+    option.value is evaluated!
+
+    Attributes
+    ----------
+    key : str
+        The fully qualified section.name
+    value : any
+        The value for this option. If this is a complex config option then
+        the callback is called EACH TIME value is evaluated.
+    section : str
+        The section of this option. Example: 'global'.
+    name : str
+        See __init__.
+    description : str
+        See __init__.
+    where_defined : str
+        Indicates which file set this config option.
+        ConfigOption.DEFAULT_DEFINITION means this file.
+    is_default: bool
+        True if the config value is equal to its default value.
+    visibility : {"visible", "hidden"}
+        See __init__.
+    scriptable : bool
+        See __init__.
+    deprecated: bool
+        See __init__.
+    deprecation_text : str or None
+        See __init__.
+    expiration_date : str or None
+        See __init__.
+    replaced_by : str or None
+        See __init__.
+    sensitive : bool
+        See __init__.
+    env_var: str
+        The name of the environment variable that can be used to set the option.
+    '''
+
+    # This is a special value for ConfigOption.where_defined which indicates
+    # that the option default was not overridden.
+    DEFAULT_DEFINITION = "<default>"
+
+    # This is a special value for ConfigOption.where_defined which indicates
+    # that the options was defined by Streamlit's own code.
+    STREAMLIT_DEFINITION = "<streamlit>"
+
+    def __init__(
+        self,
+        key: str,
+        description: str | None = None,
+        default_val: Any | None = None,
+        visibility: str = "visible",
+        scriptable: bool = False,
+        deprecated: bool = False,
+        deprecation_text: str | None = None,
+        expiration_date: str | None = None,
+        replaced_by: str | None = None,
+        type_: type = str,
+        sensitive: bool = False,
+    ):
+        """Create a ConfigOption with the given name.
+
+        Parameters
+        ----------
+        key : str
+            Should be of the form "section.optionName"
+            Examples: server.name, deprecation.v1_0_featureName
+        description : str
+            Like a comment for the config option.
+        default_val : any
+            The value for this config option.
+        visibility : {"visible", "hidden"}
+            Whether this option should be shown to users.
+        scriptable : bool
+            Whether this config option can be set within a user script.
+        deprecated: bool
+            Whether this config option is deprecated.
+        deprecation_text : str or None
+            Required if deprecated == True. Set this to a string explaining
+            what to use instead.
+        expiration_date : str or None
+            Required if deprecated == True. set this to the date at which it
+            will no longer be accepted. Format: 'YYYY-MM-DD'.
+        replaced_by : str or None
+            If this is option has been deprecated in favor or another option,
+            set this to the path to the new option. Example:
+            'server.runOnSave'. If this is set, the 'deprecated' option
+            will automatically be set to True, and deprecation_text will have a
+            meaningful default (unless you override it).
+        type_ : one of str, int, float or bool
+            Useful to cast the config params sent by cmd option parameter.
+        sensitive: bool
+            Sensitive configuration options cannot be set by CLI parameter.
+        """
+        # Parse out the section and name.
+        self.key = key
+        key_format = (
+            # Capture a group called "section"
+            r"(?P<section>"
+            # Matching text comprised of letters and numbers that begins
+            # with a lowercase letter with an optional "_" preceding it.
+            # Examples: "_section", "section1"
+            r"\_?[a-z][a-zA-Z0-9]*"
+            r")"
+            # Separator between groups
+            r"\."
+            # Capture a group called "name"
+            r"(?P<name>"
+            # Match text comprised of letters and numbers beginning with a
+            # lowercase letter.
+            # Examples: "name", "nameOfConfig", "config1"
+            r"[a-z][a-zA-Z0-9]*"
+            r")$"
+        )
+        match = re.match(key_format, self.key)
+        assert match, f'Key "{self.key}" has invalid format.'
+        self.section, self.name = match.group("section"), match.group("name")
+
+        self.description = description
+
+        self.visibility = visibility
+        self.scriptable = scriptable
+        self.default_val = default_val
+        self.deprecated = deprecated
+        self.replaced_by = replaced_by
+        self.is_default = True
+        self._get_val_func: Callable[[], Any] | None = None
+        self.where_defined = ConfigOption.DEFAULT_DEFINITION
+        self.type = type_
+        self.sensitive = sensitive
+        # infer multiple values if the default value is a list or tuple
+        self.multiple = isinstance(default_val, (list, tuple))
+
+        if self.replaced_by:
+            self.deprecated = True
+            if deprecation_text is None:
+                deprecation_text = "Replaced by %s." % self.replaced_by
+
+        if self.deprecated:
+            assert expiration_date, "expiration_date is required for deprecated items"
+            assert deprecation_text, "deprecation_text is required for deprecated items"
+            self.expiration_date = expiration_date
+            self.deprecation_text = textwrap.dedent(deprecation_text)
+
+        self.set_value(default_val)
+
+    def __repr__(self) -> str:
+        return repr_(self)
+
+    def __call__(self, get_val_func: Callable[[], Any]) -> ConfigOption:
+        """Assign a function to compute the value for this option.
+
+        This method is called when ConfigOption is used as a decorator.
+
+        Parameters
+        ----------
+        get_val_func : function
+            A function which will be called to get the value of this parameter.
+            We will use its docString as the description.
+
+        Returns
+        -------
+        ConfigOption
+            Returns self, which makes testing easier. See config_test.py.
+
+        """
+        assert get_val_func.__doc__, (
+            "Complex config options require doc strings for their description."
+        )
+        self.description = get_val_func.__doc__
+        self._get_val_func = get_val_func
+        return self
+
+    @property
+    def value(self) -> Any:
+        """Get the value of this config option."""
+        if self._get_val_func is None:
+            return None
+        return self._get_val_func()
+
+    def set_value(self, value: Any, where_defined: str | None = None) -> None:
+        """Set the value of this option.
+
+        Parameters
+        ----------
+        value
+            The new value for this parameter.
+        where_defined : str
+            New value to remember where this parameter was set.
+
+        """
+        self._get_val_func = lambda: value
+
+        if where_defined is None:
+            self.where_defined = ConfigOption.DEFAULT_DEFINITION
+        else:
+            self.where_defined = where_defined
+
+        self.is_default = value == self.default_val
+
+        if self.deprecated and self.where_defined != ConfigOption.DEFAULT_DEFINITION:
+            if self.is_expired():
+                # Import here to avoid circular imports
+                from streamlit.logger import get_logger
+
+                LOGGER = get_logger(__name__)
+                LOGGER.error(
+                    textwrap.dedent(
+                        f"""
+                    ════════════════════════════════════════════════
+                    {self.key} IS NO LONGER SUPPORTED.
+
+                    {self.deprecation_text}
+
+                    Please update {self.where_defined}.
+                    ════════════════════════════════════════════════
+                    """
+                    )
+                )
+            else:
+                # Import here to avoid circular imports
+                from streamlit.logger import get_logger
+
+                LOGGER = get_logger(__name__)
+                LOGGER.warning(
+                    textwrap.dedent(
+                        f"""s
+                    ════════════════════════════════════════════════
+                    {self.key} IS DEPRECATED.
+                    {self.deprecation_text}
+
+                    This option will be removed on or after {self.expiration_date}.
+
+                    Please update {self.where_defined}.
+                    ════════════════════════════════════════════════
+                    """
+                    )
+                )
+
+    def is_expired(self) -> bool:
+        """Returns true if expiration_date is in the past."""
+        if not self.deprecated:
+            return False
+
+        expiration_date = _parse_yyyymmdd_str(self.expiration_date)
+        now = datetime.datetime.now()
+        return now > expiration_date
+
+    @property
+    def env_var(self):
+        """
+        Get the name of the environment variable that can be used to set the option.
+        """
+        name = self.key.replace(".", "_")
+        return f"STREAMLIT_{to_snake_case(name).upper()}"
+
+
+def _parse_yyyymmdd_str(date_str: str) -> datetime.datetime:
+    year, month, day = (int(token) for token in date_str.split("-", 2))
+    return datetime.datetime(year, month, day)

streamlit/config_util.py

@@ -0,0 +1,177 @@
+# 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 re
+
+from streamlit import cli_util
+from streamlit.config_option import ConfigOption
+
+
+def server_option_changed(
+    old_options: dict[str, ConfigOption], new_options: dict[str, ConfigOption]
+) -> bool:
+    """Return True if and only if an option in the server section differs
+    between old_options and new_options.
+    """
+    for opt_name, opt_val in old_options.items():
+        if not opt_name.startswith("server"):
+            continue
+
+        old_val = opt_val.value
+        new_val = new_options[opt_name].value
+        if old_val != new_val:
+            return True
+
+    return False
+
+
+def show_config(
+    section_descriptions: dict[str, str],
+    config_options: dict[str, ConfigOption],
+) -> None:
+    """Print the given config sections/options to the terminal."""
+
+    out = []
+    out.append(
+        _clean(
+            """
+        # Below are all the sections and options you can have in
+        ~/.streamlit/config.toml.
+    """
+        )
+    )
+
+    def append_desc(text):
+        out.append("# " + cli_util.style_for_cli(text, bold=True))
+
+    def append_comment(text):
+        out.append("# " + cli_util.style_for_cli(text))
+
+    def append_section(text):
+        out.append(cli_util.style_for_cli(text, bold=True, fg="green"))
+
+    def append_setting(text):
+        out.append(cli_util.style_for_cli(text, fg="green"))
+
+    for section, _ in section_descriptions.items():
+        # We inject a fake config section used for unit tests that we exclude here as
+        # its options are often missing required properties, which confuses the code
+        # below.
+        if section == "_test":
+            continue
+
+        section_options = {
+            k: v
+            for k, v in config_options.items()
+            if v.section == section and v.visibility == "visible" and not v.is_expired()
+        }
+
+        # Only show config header if section is non-empty.
+        if len(section_options) == 0:
+            continue
+
+        out.append("")
+        append_section("[%s]" % section)
+        out.append("")
+
+        for key, option in section_options.items():
+            key = option.key.split(".")[1]
+            description_paragraphs = _clean_paragraphs(option.description or "")
+
+            last_paragraph_idx = len(description_paragraphs) - 1
+
+            for i, paragraph in enumerate(description_paragraphs):
+                # Split paragraph into lines
+                lines = paragraph.rstrip().split(
+                    "\n"
+                )  # Remove trailing newline characters
+
+                # If the first line is empty, remove it
+                if lines and not lines[0].strip():
+                    lines = lines[1:]
+
+                # Choose function based on whether it's the first paragraph or not
+                append_func = append_desc if i == 0 else append_comment
+
+                # Add comment character to each line and add to out
+                for line in lines:
+                    append_func(line.lstrip())
+
+                # # Add a line break after a paragraph only if it's not the last paragraph
+                if i != last_paragraph_idx:
+                    out.append("")
+
+            import toml
+
+            toml_default = toml.dumps({"default": option.default_val})
+            toml_default = toml_default[10:].strip()
+
+            if len(toml_default) > 0:
+                # Ensure a line break before appending "Default" comment, if not already there
+                if out[-1] != "":
+                    out.append("")
+                append_comment("Default: %s" % toml_default)
+            else:
+                # Don't say "Default: (unset)" here because this branch applies
+                # to complex config settings too.
+                pass
+
+            if option.deprecated:
+                append_comment(cli_util.style_for_cli("DEPRECATED.", fg="yellow"))
+                for line in _clean_paragraphs(option.deprecation_text):
+                    append_comment(line)
+                append_comment(
+                    "This option will be removed on or after %s."
+                    % option.expiration_date
+                )
+
+            option_is_manually_set = (
+                option.where_defined != ConfigOption.DEFAULT_DEFINITION
+            )
+
+            if option_is_manually_set:
+                append_comment("The value below was set in %s" % option.where_defined)
+
+            toml_setting = toml.dumps({key: option.value})
+
+            if len(toml_setting) == 0:
+                toml_setting = f"# {key} =\n"
+            elif not option_is_manually_set:
+                toml_setting = f"# {toml_setting}"
+
+            append_setting(toml_setting)
+
+    cli_util.print_to_cli("\n".join(out))
+
+
+def _clean(txt: str) -> str:
+    """Replace sequences of multiple spaces with a single space, excluding newlines.
+
+    Preserves leading and trailing spaces, and does not modify spaces in between lines.
+    """
+    return re.sub(" +", " ", txt)
+
+
+def _clean_paragraphs(txt: str) -> list[str]:
+    """Split the text into paragraphs, preserve newlines within the paragraphs."""
+    # Strip both leading and trailing newlines.
+    txt = txt.strip("\n")
+    paragraphs = txt.split("\n\n")
+    cleaned_paragraphs = [
+        "\n".join(_clean(line) for line in paragraph.split("\n"))
+        for paragraph in paragraphs
+    ]
+    return cleaned_paragraphs

streamlit/connections/__init__.py

@@ -0,0 +1,28 @@
+# 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 streamlit.connections.base_connection import BaseConnection
+from streamlit.connections.snowflake_connection import SnowflakeConnection
+from streamlit.connections.snowpark_connection import SnowparkConnection
+from streamlit.connections.sql_connection import SQLConnection
+
+ExperimentalBaseConnection = BaseConnection
+
+__all__ = [
+    "BaseConnection",
+    "SnowflakeConnection",
+    "SnowparkConnection",
+    "SQLConnection",
+    "ExperimentalBaseConnection",
+]

streamlit/connections/base_connection.py

@@ -0,0 +1,174 @@
+# 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 json
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+from streamlit.runtime.secrets import AttrDict, secrets_singleton
+from streamlit.util import calc_md5
+
+RawConnectionT = TypeVar("RawConnectionT")
+
+
+class BaseConnection(ABC, Generic[RawConnectionT]):
+    """The abstract base class that all Streamlit Connections must inherit from.
+
+    This base class provides connection authors with a standardized way to hook into the
+    ``st.connection()`` factory function: connection authors are required to provide an
+    implementation for the abstract method ``_connect`` in their subclasses.
+
+    Additionally, it also provides a few methods/properties designed to make
+    implementation of connections more convenient. See the docstrings for each of the
+    methods of this class for more information
+
+    .. note::
+        While providing an implementation of ``_connect`` is technically all that's
+        required to define a valid connection, connections should also provide the user
+        with context-specific ways of interacting with the underlying connection object.
+        For example, the first-party SQLConnection provides a ``query()`` method for
+        reads and a ``session`` property for more complex operations.
+    """
+
+    def __init__(self, connection_name: str, **kwargs) -> None:
+        """Create a BaseConnection.
+
+        This constructor is called by the connection factory machinery when a user
+        script calls ``st.connection()``.
+
+        Subclasses of BaseConnection that want to overwrite this method should take care
+        to also call the base class' implementation.
+
+        Parameters
+        ----------
+        connection_name : str
+            The name of this connection. This corresponds to the
+            ``[connections.<connection_name>]`` config section in ``st.secrets``.
+        kwargs : dict
+            Any other kwargs to pass to this connection class' ``_connect`` method.
+
+        Returns
+        -------
+        None
+        """
+        self._connection_name = connection_name
+        self._kwargs = kwargs
+
+        self._config_section_hash = calc_md5(json.dumps(self._secrets.to_dict()))
+        secrets_singleton.file_change_listener.connect(self._on_secrets_changed)
+
+        self._raw_instance: RawConnectionT | None = self._connect(**kwargs)
+
+    def __del__(self) -> None:
+        secrets_singleton.file_change_listener.disconnect(self._on_secrets_changed)
+
+    def __getattribute__(self, name: str) -> Any:
+        try:
+            return object.__getattribute__(self, name)
+        except AttributeError as e:
+            if hasattr(self._instance, name):
+                raise AttributeError(
+                    f"`{name}` doesn't exist here, but you can call `._instance.{name}` instead"
+                )
+            raise e
+
+    # Methods with default implementations that we don't expect subclasses to want or
+    # need to overwrite.
+    def _on_secrets_changed(self, _) -> None:
+        """Reset the raw connection object when this connection's secrets change.
+
+        We don't expect either user scripts or connection authors to have to use or
+        overwrite this method.
+        """
+        new_hash = calc_md5(json.dumps(self._secrets.to_dict()))
+
+        # Only reset the connection if the secrets file section specific to this
+        # connection has changed.
+        if new_hash != self._config_section_hash:
+            self._config_section_hash = new_hash
+            self.reset()
+
+    @property
+    def _secrets(self) -> AttrDict:
+        """Get the secrets for this connection from the corresponding st.secrets section.
+
+        We expect this property to be used primarily by connection authors when they
+        are implementing their class' ``_connect`` method. User scripts should, for the
+        most part, have no reason to use this property.
+        """
+        connections_section = None
+        if secrets_singleton.load_if_toml_exists():
+            connections_section = secrets_singleton.get("connections")
+
+        if type(connections_section) is not AttrDict:
+            return AttrDict({})
+
+        return connections_section.get(self._connection_name, AttrDict({}))
+
+    def reset(self) -> None:
+        """Reset this connection so that it gets reinitialized the next time it's used.
+
+        This method can be useful when a connection has become stale, an auth token has
+        expired, or in similar scenarios where a broken connection might be fixed by
+        reinitializing it. Note that some connection methods may already use ``reset()``
+        in their error handling code.
+
+        Returns
+        -------
+        None
+
+        Example
+        -------
+        >>> import streamlit as st
+        >>>
+        >>> conn = st.connection("my_conn")
+        >>>
+        >>> # Reset the connection before using it if it isn't healthy
+        >>> # Note: is_healthy() isn't a real method and is just shown for example here.
+        >>> if not conn.is_healthy():
+        ...     conn.reset()
+        >>>
+        >>> # Do stuff with conn...
+        """
+        self._raw_instance = None
+
+    @property
+    def _instance(self) -> RawConnectionT:
+        """Get an instance of the underlying connection, creating a new one if needed."""
+        if self._raw_instance is None:
+            self._raw_instance = self._connect(**self._kwargs)
+
+        return self._raw_instance
+
+    # Abstract fields/methods that subclasses of BaseConnection must implement
+    @abstractmethod
+    def _connect(self, **kwargs) -> RawConnectionT:
+        """Create an instance of an underlying connection object.
+
+        This abstract method is the one method that we require subclasses of
+        BaseConnection to provide an implementation for. It is called when first
+        creating a connection and when reconnecting after a connection is reset.
+
+        Parameters
+        ----------
+        kwargs : dict
+
+        Returns
+        -------
+        RawConnectionT
+            The underlying connection object.
+        """
+        raise NotImplementedError