solara-ui 1.39.0__py2.py3-none-any.whl → 1.40.0__py2.py3-none-any.whl

solara/website/pages/documentation/advanced/content/30-enterprise/00-overview.md

@@ -2,6 +2,6 @@
 
 Solara enterprise is a not Open Source, but the source code is visible, is free for non-commercial use and installable from pypi.
 
-For commercial use, you require a license. Please [contact](/contact) us for more information.
+For commercial use, you require a license. Please see [pricing](/pricing) for more information.
 
 Solara-enterprise will stay free for non-commercial use and features that are in solara will **not be moved to solara-enterprise**.

solara/website/pages/documentation/advanced/content/30-enterprise/10-oauth.md

@@ -44,12 +44,15 @@ from solara_enterprise import auth
 @solara.component
 def Page():
     if not auth.user.value:
-        solara.Button("Login", icon_name="mdi-login", href=auth.get_login_url())
+        # `get_login_url` should automatically redirect the user back to the current page.
+        # The URL argument is only used here as an example.
+        solara.Button("Login", icon_name="mdi-login", href=auth.get_login_url("documentation/advanced/enterprise/oauth"))
     else:
         userinfo = auth.user.value['userinfo']
         if 'name' in userinfo:
             solara.Markdown(f"### Welcome {userinfo['name']}")
-        solara.Button("Logout", icon_name="mdi-logout", href=auth.get_logout_url())
+        # See above comment
+        solara.Button("Logout", icon_name="mdi-logout", href=auth.get_logout_url("documentation/advanced/enterprise/oauth"))
 ```
 ## How to configure OAuth
 

solara/website/pages/documentation/api/hooks/use_thread.md

@@ -56,3 +56,9 @@ graph TD;
     RUNNING-- "work finished" -->FINISHED
     RUNNING-- "cancel()" -->CANCELLED
 ```
+
+## Future deprecation
+
+Note that [`use_task`](/https://solara.dev/documentation/components/lab/use_task) is an alternative to `use_thread` that will most likely
+replace `use_thread` in the future. Compared to `use_thread`, `use_task` has no intrusive cancel, which turned out to be too large of
+a performance overhead to be useful. Also, `use_task` can run async functions, which is not possible with `use_thread`.

solara/website/pages/documentation/components/data/pivot_table.py

@@ -54,10 +54,10 @@ def Page():
         return solara.Markdown("This example requires vaex, please install it with `pip install vaex`")
     with solara.Div() as main:
         solara.Markdown("# Titanic")
-        selected, on_selected = solara.use_state({"x": [0, 0]})
+        selected, on_selected = solara.use_state({"x": [0, 0]})  # noqa: SH101
         solara.provide_cross_filter()
         with solara.VBox():
-            type, set_type = solara.use_state("view")
+            type, set_type = solara.use_state("view")  # noqa: SH101
             with solara.ToggleButtonsSingle(type, on_value=set_type):
                 solara.Button("PivotTableView", value="view")
                 solara.Button("PivotTable", value="df")

solara/website/pages/documentation/components/input/input.py

@@ -13,6 +13,8 @@ Page = NoPage
 
 
 __doc__ += apidoc(solara.InputText.f)  # type: ignore
+__doc__ += "# InputTextArea"
+__doc__ += apidoc(solara.InputTextArea.f)  # type: ignore
 __doc__ += "# InputFloat"
 __doc__ += apidoc(solara.InputFloat.f)  # type: ignore
 __doc__ += "# InputInt"

solara/website/pages/documentation/components/output/sql_code.py

@@ -42,8 +42,8 @@ if vaex is not None:
 def Page():
     if vaex is None:
         return solara.Error("Vaex is not installed, run pip install vaex-core vaex-hdf5")
-    query, set_query = solara.use_state("SELECT * from titanic")
-    query_executed, set_query_executed = solara.use_state(cast(Optional[str], None))
+    query, set_query = solara.use_state("SELECT * from titanic")  # noqa: SH101
+    query_executed, set_query_executed = solara.use_state(cast(Optional[str], None))  # noqa: SH101
 
     def run_query(cancel: threading.Event) -> pd.DataFrame:
         if not query_executed:
@@ -55,7 +55,7 @@ def Page():
         df = pd.DataFrame(cursor.fetchall(), columns=[k[0] for k in cursor.description])
         return df
 
-    result: solara.Result[pd.DataFrame] = solara.use_thread(run_query, dependencies=[query_executed])
+    result: solara.Result[pd.DataFrame] = solara.use_thread(run_query, dependencies=[query_executed])  # noqa: SH101
     with solara.VBox() as main:
         solara.SqlCode(query=query, tables=table_hints, on_query=set_query)
         enable_execute = (query != query_executed) or result.error is not None

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

@@ -1,5 +1,5 @@
 import solara
-from solara.website.components import Gallery
+from solara.website.components import Gallery, MarkdownWithMetadata
 
 title = "Examples"
 
@@ -34,7 +34,7 @@ def Layout(children):
                 doc = module.__doc__
                 if doc:
                     with solara.VBox(grow=True):
-                        solara.Markdown(doc)
+                        MarkdownWithMetadata(doc)
                 with solara.HBox():
                     if route_current.path != "/":
                         solara.Button("View source code on GitHub", icon_name="mdi-github-circle", href=github_url, class_="ma-2", target="_blank", text=True)

solara/website/pages/documentation/getting_started/content/04-tutorials/_jupyter_dashboard_1.ipynb

@@ -35,7 +35,7 @@
     "\n",
     "We will use a subsample of the [San Fanfrisco crime dataset](https://www.kaggle.com/competitions/sf-crime/data) which contains information on types of crimes and where they were committed.\n",
     "\n",
-    "[Download the CSV file](https://raw.githubusercontent.com/widgetti/solara/master/solara/website/pages/docs/content/04-tutorial/SF_crime_sample.csv.gz) if you want to run this locally, or let the code below sort it out."
+    "[Download the CSV file](https://github.com/widgetti/solara/raw/master/solara/website/pages/documentation/getting_started/content/04-tutorials/SF_crime_sample.csv.gz) if you want to run this locally, or let the code below sort it out."
    ]
   },
   {
@@ -350,7 +350,7 @@
     "\n",
     "ROOT = Path(solara.__file__).parent / \"website\" / \"pages\" / \"docs\" / \"content\" / \"04-tutorial\"\n",
     "path = ROOT / Path(\"SF_crime_sample.csv.gz\")\n",
-    "url = \"https://raw.githubusercontent.com/widgetti/solara/master/solara/website/pages/docs/content/04-tutorial/SF_crime_sample.csv\"\n",
+    "url = \"https://github.com/widgetti/solara/raw/master/solara/website/pages/documentation/getting_started/content/04-tutorials/SF_crime_sample.csv.gz\"\n",
     "\n",
     "if path.exists():\n",
     "    df_crime = pd.read_csv(path)\n",

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

@@ -41,7 +41,7 @@ By utilizing both Widget Components and Function Components, you can create flex
 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.
+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](/documentation/components/layout/column).
 
 Here's an example of a simple Solara component that displays a button:
 
@@ -69,7 +69,7 @@ def MyApp():
     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).
+In this example, we create a `MyApp` function decorated with `@solara.component`. The function creates 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.
@@ -87,7 +87,7 @@ 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.
+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.
 
@@ -111,7 +111,7 @@ def MyButton(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.
+To manage the state of a component in Solara, you can use the [`solara.reactive()`](/documentation/api/utilities/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
@@ -119,22 +119,25 @@ 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.
@@ -143,33 +146,35 @@ By using arguments and state in your Solara components, you can create more dyna
 
 ### 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.
+In addition to using reactive variables for global or application-wide state, you can also manage internal or component-specific state using the [`use_reactive`](/documentation/api/hooks/use_reactive) hook in Solara. The `use_reactive` hook allows you to define reactive variables which 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.
+To use the `use_reactive` hook, call the solara.use_reactive() function inside your component function. This function takes an initial value as an argument and returns a the same reactive variable on each render.
 
-Here's an example that demonstrates the use of the use_state hook to manage internal state in a Solara component:
+Here's an example that demonstrates the use of the use_reactive hook to manage internal state in a Solara component:
 
 ```solara
 import solara
 
+
 @solara.component
 def Counter():
-    count, set_count = solara.use_state(0)
+    count = solara.use_reactive(0)
 
     def increment():
-        set_count(count + 1)
+        count.value += 1
 
     solara.Button("Increment", on_click=increment)
-    solara.Info(f"Counter: {count}")
+    solara.Info(f"Counter: {count.value}")
+
 
 @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.
+In this example, we define a Counter component that uses the `use_reactive` hook to manage its internal state. We create a reactive variable called `count` with an initial value of 0 and a function `increment` 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.
+By using the `use_reactive` 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
 
@@ -216,7 +221,7 @@ This example demonstrates Solara's lazy rendering, where only the relevant compo
 
 
 ## 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 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_reactive` 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.
 

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

@@ -33,21 +33,26 @@ def Page():
 
 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
+You may have heard that globals are considered a bad practice. As with many things, it depends on the context. A possible downside of using a global is that it does not
+allow you to create multiple instances of the same component with different states. But if the state reflects application state, there is by definition only one instance
+of it needed.
 
-[`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.
+### Local component state using solara.use_reactive
 
-Example:
-```solara
+If you do need state that is specific to a component, you should use [`solara.use_reactive`](/documentation/api/hooks/use_reactive) hook. This hook allow you to create local state variables that are scoped to a specific component. This approach is useful 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.
+
+
+```solara hl_lines="6 8"
 import solara
 
+
 @solara.component
 def ReusableComponent():
-    # color = solara.use_reactive("red")  # another possibility
-    color, set_color = solara.use_state("red")  # local state
+    color = solara.use_reactive("red")  # local state (instead of top level solara.reactive)
     solara.Select(label="Color",values=["red", "green", "blue", "orange"],
-                    value=color, on_value=set_color)
-    solara.Markdown("### Solara is awesome", style={"color": color})
+                  value=color)
+    solara.Markdown("### Solara is awesome", style={"color": color.value})
+
 
 @solara.component
 def Page():
@@ -57,22 +62,27 @@ def Page():
 
 ```
 
-## Local component state using solara.use_reactive
+### Local component state using solara.use_state (not recommended)
 
+[`solara.use_state`](/documentation/api/hooks/use_state) is a hook that might be a bit more familiar to React developers. It also allows you to create local state variables that are scoped to a specific component, however, instead of using reactive variables, it uses a tuple of a value and a setter function.
 
-`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.
+We generally recommend using `use_reactive` over `use_state` as it is more easy to refactor between global application state and local component state by switching between `use_reactive` and `reactive`. There is no equivalent for `use_state` at the global level.
 
+If we take the previous example and replace `use_reactive` by `use_state`, we get:
 
-If we take the previous example using `use_state`, are replace `use_state` by `use_reactive`, we get:
-```solara
+Example:
+```solara hl_lines="6 9"
 import solara
 
+
 @solara.component
 def ReusableComponent():
-    color = solara.use_reactive("red")  # another possibility
+    # color = solara.use_reactive("red")  # instead of use_reactive (not recommended)
+    color, set_color = solara.use_state("red")  # local state
     solara.Select(label="Color",values=["red", "green", "blue", "orange"],
-                  value=color)
-    solara.Markdown("### Solara is awesome", style={"color": color.value})
+                    value=color, on_value=set_color)
+    solara.Markdown("### Solara is awesome", style={"color": color})
+
 
 @solara.component
 def Page():
@@ -82,6 +92,186 @@ def Page():
 
 ```
 
+## Mutation pittfalls
+
+In Python, strings, numbers, and tuples are immutable. This means that you cannot change the value of a string, number, or tuple in place.
+Instead, you need to create a new object and assign that to a variable.
+
+```python
+a = 1
+b = a
+# a.value = 2  # ERROR: numbers are immutable
+a = 2  # instead, re-assign a new value, the number 1 will not change
+assert b == 1 # b is still 1
+```
+However, many objects in Python are mutable, including lists and dictionaries or potentially user defined classes. This means that you can change the value of a list, dictionary, or user defined class in place without creating a new object.
+```python
+a = [1, 2, 3]
+b = a  # b points to the same list as a
+a.append(4)  # a is now [1, 2, 3, 4]
+assert b == [1, 2, 3, 4]  # b is also [1, 2, 3, 4]
+```
+
+### Not mutating lists
+
+However, mutations in Python are not observable. **This means that if you change the value of a list, dictionary, or user defined class, Solara does not know that the value has changed and does not know it needs to re-render a component that uses that value.**
+
+```python
+import solara
+
+reactive_list = solara.reactive([1, 2, 3])
+# The next line will not trigger a re-render of a component
+reactive_list.value.append(4)  # ERROR: mutating a list is not observable in Python
+```
+
+Although Solara could potentially track mutations of lists and dictionaries, that would be difficult to do for user defined classes, since we would need to know which methods mutate the object and which do not. Therefore, we have chosen not to include
+any magic tracking of mutations in Solara, and instead require you to re-assign a new value to a reactive variable if you want to trigger a re-render.
+
+```python hl_lines="5"
+import solara
+
+reactive_list = solara.reactive([1, 2, 3])
+# Instead, re-assign a new value
+reactive_list.value = [*reactive_list.value, 4]  # GOOD: re-assign a new list
+```
+
+### Not mutating dictionaries
+
+A similar pattern applies to dictionaries.
+
+```python
+import solara
+
+reactive_dict = solara.reactive({"a": 1, "b": 2})
+reactive_dict.value = {**reactive_dict.value, "c": 3}  # GOOD: re-assign a new dictionary
+# deleting a key
+reactive_dict.value = {k: v for k, v in reactive_dict.value.items() if k != "a"}  # GOOD: re-assign a new dictionary
+# deleting a key (method 2)
+dict_copy = reactive_dict.value.copy()
+del dict_copy["b"]
+reactive_dict.value = dict_copy  # GOOD: re-assign a new dictionary
+```
+
+### Not mutating user defined classes
+
+Or user defined classes, like a Pandas DataFrame.
+
+```python
+import solara
+import pandas as pd
+
+reactive_df = solara.reactive(pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]}))
+# reactive_df.value.append({"a": 4, "b": 7})  # BAD: mutating a DataFrame is not observable in Python
+df_copy = reactive_df.value.copy(deep=True)  # for Pandas 3, deep=True is not necessary
+df_copy = df_copy.append({"a": 4, "b": 7}, ignore_index=True)
+reactive_df.value = df_copy  # GOOD: re-assign a new DataFrame
+```
+
+
+## Creating a store
+
+Using reactive variables is a powerful way to manage state in your Solara applications. However, as your application grows, you may find that you need a more structured way to manage your state.
+
+In larger applications, you may want to create a store to manage your application's state. A store is a regular Python class where all attributes are reactive variables.
+
+In your Python class you are free to expose the reactive variables as attributes, or you can create properties to make certain attributes read-only or to add additional logic when setting an attribute.
+
+A complete TODO application demonstrates this below.
+
+```solara
+import uuid
+from typing import Callable
+
+import solara
+
+
+# this todo item is only a collection of reactive values
+class TodoItem:
+    def __init__(self, text: str, done: bool = False):
+        self.text = solara.reactive(text)
+        self.done = solara.reactive(done)
+        self._uuid = solara.reactive(str(uuid.uuid4()))
+        self._dirty = solara.reactive(True)
+
+    def __str__(self) -> str:
+        return f"{self.text.value} ({'done' if self.done else 'not done'})"
+
+
+# However, this class really adds some logic to the todo items
+class TodoStore:
+    def __init__(self, items: list[TodoItem]):
+        # we keep the items as a protected attribute
+        self._items = solara.reactive(items)
+        self.add_item_text = solara.reactive("")
+
+    @property
+    def items(self):
+        # and make the items read only for a property
+        return self._items.value
+
+    def add_item(self, item):
+        self._items.value = [*self._items.value, item]
+        # reset the new text after adding a new item
+        self.add_item_text.value = ""
+
+    def add(self):
+        self.add_item(TodoItem(text=self.add_item_text.value))
+
+    def remove(self, item: TodoItem):
+        self._items.value = [k for k in self.items if k._uuid.value != item._uuid.value]
+
+    @property
+    def done_count(self):
+        return len([k for k in self.items if k.done.value])
+
+    @property
+    def done_percentage(self):
+        if len(self.items) == 0:
+            return 0
+        else:
+            return self.done_count / len(self.items) * 100
+
+
+@solara.component
+def TodoItemCard(item: TodoItem, on_remove: Callable[[TodoItem], None]):
+    with solara.Card():
+        solara.InputText("", value=item.text)
+        solara.Switch(label="Done", value=item.done)
+        solara.Button("Remove", on_click=lambda: on_remove(item))
+
+
+# The TodoApp component is reusable, so in the future
+# we could have multiple TodoApp components if needed
+# (e.g. multiple lists of todos)
+
+default_store = TodoStore(
+    [
+        TodoItem(text="Write a blog post", done=False),
+        TodoItem(text="Take out the trash", done=True),
+        TodoItem(text="Do the laundry", done=False),
+    ]
+)
+
+
+@solara.component
+def TodoApp(store: TodoStore = default_store):
+    for item in store.items:
+        TodoItemCard(item, on_remove=store.remove)
+
+    with solara.Card("New item"):
+        solara.InputText(label="Text", value=store.add_item_text)
+        solara.Button("Add new", on_click=store.add)
+    solara.ProgressLinear(value=store.done_percentage)
+
+
+@solara.component
+def Page():
+    TodoApp()
+```
+
+
+
+
 ## 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.
 

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

@@ -65,7 +65,7 @@ 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.
+Note that we need at least 1 thread per user due to the use of a websocket. *Make sure you understand the implications of using multiple workers by reading [about handling multiple workers with solara server](https://solara.dev/documentation/advanced/understanding/solara-server#handling-multiple-workers)*
 
 ### Embedding in an existing Flask application
 
@@ -98,6 +98,8 @@ For [Starlette](https://www.starlette.io/) we will assume [uvicorn](http://www.u
 $ SOLARA_APP=sol.py uvicorn --workers 4 --host 0.0.0.0 --port 8765 solara.server.starlette:app
 ```
 
+*Make sure you understand the implications of using multiple workers by reading [about handling multiple workers with solara server](https://solara.dev/documentation/advanced/understanding/solara-server#handling-multiple-workers)*
+
 ### 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.