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

solara/website/pages/documentation/advanced/content/10-howto/50-ipywidget_libraries.md

@@ -1,120 +0,0 @@
-# How can I use ipywidget library X?
-
-Solara can work with any ipywidget library, such as [ipyleaflet](https://github.com/jupyter-widgets/ipyleaflet), [ipydatagrid](https://github.com/bloomberg/ipydatagrid) or [bqplot](https://github.com/bqplot/bqplot).
-
-After `solara` is imported, every widget class has an extra `.element(...)` method added to itself. This allows us to create elements for all existing widgets. For example using regular ipywidgets:
-
-```python
-import ipywidgets
-button_element = ipywidgets.Button.element(description="Click me")
-```
-
-## Example with ipyleaflet
-
-For instance, if we want to use ipyleaflet using the classical ipywidget API, we can do:
-
-```python
-import ipyleaflet
-
-map = ipyleaflet.Map(center=(52, 10), zoom=8)
-
-marker = Marker(location=(52.1, 10.1), draggable=True)
-m.add_layer(marker)
-```
-
-In Solara, we should not create widgets, but elements instead. We can create elements using the `.element(...)` method. This method takes the same arguments as the widget constructor, but returns an element instead of a widget. The element can be used in the same way as a widget, but it is not a widget. It is a special object that can be used in Solara.
-
-However, how do we add the marker to the map? The map element object does not have an `add_layer` method. That is the downside of using the React-like API of Solara. We cannot call methods on the widget
-anymore. Instead, we need to pass the marker to the layers argument. That, however, introduces a new problem. Ipyleaflet by default adds a layer to the map when it is created, and the `add_layer` adds the second layer. We now need to manually add the map layer ourselves.
-
-Putting this together.
-```solara
-import ipyleaflet
-import solara
-
-url = ipyleaflet.basemaps.OpenStreetMap.Mapnik["url"]
-
-@solara.component
-def Page():
-    marker = ipyleaflet.Marker.element(location=(52.1, 10.1), draggable=True)
-    map = ipyleaflet.Map.element(
-        center=(52, 10),
-        zoom=8,
-        layers=[
-            ipyleaflet.TileLayer.element(url=url),
-            marker,
-        ],
-    )
-```
-
-Note that this is about the worst example of something that looks easy in ipyleaflet using the classical API becoming a bit more involved in Solara.
-In practice, this does not happen often, and your code in general will be shorter and more readable.
-
-Another thing of note is that ipyleaflet uses CSS `z-index` to layer content, potentially causing issues with your map overlaying other content. This can be avoided by styling the parent element of the map with `isolation: isolate;`. For examples of how to do this, you can see the below examples.
-
-See also [the basic ipyleaflet example](/examples/libraries/ipyleaflet) and [the advanced ipyleaflet example](/examples/libraries/ipyleaflet_advanced).
-
-## Example with ipywidgets
-
-Most widgets in (classic) ipywidgets can be used without problems in Solara. Two widgets stand out that are difficult to use.
-
-### Image
-
-The `Image` widget can be used normally, but we cannot use the factory methods like `Image.from_file` and `Image.from_url`, for this reason we create the [Image](/api/image) component that
-makes this easier.
-
-### Video
-
-The `Video` widget does not have a corresponding component in solara (yet), but we can manually fill in the `value`. For example:
-
-```solara
-import solara
-import ipywidgets
-
-url = 'https://user-images.githubusercontent.com/1765949/240697327-25b296bd-72c6-4412-948b-2d37e8196260.mp4'
-
-
-@solara.component
-def Page():
-    ipywidgets.Video.element(value=url.encode('utf8'),
-        format='url',
-        width=500
-    )
-
-```
-
-## Wrapper libraries
-
-However, because we care about type safety, we generate wrapper components for some libraries. This enables type completion in VSCode, type checks with VSCode, and mypy.
-
-The following libraries are fully wrapped:
-
-  * `ipywidgets` wrapper: `reacton.ipywidgets`
-  * `ipyvuetify` wrapper: `reacton.ipyvuetify`
-  * `bqplot` wrapper: `reacton.bqplot`
-  * `ipycanvas` wrapper: `reacton.ipycanvas`
-
-This allows us to do instead:
-```python
-import reacton.ipywidgets as w
-button_element = w.Button(description="Click me)
-```
-
-And enjoy auto complete and type checking.
-
-## Create your own wrapper
-
-The best example would be to take a look at the source code for now:
-
-  * [ipywidgets](https://github.com/widgetti/reacton/blob/master/reacton/ipywidgets.py)
-  * [bqplot](https://github.com/widgetti/reacton/blob/master/reacton/bqplot.py)
-  * [ipyvuetify](https://github.com/widgetti/reacton/blob/master/reacton/ipyvuetify.py)
-
-The code is generated by executing:
-
-    $ python -m reacton.ipywidgets
-
-
-## Limitation
-
-Reacton assumes the widget constructor arguments match the traits. If this is not the case, this may result in runtime errors. If this leads to issues, please open an [Issue](https://github.com/widgetti/solara/issues/new) to discuss this.

solara/website/pages/documentation/advanced/content/20-understanding/00-introduction.md

@@ -1,4 +0,0 @@
-# Introduction
-
-Solara builds on existing technologies. If you are new to Solara or some of the underlying technologies, you may feel lost at times.
-These 'understanding' guides are meant to help you understand topics at a deeper level and how they connect to Solara.

solara/website/pages/documentation/advanced/content/20-understanding/05-ipywidgets.md

@@ -1,30 +0,0 @@
-# IPywidgets
-
- * [Documentation](https://ipywidgets.readthedocs.io/en/stable/)
- * [GitHub](https://github.com/jupyter-widgets/ipywidgets)
-
-IPywidgets is a Python library for creating UI objects that live in the Python side *and* on the browser side. They provide bi-directional communication, meaning you can change a slider in the browser, or from the Python side. `IPywidgets` takes care of communication and synchronization.
-
-With ipywidgets you get access to the browser without writing a single line of JavaScript or CSS.
-
-
-## Solara and ipywidgets
-
-Solara can use almost all existing ipywidgets, from the core library that provides sliders, to [ipyvuetify](./ipyvuetify) which gives us rich UI elements, to ipyvolume that gives us interactive 3d visualizations.
-
-## Where do ipywidgets work?
-
-There are various places where ipywidgets work, and [Solara server](./solara-server) is one of these. There is a [list of frontends that support](https://github.com/jupyter/jupyter/wiki/Jupyter-Widgets#frontends-that-support-jupyter-widgets) meaning that you ipywidgets based applications run
-on many places (From Jupyter Notebook, Jupyter Lab, Google Colab to even VS Code).
-
-## Which ipywidget libraries exist?
-
-There is a list [of ipywidget libraries](https://github.com/jupyter/jupyter/wiki/Jupyter-Widgets#custom-jupyter-widgets), but that are probably
-many more.
-
-
-## Do all ipywidget libraries work with Solara server?
-
-All these libraries should work with [Solara server](./solara-server), but we have not tested all of them. If you use a regular ipywidget based app, you should not run into issues. If you do, consider [opening a GitHub issue](https://github.com/widgetti/solara/issues/new)
-
-If you write a Reacton-based Solara application, check out [the reacton page](./reacton).

solara/website/pages/documentation/advanced/content/20-understanding/06-ipyvuetify.md

@@ -1,38 +0,0 @@
-# ipyvuetify
-
- * [Documentation](https://ipyvuetify.readthedocs.io/)
- * [GitHub](https://github.com/widgetti/ipyvuetify)
-
-
-ipyvuetify is an [ipywidget based](./ipywidgets) library, that wraps the [Vuetify component library](https://v2.vuetifyjs.com/) to give beautiful
-material design based widgets.
-
-![ipyvuetify screencast demo](https://user-images.githubusercontent.com/46192475/79730684-78954880-82f1-11ea-855b-43a2b619ca04.gif)
-
-## Reacton and ipyvuetify
-
-We consider ipyvuetify one of the most essential ipywidget libraries, and that is the reason why [Reacton](/documentation/advanced/understanding/reacton) ships with
-generated ipyvuetify components to make your app type safe.
-
-```solara
-
-import solara
-# rv is the reacton-ipyvuetify wrapper for Reacton/Solara
-import reacton.ipyvuetify as rv
-
-
-@solara.component
-def Page():
-    clicks, set_clicks = solara.use_state(0)
-    def my_click_handler(*ignore_args):
-        # trigger a new render with a new value for clicks
-        set_clicks(clicks+1)
-    button = rv.Btn(children=[f"Clicked {clicks} times"])
-    rv.use_event(button, 'click', my_click_handler)
-    return button
-```
-
-
-## Solara and ipyvuetify
-
-Many of the Solara components are based on ipyvuetify. Do not hesitate the look at the [source code of the Solara components](https://github.com/widgetti/solara/tree/master/solara/components) to learn how to create your own components.

solara/website/pages/documentation/advanced/content/20-understanding/10-reacton.md

@@ -1,24 +0,0 @@
-# Reacton
-
- * [Documentation](https://reacton.solara.dev/)
- * [GitHub](https://github.com/widgetti/reacton/)
-
-Reacton is a React-like layer around ipywidgets.
-
-Using a declarative way, in a React (JS) style, makes your codebase smaller, less error-prone, and easier to reason about. We don't see a good reason not to use it.
-
-Also, React has proven itself, and by adopting a proven technology, we can stand on the shoulders of giants, make use of a lot of existing resources, and do not have to reinvent the wheel.
-
-
-## Solara or Reacton?
-
-We consider Solara a superset of Reacton, and that's why the full namespace of the `reacton` package is imported into the `solara` package.
-Therefore, you can write `solara.use_state` or `reacton.use_state`, they are the same function.
-
-The reason for this is simplicity for newcomers, who don't care about the difference between `solara` and `reacton`.
-But in practice, it also saves having to import both `solara` and `reacton`.
-Also, when writing Solara based apps, one does not think about Reacton anymore, it is all Solara.
-
-## How do I use Reacton or Solara with ipywidget library X
-
-[The reacton documentation has a page on this](https://reacton.solara.dev/en/latest/libraries/)

solara/website/pages/documentation/advanced/content/20-understanding/12-reacton-basics.md

@@ -1,104 +0,0 @@
-# Reacton basic understanding
-
-
-Let us take our favorite component, and try to understand a bit better how it works to improve your understanding of Reacton and thus how to use Solara.
-
-
-```solara
-import solara
-
-
-@solara.component
-def ClickButton():
-    clicks, set_clicks = solara.use_state(0)
-
-    def my_click_hander():
-        set_clicks(clicks + 1)
-
-    return solara.Button(label=f"Clicked: {clicks}", on_click=my_click_hander)
-
-Page = ClickButton
-```
-
-This example does a few things:
-
- * Add state (`clicks`) to the component.
- * Create a callback function (`my_click_handler`). When executed, it will increase ask Solara/Reacton to increase the `clicks` value on the next render, by calling `set_clicks`.
- * Pass the callback function to the child component (`Button`).
- * Set the `label` value on each render.
-
-Now if a user clicks the button:
-
- * The `my_click_hander` callback will be called by Solara/Reacton.
- * Your code (the body of `my_click_hander`) will be executed and will ask Reacton to change the state of `clicks` by increasing the value by 1.
- * Solara/Reacton got asked to change the of `clicks`, and will execute your render function (the body of the `ClickButton` component) once.
- * Solara/Reacton will compare the return value of your component and will update the associated widget. In this case it will update the label to `"`Clicked: 1"`.
-
-This pattern is very common, where a parent component (ClickButton) managed the state (the number of times clicked), and state changes (increasing the clicks by 1 on a button click).
-
-## Graphically
-
-Is the above text a bit dry? Maybe the annotated code will make it easier to understand for you.
-
-![basics](https://dxhl76zpt6fap.cloudfront.net/public/docs/reacton-basics.webp)
-
-
-## Going deeper
-
-
-Still not satisfied? Let's go through all the steps in more detail in this sequence diagram:
-
-```mermaid
-sequenceDiagram
-    actor You
-    participant Frontend as Frontend
-    participant ipywidgets as IPyWidgets
-    participant react as Reacton
-    participant component as ButtonClick
-    participant app as Solara
-
-    app->>component: el=ButtonClick()
-    app->>react: render(el)
-
-    activate react
-    react->>component: render()
-    component->>react: use_state(0)<br>(returns 0)
-
-    react->>react: reconsolidate()
-    react->>ipywidgets: create Button<br>description="Clicked: 0"
-    deactivate react
-    ipywidgets--)Frontend: create Button view
-
-    You->>Frontend: clicks button
-
-    Frontend--)ipywidgets: Button clicked
-    ipywidgets->>component: on_click
-    activate component
-    component->>react: set_clicks(1)
-    activate react
-    deactivate component
-    react->>+component: render()
-    component->>-react: use_state(0)<br> (now returns 1)
-    react->>react: reconsolidate()
-    react->>ipywidgets: update Button<br>description="Clicked 1"
-    deactivate react
-    ipywidgets--)Frontend: update Button<br>description="Clicked 1"
-```
-
-In words
-
-   1. Solara create `el = ButtonClick()` from your component.
-   1. The `display(el)` triggers the call to Reacton.
-   1. The render call enters the render phase, which will call the function body (which we call render function) of the `ButtonClick` component.
-   1. Our ButtonClick render function calls [`use_state`](/documentation/api/hooks/use_state). Because this is our first render phase, this returns the initial value (0).
-   1. The ButtonClick render function returns a Button element (not a widget!) with `description="Clicked: 0 times"`.
-   1. The Reacton render call is done with the render phase, and enters the reconciliation phase, where it looks at the difference between the real widgets and the virtual widgets tree (represented by the Reacton elements). We find there is no previous widget associated with the virtual widget (or element) and decide to create a widget.
-   1. Asynchronously via the Jupyter protocol, a widget model and view are created and displayed to the user in the browser.
-   1. The user clicks on the button.
-   1. The `on_click` handler gets triggered on the Python side, inside of the `ButtonClick` component (called `my_click_handler`).
-   1. `my_click_handler` handler calls `set_clicks(1)` which triggers a re-render.
-   1. The render call enters the render phase, which calls the render function of `ButtonClick` for the second time.
-   1. Our ButtonClick render function calls [`reacton.use_state`](#use_state). Because this is our second render phase, this returns the last set value, which is 1.
-   1. The ButtonClick render function returns a new Button element (not a widget!) with the description `"Clicked: 1 times"`.
-   1. The Reacton render call is done with the render phase, and enters the reconciliation phase, where it looks at the difference between the real widgets and the virtual widgets tree (represented by the Reacton elements). We find there is a widget associated with the virtual widget (or element) and decide to update the changed attributes of the widget and set `description` to `"Clicked: 1 times"`.
-   1. Asynchronously via the Jupyter protocol, the widet model and view are being updated in the browser.

solara/website/pages/documentation/advanced/content/20-understanding/15-anatomy.md

@@ -1,19 +0,0 @@
-# Anatomy
-
-For communication, it is useful to speak the same language and use the same idiom.
-As a reference, we provide this "anatomy" image of our favorite `ClickButton` component with a layout that we consider best practice.
-
-![anatomy](https://dxhl76zpt6fap.cloudfront.net/public/docs/anatomy.webp)
-
-## Explanations
-
- * Import `solara` and you also get the `reacton` namespace with it (saves typing, and finding/remembering which hooks is in which packages)
- * Add a `@solara.component` decorator to turn your function into a component.
- * Start with `use_state` hooks and other hooks. This avoids issues with [conditional hooks](/documentation/advanced/understanding/rules-of-hooks) or hooks in loops.
- * Data/state flows down (to children)
- * Information (events, data) flows up from children via events and callbacks (`on_<some_event_name>=my_callback`).
- * If you need multiple components, use a [parent container component](/documentation/components/layout/app_layout) as context manager. A good default name to give this context manager is `main`. Don't forget to return it in your render function!
- * The body of your component (the function you wrote) is called the render function.
- * In between the hooks as defining all your elements, you put your custom code, like checking variables, defining callbacks, and other logic.
- * The only way for a component to cause itself to rerender is to have state (using `use_state`) and change it (calling the second return value with a different value).
- * Reacton is declarative. Your render function gets executed after every state change (and thus should be relatively cheap to execute). Reacton will find out the changes for you and will add, remove and update the associated widgets for you. This means you can easily do conditional rendering (creating an element in an if statement or in a loop).

solara/website/pages/documentation/advanced/content/20-understanding/17-rules-of-hooks.md

@@ -1,3 +0,0 @@
-# Rules of hooks
-
-For now, we refer to the [ReactJS documentation](https://reactjs.org/docs/hooks-rules.html).

solara/website/pages/documentation/advanced/content/20-understanding/18-containers.md

@@ -1,160 +0,0 @@
-# Laying out components with containers
-
-## Introduction
-Some components, such as our favorite `ClickButton` only add logic on top of an existing component:
-
-```solara
-import solara
-
-
-@solara.component
-def ClickButton():
-    clicks, set_clicks = solara.use_state(0)
-
-    def my_click_hander():
-        set_clicks(clicks + 1)
-
-    # We return a single component
-    return solara.Button(label=f"Clicked: {clicks}", on_click=my_click_hander)
-
-Page = ClickButton
-```
-
-
-## Containers with children
-However, more sophisticated components will add multiple components together into a container component, let's take a look at an example.
-
-```solara
-import solara
-
-
-@solara.component
-def FancyClickButton():
-    clicks, set_clicks = solara.use_state(0)
-
-    def increase_count():
-        set_clicks(clicks + 1)
-
-    def reset_count():
-        set_clicks(0)
-
-    button_increase = solara.Button(label=f"Clicked: {clicks}", on_click=increase_count)
-    button_reset = solara.Button(label="Reset", on_click=reset_count)
-
-    return solara.Row(children=[button_increase,
-                                 button_reset,
-                                 ])
-
-
-Page = FancyClickButton
-
-```
-
-
-Here we use an [HBox](/documentation/components/layout/hbox) to lay out two child components horizontally.
-
-
-## Cleaner way to add children to containers
-
-Because using container components is so common, we created a more convenient way to pass children to components and made your code look neater and more structured as well (avoiding nested lists).
-
-```solara
-import solara
-
-
-@solara.component
-def FancyClickButton():
-    clicks, set_clicks = solara.use_state(0)
-
-    def increase_count():
-        set_clicks(clicks + 1)
-
-    def reset_count():
-        set_clicks(0)
-
-    with solara.Row() as main:
-        solara.Button(label=f"Clicked: {clicks}", on_click=increase_count)
-        solara.Button(label="Reset", on_click=reset_count)
-    return main
-
-Page = FancyClickButton
-
-```
-
-Here we are using the top-level Row as a context manager (with the name `main`). All child elements created within this context are automatically added as a child.
-
-### About Context managers
-
-Context managers are a Python language feature, there are two ways to use them:
-
-```python
-
-with some_anonymous_context_manager():
-    print("some code")
-
-with some_named_context_manager() as this_is_my_name:
-    print("some other code")
-```
-
-Where the last example assigns the context manager to a variable. In Solara we only need to do that to the top context manager, since we need to return that in our [render function](/documentation/advanced/understanding/anatomy).
-
-All Reacton or Solara components return elements that can be used as context managers. Context managers allow for code to be executed before and after your code block inside of the context manager. This allows us to capture all elements created inside of the context manager. If you want to know more about context managers, consult the Python documentation since this is not Solara specific.
-
-
-### Nested layout
-
-Adding children using context managers work at any level, you can nest Rows and Columns [or any other containers](/api#components).
-
-
-```solara
-import solara
-
-
-@solara.component
-def FancyClickButton():
-    clicks, set_clicks = solara.use_state(0)
-
-    def increase_count():
-        set_clicks(clicks + 1)
-
-    def reset_count():
-        set_clicks(0)
-
-    with solara.Column() as main:
-        with solara.Row():
-            solara.Button(label=f"Clicked: {clicks}", on_click=increase_count)
-            solara.Button(label="Reset", on_click=reset_count)
-        solara.Text("I am a child of a VBox")
-    return main
-
-Page = FancyClickButton
-
-```
-
-
-## Automatic containers
-
-
-Instead of returning the main container, Solara also allows you to not have a return value (or return `None`).
-If that is the case, Solara will look at what elements you created. If you created one, that element will be taken
-as a return value instead. If you make more than one element, those elements will be automatically wrapped by
-a [Column](/documentation/components/layout/column). The only benefit of returning an element, is that we can infer the correct return type,
-which can be useful for testing purposes. Users should probably never return an element, but use the automatic
-container feature.
-
-```solara
-import solara
-
-
-@solara.component
-def ClickButton():
-    clicks, set_clicks = solara.use_state(0)
-
-    def my_click_hander():
-        set_clicks(clicks + 1)
-
-    solara.Button(label=f"Clicked: {clicks}", on_click=my_click_hander)
-    solara.Button(label=f"Reset", on_click=lambda: set_clicks(0))
-
-Page = ClickButton
-```

solara/website/pages/documentation/advanced/content/20-understanding/20-solara.md

@@ -1,13 +0,0 @@
-# Solara
-
-Solara combines [ipywidgets](./ipywidgets), [reacton](./reacton) and puts it into a opinionated framework to make web apps with a focus on data (data apps for short).
-
-Solara consists of two main parts
-
-## Solara-ui
-
-A set of opinionated react components and hooks that allow you to build web apps and data apps faster.
-
-## Solara-server
-
-A web framework for deploying web apps or data apps in production. Opinionated about pages and routing.