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

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,76 @@
+---
+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.

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,89 @@
+---
+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
+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

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
+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

solara/website/pages/documentation/getting_started/content/02-installing.md

@@ -0,0 +1,134 @@
+---
+title: Installing Solara
+description: Installation should be as easy as running pip install Solara. Read on for advanced setups.
+---
+# Installation
+
+## Create a virtual environment
+
+It is best to install Solara into a virtual environment unless you know what you are doing (you already have a virtual environment, or you are using conda or docker).
+
+See also [The Python Packaging User Guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) for more information about virtual environments.
+
+
+### OSX/Unix/Linux
+
+Setting up a virtual environment on OSX/Unix/Linux:
+
+    $ python -m venv solara-env
+    $ source ./solara-env/bin/activate
+
+### Windows
+
+Setting up a virtual environment on Windows:
+
+    > py -m venv solara-env
+    > solara-env\Scripts\activate
+
+
+## Install Solara as a user
+
+Now install Solara using pip:
+
+    $ pip install solara
+
+## Bleeding edge
+
+If you want to install an unreleased version of Solara (e.g. because we just merged a feature you need)
+
+
+```
+$ pip install "solara @ git+https://github.com/widgetti/solara"
+```
+
+Or put the following in your `requirements.txt`:
+
+```
+solara @ https://github.com/widgetti/solara/package/archive/master.tar.gz
+
+```
+
+If you want to do development on Solara, read the [development documentation](/documentation/advanced/development/setup).
+
+## Air-gapped installation / Firewalled network
+
+If you want to have Solara running in an air-gapped environment or where access to a CDN is not possible due to firewall rules, you have two options
+
+
+### Pre-install assets
+
+Normally, Solara fetches assets (CSS, JavaScript and fonts) from a CDN on the fly, if that is not possible, you can pre-install the assets by running
+
+```
+$ pip install "solara[assets]"
+```
+
+### Airgapped install
+
+If you cannot install `solara` or `solara-assets` from pypi because the server is not connected to the internet, you can
+follow the following steps to install Solara:
+
+```bash
+# Download the required wheels from pypi.
+$ pip wheel --wheel-dir solara-air-gapped "solara[assets]"
+# Zip them in a tarball.
+$ tar zcfv solara-air-gapped.tar.gz solara-air-gapped
+# Copy the tarball to your server.
+$ scp solara-air-gapped.tar.gz yourusername@youmachine:~/solara-air-gapped.tar.gz
+# ssh into your server.
+$ ssh yourusername@yourmachine
+...
+#  Unzip the tarball.
+$ tar zxfv solara-air-gapped.tar.gz
+# Install all wheels.
+$ pip install solara-air-gapped/*.whl
+```
+
+## Solara subpackages
+
+The `solara` package is a meta package that installs all the necessary dependencies to get started with Solara. By default, we install:
+
+  * [`pip install "solara-ui[all]"`](https://pypi.org/project/solara-ui)
+  * [`pip install "solara-server[starlette,dev]"`](https://pypi.org/project/solara-ui) -
+
+Note that the solara (meta) package will pin exact versions of solara-ui and solara-server, which ensures you always get compatible version of the subpackages.
+For more flexibility, and control over what you install, you can install the subpackages directly.
+
+
+### The `solara-ui` package
+
+This package contains only the UI components, hooks and other utilities. This is the only package you need if you want to use Solara in a Jupyter environment. There are optional dependencies giving you
+more control over what you want to install:
+
+ * `pip install "solara-ui"` - Only the UI components, hooks and other utilities.
+ * `pip install "solara-ui[markdown]"` - The above, with support for markdown rendering.
+ * `pip install "solara-ui[cache]"` - The above, with support for [caching](https://solara.dev/docs/reference/caching)
+ * `solara-ui[all]` - Installs all optional dependencies.
+
+### The `solara-server` package
+
+This will let you run solara applications outside a Jupyter server. See [Understanding Solara Server](https://solara.dev/documentation/advanced/understanding/solara-server) for more details about solara server.
+
+For deployments, we recommend ``pip install "solara-server[starlette]"` which will install the starlette backend for solara server. For development, you can install the `dev` extra to get the development dependencies that enabled hot reloading.
+
+The `solara-server` packages supports the following optional dependencies:
+
+ * `pip install "solara-server"` - Only the solara server code with required dependencies, this in general is not a functional server (it needs starlette or flask to run).
+ * `pip install "solara-server[starlette]"` - The solara server with the starlette backend.
+ * `pip install "solara-server[flask]"` - The solara server with the starlette backend and development dependencies.
+ * `pip install "solara-server[dev]"` - The solara server with dependencies for development for enabling hot reloading.
+ * `pip install "solara-server[all]"` - Installs all optional dependencies.
+
+
+
+
+### The `pytest-ipywidgets` package
+
+This package is a plugin for pytest that lets you test ipywidgets with playwright. It is useful for testing your ipywidgets or solara applications in a (headless) browser.
+See [Our testing documentation](https://solara.dev/docs/advanced/testing) for more information.
+
+ * `pip install "pytest-ipywidgets"` - Minimal installation for testing ipywidgets.
+ * `pip install "pytest-ipywidgets[voila]"` - The above, with a compatible version of voila.
+ * `pip install "pytest-ipywidgets[jupyterlab]"` - The above, with a compatible version of jupyterlab.
+ * `pip install "pytest-ipywidgets[notebook]"` - The above, with a compatible version of notebook.
+ * `pip install "pytest-ipywidgets[all]"` - Installs all optional dependencies.

solara/website/pages/documentation/getting_started/content/04-tutorials/00-overview.md

@@ -0,0 +1,14 @@
+---
+title: Solara Tutorials
+description: A collection of tutorials for those learning to use Solara, each geared towards a users coming from particular backgrounds, such as data science, or
+    users coming from other frameworks like Streamlit.
+---
+# Tutorials
+
+Instead of having one tutorial, we have tutorials for different audiences.
+
+  * [Jupyter Dashboard](/documentation/getting_started/tutorials/jupyter-dashboard-part1): Learn to create a dashboard in the Jupyter notebook.
+  * [Data science](/documentation/getting_started/tutorials/data-science): In this tutorial, we will introduce Solara from the perspective of a data scientist or when you are thinking of using Solara for a data science app.
+  * [Web app](/documentation/getting_started/tutorials/web-app): You are not a data scientist, but you are interested in using Solara to create a web app using Pure Python.
+  * [IPywidgets user](/documentation/getting_started/tutorials/ipywidgets): If you are already using [ipywidgets](/documentation/advanced/understanding/ipywidgets) you will learn how to use the [Solara server](/documentation/advanced/understanding/solara-server) to render your regular ipywidget applications.
+  * [Streamlit](/documentation/getting_started/tutorials/streamlit): If you are an existing Streamlit user, this might appeal more to you.

solara/website/pages/documentation/getting_started/content/04-tutorials/10_data_science.py

@@ -0,0 +1,13 @@
+from pathlib import Path
+
+import solara
+import solara.components.applayout
+from solara.website.components.notebook import Notebook
+
+HERE = Path(__file__).parent
+
+
+@solara.component
+def Page():
+    # only execute once, other
+    Notebook(HERE / "_data_science.ipynb")

solara/website/pages/documentation/getting_started/content/04-tutorials/20-web-app.md

@@ -0,0 +1,89 @@
+---
+title: Tutorial - Building web apps in python using Solara
+description: In this tutorial, you will learn how to use Solara to create a tiny web app using only Python. You can run these apps using either Solara server,
+    Jupyter lab / notebook, or whatever server infrastructure you prefer.
+---
+# Tutorial: Web app
+
+In this tutorial, you will learn how to use Solara to create a tiny web app using only Python.
+
+## You should know
+This tutorial will assume you have successfully installed Solara.
+
+If not, please follow the [Installation guide](/documentation/getting_started/installing).
+
+## Generate a script file
+The simplest way to get started is to run the command
+
+```bash
+$ solara create button
+Wrote:  /Users/maartenbreddels/github/widgetti/solara/sol.py
+Run as:
+         $ solara run /Users/maartenbreddels/github/widgetti/solara/sol.py
+```
+
+This will create the `sol.py` file with the following content.
+```solara
+import solara
+
+clicks = solara.reactive(0)
+
+
+@solara.component
+def Page():
+    color = "green"
+    if clicks.value >= 5:
+        color = "red"
+
+    def increment():
+        clicks.value += 1
+        print("clicks", clicks)
+
+    solara.Button(label=f"Clicked: {clicks}", on_click=increment, color=color)
+```
+
+
+## Run the script
+
+Using [Solara server](/documentation/advanced/understanding/solara-server), we can now run our Python script using:
+
+```bash
+$ solara run sol.py
+Solara server is starting at http://localhost:8765
+```
+
+If you open the URL in your browser ([or click here](http://localhost:8765)), you should see the same example as above.
+
+Solara will run your script once, and will look for the `Page` component. Solara expects this component to exist
+and be a [Reacton](/documentation/advanced/understanding/reacton) component. (See the [IPywidget tutorial](/documentation/getting_started/tutorials/ipywidgets) to learn how to render a regular ipywidget).
+
+Since your script is only run once, you could put in the main body of your script code that only needs to run once (e.g. loading data from disk)
+
+Every browser/user that connects will get an independent version of the state (in this case the number of clicks), so
+you do not share the number of clicks with other people.
+
+## Modify the script
+
+Lets modify the script a little bit, possibly in this way:
+
+```diff
+-    solara.Button(label=f"Clicked: {clicks}", on_click=increment, color=color)
++    label = "Not clicked yet" if clicks.value == 0 else f"Clicked: {clicks}"
++    solara.Button(label=label, on_click=increment, color=color)
+```
+
+If we save the script, Solara will automatically reload your script and update
+your browser (we call this feature [hot reloading](/documentation/advanced/reference/reloading)).
+
+Note that Solara will remember your state (e.g., the number of buttons clicked) when the app reloads.
+
+(*Note: Upgrade to solara 1.14.0 for a fix in hot reloading using `pip install "solara>=1.14.0"`*)
+
+## What you have learned
+
+   * How to create a Python script `sol.py` by running `solara create button`
+   * How to run the script with Solara server by running `solara run sol.py`
+   * Your script is executed once, which is useful for loading data in the main body of your script only once.
+   * Your script should have a component called `Page`.
+   * Every user has its own state (in the above example, the number of clicks)
+   * If you save your script, Solara will automatically re-execute your script, and all attached users will see the changes directly (hot reloading).