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

streamlit/commands/page_config.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.
+
+from __future__ import annotations
+
+import random
+from collections.abc import Mapping
+from pathlib import Path
+from textwrap import dedent
+from typing import TYPE_CHECKING, Any, Final, Literal, Union, cast
+
+from typing_extensions import TypeAlias
+
+from streamlit.elements.lib.image_utils import AtomicImage, image_to_url
+from streamlit.errors import (
+    StreamlitInvalidMenuItemKeyError,
+    StreamlitInvalidPageLayoutError,
+    StreamlitInvalidSidebarStateError,
+    StreamlitInvalidURLError,
+)
+from streamlit.proto.ForwardMsg_pb2 import ForwardMsg as ForwardProto
+from streamlit.proto.PageConfig_pb2 import PageConfig as PageConfigProto
+from streamlit.runtime.metrics_util import gather_metrics
+from streamlit.runtime.scriptrunner_utils.script_run_context import get_script_run_ctx
+from streamlit.string_util import is_emoji, validate_material_icon
+from streamlit.url_util import is_url
+
+if TYPE_CHECKING:
+    from typing_extensions import TypeGuard
+
+GET_HELP_KEY: Final = "get help"
+REPORT_A_BUG_KEY: Final = "report a bug"
+ABOUT_KEY: Final = "about"
+
+PageIcon: TypeAlias = Union[AtomicImage, str]
+Layout: TypeAlias = Literal["centered", "wide"]
+InitialSideBarState: TypeAlias = Literal["auto", "expanded", "collapsed"]
+_GetHelp: TypeAlias = Literal["Get help", "Get Help", "get help"]
+_ReportABug: TypeAlias = Literal["Report a bug", "report a bug"]
+_About: TypeAlias = Literal["About", "about"]
+MenuKey: TypeAlias = Literal[_GetHelp, _ReportABug, _About]
+MenuItems: TypeAlias = Mapping[MenuKey, Union[str, None]]
+
+# Emojis recommended by https://share.streamlit.io/rensdimmendaal/emoji-recommender/main/app/streamlit.py
+# for the term "streamlit". Watch out for zero-width joiners,
+# as they won't parse correctly in the list() call!
+RANDOM_EMOJIS: Final = list(
+    "🔥™🎉🚀🌌💣✨🌙🎆🎇💥🤩🤙🌛🤘⬆💡🤪🥂⚡💨🌠🎊🍿😛🔮🤟🌃🍃🍾💫▪🌴🎈🎬🌀🎄😝☔⛽🍂💃😎🍸🎨🥳☀😍🅱🌞😻🌟😜💦💅🦄😋😉👻🍁🤤👯🌻‼🌈👌🎃💛😚🔫🙌👽🍬🌅☁🍷👭☕🌚💁👅🥰🍜😌🎥🕺❕🧡☄💕🍻✅🌸🚬🤓🍹®☺💪😙☘🤠✊🤗🍵🤞😂💯😏📻🎂💗💜🌊❣🌝😘💆🤑🌿🦋😈⛄🚿😊🌹🥴😽💋😭🖤🙆👐⚪💟☃🙈🍭💻🥀🚗🤧🍝💎💓🤝💄💖🔞⁉⏰🕊🎧☠♥🌳🏾🙉⭐💊🍳🌎🙊💸❤🔪😆🌾✈📚💀🏠✌🏃🌵🚨💂🤫🤭😗😄🍒👏🙃🖖💞😅🎅🍄🆓👉💩🔊🤷⌚👸😇🚮💏👳🏽💘💿💉👠🎼🎶🎤👗❄🔐🎵🤒🍰👓🏄🌲🎮🙂📈🚙📍😵🗣❗🌺🙄👄🚘🥺🌍🏡♦💍🌱👑👙☑👾🍩🥶📣🏼🤣☯👵🍫➡🎀😃✋🍞🙇😹🙏👼🐝⚫🎁🍪🔨🌼👆👀😳🌏📖👃🎸👧💇🔒💙😞⛅🏻🍴😼🗿🍗♠🦁✔🤖☮🐢🐎💤😀🍺😁😴📺☹😲👍🎭💚🍆🍋🔵🏁🔴🔔🧐👰☎🏆🤡🐠📲🙋📌🐬✍🔑📱💰🐱💧🎓🍕👟🐣👫🍑😸🍦👁🆗🎯📢🚶🦅🐧💢🏀🚫💑🐟🌽🏊🍟💝💲🐍🍥🐸☝♣👊⚓❌🐯🏈📰🌧👿🐳💷🐺📞🆒🍀🤐🚲🍔👹🙍🌷🙎🐥💵🔝📸⚠❓🎩✂🍼😑⬇⚾🍎💔🐔⚽💭🏌🐷🍍✖🍇📝🍊🐙👋🤔🥊🗽🐑🐘🐰💐🐴♀🐦🍓✏👂🏴👇🆘😡🏉👩💌😺✝🐼🐒🐶👺🖕👬🍉🐻🐾⬅⏬▶👮🍌♂🔸👶🐮👪⛳🐐🎾🐕👴🐨🐊🔹©🎣👦👣👨👈💬⭕📹📷"
+)
+
+# Also pick out some vanity emojis.
+ENG_EMOJIS: Final = [
+    "🎈",  # st.balloons 🎈🎈
+    "🤓",  # Abhi
+    "🏈",  # Amey
+    "🚲",  # Thiago
+    "🐧",  # Matteo
+    "🦒",  # Ken
+    "🐳",  # Karrie
+    "🕹️",  # Jonathan
+    "🇦🇲",  # Henrikh
+    "🎸",  # Guido
+    "🦈",  # Austin
+    "💎",  # Emiliano
+    "👩‍🎤",  # Naomi
+    "🧙‍♂️",  # Jon
+    "🐻",  # Brandon
+    "🎎",  # James
+    # TODO: Solicit emojis from the rest of Streamlit
+]
+
+
+def _lower_clean_dict_keys(dict: MenuItems) -> dict[str, Any]:
+    return {str(k).lower().strip(): v for k, v in dict.items()}
+
+
+def _get_favicon_string(page_icon: PageIcon) -> str:
+    """Return the string to pass to the frontend to have it show
+    the given PageIcon.
+
+    If page_icon is a string that looks like an emoji (or an emoji shortcode),
+    we return it as-is. Otherwise we use `image_to_url` to return a URL.
+
+    (If `image_to_url` raises an error and page_icon is a string, return
+    the unmodified page_icon string instead of re-raising the error.)
+    """
+
+    # Choose a random emoji.
+    if page_icon == "random":
+        return get_random_emoji()
+
+    # If page_icon is an emoji, return it as is.
+    if isinstance(page_icon, str) and is_emoji(page_icon):
+        return page_icon
+
+    if isinstance(page_icon, str) and page_icon.startswith(":material"):
+        return validate_material_icon(page_icon)
+
+    # Convert Path to string if necessary
+    if isinstance(page_icon, Path):
+        page_icon = str(page_icon)
+
+    # Fall back to image_to_url.
+    try:
+        return image_to_url(
+            page_icon,
+            width=-1,  # Always use full width for favicons
+            clamp=False,
+            channels="RGB",
+            output_format="auto",
+            image_id="favicon",
+        )
+    except Exception:
+        if isinstance(page_icon, str):
+            # This fall-thru handles emoji shortcode strings (e.g. ":shark:"),
+            # which aren't valid filenames and so will cause an Exception from
+            # `image_to_url`.
+            return page_icon
+        raise
+
+
+@gather_metrics("set_page_config")
+def set_page_config(
+    page_title: str | None = None,
+    page_icon: PageIcon | None = None,
+    layout: Layout = "centered",
+    initial_sidebar_state: InitialSideBarState = "auto",
+    menu_items: MenuItems | None = None,
+) -> None:
+    """
+    Configures the default settings of the page.
+
+    .. note::
+        This must be the first Streamlit command used on an app page, and must only
+        be set once per page.
+
+    Parameters
+    ----------
+    page_title: str or None
+        The page title, shown in the browser tab. If None, defaults to the
+        filename of the script ("app.py" would show "app • Streamlit").
+
+    page_icon : Anything supported by st.image (except list), str, or None
+        The page favicon. If ``page_icon`` is ``None`` (default), the favicon
+        will be a monochrome Streamlit logo.
+
+        In addition to the types supported by |st.image|_ (except list), the
+        following strings are valid:
+
+        - A single-character emoji. For example, you can set ``page_icon="🦈"``.
+
+        - An emoji short code. For example, you can set ``page_icon=":shark:"``.
+          For a list of all supported codes, see
+          https://share.streamlit.io/streamlit/emoji-shortcodes.
+
+        - The string literal, ``"random"``. You can set ``page_icon="random"``
+          to set a random emoji from the supported list above.
+
+        - An icon from the Material Symbols library (rounded style) in the
+          format ``":material/icon_name:"`` where "icon_name" is the name
+          of the icon in snake case.
+
+          For example, ``page_icon=":material/thumb_up:"`` will display the
+          Thumb Up icon. Find additional icons in the `Material Symbols \
+          <https://fonts.google.com/icons?icon.set=Material+Symbols&icon.style=Rounded>`_
+          font library.
+
+        .. note::
+            Colors are not supported for Material icons. When you use a
+            Material icon for favicon, it will be black, regardless of browser
+            theme.
+
+        .. |st.image| replace:: ``st.image``
+        .. _st.image: https://docs.streamlit.io/develop/api-reference/media/st.image
+
+    layout: "centered" or "wide"
+        How the page content should be laid out. Defaults to "centered",
+        which constrains the elements into a centered column of fixed width;
+        "wide" uses the entire screen.
+
+    initial_sidebar_state: "auto", "expanded", or "collapsed"
+        How the sidebar should start out. Defaults to "auto",
+        which hides the sidebar on small devices and shows it otherwise.
+        "expanded" shows the sidebar initially; "collapsed" hides it.
+        In most cases, you should just use "auto", otherwise the app will
+        look bad when embedded and viewed on mobile.
+
+    menu_items: dict
+        Configure the menu that appears on the top-right side of this app.
+        The keys in this dict denote the menu item you'd like to configure:
+
+        - "Get help": str or None
+            The URL this menu item should point to.
+            If None, hides this menu item.
+        - "Report a Bug": str or None
+            The URL this menu item should point to.
+            If None, hides this menu item.
+        - "About": str or None
+            A markdown string to show in the About dialog.
+            If None, only shows Streamlit's default About text.
+
+        The URL may also refer to an email address e.g. ``mailto:john@example.com``.
+
+    Example
+    -------
+    >>> import streamlit as st
+    >>>
+    >>> st.set_page_config(
+    ...     page_title="Ex-stream-ly Cool App",
+    ...     page_icon="🧊",
+    ...     layout="wide",
+    ...     initial_sidebar_state="expanded",
+    ...     menu_items={
+    ...         'Get Help': 'https://www.extremelycoolapp.com/help',
+    ...         'Report a bug': "https://www.extremelycoolapp.com/bug",
+    ...         'About': "# This is a header. This is an *extremely* cool app!"
+    ...     }
+    ... )
+    """
+
+    msg = ForwardProto()
+
+    if page_title is not None:
+        msg.page_config_changed.title = page_title
+
+    if page_icon is not None:
+        msg.page_config_changed.favicon = _get_favicon_string(page_icon)
+
+    pb_layout: PageConfigProto.Layout.ValueType
+    if layout == "centered":
+        pb_layout = PageConfigProto.CENTERED
+    elif layout == "wide":
+        pb_layout = PageConfigProto.WIDE
+    else:
+        raise StreamlitInvalidPageLayoutError(layout=layout)
+
+    msg.page_config_changed.layout = pb_layout
+
+    pb_sidebar_state: PageConfigProto.SidebarState.ValueType
+    if initial_sidebar_state == "auto":
+        pb_sidebar_state = PageConfigProto.AUTO
+    elif initial_sidebar_state == "expanded":
+        pb_sidebar_state = PageConfigProto.EXPANDED
+    elif initial_sidebar_state == "collapsed":
+        pb_sidebar_state = PageConfigProto.COLLAPSED
+    else:
+        raise StreamlitInvalidSidebarStateError(
+            initial_sidebar_state=initial_sidebar_state
+        )
+
+    msg.page_config_changed.initial_sidebar_state = pb_sidebar_state
+
+    if menu_items is not None:
+        lowercase_menu_items = cast(MenuItems, _lower_clean_dict_keys(menu_items))
+        validate_menu_items(lowercase_menu_items)
+        menu_items_proto = msg.page_config_changed.menu_items
+        set_menu_items_proto(lowercase_menu_items, menu_items_proto)
+
+    ctx = get_script_run_ctx()
+    if ctx is None:
+        return
+    ctx.enqueue(msg)
+
+
+def get_random_emoji() -> str:
+    # Weigh our emojis 10x, cuz we're awesome!
+    # TODO: fix the random seed with a hash of the user's app code, for stability?
+    return random.choice(RANDOM_EMOJIS + 10 * ENG_EMOJIS)
+
+
+def set_menu_items_proto(lowercase_menu_items, menu_items_proto) -> None:
+    if GET_HELP_KEY in lowercase_menu_items:
+        if lowercase_menu_items[GET_HELP_KEY] is not None:
+            menu_items_proto.get_help_url = lowercase_menu_items[GET_HELP_KEY]
+        else:
+            menu_items_proto.hide_get_help = True
+
+    if REPORT_A_BUG_KEY in lowercase_menu_items:
+        if lowercase_menu_items[REPORT_A_BUG_KEY] is not None:
+            menu_items_proto.report_a_bug_url = lowercase_menu_items[REPORT_A_BUG_KEY]
+        else:
+            menu_items_proto.hide_report_a_bug = True
+
+    if ABOUT_KEY in lowercase_menu_items:
+        if lowercase_menu_items[ABOUT_KEY] is not None:
+            menu_items_proto.about_section_md = dedent(lowercase_menu_items[ABOUT_KEY])
+
+
+def validate_menu_items(menu_items: MenuItems) -> None:
+    for k, v in menu_items.items():
+        if not valid_menu_item_key(k):
+            raise StreamlitInvalidMenuItemKeyError(key=k)
+        if v is not None and (
+            not is_url(v, ("http", "https", "mailto")) and k != ABOUT_KEY
+        ):
+            raise StreamlitInvalidURLError(url=v)
+
+
+def valid_menu_item_key(key: str) -> TypeGuard[MenuKey]:
+    return key in {GET_HELP_KEY, REPORT_A_BUG_KEY, ABOUT_KEY}

streamlit/components/__init__.py

@@ -0,0 +1,13 @@
+# 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/components/lib/__init__.py

@@ -0,0 +1,13 @@
+# 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/components/lib/local_component_registry.py

@@ -0,0 +1,84 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2025)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import os
+import threading
+from typing import TYPE_CHECKING, Final
+
+from streamlit import util
+from streamlit.components.types.base_component_registry import BaseComponentRegistry
+from streamlit.errors import StreamlitAPIException
+from streamlit.logger import get_logger
+
+if TYPE_CHECKING:
+    from streamlit.components.types.base_custom_component import BaseCustomComponent
+
+_LOGGER: Final = get_logger(__name__)
+
+
+class LocalComponentRegistry(BaseComponentRegistry):
+    def __init__(self) -> None:
+        self._components: dict[str, BaseCustomComponent] = {}
+        self._lock = threading.Lock()
+
+    def __repr__(self) -> str:
+        return util.repr_(self)
+
+    def register_component(self, component: BaseCustomComponent) -> None:
+        """Register a CustomComponent.
+
+        Parameters
+        ----------
+        component : BaseCustomComponent
+            The component to register.
+        """
+
+        # Validate the component's path
+        abspath = component.abspath
+        if abspath is not None and not os.path.isdir(abspath):
+            raise StreamlitAPIException(f"No such component directory: '{abspath}'")
+
+        with self._lock:
+            existing = self._components.get(component.name)
+            self._components[component.name] = component
+
+        if existing is not None and component != existing:
+            _LOGGER.warning(
+                "%s overriding previously-registered %s",
+                component,
+                existing,
+            )
+
+        _LOGGER.debug("Registered component %s", component)
+
+    def get_component_path(self, name: str) -> str | None:
+        """Return the filesystem path for the component with the given name.
+
+        If no such component is registered, or if the component exists but is
+        being served from a URL, return None instead.
+        """
+        component = self._components.get(name, None)
+        return component.abspath if component is not None else None
+
+    def get_module_name(self, name: str) -> str | None:
+        component = self._components.get(name, None)
+        return component.module_name if component is not None else None
+
+    def get_component(self, name: str) -> BaseCustomComponent | None:
+        return self._components.get(name, None)
+
+    def get_components(self) -> list[BaseCustomComponent]:
+        return list(self._components.values())

streamlit/components/types/__init__.py

@@ -0,0 +1,13 @@
+# 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/components/types/base_component_registry.py

@@ -0,0 +1,99 @@
+# 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 abc import abstractmethod
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from streamlit.components.types.base_custom_component import BaseCustomComponent
+
+
+class BaseComponentRegistry(Protocol):
+    """Interface for ComponentRegistries."""
+
+    @abstractmethod
+    def register_component(self, component: BaseCustomComponent) -> None:
+        """Register a CustomComponent.
+
+        Parameters
+        ----------
+        component : CustomComponent
+            The component to register.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_component_path(self, name: str) -> str | None:
+        """Return the filesystem path for the component with the given name.
+
+        If no such component is registered, or if the component exists but is
+        being served from a URL, return None instead.
+
+        Parameters
+        ----------
+        name: name of the component
+
+        Returns
+        -------
+        str or None
+            The name of the specified component or None if no component with the given name has been registered.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_module_name(self, name: str) -> str | None:
+        """Return the module name for the component with the given name.
+
+        If no such component is registered, return None instead.
+
+        Parameters
+        ----------
+        name: name of the component
+
+        Returns
+        -------
+        str or None
+            The module_name of the specified component or None if no component with the given name has been registered.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_component(self, name: str) -> BaseCustomComponent | None:
+        """Return the registered component with the given name.
+
+        If no such component is registered, return None instead.
+
+        Parameters
+        ----------
+        name: name of the component
+
+        Returns
+        -------
+        component or None
+            The component with the provided name or None if component with the given name has been registered.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_components(self) -> list[BaseCustomComponent]:
+        """Returns a list of custom components that are registered in this registry.
+
+        Returns
+        -------
+        list[CustomComponents]
+            A list of registered custom components.
+        """
+        raise NotImplementedError

streamlit/components/types/base_custom_component.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.
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from streamlit import util
+from streamlit.errors import StreamlitAPIException
+
+if TYPE_CHECKING:
+    from streamlit.runtime.state.common import WidgetCallback
+
+
+class MarshallComponentException(StreamlitAPIException):
+    """Class for exceptions generated during custom component marshalling."""
+
+    pass
+
+
+class BaseCustomComponent(ABC):
+    """Interface for CustomComponents."""
+
+    def __init__(
+        self,
+        name: str,
+        path: str | None = None,
+        url: str | None = None,
+        module_name: str | None = None,
+    ):
+        if (path is None and url is None) or (path is not None and url is not None):
+            raise StreamlitAPIException(
+                "Either 'path' or 'url' must be set, but not both."
+            )
+
+        self._name = name
+        self._path = path
+        self._url = url
+        self._module_name = module_name
+
+    def __repr__(self) -> str:
+        return util.repr_(self)
+
+    def __call__(
+        self,
+        *args,
+        default: Any = None,
+        key: str | None = None,
+        on_change: WidgetCallback | None = None,
+        **kwargs,
+    ) -> Any:
+        """An alias for create_instance."""
+        return self.create_instance(
+            *args,
+            default=default,
+            key=key,
+            on_change=on_change,
+            **kwargs,
+        )
+
+    @property
+    def abspath(self) -> str | None:
+        if self._path is None:
+            return None
+        return os.path.abspath(self._path)
+
+    @property
+    def module_name(self) -> str | None:
+        return self._module_name
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def path(self) -> str | None:
+        return self._path
+
+    @property
+    def url(self) -> str | None:
+        return self._url
+
+    def __str__(self) -> str:
+        return f"'{self.name}': {self.path if self.path is not None else self.url}"
+
+    @abstractmethod
+    def __eq__(self, other) -> bool:
+        """Equality operator."""
+        return NotImplemented
+
+    @abstractmethod
+    def __ne__(self, other) -> bool:
+        """Inequality operator."""
+        return NotImplemented
+
+    @abstractmethod
+    def create_instance(
+        self,
+        *args,
+        default: Any = None,
+        key: str | None = None,
+        on_change: WidgetCallback | None = None,
+        **kwargs,
+    ) -> Any:
+        """Create a new instance of the component.
+
+        Parameters
+        ----------
+        *args
+            Must be empty; all args must be named. (This parameter exists to
+            enforce correct use of the function.)
+        default: any or None
+            The default return value for the component. This is returned when
+            the component's frontend hasn't yet specified a value with
+            `setComponentValue`.
+        key: str or None
+            If not None, this is the user key we use to generate the
+            component's "widget ID".
+        on_change: WidgetCallback or None
+            An optional callback invoked when the widget's value changes. No arguments are passed to it.
+        **kwargs
+            Keyword args to pass to the component.
+
+        Raises
+        ------
+        MarshallComponentException
+            Raised when args is not empty or component cannot be marshalled.
+        StreamlitAPIException
+            Raised when PyArrow is not installed.
+
+        Returns
+        -------
+        any or None
+            The component's widget value.
+
+        """
+        raise NotImplementedError