streamlit-nightly 1.33.1.dev20240407__py2.py3-none-any.whl → 1.33.1.dev20240409__py2.py3-none-any.whl

streamlit/components/lib/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2024)
+#
+# 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,82 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2024)
+#
+# 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 Final
+
+from streamlit import util
+from streamlit.components.types.base_component_registry import BaseComponentRegistry
+from streamlit.components.types.base_custom_component import BaseCustomComponent
+from streamlit.errors import StreamlitAPIException
+from streamlit.logger import get_logger
+
+_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-2024)
+#
+# 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,98 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2024)
+#
+# 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 Protocol
+
+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,137 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2024)
+#
+# 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 Any
+
+from streamlit import util
+from streamlit.errors import StreamlitAPIException
+
+
+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,
+        **kwargs,
+    ) -> Any:
+        """An alias for create_instance."""
+        return self.create_instance(*args, default=default, key=key, **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,
+        **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".
+        **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

streamlit/components/v1/__init__.py

@@ -12,11 +12,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# `html` and `iframe` are part of Custom Components, so they appear in this
-# `streamlit.components.v1` namespace.
+"""
+This directory contains the files and modules for the exposed API.
+"""
+
 import streamlit
-from streamlit.components.v1.components import declare_component
+from streamlit.components.v1.component_registry import declare_component
 
+# `html` and `iframe` are part of Custom Components, so they appear in this
+# `streamlit.components.v1` namespace.
 html = streamlit._main._html
 iframe = streamlit._main._iframe
 

streamlit/components/v1/component_registry.py

@@ -0,0 +1,103 @@
+# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2024)
+#
+# 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 inspect
+import os
+from types import FrameType
+
+from streamlit.components.types.base_component_registry import BaseComponentRegistry
+from streamlit.components.v1.custom_component import CustomComponent
+from streamlit.runtime import get_instance
+
+
+def _get_module_name(caller_frame: FrameType) -> str:
+    # Get the caller's module name. `__name__` gives us the module's
+    # fully-qualified name, which includes its package.
+    module = inspect.getmodule(caller_frame)
+    assert module is not None
+    module_name = module.__name__
+
+    # If the caller was the main module that was executed (that is, if the
+    # user executed `python my_component.py`), then this name will be
+    # "__main__" instead of the actual package name. In this case, we use
+    # the main module's filename, sans `.py` extension, as the component name.
+    if module_name == "__main__":
+        file_path = inspect.getfile(caller_frame)
+        filename = os.path.basename(file_path)
+        module_name, _ = os.path.splitext(filename)
+
+    return module_name
+
+
+def declare_component(
+    name: str,
+    path: str | None = None,
+    url: str | None = None,
+) -> CustomComponent:
+    """Create and register a custom component.
+
+    Parameters
+    ----------
+    name: str
+        A short, descriptive name for the component. Like, "slider".
+    path: str or None
+        The path to serve the component's frontend files from. Either
+        `path` or `url` must be specified, but not both.
+    url: str or None
+        The URL that the component is served from. Either `path` or `url`
+        must be specified, but not both.
+
+    Returns
+    -------
+    CustomComponent
+        A CustomComponent that can be called like a function.
+        Calling the component will create a new instance of the component
+        in the Streamlit app.
+
+    """
+
+    # Get our stack frame.
+    current_frame: FrameType | None = inspect.currentframe()
+    assert current_frame is not None
+    # Get the stack frame of our calling function.
+    caller_frame = current_frame.f_back
+    assert caller_frame is not None
+    module_name = _get_module_name(caller_frame)
+
+    # Build the component name.
+    component_name = f"{module_name}.{name}"
+
+    # Create our component object, and register it.
+    component = CustomComponent(
+        name=component_name, path=path, url=url, module_name=module_name
+    )
+    get_instance().component_registry.register_component(component)
+
+    return component
+
+
+# Keep for backwards-compatibility for now as we don't know whether existing custom
+# components use this method. We made significant refactors to the custom component
+# registry code in https://github.com/streamlit/streamlit/pull/8193 and after
+# that is out in the wild, we can follow-up with more refactorings, e.g. remove
+# the following class and method. When we do that, we should conduct some testing with
+# popular custom components.
+class ComponentRegistry:
+    @classmethod
+    def instance(cls) -> BaseComponentRegistry:
+        """Returns the ComponentRegistry of the runtime instance."""
+
+        return get_instance().component_registry