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

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

@@ -0,0 +1,196 @@
+---
+title: Building multi-page apps in Solara
+description: The simplest way to create a multi-page app is to create a directory with multiple scripts.
+---
+
+# Multi-page support
+
+In the [Web App tutorial](/documentation/getting_started/tutorials/web-app), we created an application consisting of a single page. Web applications generally have multiple pages, and Solara supports this as well.
+
+
+## Multiple scripts
+
+The simplest way to create a multi-page app is to create a directory with multiple scripts.
+
+```bash
+$ solara create button multipage-demo/01-click-button.py
+Wrote:  /mypath/multipage-demo/01-click-button.py
+...
+$ solara create markdown multipage-demo/02-markdown-editor.py
+Wrote:  /mypath/multipage-demo/02-markdown-editor.py
+...
+```
+
+
+You should have the following directory structure:
+
+```
+multipage-demo
+├── 01-click-button.py
+└── 02-markdown-editor.py
+```
+
+Now run Solara, with this directory as argument:
+
+```bash
+$ solara run ./multipage-demo
+Solara server is starting at http://localhost:8765
+```
+
+Giving you an output like:
+
+![screencapture](https://user-images.githubusercontent.com/1765949/214879312-19323de3-c4ce-4528-ac84-5aa0021ca5b4.gif)
+
+Solara now:
+
+   * Sort the paths according to the filename (hence the 01- and 02- prefix)
+   * Generate a nice URL by stripping of prefix, splitting the filename taking out `-`, `_` and spaces, and join them together using a `-`  (e.g. "/markdown-editor").
+   * Generate a nice default title similar to the link, but now capitalize the first letter and join with a space instead  (e.g. "Mardown Editor").
+   * The first page will be the default (and its URL will be empty instead, i.e., the empty string `""`)
+   * Since the first script does not define a `Layout` component, nor did we add a `__init__.py` with a `Layout` component, Solara will add a [Layout component](/documentation/components/layout/app_layout) which includes a navigation sidebar.
+   * If a path is a directory, Solara will recursively scan the subdirectory and include it in the navigation. Read more on this in the [Layout section](layout)
+
+Solara will render two pages:
+
+   * http://localhost:8765 with title "Click Button"
+   * http://localhost:8765/markdown-editor with title "Markdown Editor"
+
+
+
+## Classical widgets support
+
+Multipage is also supported for regular ipywidgets.  An example directory can be seen on [GitHub](https://github.com/widgetti/solara/tree/master/tests/unit/solara_test_apps/multipage),
+which we use for testing.
+
+A large difference between using regular ipywidgets for pages compared to using components is that there is no lifecycle
+management in regular ipywidgets. This means Solara cannot clean up your ipywidget-based page (garbage-collect the unused widgets, unregister callbacks)
+when a user navigates away from your page.
+
+At the same time, rerunning your regular ipywidget-based script each time a user navigates to that page will result in a buildup of many widgets.
+
+This means that Solara will run your page once (the first time it is loaded by a user/browser tab), and, when navigating back,
+will show the page in the same state as when the user left the page.
+
+
+## As a package
+
+Once you start building a larger application, it pays off using a Python package instead. This allows you to organize and distribute your app as a Python package (as a wheel for instance) and allows you to organize your application
+into reusable packages for components, stores, hooks etc.
+
+As a quickstart, we can generate a startup project using:
+```bash
+$ solara create portal solara-test-portal
+Wrote:  /Users/maartenbreddels/github/widgetti/solara/solara-test-portal
+Install as:
+         $ (cd solara-test-portal; pip install -e .)
+Run as:
+         $ solara run solara_test_portal.pages
+```
+
+You should have the following directory structure:
+```bash
+├── LICENSE
+├── Procfile # will make it run on heroku
+├── mypy.ini # adds strict type checking
+├── pyproject.toml  # make it installable with pip/hatch etc
+└── solara_test_portal  # Python package containing all code
+    ├── __init__.py
+    ├── components # contains general react components
+    │   ├── __init__.py
+    │   ├── header.py
+    │   └── layout.py
+    ├── content  # contains content (markdown articles in this case)
+    │   └── articles
+    │       ├── 7-reasons-why-i-love-vaex-for-data-science.md
+    │       └── a-hybrid-apache-arrow-numpy-dataframe-with-vaex-version-4.md
+    ├── data.py  # here is where we store shared data or application state
+    └── pages  # contains the pages
+        ├── __init__.py
+        ├── article
+        │   └── __init__.py
+        ├── tabular.py
+        └── viz
+            ├── __init__.py
+            └── overview.py
+```
+
+Install it using
+```bash
+$ (cd solara-test-portal; pip install -e .)
+```
+
+Run it with
+```bash
+$ solara run solara_test_portal.pages
+Solara server is starting at http://localhost:8765
+```
+
+Go to http://localhost:8765 ([or click here](http://localhost:8765)), explore the source code, edit it, save it, and watch the web app reload instantly.
+
+
+## In a single script
+
+If you want to setup a multipage app in a single script, you do not need to define a `Page` component, but you can define a list of routes.
+
+```python
+import solara
+
+
+@solara.component
+def Home():
+    solara.Markdown("Home")
+
+
+@solara.component
+def About():
+    solara.Markdown("About")
+
+
+routes = [
+    solara.Route(path="/", component=Home, label="home"),
+    solara.Route(path="about", component=About, label="about"),
+]
+```
+
+See more details in the [Route section](/documentation/advanced/understanding/routing).
+
+## Dynamic pages
+
+In the previous section we created the example portal app. Taking a look at
+tabular.py, we see the `Page` component takes an additional arguments.
+
+```python
+@solara.component
+def Page(name: str):
+    ...
+```
+
+
+Solara recognizes this and will pass all routes such as `/tabular/foo` and `/tabular/bar` to this Page component passing for instance `"foo"` or `"bar"` as an argument, such that you can dynamically render a page based on the URL.
+
+An example Page component could look like this:
+
+```python
+@solara.component
+def Page(name: str = "foo"):
+    subpages = ["foo", "bar", "solara", "react-ipywidgets"]
+    solara.Markdown(f"You are at: {name}")
+    # bunch of buttons which navigate to our dynamic route
+    with solara.Row():
+        for subpage in subpages:
+            with solara.Link(subpage):
+                solara.Button(label=f"Go to: {subpage}")
+```
+
+By giving the name argument a default value of `"foo"`, Solara will also accept the `/tabular` url.
+
+# What you have learned
+
+  * Putting multiple Solara app script into a directory allows Solara to show a multipage app.
+  * If no `Layout` component is provided, Solara adds a default navigation sidebar.
+  * Large application can benefit from setting up a Python package, use `solara create portal my-name` to create one.
+  * By adding an argument to the `Page` component, routes like `/tabular` will turn into dynamic routes (e.g. `/tabular/dynamic-name`) and pass the argument (`"dynamic-name"` in this case) to the `Page` component to implement dynamic pages.
+
+# What next?
+
+  * Also check out the [Multipage example](/documentation/examples/fullscreen/multipage) for more inspiration.

solara/website/pages/documentation/advanced/content/10-howto/20-layout.md

@@ -0,0 +1,125 @@
+---
+title: Making different layouts in Solara
+description: Solara comes with a layout system ideal for data apps. Learn how to use them in this short guide.
+---
+
+# Layout
+
+Solara comes with a layout system ideal for data apps.
+
+The following example shows 80% of what you need to know to lay out your app.
+
+```solara
+import solara
+
+@solara.component
+def Page():
+    with solara.Column():
+        solara.Title("I'm in the browser tab and the toolbar")
+        with solara.Sidebar():
+            solara.Markdown("## I am in the sidebar")
+            solara.SliderInt(label="Ideal for placing controls")
+        solara.Info("I'm in the main content area, put your main content here")
+        with solara.Card("Use solara.Columns([1, 2]) to create relatively sized columns"):
+            with solara.Columns([1, 2]):
+                solara.Success("I'm in the first column")
+                solara.Warning("I'm in the second column, I am twice as wide")
+                solara.Info("I am like the first column")
+
+        with solara.Card("Use solara.Column() to create a full width column"):
+            with solara.Column():
+                solara.Success("I'm first in this full with column")
+                solara.Warning("I'm second in this full with column")
+                solara.Error("I'm third in this full with column")
+
+        with solara.Card("Use solara.ColumnsResponsive(6, large=4) to response to screen size"):
+            with solara.ColumnsResponsive(6, large=4):
+                for i in range(6):
+                    solara.Info("two per column on small screens, three per column on large screens")
+```
+
+[Navigate here to watch this layout in a full browser window](/documentation/examples/fullscreen/layout-demo)
+
+The key takeaways are:
+
+  * By default, Solara will wrap your component in an [AppLayout](/documentation/components/layout/app_layout), which will give you:
+    * Room for a sidebar, that you can populate using the [Sidebar](/documentation/components/layout/sidebar) component.
+    * A toolbar showing the [Title](/documentation/components/page/title).
+    * Not visible here: In the case of [multiple pages](/documentation/advanced/howto/multipage) will include page navigation tabs. See [The multipage demo app](/documentation/examples/fullscreen/multipage) for an example.
+  * Use [Card](/documentation/components/layout/card) to put related components together with a title.
+  * Use [Column](/documentation/components/layout/column) to simply layout components under each other.
+  * Use [Columns](/documentation/components/layout/columns) if you want to have a few columns with relative sizes next to each other.
+  * Use [ColumnsResponsive](/documentation/components/layout/columns_responsive) to have the column widths respond to screen size.
+
+
+
+## Changing the default layout
+
+While [AppLayout](/documentation/components/layout/app_layout) may be sufficient in 80% of the cases. Solara provides a way to change this default layout in [Solara server](/documentation/advanced/understanding/solara-server).
+
+You can define your own `Layout` component in the `__init__.py` file in the same directory of your app script.
+
+
+For instance, putting the following `Layout` component in `__init__.py` will give you effectively the same [AppLayout](/documentation/components/layout/app_layout):
+```python
+@solara.component
+def Layout(children=[]):
+    print("I get called before the Page component gets rendered")
+    return solara.AppLayout(children=children)
+```
+
+
+### No Layout
+If you do not want to have any layout, you can disable it using:
+
+```python
+@solara.component
+def Layout(children=[]):
+    # there will only be 1 child, which is the Page()
+    return children[0]
+```
+
+This layout leaves every page responsible for creating its own header, footer, and/or menu structure for navigation.
+
+
+### Layout with navigation
+
+In case you want to set up your own layout system, which sets up navigation as well, this example may get you started. It may help
+to [understand routing](/documentation/advanced/understanding/routing).
+```python
+@solara.component
+def Layout(children=[]):
+    # Note that children being passed here for this example will be a Page() element.
+    route_current, routes_all = solara.use_route()
+    with solara.Column():
+        # put all buttons in a single row
+        with solara.Row():
+            for route in routes_all:
+                with solara.Link(route):
+                    solara.Button(route.path, color="red" if route_current == route else None)
+        # under the navigation buttons, we add our children (the single Page())
+        solara.Column(children=children)
+```
+
+
+### Nested Layouts
+
+Each subdirectory (or subpackage) can define a `Layout` component in its own `__init__.py`, which then is embedded into the parent Layout to provide a hierarchical
+nested layout tree.
+
+This is useful for larger apps where each subdirectory may add a bit of layout/chrome around your page.
+
+
+
+## Components
+
+The following [Container components](/documentation/advanced/understanding/containers) can be used to define the layout of you app.
+
+ * [Row](/documentation/components/layout/row)
+ * [Column](/documentation/components/layout/column)
+ * [ColumnsResponsive](/documentation/components/layout/columns_responsive)
+ * [GridFixed](/documentation/components/layout/gridfixed)
+ * [GridDraggable](/documentation/components/layout/griddraggable)
+ * [VBox](/documentation/components/layout/vbox) (kept for ipywidgets compatibility, please use Column)
+ * [HBox](/documentation/components/layout/hbox) (kept for ipywidgets compatibility, please use Row)
+ * [AppLayout](/documentation/components/layout/app_layout) Not often used directly, since Solara will already wrap your page in it. Sometimes re-used in a new `Layout` component.

solara/website/pages/documentation/advanced/content/10-howto/30-testing.md

@@ -0,0 +1,162 @@
+---
+title: Testing your Solara application, both front and back end
+description: Using solara you can test both the front and back end functionalities of your application.
+---
+
+# Testing with Solara
+
+
+## Testing without a Browser
+
+We recommend using pytest to test the application logic of your Solara components. To get inspiration for writing tests that cover component logic and their interactions with existing components, refer to the [tests in the Solara repository](https://github.com/widgetti/solara/tree/master/tests).
+
+## Testing with a Browser
+
+### Installation
+
+Solara is using the `pytest-ipywidgets` pytest plugin together with [Playwright for Python](https://playwright.dev/python/) to test your widgets, components or applications using a browser, for both unit as well as integration tests.
+
+To install `pytest-ipywidgets` and Playwright for Python, run the following commands:
+```
+$ pip install "pytest-ipywidgets[solara]"  # or "pytest-ipywidgets[all]" if you also want to test with Jupyter Lab, Jupiter Notebook and Voila.
+$ playwright install chromium
+```
+
+### Testing widgets using Solara server
+
+The most convenient way to test a widget, is by including the `solara_test` fixture in your test function arguments. Here's an example:
+
+```python
+# file tests/ui/test_widget_button.py
+import ipywidgets as widgets
+import playwright.sync_api
+from IPython.display import display
+
+def test_widget_button_solara(solara_test, page_session: playwright.sync_api.Page):
+    # this all runs in process, which only works with solara
+    # also, this test is only with pure ipywidgets
+    button = widgets.Button(description="Click Me!")
+
+    def change_description(obj):
+        button.description = "Tested event"
+
+    button.on_click(change_description)
+    display(button)
+    button_sel = page_session.locator("text=Click Me!")
+    button_sel.wait_for()
+    button_sel.click()
+    page_session.locator("text=Tested event").wait_for()
+```
+When this fixture is used, we can use the standard IPython display call to add your widget to the page. Using the `page_session` fixture, we can interact with the widget in the browser,
+in this case we trigger a button click in the browser and check if the button description changes to "Tested event".
+
+Run this test with pytest as follows:
+
+```bash
+pytest tests/ui/test_widget_button.py --headed # remove --headed to run headless
+```
+
+
+
+# Testing in the main Jupyter Environments
+
+In case you want to test your component in the main Jupyter environments (e.g., Jupyter Notebook, Jupyter Lab, Voila, and Solara) to ensure it renders correctly, use the `ipywidgets_runner` fixture to run code snippets. Here's an example:
+
+```python
+import ipywidgets as widgets
+import playwright.sync_api
+from IPython.display import display
+
+
+def test_solara_button_all(ipywidgets_runner, page_session: playwright.sync_api.Page, assert_solara_snapshot):
+    # this function (or rather its lines) will be executed in the kernel
+    # voila, lab, classic notebook and solara will all execute it
+    def kernel_code():
+        import solara
+
+        @solara.component
+        def Button():
+            text, set_text = solara.use_state("Click Me!")
+
+            def on_click():
+                set_text("Tested event")
+
+            solara.Button(text, on_click=on_click)
+
+        display(Button())
+
+    ipywidgets_runner(kernel_code)
+    button_sel = page_session.locator("button >> text=Click Me!")
+    assert_solara_snapshot(button_sel.screenshot())
+    button_sel.wait_for()
+    button_sel.click()
+    page_session.locator("button >> text=Tested event").wait_for()
+    page_session.wait_for_timeout(1000)
+```
+
+Note that the function in the code will be executed in a different process (a Jupyter kernel), which will make it harder to debug and slower to run.
+Because the function code executes in the kernel, you do not have access to local variables. However, by passing a dictionary as second argument
+to `ipywidgets_runner` we can pass in extra local variables (e.g. `ipywidgets_runner(kernel_code, {"extra_argument": extra_argument})`).
+
+## Limiting the Jupyter Environments
+To limit the ipywidgets_runner fixture to only run in a specific environment, use the `SOLARA_TEST_RUNNERS` environment variable:
+
+ * `SOLARA_TEST_RUNNERS=solara pytest tests/ui`
+ * `SOLARA_TEST_RUNNERS=voila pytest tests/ui`
+ * `SOLARA_TEST_RUNNERS=jupyter_lab pytest tests/ui`
+ * `SOLARA_TEST_RUNNERS=jupyter_notebook pytest tests/ui`
+ * `SOLARA_TEST_RUNNERS=solara,voila pytest tests/ui`
+
+
+
+# Organizing Tests and Managing Snapshots
+We recommend organizing your visual tests in a separate directory, such as `tests/ui`. This allows you to run fast tests (`test/unit`) separately from slow tests (t`est/ui`). Use the `solara_snapshots_directory` fixture to change the default directory for storing snapshots, which is `tests/ui/snapshots` by default.
+
+```bash
+$ pytest tests/unit  # run fast test
+$ pytest tests/ui    # run slow test
+$ pytest tests       # run all tests
+```
+
+To compare a captured image from a part of your page with the reference image, use the `assert_solara_snapshot` fixture. For example, `assert_solara_snapshot(button_sel.screenshot())` will take a screenshot of the button and compare it to the reference image. If the images are different, the test will fail.
+
+For local development, you can use the --solara-update-snapshots flag to update the reference images. This will overwrite the existing reference images with the new ones generated during the test run. However, you should carefully review the changes before committing them to your repository to ensure the updates are accurate and expected.
+
+
+# Continuous Integration Recommendations
+
+When a test fails, the output will be placed in a directory structure similar to what would be put in the `solara_snapshots_directory` directory but under the test-results directory in the root of your project (unless changed by passing `--output=someotherdirectory` to pytest).
+
+In CI, we recommend downloading this directory using, for example, GitHub Actions:
+
+```yaml
+- name: Download test results
+  uses: actions/download-artifact@v2
+  with:
+    name: myproject-test-results
+    path: test-results
+```
+
+
+After inspecting and approving the screenshots, you can copy them to the `solara_snapshots_directory` directory and commit them to your repository. This way, you ensure that the reference images are up-to-date and accurate for future tests.
+
+
+# Note about the Playwright
+
+Visual testing with solara is based on [Playwright for Python](https://playwright.dev/python/), which provides a `page` fixture. However, this fixture will make a new page for each test, which is not what we want. Therefore, we provide a `page_session` fixture that will reuse the same page for all tests. This is important because it will make the tests faster.
+
+By following these recommendations and guidelines, you can efficiently test your Solara applications and ensure a smooth developer experience.
+
+# Configuration
+
+## Changing the Hostname
+
+To configure the hostname the socket is bound to when starting the test server, use the `HOST` or `SOLARA_HOST` environment variable (e.g. `SOLARA_HOST=0.0.0.0`). This hostname is also used for the jupyter server and voila. Alternatively the `--solara-host` argument can be passed on the command line for pytest.
+
+## Changing the Port
+
+To configure the ports the socket is bound to when starting the test servers, use the `PORT` environment variable (e.g. `PORT=18865`). This port and subsequent port will be used for solara-server, jupyter-server and voila. Alternatively the `--solara-port` argument can be passed on the command line for pytest for the solara server, and `--jupyter-port` and `--voila-port` for the ports of jupyter server and voila respectively.
+
+## Vuetify warmup
+
+By default, we insert an ipyvuetify widget with an icon into the frontend to force loading all the vuetify assets, such as CSS and fonts. However, if you are using the solara test plugin to test pure ipywidgets or a 3rd ipywidget based party library you might not need this. Disable this vuetify warmup phase by passing the `--no-solara-vuetify-warmup` argument to pytest, or setting the environment variable `SOLARA_TEST_VUETIFY_WARMUP` to a falsey value (e.g. `SOLARA_TEST_VUETIFY_WARMUP=0`).

solara/website/pages/documentation/advanced/content/10-howto/31-debugging.md

@@ -0,0 +1,69 @@
+---
+title: Debugging Solara applications
+description: You can use the Python debugger to debug your Solara app.
+---
+# Debugging
+
+## PDB
+
+You can use the [python debugger](https://docs.python.org/3/library/pdb.html) to debug your Solara app.
+
+Simply add `breakpoint()` to your code, and trigger the code, and you will enter the debugger.
+
+```python
+import solara
+
+clicks = solara.reactive(0)
+
+
+@solara.component
+def Page():
+    color = "green"
+    if clicks.value >= 5:
+        color = "red"
+
+    def increment():
+        clicks.value += 1
+        # this will trigger the debugger
+        breakpoint()
+        print("clicks", clicks)  # noqa
+
+    solara.Button(label=f"Clicked: {clicks}", on_click=increment, color=color)
+```
+
+## PyCharm or IntelliJ
+
+You can also use the debugger of PyCharm or IntelliJ to debug your Solara app.
+The following settings works for PyCharm or IntelliJ:
+
+![](https://dxhl76zpt6fap.cloudfront.net/public/docs/howto/debugger-intellij.webp)
+
+## VSCode
+
+
+In VSCode, you can use the following launch.json to debug your Solara app:
+
+```json
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Solara: Launch",
+            "type": "python",
+            "request": "launch",
+            "program": "/Users/maartenbreddels/miniconda3/envs/dev/bin/solara",
+            "args": [
+                "run",
+                "${file}"
+            ],
+            "console": "integratedTerminal",
+            "justMyCode": true,
+        }
+    ]
+}
+```
+
+Now keep your script tab open, and press F5 to start debugging (or click the play icon in the UI).

solara/website/pages/documentation/advanced/content/10-howto/40-embed.md

@@ -0,0 +1,49 @@
+---
+title: Embedding Solara applications into existing websites
+description: Solara can be embedded into existing websites. Although it is technically possible to embed a Solara app into an existing webpage,
+    we currently support embedding primarily via iframes.
+---
+
+# Embedding in existing websites
+
+Solara can be embedded into existing websites. Although it is technically possible to embed a Solara app into an existing webpage, we currently support embedding primarily via iframes.
+
+
+## Embed via iframe
+
+Here we demonstrate how to embed Solara into an existing webpage via an iframe. Let's start by creating a simple HTML page (here we choose the filename embed.html):
+
+```html
+<html>
+<body>
+    <h1>This is on the main page</h1>
+    <iframe src="http://localhost:8765" width="100%" height="100%"></iframe>
+</body>
+</html>
+```
+
+Now, start an http server (in this example we use the standard Python http server):
+```bash
+$ python -m http.server
+Serving HTTP on :: port 8000 (http://[::]:8000/) ...
+```
+
+Additionally, start the Solara server:
+
+```bash
+$ solara run my-solara-app.py
+Solara server is starting at http://localhost:8765
+```
+
+Ensure the port number matches that of the iframe in `embed.html`. Now open `http://localhost:8000/embed.html` in your browser, and you should see the Solara app embedded in the page.
+
+If you do not see your app, you can open the browser developer tools in your browser and look for errors in the console. If you use the Brave browser, you might want to disable the Brave shields for your local server.
+
+### Security considerations
+
+Solara uses a cookie to implement sessions. To support cookies settings in an iframe, we set the session cookie using `Secure`, and `SameSite=Strict`. See [https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies](MDN) for more details. This means that we can only support loading via iframes via https or localhost.
+
+
+## Embed into an existing page
+
+If embedding into an iframe does not suit your needs (for example, dialogs not being fullscreen), [please contact us](/contact) and we can discuss other options.