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

solara/website/pages/documentation/getting_started/content/05-fundamentals/00-overview.md

@@ -0,0 +1,11 @@
+---
+title: Fundamentals of Solara
+description: These articles dive deeper into the fundamental aspects of Soalra, like using components, hooks, and managing state.
+---
+# Fundamentals
+
+If you want to dive deeper into Solara, this section is for you. We will cover the following topics:
+
+  * [Components](/documentation/getting_started/fundamentals/components)
+  * Hooks (soon)
+  * [State management](/documentation/getting_started/fundamentals/state-management)

solara/website/pages/documentation/getting_started/content/05-fundamentals/10-components.md

@@ -0,0 +1,223 @@
+---
+title: Introduction to Solara components
+description: In Solara, components are the building blocks of your web application. They allow you to create modular, reusable, and maintainable user interface elements
+    that can be combined to create a complete and interactive application.
+---
+<!-- TODO: column auto -->
+
+# Introduction to Components
+
+In Solara, components are the building blocks of your web application. They allow you to create modular, reusable, and maintainable user interface (UI) elements that can be combined to create a complete and interactive application. Components can range from simple UI elements, such as buttons or text inputs, to more complex and custom visualizations or forms.
+
+The primary benefits of using components in Solara include:
+
+ * Modularity: Components can be designed independently and then combined to form more complex UIs. This modular approach promotes separation of concerns, making it easier to reason about and maintain each part of your application.
+ * Reusability: Components can be reused across different parts of your application or even across multiple projects. This can save time and effort by reducing the need to rewrite similar code and can lead to more consistent UIs.
+ * Maintainability: By breaking your application into smaller, self-contained components, it becomes easier to understand, debug, and update your code. This results in more maintainable and resilient applications.
+ * Performance: When a component instance depends on a specific state, and that state changes, only the render function of the affected component instance will be re-executed. This selective re-rendering ensures that other components or instances that do not depend on the changed state remain unaffected, leading to more efficient performance.
+
+## Types of Components
+
+In Solara, there are two main types of components: Widget Components and Function Components.
+
+## Widget components
+
+Widget Components correspond to ipywidgets and are responsible for rendering visual elements in the browser, such as buttons, sliders, or performing layout tasks. These components are the foundation of your user interface and provide the essential building blocks for creating interactive applications.
+
+Solara mainly uses the [ipyvuetify library](/documentation/advanced/understanding/ipyvuetify) for its widget components. It provides a set of high-level components that can be used to create rich, interactive user interfaces.
+
+See the [components page](/documentation/components) for a complete list of basic UI components.
+
+## Function Components
+
+Function Components (Components for short), on the other hand, are responsible for combining logic, state, and other components to create more complex and dynamic applications. These components serve as a way to create reusable and modular structures that can be easily integrated into your application.
+
+These are the components that you will be writing when building Solara applications.
+
+By utilizing both Widget Components and Function Components, you can create flexible and powerful applications that provide a rich user experience while maintaining a clean and organized codebase.
+
+## Creating New Components
+
+In Solara, users can create their own custom components without any special distinction from the built-in components provided by the framework, they are all components. These user-defined components have the same capabilities and can be composed seamlessly alongside Solara's components, allowing for the creation of highly customized and reusable user interfaces.
+
+# Defining Components
+To create a component in Solara, you'll start by defining a Python function decorated with @solara.component. Inside the function, you can create the component's structure by calling Solara's built-in components or creating custom components to suit your specific needs. If a single element is created, it's taken as the component's main element. If multiple elements are created, they are automatically wrapped in a Column component.
+
+Here's an example of a simple Solara component that displays a button:
+
+```python
+import solara
+
+@solara.component
+def MyButton():
+    solara.Button("Click me!")
+```
+
+In this example, we create a component function named MyButton and apply the @solara.component decorator to it. Within the component function, a Button component from Solara is created, displaying the text "Click me!".
+
+## Using Components
+Once you've created your components, you can use them in your Solara app by calling the components to create elements. Elements, the lightweight representations of components, can be combined to build complex UIs. They can also be passed as arguments to other components, enabling a flexible and modular application structure.
+
+Here's an example of using the `MyButton` component we defined earlier:
+
+```python
+import solara
+
+@solara.component
+def MyApp():
+    MyButton()
+    MyButton()
+```
+
+In this example, we create a `MyApp` function decorated with `@solara.component`. The function create two MyButton elements, resulting in two buttons (or two component instances).
+
+## Handling User Interactions
+Components in Solara can capture user input and respond to events, such as button clicks or form submissions. To handle user interactions, you'll define callback functions and connect them to your components using Solara's event handling system.
+
+Here's an example of a Solara component that displays a button and responds to click events:
+
+```python
+import solara
+
+def on_button_click(event):
+    print("Button clicked!")
+
+@solara.component
+def MyInteractiveButton():
+    solara.Button("Click me!", on_click=on_button_click)
+```
+
+In this example, we define a function called on_button_click that will be executed when the button is clicked. In the MyInteractiveButton function, we create a Button component and set the on_click argument to the on_button_click function.
+
+By following these steps, you can create and use components to build rich, interactive applications with Solara.
+
+
+## Component Arguments and State
+In Solara, components can accept arguments and maintain internal state to manage their behavior and appearance. This section will explain how to use arguments and state in your Solara components and provide code examples to demonstrate their usage.
+
+### Component Arguments
+Arguments are the values that you pass to a component when you call it, allowing you to customize its behavior and appearance. You can define the arguments your component accepts by specifying them as parameters in the component function. This makes your components more reusable and flexible, as you can easily modify their behavior by passing different argument values.
+
+Here's an example of a Solara component that accepts an argument:
+
+```python
+import solara
+
+@solara.component
+def MyButton(text):
+    solara.Button(text)
+```
+
+In this example, we define a function called MyButton that takes a single argument, text. The render function creates a Button component from Solara with the specified text.
+
+### Using Application state in Components
+To manage the state of a component in Solara, you can use the solara.reactive() function to create reactive variables. Reactive variables are used to store values that can change over time and automatically trigger component updates when their values change. This allows you to create components that respond to changes in data and user interactions.
+
+Here's an example that demonstrates the use of reactive variables in Solara components:
+```solara
+import solara
+
+counter = solara.reactive(0)
+
+def increment():
+    counter.value += 1
+
+@solara.component
+def CounterDisplay():
+    solara.Info(f"Counter: {counter.value}")
+
+@solara.component
+def IncrementButton():
+    solara.Button("Increment", on_click=increment)
+
+@solara.component
+def Page():
+    IncrementButton()
+    CounterDisplay()
+
+```
+
+In this example, we create a reactive variable counter with an initial value of 0. We define two components: `CounterDisplay` and `IncrementButton`. `CounterDisplay` renders the current value of counter, while `IncrementButton` increments the value of counter when clicked. Whenever the counter value changes, `CounterDisplay` automatically updates to display the new value.
+
+By using arguments and state in your Solara components, you can create more dynamic and interactive applications that respond to user input and changes in data.
+
+### Internal State in Components
+
+In addition to using reactive variables for global or application-wide state, you can also manage internal or component-specific state using the use_state hook in Solara. The use_state hook allows you to define state variables that are local to a component, and automatically trigger updates when their values change.
+
+To use the use_state hook, call the solara.use_state() function inside your component function. This function takes an initial value as an argument and returns a tuple containing the current state value and a function to update the state.
+
+Here's an example that demonstrates the use of the use_state hook to manage internal state in a Solara component:
+
+```solara
+import solara
+
+@solara.component
+def Counter():
+    count, set_count = solara.use_state(0)
+
+    def increment():
+        set_count(count + 1)
+
+    solara.Button("Increment", on_click=increment)
+    solara.Info(f"Counter: {count}")
+
+@solara.component
+def Page():
+    Counter()
+```
+
+In this example, we define a Counter component that uses the use_state hook to manage its internal state. We create a state variable count with an initial value of 0 and a function set_count to update the state. The increment function increments the value of count when the button is clicked. Whenever the count value changes, the component automatically updates to display the new value.
+
+By using the use_state hook, you can manage the internal state of your components and create more dynamic and interactive applications that respond to user input and changes in data.
+
+## Lazy Rendering in Solara Components
+
+In Solara, understanding the relationship between components, elements, and instances is essential to grasp the rendering process. Components serve as a blueprint or template for defining the structure and behavior of a part of the user interface. Elements are lightweight virtual representations of components, created when the components are invoked. Instances, on the other hand, represent the function body of the component and its state.
+
+Solara employs a "lazy rendering" approach, where the rendering of a component's children is deferred until it is necessary. When a component is invoked, an element is created immediately, representing that particular instance of the component. However, the actual rendering of the component's children is postponed until the component is rendered within the virtual tree, either as a child of another component or as the root component. This allows Solara to optimize the rendering process and update only the necessary components when the application state or component arguments change.
+
+Lazy rendering in Solara ensures that the render function is executed only when necessary, improving the application's performance. To illustrate this concept, let's consider the following example:
+
+
+```solara
+import solara
+
+counter = solara.reactive(0)
+
+@solara.component
+def CounterDisplay():
+    solara.Info(f"Counter: {counter.value}")
+
+@solara.component
+def IncrementButton():
+    def increment():
+        counter.value += 1
+
+    solara.Button("Increment", on_click=increment)
+
+@solara.component
+def RandomText():
+    import random
+    solara.Info(f"Random number: {random.random()}")
+
+@solara.component
+def Page():
+    IncrementButton()
+    CounterDisplay()
+    RandomText()
+```
+
+In this example, we define several components: `IncrementButton`, `CounterDisplay`, and `RandomText`. The `IncrementButton` component increments the value of the counter reactive variable when clicked. The `CounterDisplay` component displays the current value of the counter. The `RandomText` component displays a random number but does not depend on any state or reactive variables.
+
+When the user clicks the `IncrementButton`, the counter reactive variable is updated, and the `CounterDisplay` component re-renders to show the new value. The RandomText component does not re-render in this scenario because it does not depend on any state or reactive variables.
+
+This example demonstrates Solara's lazy rendering, where only the relevant components are instantiated and rendered based on changes in their arguments or internal state. This ensures that the render function is executed only when necessary, improving the application's performance.
+
+
+## Conclusions
+In conclusion, understanding components, their arguments, and how to manage their internal state is crucial for building Solara applications. To create more advanced components, you need to have a deeper understanding of hooks, such as the use_state hook we have already discussed.
+
+In the next fundamentals article, we will explore more hooks available in Solara, which will enable you to build more sophisticated components that cater to a wide range of use cases. By learning about hooks, you can create powerful components that can manage state, interact with other components, and respond to user input.
+
+To summarize, components are the building blocks of Solara applications, and they can accept arguments to customize their behavior and appearance. Managing state in components can be done either through local (component) state or application-wide state, each with its advantages and disadvantages. By striking a balance between reusable components and application-specific code, you can create scalable and maintainable applications in Solara. With a solid understanding of components and their state management, you are well on your way to creating powerful and interactive web applications with Solara.

solara/website/pages/documentation/getting_started/content/05-fundamentals/50-state-management.md

@@ -0,0 +1,88 @@
+---
+title: Introduction to state management in Solara
+description: State management is a crucial aspect of building data-focused web applications with Solara. By effectively managing state, you can create interactive
+    and responsive applications that react to changes in data and user input.
+---
+# Introduction
+
+State management is a crucial aspect of building data-focused web applications with Solara. By effectively managing state, you can create interactive and responsive applications that react to changes in data and user input. In Solara, there are two primary ways to define state: global application state using [`solara.reactive`](/documentation/api/utilities/reactive) and local component state using [`solara.use_state`](/documentation/api/hooks/use_state) or [`solara.use_reactive`](/documentation/api/hooks/use_reactive). This article will discuss these two approaches and provide examples of how to use them in your Solara applications.
+
+## Two main ways of defining state in Solara
+
+### Global application state using solara.reactive
+
+Using [`solara.reactive`](/documentation/api/utilities/reactive) allows you to create global state variables that can be accessed and modified from any component within your application. This approach is useful when you need to manage state that is shared across multiple components or when you want to maintain consistency throughout your application.
+
+Example:
+
+```solara
+import solara
+
+color = solara.reactive("red")
+
+@solara.component
+def SomeAppSpecificComponent():
+    solara.Select(label="Color", values=["red", "green", "blue", "orange"], value=color)
+    solara.Markdown("### Solara is awesome", style={"color": color.value})
+
+@solara.component
+def Page():
+    SomeAppSpecificComponent()
+
+```
+
+In this case, the `SomeAppSpecificComponent` is not reusable in the sense that a second component has a different state. The `color` variable is global and shared across all components. This component is meant to be used only once, and mainly helps to organize the code.
+
+## Local component state using solara.use_state
+
+[`solara.use_state`](/documentation/api/hooks/use_state) is a hook that allows you to manage local state within a specific component. This approach is beneficial when you want to encapsulate state within a component, making it self-contained and modular. Local state management is suitable for situations where state changes only affect the component and do not need to be shared across the application.
+
+Example:
+```solara
+import solara
+
+@solara.component
+def ReusableComponent():
+    # color = solara.use_reactive("red")  # 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("### Solara is awesome", style={"color": color})
+
+@solara.component
+def Page():
+    # this component is used twice, but each instance has its own state
+    ReusableComponent()
+    ReusableComponent()
+
+```
+
+## Local component state using solara.use_reactive
+
+
+`use_reactive` is the middle ground between `use_state` and `reactive`. It allows you to create a reactive variable that is scoped to a specific component. This is more a matter of taste, we generally recommend using `use_reactive`, but if you prefer a little less magic, you can use `use_state` instead.
+
+
+If we take the previous example using `use_state`, are replace `use_state` by `use_reactive`, we get:
+```solara
+import solara
+
+@solara.component
+def ReusableComponent():
+    color = solara.use_reactive("red")  # another possibility
+    solara.Select(label="Color",values=["red", "green", "blue", "orange"],
+                  value=color)
+    solara.Markdown("### Solara is awesome", style={"color": color.value})
+
+@solara.component
+def Page():
+    # this component is used twice, but each instance has its own state
+    ReusableComponent()
+    ReusableComponent()
+
+```
+
+## Conclusion
+Understanding the advantages and disadvantages of reusable components and application-specific code can help you strike the right balance between modularity and simplicity when building your Solara applications.
+
+By understanding the trade-offs between local and application state, as well as reusable components and application-specific code, you can make better decisions when designing and building your Solara applications. Both approaches have their benefits and drawbacks, but choosing the right method for your specific use case will help you create more efficient, maintainable, and scalable applications.

solara/website/pages/documentation/getting_started/content/07-deploying/00-overview.md

@@ -0,0 +1,7 @@
+---
+title: Overview of how to deploy your Solara application or dashboard
+description: Solara apps can be easily either self hosted, or hosted on a variety of cloud platforms.
+---
+# Deploying a solara app
+
+A Solara app can be [self hosted](/documentation/getting_started/deploying/self-hosted) or [cloud hosted](/documentation/getting_started/deploying/cloud-hosted).

solara/website/pages/documentation/getting_started/content/07-deploying/10-self-hosted.md

@@ -0,0 +1,273 @@
+---
+title: Deploying and hosting your own Solara app
+description: Solara is compatible with many different hosting solutions, such as Flask, Starlette, FastAPI, and Voila.
+---
+# Self hosted deployment
+
+ * [Flask](#flask)
+ * [Starlette](#flask)
+ * [FastAPI](#flask)
+ * [Voila](#voila)
+ * [Panel](#panel)
+ * [Nginx](#nginx)
+ * [Docker](#docker)
+
+
+Solara runs on several web frameworks, such as
+
+ * [Flask](https://flask.palletsprojects.com/)
+ * [Starlette](https://www.starlette.io/) (and thus [FastAPI](https://fastapi.tiangolo.com/))
+
+The most straightforward and well-tested method to deploy Solara is through the `solara run` command:
+
+    $ solara run sol.py --production
+
+which uses Starlette under the hood.
+
+Your `sol.py` file could resemble the following:
+
+```python
+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)  # noqa
+
+    solara.Button(label=f"Clicked: {clicks}", on_click=increment, color=color)
+```
+
+
+If you're aiming to integrate Solara with other web frameworks such as [Flask](https://flask.palletsprojects.com/deploying/), [Starlette](https://www.starlette.io/), or [FastAPI](https://fastapi.tiangolo.com/), you normally do not execute `solara run sol.py`.
+Instead, start your chosen web framework as directed by their documentation and configure Solara via environment variables. For instance, instead of running the development server like `solara run sol.py`, set the `SOLARA_APP` environment variable to `sol.py`:
+
+    $ export SOLARA_APP=sol.py
+    # run flask or starlette
+
+or look at the examples below for more detailed instructions per web framework. Note that when solara is used this way it [by default runs in production mode](https://solara.dev/documentation/advanced/understanding/solara-server).
+
+## Flask
+
+For Flask, you can consult [the Flask documentation](https://flask.palletsprojects.com/deploying/).
+
+A common solution is to use [gunicorn](https://gunicorn.org/) as the WSGI HTTP Server.
+
+A typical command would be:
+```
+$ SOLARA_APP=sol.py gunicorn --workers 4 --threads=20 -b 0.0.0.0:8765 solara.server.flask:app
+```
+
+Note that we need at least 1 thread per user due to the use of a websocket.
+
+### Embedding in an existing Flask application
+
+If you already have a Flask app and want to add your Solara app behind a prefix, say `'/solara/'`, you can add the [Blueprint](https://flask.palletsprojects.com/blueprints/) to your existing app as follows.
+
+```python
+from flask import Flask
+import solara.server.flask
+
+app = Flask(__name__)
+app.register_blueprint(solara.server.flask.blueprint, url_prefix="/solara/")
+
+@app.route("/")
+def hello_world():
+    return "<p>Hello, World!</p>"
+```
+
+Save this file as `"app.py"` and run
+
+    $  SOLARA_APP=sol.py flask run
+     * Running on http://127.0.0.1:5000/
+
+If you navigate to [http://127.0.0.1:5000/solara](http://127.0.0.1:5000/solara) you should see the Solara app.
+
+## Starlette
+
+For [Starlette](https://www.starlette.io/) we will assume [uvicorn](http://www.uvicorn.org/) for the ASGI webserver and follow their [deployment documentation](https://www.uvicorn.org/deployment/):
+
+```
+$ SOLARA_APP=sol.py uvicorn --workers 4 --host 0.0.0.0 --port 8765 solara.server.starlette:app
+```
+
+### Embedding in an existing Starlette application
+
+If you already have a Starlette app and want to add your Solara app behind a prefix, say `'/solara/'`, you can mount the Starlette routes for Solara to your existing app as follows.
+
+```python
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Mount, Route
+
+import solara.server.starlette
+
+
+def myroot(request: Request):
+    return JSONResponse({"framework": "solara"})
+
+
+routes = [
+    Route("/", endpoint=myroot),
+    Mount("/solara/", routes=solara.server.starlette.routes),
+]
+
+app = Starlette(routes=routes)
+```
+
+Save this file as `"solara_on_starlette.py"` and run
+
+```
+$  SOLARA_APP=sol.py uvicorn solara_on_starlette:app
+...
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+...
+```
+
+If you navigate to [http://127.0.0.1:8000/solara](http://127.0.0.1:8000/solara) you should see the Solara app.
+
+## FastAPI
+
+Since [FastAPI](https://fastapi.tiangolo.com/) is built on Starlette, see the section on [Starlette](#starlette) about how to deploy a Starlette app.
+
+### Embedding in an existing FastAPI application
+
+Use `app.mount` to mount the Solara app into your existing FastAPI app.
+
+```python
+from fastapi import FastAPI
+import solara.server.fastapi
+
+app = FastAPI()
+
+
+@app.get("/")
+def read_root():
+    return {"Hello": "World"}
+
+
+app.mount("/solara/", app=solara.server.fastapi.app)
+```
+
+Save this file as `"solara_on_fastapi.py"` and run
+
+```
+$  SOLARA_APP=sol.py uvicorn solara_on_fastapi:app
+...
+INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+...
+```
+
+If you navigate to [http://127.0.0.1:8000/solara](http://127.0.0.1:8000/solara) you should see the Solara app.
+
+
+## Voila
+
+If you use Voila, [you can use those deployment options](https://voila.readthedocs.io/en/stable/deploy.html).
+
+Make sure you run a notebook where you display the app, e.g.
+```python
+@solara.component
+def Page():
+    ...
+element = Page()
+display(element)
+```
+
+Or consider using [Voila-vuetify](https://github.com/voila-dashboards/voila-vuetify).
+
+Solara apps in Voila do not have support for [routing](/documentation/advanced/understanding/routing)/[multipage](/documentation/advanced/howto/multipage).
+
+
+## Panel
+
+[Panel](https://panel.holoviz.org/) supports [IPyWidgets](https://panel.holoviz.org/reference/panes/IPyWidget.html), which
+means we can also embed the resulting widget from Reacton or Solara. See their [section on deployment](https://panel.holoviz.org/user_guide/Server_Deployment.html) and use the following code as an example of how to include a react component.
+```python
+import panel as pn
+import solara
+
+
+@solara.component
+def ButtonClick(label="Hi"):
+    clicks, set_clicks = solara.use_state(0)
+    def increment():
+        set_clicks(clicks + 1)
+    return solara.Button(f"{label}: Clicked {clicks} times", on_click=increment)
+
+# this creates just an element, Panel doesn't know what to do with that
+element = ButtonClick("Solara+Panel")
+# we explicitly ask Reacton to render it, and give us the widget
+button_widget, render_context = reacton.render_fixed(element)
+# mark this panel to be served by the panel server
+pn.panel(button_widget).servable()
+```
+
+For development/testing purposes, run this script as:
+
+    $ panel serve solara_in_panel.py
+
+Solara apps in Panel do not have support for [routing](/documentation/advanced/understanding/routing)/[multipage](/documentation/advanced/howto/multipage).
+
+## Nginx
+
+If you use Nginx as a (reverse) proxy in front of your Python web server, a minimal
+configuration would be:
+
+```
+server {
+    server_name widgetti.io;
+    listen 80
+    location /solara/ {
+            # the local solara server (could be using Starlette/uvicorn)
+            proxy_pass http://localhost:8765/;
+
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Script-Name /solara;  # informs solara to produce correct urls
+
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection "upgrade";
+            proxy_read_timeout 86400;
+    }
+}
+```
+
+Note that if we use `location /` instead of `location /solara/`, we can skip the `proxy_set_header X-Script-Name /solara` line.
+
+An alternative to using the `X-Script-Name` header with uvicorn, would be to pass the `--root-path` flag, e.g.:
+
+```
+$ SOLARA_APP=sol.py uvicorn --workers 1 --root-path /solara -b 0.0.0.0:8765 solara.server.flask:app
+```
+
+## Docker
+
+There is nothing special about running Solara in Docker. The only things you probably need to change is the interface the server binds to.
+Solara by default binds to localhost, so that it is not accessible from the outside world. Apart from that localhost (or `::1` in case of IPv6)
+might not be available, you probably want the outside world to see your Solara app. For that, you can use `--host=0.0.0.0` or `--host=::` option to bind to all interfaces.
+
+Your Dockerfile could look like:
+
+```Dockerfile
+FROM ....
+
+...
+CMD ["solara", "run", "sol.py", "--host=0.0.0.0", "--production"]
+
+```
+
+For a complete example, you can take a look at:
+  * [https://huggingface.co/spaces/solara-dev/template](https://huggingface.co/spaces/solara-dev/template)
+  * [https://huggingface.co/spaces/giswqs/solara-template/tree/main](https://huggingface.co/spaces/giswqs/solara-template/tree/main)
+  * [https://github.com/opengeos/solara-template](https://github.com/opengeos/solara-template)