solara 1.30.1__py2.py3-none-any.whl → 1.31.0__py2.py3-none-any.whl

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

@@ -1,125 +0,0 @@
----
-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/getting_started/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/getting_started/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

@@ -1,85 +0,0 @@
----
-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/website/pages/documentation/getting_started/content/04-tutorials/00-overview.md

@@ -1,14 +0,0 @@
----
-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

@@ -1,13 +0,0 @@
-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

@@ -1,89 +0,0 @@
----
-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/getting_started/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).

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

@@ -1,124 +0,0 @@
----
-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

@@ -1,146 +0,0 @@
----
-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/getting_started/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).