solara-ui 1.31.0__py2.py3-none-any.whl

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

@@ -0,0 +1,69 @@
+"""
+# 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.VBox() as main:
+        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}")
+
+    return main

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

@@ -0,0 +1,58 @@
+# 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
+```

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

@@ -0,0 +1,44 @@
+import time
+from pathlib import Path
+from typing import Optional, cast
+
+import solara
+from solara.alias import rv, 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])
+
+    with solara.VBox() as main:
+        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})")
+            rv.ProgressLinear(indeterminate=True)
+    return main

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,31 @@
+"""# 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()
+    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 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})")
+    return main
+
+
+__doc__ += apidoc(solara.Route, full=True)  # type: ignore

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

@@ -0,0 +1,80 @@
+"""
+# 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.VBox() as main:
+        with solara.HBox():
+            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}")
+    return main
+
+
+@solara.component
+def Page():
+    # this gets the top level routes, '/' and 'fruit'
+    route_current, routes_all = solara.use_route()
+    with solara.VBox() as main:
+        with solara.Card("Navigation using buttons"):
+            with solara.HBox():
+                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}")
+    return main
+
+
+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

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

@@ -0,0 +1,27 @@
+"""
+# on_kernel_start
+
+Run a function when a virtual kernel (re)starts and optionally run a cleanup function on shutdown.
+
+```python
+def on_kernel_start(f: Callable[[], Optional[Callable[[], None]]]) -> Callable[[], None]:
+    ...
+```
+
+`f` will be called on each virtual kernel (re)start. This (usually) happens each time a browser tab connects to the server
+[see solara server for more details](https://solara.dev/docs/understanding/solara-server).
+The (optional) function returned by `f` will be called on kernel shutdown.
+
+Note that the cleanup functions are called in reverse order with respect to the order in which they were registered
+(e.g. the cleanup function of the last call to `on_kernel_start` will be called first on kernel shutdown).
+
+The return value of on_kernel_start is a cleanup function that will remove the callback from the list of callbacks to be called on kernel start.
+
+During hot reload, the callbacks that are added from scripts or modules that will be reloaded will be removed before the app is loaded
+again. This can cause the order of the callbacks to be different than at first run.
+"""
+
+from solara.website.components import NoPage
+
+title = "on_kernel_start"
+Page = NoPage

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

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

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

@@ -0,0 +1,104 @@
+"""
+
+# Component.widget
+
+Create a classic ipywidget from a component.
+
+```python
+def widget(self, **kwargs):
+    ...
+```
+
+
+This will create a widget from the component. The widget will be a
+subclass of `ipywidgets.VBox` and `ipywidgets.ValueWidget`.
+
+Example
+
+```python
+import solara
+widget = solara.FileDownload.widget(data="some text data", filename="solara-demo.txt")
+```
+
+This is very useful if you are migrating your application from a classic
+ipywidget to solara. See [also the ipywidgets tutorial](/documentation/getting_started/tutorials/ipywidgets).
+
+The `ipywidgets.ValueWidget` is used to enable the use of the widget in
+interact, or interactive. The `ipywidgets.VBox` is used to enable
+nesting of widgets.
+
+All keyword arguments will be passed to the component.
+Each argument pair of `on_<name>` and `<name>` will
+be added as a trait in the widget.
+
+For example,
+
+```solara
+import solara
+import ipywidgets as widgets
+import random
+
+
+countries_demo_data = {
+    "Netherlands": ["Amsterdam", "Rotterdam", "The Hague"],
+    "Germany": ["Berlin", "Hamburg", "Munich"],
+    "France": ["Paris", "Marseille", "Lyon"],
+}
+
+
+# this component can be used in a component three, but ...
+@solara.component
+def LocationSelect(value, on_value, countries=countries_demo_data):
+    country, city = value
+    cities = countries.get(country, [])
+    # reset to None if not in the list of countries
+    if city not in cities:
+        city = None
+        # update the state if we changed/reset city
+        on_value((country, city))
+
+    with solara.Card("Location"):
+        solara.Select(label="country",
+                      values=list(countries),
+                      value=country,
+                      on_value=lambda country: on_value((country, city)),
+        )
+        solara.Select(label="city",
+                      values=cities,
+                      value=city,
+                      on_value=lambda city: on_value((country, city)),
+        )
+
+
+# Using .widget(...) we can create a widget from it.
+# For use with interact:
+@widgets.interact(location=LocationSelect.widget(value=("Netherlands", "Amsterdam")))
+def f(size=3.4, location=None):
+    print(size, location)
+
+
+# Or to add to your VBox:
+widgets.VBox(
+    [LocationSelect.widget(value=("Netherlands", "Amsterdam"))]
+)
+
+# this is how you'd use it as a component
+@solara.component
+def Page():
+    value, set_value = solara.use_state(("Netherlands", "Amsterdam"))
+    def pick():
+        country = random.choice(list(countries_demo_data))
+        city = random.choice(countries_demo_data[country])
+        set_value((country, city))
+
+    LocationSelect(value=value, on_value=set_value)
+    solara.Button("Pick random place", on_click=pick)
+
+```
+
+"""
+
+from solara.website.components import NoPage
+
+Page = NoPage
+title = "widget"

solara/website/pages/documentation/components/__init__.py

@@ -0,0 +1,12 @@
+import solara
+from solara.website.components import CategoryLayout, Gallery
+
+
+@solara.component
+def Page(route_external=None):
+    Gallery(route_external)
+
+
+@solara.component
+def Layout(children=[]):
+    CategoryLayout(children=children)