solara-ui 1.45.0__py3-none-any.whl

solara/website/pages/documentation/examples/visualization/__init__.py

@@ -0,0 +1,6 @@
+import solara
+
+
+@solara.component
+def Page():
+    return solara.Markdown("Click an example on the left")

solara/website/pages/documentation/examples/visualization/annotator.py

@@ -0,0 +1,67 @@
+"""# Image annotation with Solara
+
+This example displays how to annotate images with different drawing tools in plotly figures. Use the canvas
+below to draw shapes and visualize the canvas callback.
+
+
+Check [plotly docs](https://dash.plotly.com/annotations) for more information about image annotation.
+"""
+
+import json
+
+import plotly.graph_objects as go
+
+import solara
+
+title = "Plotly Image Annotator"
+shapes = solara.reactive(None)
+
+
+class CustomEncoder(json.JSONEncoder):
+    """
+    Custom JSON encoder for Plotly objects.
+
+    Plotly may return objects that the standard JSON encoder can't handle. This
+    encoder converts such objects to str, allowing serialization by json.dumps
+    """
+
+    def default(self, o):
+        if isinstance(o, object):
+            return str(o)
+        return super().default(o)
+
+
+@solara.component
+def Page():
+    def on_relayout(data):
+        if data is None:
+            return
+
+        relayout_data = data["relayout_data"]
+
+        if "shapes" in relayout_data:
+            shapes.value = relayout_data["shapes"]
+
+    fig = go.FigureWidget(
+        layout=go.Layout(
+            showlegend=False,
+            autosize=True,
+            dragmode="drawrect",
+            modebar={
+                "add": [
+                    "drawclosedpath",
+                    "drawcircle",
+                    "drawrect",
+                    "eraseshape",
+                ]
+            },
+        )
+    )
+
+    solara.FigurePlotly(fig, on_relayout=on_relayout)
+    if not shapes.value:
+        solara.Markdown("## Draw on the canvas")
+    else:
+        solara.Markdown("## Data returned by drawing")
+        formatted_shapes = str(json.dumps(shapes.value, indent=2, cls=CustomEncoder))
+        solara.Preformatted(formatted_shapes)

solara/website/pages/documentation/examples/visualization/linked_views.py

@@ -0,0 +1,81 @@
+"""# Linked views
+
+This example shows how to create linked views. The clicked row information is passed up to the parent component using an event,
+and then passed down to both child components.
+
+"""
+
+import dataclasses
+from typing import Callable, cast
+
+import plotly.express as px
+
+import solara
+
+df = px.data.iris()
+columns = list(df.columns)
+
+
+@dataclasses.dataclass
+class ClickPoint:
+    row_index: int
+    x_column: str
+    y_column: str
+
+
+def find_row_index(fig, click_data):
+    # goes from trace index and point index to row index in a dataframe
+    # requires passing df.index as to custom_data
+    trace_index = click_data["points"]["trace_indexes"][0]
+    point_index = click_data["points"]["point_indexes"][0]
+    trace = fig.data[trace_index]
+    return trace.customdata[point_index][0]
+
+
+@solara.component
+def ClickScatter(df, x, y, color, click_row, on_click: Callable[[ClickPoint], None]):
+    x, set_x = solara.use_state(x)
+    y, set_y = solara.use_state(y)
+    fig = px.scatter(df, x, y, color=color, custom_data=[df.index])
+
+    def on_click_trace(click_data):
+        # sanity checks
+        assert click_data["event_type"] == "plotly_click"
+        row_index = find_row_index(fig, click_data)
+        on_click(ClickPoint(row_index, x, y))
+
+    if click_row:
+        click_x = df[x].values[click_row]
+        click_y = df[y].values[click_row]
+        fig.add_trace(px.scatter(x=[click_x], y=[click_y], text=["⭐️"]).data[0])
+    # make the figure a bit smaller
+    fig.update_layout(width=340)
+    with solara.Column(style={"width": "340px"}) as main:
+        solara.FigurePlotly(fig, on_click=on_click_trace)
+        solara.Select(label="X-axis", value=x, values=columns, on_value=set_x)
+        solara.Select(label="Y-axis", value=y, values=columns, on_value=set_y)
+    return main
+
+
+@solara.component
+def Page():
+    click_point, set_click_point = solara.use_state(cast(ClickPoint, None))
+    if click_point:
+        clicked_row = click_point.row_index
+    else:
+        clicked_row = None
+
+        with solara.Row(justify="center", style={"flex-wrap": "wrap"}):
+            ClickScatter(df, "sepal_length", "sepal_width", "species", clicked_row, on_click=set_click_point)
+            ClickScatter(df, "petal_length", "petal_width", "species", clicked_row, on_click=set_click_point)
+        if click_point is not None:
+            clicked_row = click_point.row_index
+            solara.Success(f"Clicked on row {clicked_row}. Which is highlighted in the both plots.")
+            solara.Markdown(
+                f"""
+            ```python
+            row_data = {df.iloc[clicked_row].to_dict()}
+            ```"""
+            )
+        else:
+            solara.Info("Click to select a point")

solara/website/pages/documentation/examples/visualization/plotly.py

@@ -0,0 +1,44 @@
+"""# Scatter plot using Plotly
+
+This example shows how to use Plotly to create a scatter plot and a slider to do some filtering.
+
+Inspired by the dash documentation.
+
+
+## Note
+
+Solara supports plotly and plotly express. Create your figure (not a figure widget)
+and pass it to the [FigurePlotly](/documentation/components/viz/plotly) component.
+
+"""
+
+import pandas as pd
+import plotly.express as px
+import solara
+
+title = "Scatter plot using Plotly"
+
+try:
+    df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/gapminderDataFiveYear.csv")
+except Exception:
+    df = None
+
+if df is not None:
+    year_min = df["year"].min()
+    year_max = df["year"].max()
+    years = df["year"].unique().tolist()
+
+
+@solara.component
+def Page():
+    with solara.Div() as main:
+        index = solara.ui_slider(value=0, min=0, max=len(years) - 1, tick_labels=years, key="year slider index")
+        selected_year = years[index]
+
+        filtered_df = df[df.year == selected_year].copy()
+
+        fig = px.scatter(filtered_df, x="gdpPercap", y="lifeExp", size="pop", color="continent", hover_name="country", log_x=True, size_max=55)
+        fig.update_layout(transition_duration=1500)
+
+        solara.FigurePlotly(fig, dependencies=[selected_year])
+    return main

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

@@ -0,0 +1,12 @@
+from pathlib import Path
+
+import solara
+from solara.website.components.markdown import MarkdownWithMetadata
+
+title = "FAQ"
+HERE = Path(__file__)
+
+
+@solara.component
+def Page(route_external=None):
+    MarkdownWithMetadata(Path(HERE.parent / "content" / "99-faq.md").read_text())

solara/website/pages/documentation/faq/content/99-faq.md

@@ -0,0 +1,112 @@
+---
+title: FAQ about Solara
+description: Answers to some common questions about using Solara, and building your app using the framework
+---
+# FAQ
+
+## I am not interested in the server, I'm happy with Jupyter/Voila, what's in it for me?
+
+That means you simply do not use or install the server component, just use the Reacton components and run it with Voila.
+
+## Is the Solara server better than Voilà?
+
+No, they are different, and there are situations where I would recommend Voila instead of Solara.
+
+If your app is compute-heavy, and a lot of the compute is happening in pure Python, the GIL (Global Interpreter Lock) can become a bottleneck with Solara, and Voila might give you better performance per client.
+
+If you have a lot of users with short sessions, Solara spares you from having to start up a kernel for each request. Since Solara can use multiple workers in the near future, you can still scale up using multiple processes. Voila will have one process per user, while Solara can share a process with many users.
+
+
+## Can Solara run a normal Python script?
+
+Yes, this is the preferred way of using Solara. You edit a Python script, save it, Solara will detect the file change and reload the page in your browser (no interaction is needed).
+
+```bash
+$ solara myapp.py
+Solara server is starting at http://localhost:8766
+... file change detected ...
+(server refreshes, your page will reload)
+
+```
+
+## Can Solara run from a Python package/module?
+
+Over time, when your application becomes larger, you probably want to structure your application into a Python package. Instead of a filename, you pass in the package name on the command line
+
+```bash
+$ solara mystartup.killerapp --dev
+....
+```
+
+## Can Solara run Jupyter notebook?
+
+Yes, Solara will execute each cell, and after that will look for a variable or component called `Page`, like with a normal script. All other output, Markdown or other types of cells will be ignored.
+
+
+
+## Can I use Solara in my existing FastAPI/Starlette/Flask server?
+
+Yes, take a look at the `solara.server.starlette`  and `solara.server.fastapi` and `solara.server.flask` module. The usage will change over time, so read the source and be ready to change this in the future. We do plan to provide a stable API for this in the future.
+
+
+## How to fix: inotify watch limit reached?
+
+Add the line
+
+    fs.inotify.max_user_watches=524288
+
+To your /etc/sysctl.conf file, and run `sudo sysctl -p.`
+
+Or if you are using visual studio code, please read: https://code.visualstudio.com/docs/setup/linux#_visual-studio-code-is-unable-to-watch-for-file-changes-in-this-large-workspace-error-enospc
+
+
+## How can I recognize if I run in Solara, Voila or Jupyter Notebook/Lab
+
+Voila and Solara set the following environment variables (based on the CGI spec):
+
+   * SERVER_SOFTWARE
+      * Solara: e.g. 'solara/1.2.3'
+      * Voila: e.g. 'voila/1.2.3'
+   * SERVER_PORT (e.g. '8765')
+   * SERVER_NAME (e.g. 'killerapp.com')
+   * SCRIPT_NAME (only Voila, e.g. 'voila/render/notebook.ipynb')
+   * PATH_TRANSLATED (only Solara e.g. '/mnt/someapp/app.py')
+
+Jupyter Notebook/Lab/Server do not set these variables. With this information,
+it should be possible to recognize in which environment you are running in.
+
+
+## I cannot find or run `solara` from the command line
+
+
+On Linux or OSX you might see
+
+```
+$ solara
+command not found: solara
+```
+
+On Windows you might see
+
+```
+C:Users\myusername> solara
+solara: The term 'solara' is not recognized as the name of a cdlet, function,
+script file, or operable program.
+```
+
+The solara command before version 1.30 was installed with the package `solara`, but now it is installed with the package `solara-server`.
+
+If you upgrade from an older version to 1.30 or later, the order in which pip installs packages can cause the `solara` command to be uninstalled. To fix this, reinstall the `solara-server` package:
+
+```bash
+$ pip install solara-server --force-reinstall
+```
+
+# I see an error in the browser console
+
+If you see an error like this in the browser console:
+```
+Uncaught Error: Script error for "base/js/namespace", needed by: /jupyter/nbextensions/dash/main.js
+```
+
+See [ignoring notebook extensions](/documentation/advanced/understanding/solara-server#ignoring-notebook-extensions) for more information.

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

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+from solara.autorouting import generate_routes_directory
+from solara.website.components.markdown import MarkdownWithMetadata
+
+HERE = Path(__file__)
+# if we didn't put the content in the subdirectory, but pointed to the current file
+# we would include the current file recursively, causing an infinite loop
+routes = generate_routes_directory(HERE.parent / "content", MarkdownWithMetadata)

solara/website/pages/documentation/getting_started/content/00-quickstart.md

@@ -0,0 +1,107 @@
+---
+title: Solara Quickstart
+description: Get started with building web- and data-apps in pure python with Solara.
+---
+
+# Quickstart
+
+This 1-minute quickstart will get you to:
+
+   * Install Solara.
+   * Write your first Solara script.
+   * Run your script using Solara server.
+   * (Optional) Reuse your code in the Jupyter notebook.
+
+If you are an existing ipywidget user and do not want to learn the component based method, you might want to skip the quickstart and directly go to the [IPywidgets user tutorial](/documentation/getting_started/tutorials/ipywidgets).
+
+## Installation
+
+
+Run `pip install solara`, or follow the [Installation instructions](/documentation/getting_started/installing) for more detailed instructions.
+
+
+## First script
+
+Put the following Python snippet in a file (we suggest `sol.py`), or put it in a Jupyter notebook cell:
+
+```solara {pycafe-link}
+import solara
+
+# Declare reactive variables at the top level. Components using these variables
+# will be re-executed when their values change.
+sentence = solara.reactive("Solara makes our team more productive.")
+word_limit = solara.reactive(10)
+
+
+@solara.component
+def Page():
+    # Calculate word_count within the component to ensure re-execution when reactive variables change.
+    word_count = len(sentence.value.split())
+
+    solara.SliderInt("Word limit", value=word_limit, min=2, max=20)
+    solara.InputText(label="Your sentence", value=sentence, continuous_update=True)
+
+    # Display messages based on the current word count and word limit.
+    if word_count >= int(word_limit.value):
+        solara.Error(f"With {word_count} words, you passed the word limit of {word_limit.value}.")
+    elif word_count >= int(0.8 * word_limit.value):
+        solara.Warning(f"With {word_count} words, you are close to the word limit of {word_limit.value}.")
+    else:
+        solara.Success("Great short writing!")
+
+
+# The following line is required only when running the code in a Jupyter notebook:
+Page()
+```
+
+Yes, the above example is running live on the Solara documentation web server. If you change the slider the output updates.
+
+## Run the script using Solara server
+
+Run from the command line in the same directory where you put your file (`sol.py`):
+
+```bash
+$ solara run sol.py
+Solara server is starting at http://localhost:8765
+```
+
+If you open the URL in your browser ([http://localhost:8765](http://localhost:8765)), you should see the same graph in your browser, now running on your computer.
+
+## Reuse your code in the Jupyter notebook.
+
+From Jupyter Notebook (classic) or Jupyter Lab, navigate to the same directory as `sol.py`. Enter the following code in a notebook cell:
+
+```python
+from sol import Page
+display(Page())
+```
+
+You should see the following output:
+
+<img src="https://dxhl76zpt6fap.cloudfront.net/public/quickstart-notebook.webp" alt="Markdown Monster icon" style="border: 1px solid #ccc;" />
+
+In case you forgot how to start a notebook server:
+
+    $ jupyter notebook
+
+Or the more modern Jupyter lab:
+
+    $ jupyter lab
+
+
+## Run as app (experimental)
+
+You can also run the script as a standalone app. This requires the extra packages `qtpy` and `PySide6` (or `PyQt6`) to be installed.
+
+```bash
+$ pip install qtpy PySide6
+```
+
+Run from the command line in the same directory where you put your file (`sol.py`):
+
+```bash
+$ solara run sol.py --qt
+```
+
+
+<img src="https://dxhl76zpt6fap.cloudfront.net/public/solara-quickstart-app.webp" alt="Markdown Monster icon"/>

solara/website/pages/documentation/getting_started/content/01-introduction.md

@@ -0,0 +1,125 @@
+---
+title: A quick introduction to Solara
+description: Solara is an Open Source library that lets you use and build data-focused web apps (data apps) using reusable UI components. Here you'll learn the basics!
+---
+# Introduction
+
+
+## What is Solara?
+
+Solara is an Open Source library that lets you use and build data-focused web apps (data apps) using reusable UI components. Your app will work in the Jupyter notebook and production-grade web frameworks (FastAPI, Starlette, Flask, ...).
+
+Solara uses proven technologies and mature standards. Grow from a one-off experiment in the Jupyter notebook to a dynamic data portal in production.  Built on top of [Reacton](/documentation/advanced/understanding/reacton) to keep your code complexity under control and [IPywidgets](/documentation/advanced/understanding/ipywidgets) to access a rich set of UI libraries without having to write Javascript or CSS.
+
+We care about developer experience. Solara will give your hot code reloading and type hints for faster development.
+
+## Why is Solara created?
+
+How much time have you wasted investing in a web framework only to find out that what you need is impossible to do?
+
+Many frameworks only solve a specific set of problems. Once you step outside of the paved path, you get stuck.
+
+On the other extreme, you might be working with a library with no clear patterns that let you do anything. You may only be weeks away from a total code complexity nightmare, which slowly kills your project.
+
+At the same time, starting a new framework from scratch would be unwise. We prefer to build on top of solid, battle-tested libraries, such as [IPywidgets](/documentation/advanced/understanding/ipywidgets).
+
+## Why use Solara?
+
+Instead of inventing a new API with an unknown track record, we take a different approach. We look at the JavaScript world. React is a technology that has proven itself for many years. It has shown to be a good all-around model for building complex UIs.
+
+[Reacton](/documentation/advanced/understanding/reacton) is the equivalent of ReactJS for Python (and IPywidgets). It allows us to use the same reusable components and hooks as in the ReactJS ecosystem. Using Reacton, we build web/data applications without suffering from complex code bases.
+
+Looking again at the JavaScript world, we see software such as NextJS is putting a framework around ReactJS. NextJS is more opinionated than ReactJS and adds more "batteries" such as routing.
+
+Solara plays a similar role as NextJS. It builds on top of Reacton but handles things like routing for you.
+
+But Solara is also different and is even more opinionated than NextJS. The reason for this is its focus on the data-heavy Python ecosystem. For this reason, it comes with many components and hooks that make building beautiful data apps easier (see our [Documentation](/documentation)).
+
+Solara is a clear, systematic, Python-based web framework using industry-trusted technology. Smooth developer experience and enforced code modularity will allow you to build a data app at any scale while maintaining simple code.
+
+## A quick Solara example
+
+For your understanding, it might be good just to run an example.
+
+Follow the [installation instructions](/documentation/getting_started/installing) or do the TLDR:
+
+    $ pip install solara
+
+
+Create a file `myapp.py`, or put the following code in the Jupyter notebook:
+
+```solara {pycafe-link}
+import solara
+
+clicks = solara.reactive(0)
+
+
+@solara.component
+def Page():
+    def increase_clicks():
+        clicks.value += 1
+
+    solara.Button(label=f"Clicked {clicks} times", on_click=increase_clicks)
+
+# in the Jupyter notebook, uncomment the next line:
+# display(Page())
+```
+
+*Note that the above output is __live__, you can click the button and see the behaviour*.
+
+Run solara-server (if *not* using the Jupyter notebook)
+
+    $ solara run myapp.py
+    Solara server is starting at http://localhost:8765
+
+The browser should open http://127.0.0.1:8765
+
+
+
+
+## How does Solara fit into the big picture?
+
+Solara is actually two things.
+
+### Solara server
+[Solara server](/documentation/advanced/understanding/solara-server) renders ipywidgets in the browser in a very efficient manner and takes care of many other things
+such as [routing](/documentation/advanced/understanding/routing) and [Static Site Generation](/documentation/advanced/reference/static-site-generation).
+
+### Solara UI
+
+The UI part is built on top of [Reacton](/documentation/advanced/understanding/reacton), which uses the existing IPyWidgets stack. It gives a consistent set
+of modern UI components with the Material Design look, as well as a set of routines to make application development of data heavy web apps
+easier.
+
+
+### Overview
+If you use Jupyter, then you probably use the Jupyter notebook, Lab, or [Voila](/documentation/advanced/understanding/voila) to get your widgets into the browser. You may not care about [Solara server](/documentation/advanced/understanding/solara-server) and can focus on just the UI part.
+
+If you don't use Jupyter, don't know what it is, or are an ML Ops, Dev Ops, or Sys Admin, you are probably more interested in the Solara server.
+
+![Solara stack](https://dxhl76zpt6fap.cloudfront.net/public/docs/solara-stack.webp)
+
+## How do I learn Solara?
+
+We recommend going through the documentation linearly following the arrows on the bottom, meaning you will go through:
+
+ * [Installing](/documentation/getting_started/installing)
+ * [Quick start](/documentation/getting_started)
+ * [Tutorials](/documentation/getting_started/tutorials)
+
+If you want to know more about specific parts, you can go through the [How-to section](/documentation/advanced/howto) to learn more. Feel free to skip chapters, and go back to topics when you need to.
+
+
+If you want to know what components or hooks are available, or want to know more about a specific component, check out the [Documentation](/documentation) which includes live code examples. Other reference documentation can be found at the [reference section](/documentation/advanced/reference)
+
+If you feel like you miss some basic understanding and want to give a bit deeper into the what and why feel free to explore the [Understanding section](/documentation/advanced/understanding).
+
+
+[Our examples](/documentation/examples) may help you see how particular problems can be solved using Solara, or as inspiration. If you want to contribute an example, contact us on GitHub or directly open a [Pull Request](https://github.com/widgetti/solara/).
+
+
+## Where can I hire an expert?
+
+If you need consulting, training or development, you can reach us at:
+
+contact@solara.dev