solara-ui 1.45.0__py3-none-any.whl

solara/hooks/misc.py

@@ -0,0 +1,263 @@
+import dataclasses
+import io
+import json
+import logging
+import os
+
+# import tempfile
+import threading
+import time
+import urllib.request
+import uuid
+from typing import IO, Any, Callable, Tuple, TypeVar, Union, cast
+
+import solara
+from solara.datatypes import FileContentResult, Result
+
+logger = logging.getLogger("react-ipywidgets.extra.hooks")
+chunk_size_default = 1024**2
+
+__all__ = [
+    "use_download",
+    "use_fetch",
+    "use_json_load",
+    "use_json",
+    "use_file_content",
+    "use_uuid4",
+    "use_unique_key",
+    "use_state_or_update",
+    "use_previous",
+    "use_trait_observe",
+]
+T = TypeVar("T")
+U = TypeVar("U")
+
+MaybeResult = Union[T, Result[T]]
+
+
+def use_retry(*actions: Callable[[], Any]):
+    counter, set_counter = solara.use_state(0)
+
+    def retry():
+        for action in actions:
+            action()
+        set_counter(lambda counter: counter + 1)
+
+    return counter, retry
+
+
+def use_download(
+    f: MaybeResult[Union[str, os.PathLike, IO]], url, expected_size=None, delay=None, return_content=False, chunk_size=chunk_size_default
+) -> Result:
+    from .use_thread import use_thread
+
+    if not isinstance(f, Result):
+        f = Result(value=f)
+    assert isinstance(f, Result)
+    content_length, set_content_length = solara.use_state(expected_size, key="content_length")
+    downloaded_length = 0
+    file_object = hasattr(f.value, "tell")
+    if not file_object:
+        file_path = cast(Union[str, os.PathLike], f.value)
+        if os.path.exists(file_path) and expected_size is not None:
+            file_size = os.path.getsize(file_path)
+            if file_size == expected_size:
+                downloaded_length = file_size
+    downloaded_length, set_downloaded_length = solara.use_state(downloaded_length, key="downloaded_length")
+
+    def download(cancel: threading.Event):
+        assert isinstance(f, Result)
+        nonlocal downloaded_length
+        if expected_size is not None and downloaded_length == expected_size:
+            return  # we already downloaded, but hooks cannot be conditional
+
+        context: Any = None
+        if file_object:
+            context = solara.util.nullcontext()
+            output_file = cast(IO, f.value)
+        else:
+            # f = cast(Result[Union[str, os.PathLike]], f)
+            output_file = context = open(f.value, "wb")  # type: ignore
+
+        with context:
+            with urllib.request.urlopen(url) as response:
+                content_length = int(response.info()["Content-Length"])
+                logger.info("content_length for %r = %r", url, content_length)
+                set_content_length(content_length)
+                bytes_read = 0
+                while not cancel.is_set():
+                    chunk = response.read(chunk_size)
+
+                    if delay:
+                        time.sleep(delay)
+                    if not chunk:
+                        break
+                    bytes_read += len(chunk)
+                    output_file.write(chunk)
+                    set_downloaded_length(bytes_read)
+        return bytes_read
+
+    result: Result[Any] = use_thread(download, [f, url])
+    # maybe we wanna check this
+    # download_is_done = downloaded_length == content_length
+
+    if content_length is not None:
+        progress = downloaded_length / content_length
+    else:
+        progress = 0
+
+    return dataclasses.replace(result, progress=progress)
+
+
+def use_fetch(url, chunk_size=chunk_size_default):
+    # reuse the same file like object
+    f = solara.use_memo(io.BytesIO, [url])
+    result = use_download(f, url, return_content=True, chunk_size=chunk_size)
+    return dataclasses.replace(result, value=f.getvalue() if result.progress == 1 else None)
+
+
+def compose_result(head, *tail):
+    return head
+
+
+def ensure_result(input: MaybeResult[T]) -> Result[T]:
+    if isinstance(input, Result):
+        return input
+    else:
+        return Result(value=input)
+
+
+def make_use_thread(f: Callable[[T], U]):
+    from .use_thread import use_thread
+
+    def use_result(input: MaybeResult[T]) -> Result[U]:
+        input_result = ensure_result(input)
+
+        def in_thread(cancel: threading.Event):
+            if input_result.value:
+                return f(input_result.value)
+
+        return use_thread(in_thread, dependencies=[input_result.value])
+
+    return use_result
+
+
+@make_use_thread
+def use_json_load(value: bytes):
+    return json.loads(value)
+
+
+def use_json(path):
+    return use_fetch(path) | use_json_load
+
+
+def use_file_content(path, watch=False) -> FileContentResult[bytes]:
+    counter, retry = use_retry()
+
+    def read_file(*ignore):
+        try:
+            with open(path, "rb") as f:
+                return f.read()
+        except Exception as e:
+            return e
+
+    result = None
+    try:
+        mtime = os.path.getmtime(path)
+    except Exception:
+        mtime = None
+
+    content = solara.use_memo(read_file, dependencies=[path, mtime, counter])
+    if result is not None:
+        return result
+    if isinstance(content, Exception):
+        return FileContentResult[bytes](error=content, _retry=retry)
+    else:
+        return FileContentResult[bytes](value=content, _retry=retry)
+
+
+def use_force_update() -> Callable[[], None]:
+    """Returns a callable that can be used to force an update of a component.
+
+    This is used when external state has change, and we need to re-render out component.
+    """
+    _counter, set_counter = solara.use_state(0, "force update counter")
+
+    def updater():
+        set_counter(lambda count: count + 1)
+
+    return updater
+
+
+def use_uuid4(dependencies=[]) -> str:
+    """Generate a unique string using the uuid4 algorithm. Will only change when the dependencies change."""
+
+    def make_uuid(*_ignore):
+        return str(uuid.uuid4())
+
+    return solara.use_memo(make_uuid, dependencies)
+
+
+def use_unique_key(key: str = None, prefix: str = "", dependencies=[]) -> str:
+    """Generate a unique string, or use key when not None. Dependencies are forwarded to `use_uuid4`."""
+    uuid = use_uuid4(dependencies=dependencies)
+    return prefix + (key or uuid)
+
+
+def use_state_or_update(
+    initial_or_updated: T, key: str = None, eq: Callable[[Any, Any], bool] = None
+) -> Tuple[T, Callable[[Union[T, Callable[[T], T]]], None]]:
+    """This is useful for situations where a prop can change from a parent
+    component, which should be respected, and otherwise the internal
+    state should be kept.
+    """
+    value, set_value = solara.use_state(initial_or_updated, key=key, eq=eq)
+
+    def possibly_update():
+        nonlocal value
+        # only gets called when initial_or_updated changes
+        set_value(initial_or_updated)
+        # this make sure the return value gets updated directly
+        value = initial_or_updated
+
+    solara.use_memo(possibly_update, [initial_or_updated])
+    return value, set_value
+
+
+def use_previous(value: T, condition=True) -> T:
+    ref = solara.use_ref(value)
+
+    def assign():
+        if condition:
+            ref.current = value
+
+    solara.use_effect(assign, [value])
+    return ref.current
+
+
+def use_trait_observe(has_trait_object, name):
+    """Observe a trait on an object, and return its value.
+
+    This is useful when you want your component to be in sync with a trait
+    of a widget or [HasTraits object](https://traitlets.readthedocs.io/en/stable/).
+
+    When the trait changes, your component will be re-rendered.
+
+    See [use_dark_effective](/api/use_dark_effective) for an example.
+    """
+    counter = solara.use_reactive(0)
+    counter.get()  # make the main component depend on this counter
+
+    def connect():
+        def update(change):
+            counter.value += 1
+
+        has_trait_object.observe(update, name)
+
+        def cleanup():
+            has_trait_object.unobserve(update, name)
+
+        return cleanup
+
+    solara.use_effect(connect, [has_trait_object, name])
+    return getattr(has_trait_object, name)

solara/hooks/use_reactive.py

@@ -0,0 +1,151 @@
+from typing import Any, Callable, Optional, TypeVar, Union
+
+import solara
+import solara.settings
+
+T = TypeVar("T")
+
+
+def use_reactive(
+    value: Union[T, solara.Reactive[T]],
+    on_change: Optional[Callable[[T], None]] = None,
+    equals: Callable[[Any, Any], bool] = solara.util.equals_extra,
+) -> solara.Reactive[T]:
+    """Creates a reactive variable with the a local component scope.
+
+    It is a useful alternative to `use_state` when you want to use a
+    reactive variable for the component state.
+    See also [our documentation on state management](/documentation/getting_started/fundamentals/state-management).
+
+    If the variable passed is a reactive variable, it will be returned instead and no
+    new reactive variable will be created. This is useful for implementing component
+    that accept either a reactive variable or a normal value along with an optional `on_change`
+    callback.
+
+    Note that that on each call, if the value changes, the reactive variable will be updated.
+    For objects that do no implement equality comparison, the will lead to an infinite loop.
+
+    In that case, combine the `use_reactive` with `use_memo` to never trigger an update from
+    the render function.
+
+    ```python
+    @solara.component
+    def Page():
+        data = solara.use_reactive(solara.use_memo(lambda: MyDataObject()))
+        ...
+    ```
+
+    ## Arguments:
+
+     * value (Union[T, solara.Reactive[T]]): The value of the
+            reactive variable. If a reactive variable is provided, it will be
+            used directly. Otherwise, a new reactive variable will be created
+            with the provided initial value. If the argument passed changes
+            the reactive variable will be updated.
+
+     * on_change (Optional[Callable[[T], None]]): An optional callback function
+            that will be called when the reactive variable's value changes.
+
+     * equals: A function that returns True if two values are considered equal, and False otherwise.
+            The default function is `solara.util.equals`, which performs a deep comparison of the two values
+            and is more forgiving than the default `==` operator.
+            You can provide a custom function if you need to define a different notion of equality.
+
+
+    Returns:
+        solara.Reactive[T]: A reactive variable with the specified initial value
+            or the provided reactive variable.
+
+    ## Examples
+
+    ### Replacement for use_state
+    ```solara
+    import solara
+
+    @solara.component
+    def ReusableComponent():
+        color = solara.use_reactive("red")  # another possibility
+        solara.Select(label="Color",values=["red", "green", "blue", "orange"],
+                    value=color)
+        solara.Markdown("### Solara is awesome", style={"color": color.value})
+
+    @solara.component
+    def Page():
+        # this component is used twice, but each instance has its own state
+        ReusableComponent()
+        ReusableComponent()
+
+    ```
+
+    ### Flexible arguments
+
+    The `MyComponent` component can be passed a reactive variable or a normal
+    Python variable and a `on_value` callback.
+
+    ```python
+    import solara
+    from typing import Union, Optional, Callable
+
+    @solara.component
+    def MyComponent(value: Union[T, solara.Reactive[T]],
+                    on_value: Optional[Callable[[T], None]] = None,
+        ):
+        reactive_value = solara.use_reactive(value, on_value)
+        # Use the `reactive_value` in the component
+    ```
+    """
+
+    try:
+        on_change_ref = solara.use_ref(on_change)
+    except RuntimeError as e:
+        raise RuntimeError(
+            "use_reactive must be called from a component function, inside the render function.\n"
+            "Do not call it top level, use [solara.reactive()](https://solara.dev/documentation/api/utilities/reactive) instead."
+        ) from e
+    on_change_ref.current = on_change
+
+    def create():
+        if not isinstance(value, solara.Reactive):
+            from solara._stores import SharedStore, MutateDetectorStore, StoreValue, _PublicValueNotSet, _SetValueNotSet
+            from solara.toestand import ValueBase
+
+            store: ValueBase[T]
+
+            if solara.settings.storage.mutation_detection is True:
+                shared_store = SharedStore[StoreValue[T]](
+                    StoreValue[T](private=value, public=_PublicValueNotSet(), get_traceback=None, set_value=_SetValueNotSet(), set_traceback=None),
+                    unwrap=lambda x: x.private,
+                )
+                store = MutateDetectorStore[T](shared_store, equals=equals)
+            else:
+                store = SharedStore(value, equals=equals)
+
+            return solara.Reactive(store)
+
+    reactive_value = solara.use_memo(create, dependencies=[])
+    if isinstance(value, solara.Reactive):
+        reactive_value = value
+    assert reactive_value is not None
+    updating = solara.use_ref(False)
+
+    def forward_on_change():
+        def forward(value):
+            if on_change_ref.current and not updating.current:
+                on_change_ref.current(value)
+
+        return reactive_value.subscribe(forward)
+
+    def update():
+        updating.current = True
+        try:
+            if not isinstance(value, solara.Reactive):
+                reactive_value.value = value
+        finally:
+            updating.current = False
+
+    solara.use_memo(update, [value])
+    # if value is a reactive variable, and it changes, we need to subscribe to the latest
+    # reactive variable, otherwise we only link to it once
+    solara.use_effect(forward_on_change, [value] if isinstance(value, solara.Reactive) else [])
+
+    return reactive_value

solara/hooks/use_thread.py

@@ -0,0 +1,129 @@
+import functools
+import inspect
+import logging
+import os
+import threading
+from typing import Callable, Iterator, Optional, TypeVar, Union, cast
+
+import solara
+from solara.datatypes import Result, ResultState
+from solara.util import cancel_guard, nullcontext
+
+SOLARA_ALLOW_OTHER_TRACER = os.environ.get("SOLARA_ALLOW_OTHER_TRACER", False) in (True, "True", "true", "1")
+T = TypeVar("T")
+logger = logging.getLogger("solara.hooks.use_thread")
+
+
+def use_thread(
+    callback: Union[
+        Callable[[threading.Event], T],
+        Iterator[Callable[[threading.Event], T]],
+        Callable[[], T],
+        Iterator[Callable[[], T]],
+    ],
+    dependencies=[],
+    intrusive_cancel=True,
+) -> Result[T]:
+    from .misc import use_force_update, use_retry
+
+    def make_event(*_ignore_dependencies):
+        return threading.Event()
+
+    def make_lock():
+        return threading.Lock()
+
+    lock: threading.Lock = solara.use_memo(make_lock, [])
+    updater = use_force_update()
+    result_state, set_result_state = solara.use_state(ResultState.INITIAL)
+    error = solara.use_ref(cast(Optional[Exception], None))
+    result = solara.use_ref(cast(Optional[T], None))
+    running_thread = solara.use_ref(cast(Optional[threading.Thread], None))
+    counter, retry = use_retry()
+    cancel: threading.Event = solara.use_memo(make_event, [*dependencies, counter])
+
+    def run():
+        set_result_state(ResultState.STARTING)
+
+        def runner():
+            wait_for_thread = None
+            with lock:
+                # if there is a current thread already, we'll need
+                # to wait for it. copy the ref, and set ourselves
+                # as the current one
+                if running_thread.current:
+                    wait_for_thread = running_thread.current
+                running_thread.current = threading.current_thread()
+            if wait_for_thread is not None:
+                set_result_state(ResultState.WAITING)
+                # don't start before the previous is stopped
+                try:
+                    wait_for_thread.join()
+                except:  # noqa
+                    pass
+                if threading.current_thread() != running_thread.current:
+                    # in case a new thread was started that also was waiting for the previous
+                    # thread to st stop, we can finish this
+                    return
+            # we previously set current to None, but if we do not do that, we can still render the old value
+            # while we can still show a loading indicator using the .state
+            # result.current = None
+            set_result_state(ResultState.RUNNING)
+
+            sig = inspect.signature(callback)  # type: ignore
+            if sig.parameters:
+                f = functools.partial(callback, cancel)  # type: ignore
+            else:
+                f = callback  # type: ignore
+            try:
+                try:
+                    # we only use the cancel_guard context manager around
+                    # the function calls to f. We don't want to guard around
+                    # a call to react, since that might slow down rendering
+                    # during rendering
+                    with cancel_guard(cancel) if intrusive_cancel else nullcontext():
+                        value = f()
+                    if inspect.isgenerator(value):
+                        while True:
+                            try:
+                                with cancel_guard(cancel) if intrusive_cancel else nullcontext():
+                                    result.current = next(value)
+                                    error.current = None
+                            except StopIteration:
+                                break
+                            # assigning to the ref doesn't trigger a rerender, so do it manually
+                            updater()
+                        if threading.current_thread() == running_thread.current:
+                            set_result_state(ResultState.FINISHED)
+                    else:
+                        result.current = value
+                        error.current = None
+                        if threading.current_thread() == running_thread.current:
+                            set_result_state(ResultState.FINISHED)
+                except Exception as e:
+                    error.current = e
+                    if threading.current_thread() == running_thread.current:
+                        logger.exception(e)
+                        set_result_state(ResultState.ERROR)
+                    return
+                except solara.util.CancelledError:
+                    pass
+                    # this means this thread is cancelled not be request, but because
+                    # a new thread is running, we can ignore this
+            finally:
+                if threading.current_thread() == running_thread.current:
+                    running_thread.current = None
+                    logger.info("thread done!")
+                    if cancel.is_set():
+                        set_result_state(ResultState.CANCELLED)
+
+        logger.info("starting thread: %r", runner)
+        thread = threading.Thread(target=runner, daemon=True)
+        thread.start()
+
+        def cleanup():
+            cancel.set()  # cleanup for use effect
+
+        return cleanup
+
+    solara.use_effect(run, dependencies + [counter])
+    return Result[T](value=result.current, error=error.current, state=result_state, cancel=cancel.set, _retry=retry)

solara/kitchensink.py

@@ -0,0 +1,8 @@
+import reacton  # noqa: F401
+from reacton import ipyvue as vue  # noqa: F401
+from reacton import ipyvuetify as v  # noqa: F401
+from reacton import ipywidgets as w  # noqa: F401
+
+import solara as sol  # noqa: F401
+
+from . import layout  # noqa: F401

solara/lab/__init__.py

@@ -0,0 +1,34 @@
+# isort: skip_file
+from .components import *  # noqa: F401, F403
+from .utils import cookies, headers  # noqa: F401, F403
+from ..lifecycle import on_kernel_start  # noqa: F401
+from ..tasks import task, use_task, Task, TaskResult  # noqa: F401, F403
+from ..toestand import computed  # noqa: F401
+
+
+def __getattr__(name):
+    # for backwards compatibility
+    from solara.components.cross_filter import (  # noqa: F401
+        CrossFilterDataFrame,
+        CrossFilterReport,
+        CrossFilterSelect,
+        CrossFilterSlider,
+    )
+    from solara.toestand import Reactive, Ref, State  # noqa: F401
+
+    if name == "CrossFilterDataFrame":
+        return CrossFilterDataFrame
+    elif name == "CrossFilterReport":
+        return CrossFilterReport
+    elif name == "CrossFilterSelect":
+        return CrossFilterSelect
+    elif name == "CrossFilterSlider":
+        return CrossFilterSlider
+    elif name == "Reactive":
+        return Reactive
+    elif name == "Ref":
+        return Ref
+    elif name == "State":
+        return State
+    else:
+        raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

solara/lab/components/__init__.py

@@ -0,0 +1,7 @@
+from .chat import ChatBox, ChatInput, ChatMessage  # noqa: F401
+from .confirmation_dialog import ConfirmationDialog  # noqa: F401
+from .input_date import InputDate, InputDateRange  # noqa: F401
+from .input_time import InputTime as InputTime
+from .menu import ClickMenu, ContextMenu, Menu  # noqa: F401 F403
+from .tabs import Tab, Tabs  # noqa: F401
+from .theming import ThemeToggle, theme, use_dark_effective  # noqa: F401