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

solara/website/pages/documentation/getting_started/content/04-tutorials/30-ipywidgets.md

@@ -0,0 +1,124 @@
+---
+title: Tutorial - Building ipywidgets based apps
+description: Ipywidgets can be used together with Solara to build and quickly get to users your data apps or dashboards.
+---
+# Tutorial: IPywidgets
+
+If you are already using [ipywidgets](/documentation/advanced/understanding/ipywidgets) in the notebook, possibly using [Voila](/documentation/advanced/understanding/voila), you might be pleased to know that you
+can also use the [Solara server](/documentation/advanced/understanding/solara-server) to render your regular ipywidget application.
+
+We recommend you learn how to write applications using [Reacton](/documentation/advanced/understanding/reacton). However, if you have already written an application in
+pure [ipywidgets](/documentation/advanced/understanding/ipywidgets), this approach will let you gradually move from pure ipywidgets to Reacton.
+
+## You should know
+This tutorial will assume you have successfully installed Solara.
+
+If not, please follow the [Installation guide](/documentation/getting_started/installing).
+
+## Your first ipywidget based Solara app
+
+Put the following code in a file called `sol-ipywidgets.py`:
+
+```python
+import ipywidgets as widgets
+
+clicks = 0
+
+print("I get run at startup, and for every page request")
+
+def on_click(button):
+    global clicks
+    clicks += 1
+    button.description = f"Clicked {clicks} times"
+
+
+button = widgets.Button(description="Clicked 0 times")
+button.on_click(on_click)
+```
+
+And run the following command in your shell
+```bash
+$ solara run sol-ipywidgets.py:button
+Solara server is starting at http://localhost:8765
+I get run at startup, and for every page request
+...
+# your browser opens http://localhost:8765
+I get run at startup, and for every page request
+...
+```
+
+The Solara server will execute your script once before any browser connects,
+as demonstrated by the `"I get run at startup, and for every page request"` output.
+
+The `:button` part on the command line tells the Solara server the variable name of
+the widget it should render. The default name for a widget variable Solara will look
+for is `page`.
+
+For every page request (for instance, you open a second tab, or do a page refresh)
+you will see the same text printed out in the terminal.
+This tell you that each "tab" gets its own run, and its own namespace, which means
+that the `clicks` variable is not shared between multiple users.
+
+If you refresh the page, the script is executed again, and the `clicks` is set to
+`0` again.
+
+## Hot reloading
+
+If you edit your script, and save it, Solara server will re-execute it for all connected users without you having to manually refresh your browser.
+
+Try making the following code change (remove the first, add the last), and watch your browser page instantly refresh.
+```diff
+- button = widgets.Button(description="Clicked 0 times")
++ button = widgets.Button(description="Did not click yet!")
+```
+
+## Using Solara components
+
+There are a lot of [valuable components in Solara](/documentation/components), but they are written as [Reacton/Solara components](/documentation/advanced/understanding/reacton-basics), not
+classic ipywidgets.
+
+Use the [.widget(...)](/documentation/api/utilities/widget) method on a component to create a widget that can be used in your existing classic ipywidget application.
+
+```python
+
+import ipywidgets as widgets
+
+import solara
+
+clicks = 0
+
+
+def on_click(button):
+    global clicks
+    clicks += 1
+    button.description = f"Clicked {clicks} times"
+
+
+button = widgets.Button(description="Clicked 0 times")
+button.on_click(on_click)
+
+page = widgets.VBox(
+    [
+        button,
+        # using .widget(..) we can create a classic ipywidget from a solara component
+        solara.FileDownload.widget(data="some text data", filename="solara-demo.txt"),
+    ]
+)
+```
+
+Now we can run this app using:
+```
+$ solara run sol-ipywidgets.py
+```
+
+Note that we did not include the `:page` here, since solara will automatically look for that.
+
+## What you have learned
+
+  * [Solara server](/documentation/advanced/understanding/solara-server) can render [ipywidgets](/documentation/advanced/understanding/ipywidgets).
+  * Running `$ solara run filename.py:variablename` tells Solara which script to execute and which variable name from the script to render.
+  * The script is executed:
+    * Once, when the solara server starts.
+    * On each page request.
+    * For each open browser page/tab, when the script is saved (hot reloading).
+  * Using the [.widget(...)](/documentation/api/utilities/widget) method we can start using Solara components in classic ipywidget app.

solara/website/pages/documentation/getting_started/content/04-tutorials/40-streamlit.md

@@ -0,0 +1,146 @@
+---
+title: Using Solara as a more scalable alternative to Streamlit
+description: If you are coming from Streamlit, it should be simple to adapt to using Solara, and take advantage of partial re-execution, state
+    management, and reusable components.
+---
+# Tutorial: Streamlit
+
+If you are coming from [Streamlit](https://streamlit.io/) you may be happy to know Solara does not re-execute your whole script. We execute components (starting with the `Page` component), and only need to re-execute what needs to.
+
+
+## Streamlit example
+Let us start with a typical streamlit example:
+
+```python
+import streamlit as st
+
+with st.sidebar:
+    st.markdown("## My First Solara tutorial ☀️")
+    x = st.slider("x")
+x_squared = x**2
+st.markdown(f"{x} squared = {x_squared}")
+```
+
+## Translated to Solara
+
+We now translate this to the equivalent in Solara. The largest difference is we need to explicitly create (application) state using [`solara.reactive`](/documentation/api/utilities/reactive). By passing the
+reactive variable to the [SliderInt](/documentation/components/input/slider) via `value=x` we set up a two way binding between the component and the reactive variable. The generated text is passed down to the [Markdown](/documentation/components/output/markdown) component.
+
+
+```solara
+import solara
+
+x = solara.reactive(2)
+
+
+@solara.component
+def Page():
+    x_squared = x.value**2
+
+    with solara.Sidebar():
+        solara.Markdown("## My First Solara app ☀️")
+        solara.SliderInt(label="x", value=x)
+    solara.Markdown(f"{x.value} squared = {x_squared}")
+```
+
+### Running this example using Solara server
+
+If you put this script in a file called `sol.py` and run
+```
+$ solara run sol.py
+```
+You will see:
+![app screenshot](https://dxhl76zpt6fap.cloudfront.net/public/docs/app-squared.webp)
+
+Because we do some styling and because the sidebar is already used up, our preview on this page looks slightly different.
+
+[Navigate to /apps/tutorial-streamlit](/apps/tutorial-streamlit) to see this app fullscreen.
+
+
+### Running this example in the notebook
+
+If you add the above code snippet to your notebook, and include `Page()` at the end of your notebook cell, you should see:
+![app screenshot](https://dxhl76zpt6fap.cloudfront.net/public/docs/app-squared-notebook.webp)
+
+Again, slightly different for a different environment.
+
+## Hot reloading
+
+If you are using [Solara server](/documentation/advanced/understanding/solara-server), try editing `sol.py`, and watch the page reload automatically after you save your file. Notebook users can simply edit and re-run.
+
+(*Note: Upgrade to solara 1.14.0 for a fix in hot reloading using `pip install "solara>=1.14.0"`*)
+
+## How are streamlit and Solara different?
+
+### Execution model
+As the introduction says, Solara does not re-execute your whole script after user interactions.
+The main script is executed only once. With Solara you can use your main script to read large dataframes, or do some pre-calculations without the need for [caching](/documentation/advanced/reference/caching).
+
+When a user navigates to a Solara server, the `Page` component (basically a function) will get executed. The `Page` component will call (lazily) new components like [solara.Markdown](/documentation/components/output/markdown) to build up the page. If state changes due to user input, Solara will trigger a cascade of re-excecutions of components which inputs or state changed, but never your whole script, nor every component.
+
+### State
+With Solara (and [Reacton](/documentation/advanced/understanding/reacton)) state does not live in a UI component (like a slider). Application state created with [`solara.reactive`](/documentation/api/utilities/reactive) lives on its own. Connecting the state to the UI component (in this case a slider) is a separate step, done via `value=x` in the above example. In general we recommend organising your components
+similarly as in the example: [First use_state and other hooks, then calculations, at last the UI components](/documentation/advanced/understanding/anatomy).
+
+For complex situations, it is important to separate the state and the UI. Especially when you need the state of a UI component as input of the UI component itself, you can get stuck with streamlit. In Solara this follows naturally.
+
+
+## Creating a reusable component
+
+
+A big advantage of Solara is that you can create reusable components. A single component can be seen as the equivalent of a single streamlit script. However, in that case, we need to modify our component to have its own state, rather than using global application state, for this you can use the [`use_reactive`](/documentation/api/hooks/use_reactive), or [`use_state`](/documentation/api/hooks/use_state) hook.
+Read more about state management in the [state management](/documentation/getting_started/fundamentals/state-management) section.
+
+```solara
+import solara
+
+
+@solara.component
+def Square(name: str):
+    # x = solara.use_reactive(2)  # another possibility
+    x, set_x = solara.use_state(2)
+    y = x**2
+    with solara.Sidebar():
+        solara.SliderInt(label=name, value=x, on_value=set_x)
+    solara.Markdown(f'{name}: {x} squared = {y}')
+
+
+@solara.component
+def Page():
+    Square('a')
+    Square('b')
+```
+
+In this example, each instance of the `Square` component, calls `use_state`, and therefore has its own private
+x variable. Truly reusable UI components!
+
+In streamlit, this is trickier. While this would work:
+
+```python
+import streamlit as st
+
+
+def square(name):
+    with st.sidebar:
+        x = st.slider(name)
+    x_squared = x**2
+    st.markdown(f"{name}: {x} squared = {x_squared}")
+
+square("x")
+square("y")
+```
+
+Changing that "y" to "x" will lead to an error, however. If this is a problem in practice depends on the situation.
+
+### Long running function
+
+In Streamlit, it is normal for your main script to block execution. In Solara, the functions bodies of your components ([called render functions](/documentation/advanced/understanding/anatomy)) should not block. Functions that block, or take a long time to execute, should be executed in a thread, such that rendering can continue. Using threads may sound scary, but using the
+[use_thread](/documentation/api/hooks/use_thread) hook will help a lot.
+
+## What you have learned
+
+ * Solara will not continuously re-execute your script as Streamlit does.
+ * Solara will re-execute components instead, only what needs to.
+ * State in Solara is separate from the UI components, unlike streamlit, where they are strongly linked.
+ * State can be on the application level (global) for simplicity or on the component level (local) for creating reusable components.
+ * Solara should not block the render loop. Long-running functions should be executed in a thread using [use_thread](/documentation/api/hooks/use_thread).

solara/website/pages/documentation/getting_started/content/04-tutorials/50-dash.md

@@ -0,0 +1,144 @@
+---
+title: Using Solara as an alternative to Dash
+description: If you are familiar with Dash, Solara should be easy to adapt to. In Solara the state is managed and stored on the server, and components are declaratively reusable.
+---
+# Tutorial: Dash users
+
+Dash is quite different from Solara. In Dash, state lives in your browser, and via callbacks your app will change from 1 state to another. In Solara, the state lives on the server, and also state transitions happen at the server.
+
+## Dash example
+To see how Dash and Solara are different, let us start with a typical Dash example:
+
+```python
+from dash import Dash, Input, Output, callback, dcc, html
+
+app = Dash(__name__)
+
+app.layout = html.Div(
+    children=[
+        dcc.Dropdown(id="dropdown", options=["red", "green", "blue", "orange"]),
+        dcc.Markdown(id="markdown", children=["## Hello World"]),
+    ]
+)
+
+
+@callback(
+    Output("markdown", "style"),
+    Input("dropdown", "value"),
+)
+def update_markdown_style(color):
+    return {"color": color}
+
+
+if __name__ == "__main__":
+    app.run_server(debug=True)
+```
+
+*This example is inspired on [a dash example](https://dash.plotly.com/all-in-one-components).*
+
+This small app creates a dropdown (what we call Select in Solara), and some markdown text. The dropdown will trigger the callback at the server, which will update the markdown's style, which will cause the color of the text to change.
+
+## Translated to Solara
+
+In Solara, we need to explicitly create application state using [`solara.reactive`](/documentation/api/utilities/reactive). We wire this up with the [Select][/documentation/components/input/select] via `value=color` and pass the color value down to the [Markdown](/documentation/components/output/markdown) component.
+
+```solara
+import solara
+
+color = solara.reactive("red")
+
+
+@solara.component
+def Page():
+    solara.Select(label="Color", values=["red", "green", "blue", "orange"], value=color)
+    solara.Markdown("## Hello World", style={"color": color.value})
+```
+
+Since this component combines two components, we have to put them together in a [container](/documentation/advanced/understanding/containers) component, here implicitly a [Column](/documentation/components/layout/column).
+
+## Making a reusable component
+
+### In dash
+
+Following the [All in one component documentation](https://dash.plotly.com/all-in-one-components), we get:
+
+```python
+import uuid
+
+from dash import MATCH, Dash, Input, Output, State, callback, dcc, html
+
+
+class MarkdownWithColorAIO(html.Div):
+    class ids:
+        dropdown = lambda aio_id: {"component": "MarkdownWithColorAIO", "subcomponent": "dropdown", "aio_id": aio_id}
+        markdown = lambda aio_id: {"component": "MarkdownWithColorAIO", "subcomponent": "markdown", "aio_id": aio_id}
+
+    ids = ids
+
+    def __init__(self, text, colors=None, markdown_props=None, dropdown_props=None, aio_id=None):
+        colors = colors if colors else ["red", "green", "blue", "orange"]
+
+        if aio_id is None:
+            aio_id = str(uuid.uuid4())
+
+        dropdown_props = dropdown_props.copy() if dropdown_props else {}
+        if "options" not in dropdown_props:
+            dropdown_props["options"] = [{"label": i, "value": i} for i in colors]
+        dropdown_props["value"] = dropdown_props["options"][0]["value"]
+
+        markdown_props = markdown_props.copy() if markdown_props else {}
+        if "style" not in markdown_props:
+            markdown_props["style"] = {"color": dropdown_props["value"]}
+        if "children" not in markdown_props:
+            markdown_props["children"] = text
+        super().__init__([dcc.Dropdown(id=self.ids.dropdown(aio_id), **dropdown_props), dcc.Markdown(id=self.ids.markdown(aio_id), **markdown_props)])
+
+    @callback(
+        Output(ids.markdown(MATCH), "style"),
+        Input(ids.dropdown(MATCH), "value"),
+        State(ids.markdown(MATCH), "style"),
+    )
+    def update_markdown_style(color, existing_style):
+        existing_style["color"] = color
+        return existing_style
+
+
+app = Dash(__name__)
+
+app.layout = html.Div(
+    children=[
+        MarkdownWithColorAIO("## Hello World1"),
+        MarkdownWithColorAIO("## Hello World2"),
+    ]
+)
+
+if __name__ == "__main__":
+    app.run_server(debug=True)
+
+```
+
+### In Solara
+
+A big advantage of Solara is that components are reusable by default. However, we need to modify our component to have its own state, rather than using global application state. Creating local component state with [`use_reactive`](/documentation/api/hooks/use_reactive), or [`use_state`](/documentation/api/hooks/use_state) hook. Read more about state management in the [state management](/documentation/getting_started/fundamentals/state-management) section.
+
+We will rename (from `Page` to `MarkdownWithColor`) the component, add local state, and put in the markdown text as an argument.
+
+```solara
+import solara
+
+
+@solara.component
+def MarkdownWithColor(markdown_text : str):
+    # color = solara.use_reactive()  # another possibility
+    color, set_color = solara.use_state("red")  # local state
+    solara.Select(label="Color",values=["red", "green", "blue", "orange"],
+                    value=color, on_value=set_color)
+    solara.Markdown(markdown_text, style={"color": color})
+
+
+@solara.component
+def Page():
+    with solara.Columns():
+        MarkdownWithColor("## Reuse is simple")
+        MarkdownWithColor("## With solara")
+```

solara/website/pages/documentation/getting_started/content/04-tutorials/60-jupyter-dashboard-part1.py

@@ -0,0 +1,64 @@
+from pathlib import Path
+
+import solara
+from solara.website.components.mailchimp import MailChimp
+from solara.website.components.notebook import Notebook
+
+HERE = Path(__file__).parent
+title = "Jupyter Dashboard (1/3)"
+
+
+@solara.component
+def Page():
+    title = "Build your Jupyter dashboard using Solara"
+    solara.Meta(property="og:title", content=title)
+    solara.Meta(name="twitter:title", content=title)
+    solara.Title(title)
+
+    img = "https://dxhl76zpt6fap.cloudfront.net/public/docs/tutorial/jupyter-dashboard1.webp"
+    solara.Meta(name="twitter:image", content=img)
+    solara.Meta(property="og:image", content=img)
+
+    description = "Learn how to build a Jupyter dashboard and deploy it as a web app using Solara."
+    solara.Meta(name="description", property="og:description", content=description)
+    solara.Meta(name="twitter:description", content=description)
+    tags = [
+        "jupyter",
+        "jupyter dashboard",
+        "dashboard",
+        "web app",
+        "deploy",
+        "solara",
+    ]
+    solara.Meta(name="keywords", content=", ".join(tags))
+
+    Notebook(
+        Path(HERE / "_jupyter_dashboard_1.ipynb"),
+        show_last_expressions=True,
+        execute=False,
+        outputs={
+            "a7d17a84": None,  # empty output (7)
+            # original: https://github.com/widgetti/solara/assets/1765949/e844acdb-c77d-4df4-ba4c-a629f92f18a3
+            "82f1d2f7": solara.Image("https://dxhl76zpt6fap.cloudfront.net/pages/docs/content/60-jupyter-dashboard-part1/map.webp"),  # map (11)
+            "3e7ea361": None,  # (13)
+            # original: https://github.com/widgetti/solara/assets/1765949/daaa3a46-61f5-431f-8003-b42b5915da4b
+            "56055643": solara.Image("https://dxhl76zpt6fap.cloudfront.net/pages/docs/content/60-jupyter-dashboard-part1/view.webp"),  # View (15)
+            # original: https://github.com/widgetti/solara/assets/1765949/2f4daf0f-b7d8-4f70-b04a-c27542cffdb0
+            "c78010ec": solara.Image("https://dxhl76zpt6fap.cloudfront.net/pages/docs/content/60-jupyter-dashboard-part1/page.webp"),  # Page (20)
+            # original: https://github.com/widgetti/solara/assets/1765949/a691d9f1-f07b-4e06-b21b-20980476ad64
+            "18290364": solara.Image("https://dxhl76zpt6fap.cloudfront.net/pages/docs/content/60-jupyter-dashboard-part1/controls.webp"),  # Controls
+            "0ca68fe8": None,
+            "fef5d187": None,
+            # original: https://github.com/widgetti/solara/assets/1765949/f0075ad1-808d-458c-8797-e460ce4dc06d
+            "af686391": solara.Image("https://dxhl76zpt6fap.cloudfront.net/pages/docs/content/60-jupyter-dashboard-part1/full-app.webp"),  # Full app
+        },
+    )
+    solara.Markdown(
+        """
+        Explore this app live at [solara.dev](/apps/jupyter-dashboard-1).
+
+        Don’t miss the next tutorial and stay updated with the latest techniques and insights by subscribing to our newsletter.
+    """
+    )
+    location = solara.use_router().path
+    MailChimp(location=location)