solara-ui 1.45.0__py3-none-any.whl

solara/website/pages/documentation/api/hooks/use_effect.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+from solara.website.components import NoPage
+
+HERE = Path(__file__).parent
+__doc__ = open(HERE / "use_effect.md").read()
+
+Page = NoPage
+title = "use_effect"

solara/website/pages/documentation/api/hooks/use_exception.py

@@ -0,0 +1,31 @@
+import solara
+
+title = "use_exception"
+set_fail = None
+clear = None
+
+
+@solara.component
+def UnstableComponent(number: int):
+    if number == 3:
+        raise Exception("I do not like 3")
+    return solara.Text(f"You picked {number}")
+
+
+@solara.component
+def Page():
+    value, set_value = solara.use_state(1)
+    value_previous = solara.use_previous(value)
+    exception, clear_exception = solara.use_exception()
+    # print(exception)
+    if exception:
+
+        def reset():
+            set_value(value_previous)
+            clear_exception()
+
+        solara.Text("Exception: " + str(exception))
+        solara.Button(label="Go to previous state", on_click=reset)
+    else:
+        solara.IntSlider(value=value, min=0, max=10, on_value=set_value, label="Pick a number, except 3")
+        UnstableComponent(value)

solara/website/pages/documentation/api/hooks/use_memo.md

@@ -0,0 +1,16 @@
+# use_memo
+
+```python
+def use_memo(
+    f: Any,
+    dependencies: Any | None = None,
+    debug_name: str = None
+) -> Any:
+    ...
+```
+
+`use_memo` stores ([memoize](https://en.wikipedia.org/wiki/Memoization)) the function return on first render, and then excludes it from being re-executed, except when one of the `dependencies` changes. `dependencies` can take the value `None`, in which case dependencies are automatically obtained from nonlocal variables. If an empty list is passed as `dependencies` instead, the function is only executed once over the entire lifetime of the component.
+
+Not to be confused with [memorize](https://solara.dev/documentation/api/utilities/memoize) which can cache multiple return values and which can be used outside of component.
+
+See also the [Reacton docs](https://reacton.solara.dev/en/latest/api/#use_memo).

solara/website/pages/documentation/api/hooks/use_memo.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+from solara.website.components import NoPage
+
+HERE = Path(__file__).parent
+__doc__ = open(HERE / "use_memo.md").read()
+
+Page = NoPage
+title = "use_memo"

solara/website/pages/documentation/api/hooks/use_previous.py

@@ -0,0 +1,30 @@
+"""
+# use_previous
+
+```python
+def use_previous(value: T) -> T:
+    ...
+```
+
+Returns the value from a previous render phase, or the current value on the first render.
+
+
+"""
+
+import solara
+
+title = "use_previous"
+
+
+@solara.component
+def Page():
+    value, set_value = solara.use_state(4)
+    value_previous = solara.use_previous(value)
+    solara.IntSlider("value", value=value, on_value=set_value)
+    solara.Markdown(
+        f"""
+    **Current**:  `{value}`
+
+    **Previous**: `{value_previous}`
+"""
+    )

solara/website/pages/documentation/api/hooks/use_reactive.py

@@ -0,0 +1,16 @@
+"""
+# use_reactive
+
+"""
+
+import solara
+from solara.website.components import NoPage
+from solara.website.utils import apidoc
+
+title = "use_reactive"
+
+
+Page = NoPage
+
+
+__doc__ += apidoc(solara.use_reactive)  # type: ignore

solara/website/pages/documentation/api/hooks/use_state.py

@@ -0,0 +1,10 @@
+"""# use_state"""
+
+import solara
+import solara.autorouting
+from solara.website.components import NoPage
+from solara.website.utils import apidoc
+
+title = "use_state"
+Page = NoPage
+__doc__ += apidoc(solara.use_state)  # type: ignore

solara/website/pages/documentation/api/hooks/use_state_or_update.py

@@ -0,0 +1,66 @@
+"""
+# use_state_or_update
+
+Like `solara.use_state`, except it will update the value if the input value changes.
+
+This is useful to give a component state *or* allow the state to be controlled by the parent component
+
+
+"""
+
+import solara
+
+title = "use_state_or_update"
+
+
+@solara.component
+def SliderWithoutState(value: int):
+    # Note that this is a very bad practice, if value is an input change and the slider
+    # can change it, this component should have a on_value callback to allow the parent
+    # component to manage its state.
+    # This component is only for demoing/understanding.
+    return solara.IntSlider("value", value=value)
+
+
+@solara.component
+def SliderWithState(value: int):
+    # effectively, because of use_state, the value prop passed in is
+    # only a default value.
+    value, set_value = solara.use_state(value)
+    return solara.IntSlider("value", value=value, on_value=set_value)
+
+
+@solara.component
+def SliderWithStateOrUpdate(value: int):
+    value, set_value = solara.use_state_or_update(value)
+    return solara.IntSlider("value", value=value, on_value=set_value)
+
+
+@solara.component
+def Page():
+    parent_value, set_parent_value = solara.use_state(4)
+    # used to force rerenders
+    rerender_counter, set_rerender_counter = solara.use_state(4)
+    with solara.Card("Parent value selection"):
+        solara.Info("This slider value gets passed down to the child components")
+        solara.IntSlider("parent value", value=parent_value, on_value=set_parent_value)
+        solara.Button("Force redraw", on_click=lambda: set_rerender_counter(rerender_counter + 1))
+
+    with solara.Card("Child without state"):
+        solara.Info("This child will simply render the value passed into the argument, a redraw will reset it to its parent value.")
+        SliderWithoutState(parent_value)
+
+    with solara.Card("Child with state"):
+        solara.Info("This child will not care about the value passed into the prop, it manages its own state.")
+        SliderWithState(parent_value)
+
+    with solara.Card("Child with state (or update)"):
+        solara.Info("This child will update when the passes in a new value, but a redraw will not reset it.")
+        SliderWithStateOrUpdate(parent_value)
+
+    with solara.Card("Child with state + key"):
+        solara.Info(
+            "We can also use the `.key(...)` method to force the component to forget its state, this will however cause the widget to be re-created"
+            "(a performance penalty)."
+        )
+        SliderWithState(parent_value).key(f"slider-{parent_value}")

solara/website/pages/documentation/api/hooks/use_thread.md

@@ -0,0 +1,64 @@
+# use_thread
+
+```python
+def use_thread(
+    callback=Union[
+        Callable[[threading.Event], T],
+        Iterator[Callable[[threading.Event], T]],
+        Callable[[], T],
+        Iterator[Callable[[], T]],
+    ],
+    intrusive_cancel=True,
+    dependencies=[],
+) -> Result[T]:
+    ...
+```
+
+`use_thread` can be used to run medium or long running jobs in a separate thread to avoid blocking the render loop.
+
+`use_thread` takes a function as argument that takes a `threading.Event` object as argument to check whether it should stop,
+and should return it's resulting value, or yield it multiple times (thus an iterator).
+
+The return value of `use_thread` is a `Result[T]`, making it easy to have the UI reflect the state of the work being done.
+
+When an iterator is passed, the state only enters the `FINISHED` state after the last element is yielded. Partial, or incremental results can be detected when the state is still in `RUNNING`, but `Result[T].value` is not None.
+
+
+
+From any state the `.cancel()` or `.retry()` may be called, which will stop the current thread, and start all over.
+Note that at no time, two threads will run, since the new thread will always wait for the previous to finish.
+
+When `intrusive_cancel=True`, a tracer is installed into the thread, which will throw a special exception to cancel the thread. This gives some runtime overhead, and a more performant way would be to set this to false and manually inspect the `threading.Event` regularly. When this is not possible (e.g. usage of an external library), this is the only way to cancel a thread while executing.
+
+
+Note that `.value` and `.error` of the result object will only be set when a new result is returned. This makes is possible for a component to render the "previous" result (or previous error) while the new job is running.
+
+## State diagram
+
+The possible values for `Result[T].state` are stored in the dataclass `solara.ResultState`, with the possible options being
+
+* `STARTING`
+* `WAITING`
+* `RUNNING`
+* `ERROR`
+* `FINISHED`
+* `CANCELLED`
+
+These states are reflected in the below state diagram
+
+```mermaid
+graph TD;
+    INITIAL-- "Thread.start()" -->STARTING;
+    STARTING-- "previous thread running" -->WAITING;
+    STARTING-- "no previous thread" -->RUNNING;
+    WAITING-- "thread.join()" -->RUNNING;
+    RUNNING-- "on exception" -->ERROR
+    RUNNING-- "work finished" -->FINISHED
+    RUNNING-- "cancel()" -->CANCELLED
+```
+
+## Future deprecation
+
+Note that [`use_task`](/https://solara.dev/documentation/components/lab/use_task) is an alternative to `use_thread` that will most likely
+replace `use_thread` in the future. Compared to `use_thread`, `use_task` has no intrusive cancel, which turned out to be too large of
+a performance overhead to be useful. Also, `use_task` can run async functions, which is not possible with `use_thread`.

solara/website/pages/documentation/api/hooks/use_thread.py

@@ -0,0 +1,42 @@
+import time
+from pathlib import Path
+from typing import Optional, cast
+
+import solara
+from solara.alias import rw
+
+HERE = Path(__file__).parent
+title = "use_thread"
+__doc__ = open(HERE / "use_thread.md").read()
+
+
+@solara.component
+def Page():
+    number, set_number = solara.use_state(17)
+    # the number that proofs it is not a prime
+    proof, set_proof = solara.use_state(cast(Optional[int], None))
+
+    def work():
+        for i in range(3, number):
+            reminder = number % i
+            if reminder == 0:
+                set_proof(i)
+                return False
+            # make it always take ~4 seconds
+            time.sleep(4 / number)
+        return True
+
+    # work will be cancelled/restarted every time the dependency changes
+    result: solara.Result[bool] = solara.use_thread(work, dependencies=[number])
+
+    rw.IntText(value=number, on_value=set_number)
+    if result.state == solara.ResultState.FINISHED:
+        if result.value:
+            solara.Success(f"{number} is a prime!")
+        else:
+            solara.Error(f"{number} is not a prime, it can be divided by {proof} ")
+    elif result.state == solara.ResultState.ERROR:
+        solara.Error(f"Error occurred: {result.error}")
+    else:
+        solara.Info(f"Running... (status = {result.state})")
+        solara.v.ProgressLinear(indeterminate=True)

solara/website/pages/documentation/api/hooks/use_trait_observe.py

@@ -0,0 +1,12 @@
+"""# use_trait_observe"""
+
+import solara
+import solara.autorouting
+import solara.lab
+from solara.website.utils import apidoc
+
+from . import NoPage
+
+title = "use_trait_observe"
+Page = NoPage
+__doc__ += apidoc(solara.use_trait_observe)  # type: ignore

solara/website/pages/documentation/api/routing/__init__.py

@@ -0,0 +1,9 @@
+import solara
+from solara.website.components import NoPage, SubCategoryLayout
+
+Page = NoPage
+
+
+@solara.component
+def Layout(children=[]):
+    SubCategoryLayout(children=children)

solara/website/pages/documentation/api/routing/generate_routes.py

@@ -0,0 +1,10 @@
+"""# generate_routes"""
+
+import solara
+import solara.autorouting
+from solara.website.components import NoPage
+from solara.website.utils import apidoc
+
+title = "generate_routes"
+Page = NoPage
+__doc__ += apidoc(solara.autorouting.generate_routes)  # type: ignore

solara/website/pages/documentation/api/routing/generate_routes_directory.py

@@ -0,0 +1,10 @@
+"""# generate_routes_directory"""
+
+import solara
+import solara.autorouting
+from solara.website.components import NoPage
+from solara.website.utils import apidoc
+
+title = "generate_routes_directory"
+Page = NoPage
+__doc__ += apidoc(solara.autorouting.generate_routes_directory)  # type: ignore

solara/website/pages/documentation/api/routing/resolve_path.py

@@ -0,0 +1,35 @@
+"""# resolve_route"""
+
+import solara
+from solara.website.utils import apidoc
+
+title = "resolve_route"
+routes = [
+    solara.Route(path="/"),
+    solara.Route(path="kiwi"),
+    solara.Route(path="banana"),
+    solara.Route(path="apple"),
+]
+
+
+@solara.component
+def Page():
+    route_current, routes = solara.use_route()
+    with solara.VBox() as main:
+        # solara.Warning("Note the address bar in the browser. It should change to the path of the link.")
+        solara.Markdown("*Click on one of the links below to change the route and see the url in your browser change, and match the text.*")
+        with solara.VBox():
+            for route in routes:
+                path = solara.resolve_path(route)
+                # we could have passed the route object directly to Link, but we want to show the path
+                # can also be used.
+                with solara.Link(path):
+                    current = route_current is route
+                    if current:
+                        solara.Success(f"You are at {path}")
+                    else:
+                        solara.Info(f"{route.path} will navigate to {path}")
+    return main
+
+
+__doc__ += apidoc(solara.resolve_path)  # type: ignore

solara/website/pages/documentation/api/routing/route.py

@@ -0,0 +1,29 @@
+"""# Route"""
+
+import solara
+from solara.website.utils import apidoc
+
+routes = [
+    solara.Route(path="/"),
+    solara.Route(path="kiwi"),
+    solara.Route(path="banana"),
+    solara.Route(path="apple"),
+]
+
+
+@solara.component
+def Page():
+    route_current, routes = solara.use_route()
+
+    solara.Markdown("*Click on one of the links below to change the route and see the url in your browser change, and match the route.*")
+    with solara.VBox():
+        for route in routes:
+            with solara.Link(route):
+                current = route_current is route
+                if current:
+                    solara.Success(f"You are at solara.Route(path={route.path!r})")
+                else:
+                    solara.Info(f"Go to solara.Route(path={route.path!r})")
+
+
+__doc__ += apidoc(solara.Route, full=True)  # type: ignore

solara/website/pages/documentation/api/routing/use_route.py

@@ -0,0 +1,76 @@
+"""
+# use_route
+"""
+
+import solara
+from solara.website.utils import apidoc
+
+title = "use_route"
+
+
+@solara.component
+def Fruit():
+    # this gets all routes in fruit's children
+    route, routes = solara.use_route()
+
+    if route is None:
+        with solara.Link("banana") as main:
+            solara.Button("Fruit not found, go to banana")
+        return main
+
+    if route.path == "/":
+        with solara.Link("banana") as main:
+            solara.Button("Choose a fruit, I recomment banana")
+        return main
+
+    with solara.Row():
+        for route_fruit in routes[1:]:
+            with solara.Link(solara.resolve_path(route_fruit)):
+                solara.Button(route_fruit.path)
+
+        with solara.Link("/documentation/api/routing/use_route/fruit/nofruit", nofollow=True):
+            solara.Button("Wrong fruit")
+        with solara.Link("/documentation/api/routing/use_route/not-routed", nofollow=True):
+            solara.Button("Wrong url")
+    solara.Success(f"You chose {route.path}")
+
+
+@solara.component
+def Page():
+    # this gets the top level routes, '/' and 'fruit'
+    route_current, routes_all = solara.use_route()
+    with solara.Card("Navigation using buttons"):
+        with solara.Row():
+            for route in routes_all:
+                with solara.Link(route):
+                    solara.Button(route.path, color="red" if route_current == route else None)
+    with solara.Card("Content decided by route:"):
+        if route_current is None:
+            solara.Error("Page does not exist")
+            with solara.Link("fruit/kiwi"):
+                solara.Button("Go to fruit/kiwi")
+        elif route_current.path == "/":
+            with solara.Link("fruit/banana"):
+                solara.Button("Go to fruit/banana")
+        elif route_current.path == "fruit":
+            Fruit()
+        else:
+            solara.Error(f"Unknown route: {route_current.path}")
+
+
+routes = [
+    solara.Route(path="/"),
+    solara.Route(
+        path="fruit",
+        component=Fruit,
+        children=[
+            solara.Route(path="/"),
+            solara.Route(path="kiwi"),
+            solara.Route(path="banana"),
+            solara.Route(path="apple"),
+        ],
+    ),
+]
+
+sources = [Fruit.f, Page.f]  # type: ignore
+__doc__ += apidoc(solara.use_route)  # type: ignore

solara/website/pages/documentation/api/routing/use_router.py

@@ -0,0 +1,16 @@
+"""
+# use_router
+
+"""
+
+import solara
+from solara.website.components import NoPage
+from solara.website.utils import apidoc
+
+title = "use_router"
+
+
+Page = NoPage
+
+
+__doc__ += apidoc(solara.use_router)  # type: ignore

solara/website/pages/documentation/api/utilities/__init__.py

@@ -0,0 +1,9 @@
+import solara
+from solara.website.components import NoPage, SubCategoryLayout
+
+Page = NoPage
+
+
+@solara.component
+def Layout(children=[]):
+    SubCategoryLayout(children=children)

solara/website/pages/documentation/api/utilities/component_vue.py

@@ -0,0 +1,10 @@
+"""# component_vue"""
+
+import solara
+import solara.autorouting
+from solara.website.components import NoPage
+from solara.website.utils import apidoc
+
+title = "component_vue"
+Page = NoPage
+__doc__ += apidoc(solara.component_vue)  # type: ignore

solara/website/pages/documentation/api/utilities/computed.py

@@ -0,0 +1,16 @@
+"""
+# computed
+
+"""
+
+import solara
+from solara.website.components import NoPage
+from solara.website.utils import apidoc
+
+title = "computed"
+
+
+Page = NoPage
+
+
+__doc__ += apidoc(solara.lab.computed)  # type: ignore

solara/website/pages/documentation/api/utilities/display.py

@@ -0,0 +1,16 @@
+"""
+# display
+
+"""
+
+import solara
+from solara.website.components import NoPage
+from solara.website.utils import apidoc
+
+title = "display"
+
+
+Page = NoPage
+
+
+__doc__ += apidoc(solara.display)  # type: ignore

solara/website/pages/documentation/api/utilities/get_kernel_id.py

@@ -0,0 +1,16 @@
+"""
+# get_kernel_id
+
+"""
+
+import solara
+from solara.website.components import NoPage
+from solara.website.utils import apidoc
+
+title = "get_kernel_id"
+
+
+Page = NoPage
+
+
+__doc__ += apidoc(solara.get_kernel_id)  # type: ignore

solara/website/pages/documentation/api/utilities/get_session_id.py

@@ -0,0 +1,16 @@
+"""
+# get_session_id
+
+"""
+
+import solara
+from solara.website.components import NoPage
+from solara.website.utils import apidoc
+
+title = "get_session_id"
+
+
+Page = NoPage
+
+
+__doc__ += apidoc(solara.get_session_id)  # type: ignore

solara/website/pages/documentation/api/utilities/memoize.py

@@ -0,0 +1,35 @@
+"""#Memoize"""
+
+import time
+
+import solara
+import solara.lab
+from solara.website.utils import apidoc
+
+# make sure the cache is only created once
+storage = solara.cache.Memory(max_items=2)
+
+
+@solara.component
+def Page():
+    x, set_x = solara.use_state(5)
+
+    @solara.memoize(storage=storage)
+    def long_running_function(x: int) -> int:
+        """This function takes a long time to run."""
+        time.sleep(3)
+        return x**2
+
+    result = long_running_function.use_thread(x)
+
+    with solara.Card("Expensive computation") as main:
+        solara.Markdown("We cache 2 values. Each computation takes 3 seconds. If you go back to a cached value, you will see the result immediately.")
+        solara.IntSlider("x", value=x, on_value=set_x)
+        if result.state == solara.ResultState.FINISHED:
+            solara.Markdown(f"Square of {x} is {result.value}")
+        else:
+            solara.Markdown("Running...")
+    return main
+
+
+__doc__ += apidoc(solara.memoize)  # type: ignore