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

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

@@ -0,0 +1 @@
+# Solara enterprise

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

@@ -0,0 +1,171 @@
+---
+title: Using OAuth in your Solara app
+description: Open Authorization can be readily integrated into your Solara applications via the Solara-Enterprise package.
+---
+# OAuth: authentication and authorization support
+
+## What is OAuth
+
+OAuth (Open Authorization) is an open standard for token-based authentication and authorization. It enables third-party applications to obtain limited access to a user's resources on another service without exposing their credentials. The user can grant access to their resources on one site to another site without sharing their credentials, providing a secure and efficient way to authenticate users.
+
+You have probably used OAuth without realizing it when signing into various online services and applications. For example, when you use "Sign in with Google" or "Log in with Facebook" to access a third-party website or application, you are using OAuth. By leveraging OAuth, these services allow users to authenticate themselves using their existing Google or Facebook credentials, simplifying the login process and reducing the need for users to remember multiple usernames and passwords. OAuth has become an essential aspect of online identity management and is widely used by companies and developers to provide a seamless and secure authentication experience.
+
+## Installing
+
+To install Solara with OAuth support, make sure you have [Solara Enterprise](/documentation/advanced/enterprise) install by run the following command:
+
+```bash
+$ pip install solara solara-enterprise[auth]
+```
+
+
+## OAuth support in Solara
+
+Solara offers two modes for enabling OAuth: private mode and application controlled mode.
+
+### Private mode
+
+In private mode, Solara pages or any static resources are not accessible without being authenticated. This mode is suitable for web servers that should not be publicly accessible. To enable private mode, set the following environment variable:
+```bash
+SOLARA_OAUTH_PRIVATE=True
+```
+
+
+### Application controlled mode
+
+In application controlled mode, the application is responsible for checking if a user is authenticated. The application can show a login or logout link and provide user information when the user is logged in. Solara comes preconfigured to run on localhost out of the box, and no additional setup is required to enable OAuth for local development and testing.
+
+Here's an example of how to implement OAuth in application controlled mode:
+
+```solara
+import solara
+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())
+    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())
+```
+## How to configure OAuth
+
+Solara supports the following OAuth providers: [Auth0](https://auth0.com/) and [Fief](https://fief.dev/).
+
+
+### Configuring Auth0
+
+By default, Solara is configured with a test Auth0 account. This is useful for testing, but you should not use this in production. This account does limit solara running on localhost, port 8765 to 8770 (and 18765 to 18770 for running the tests).
+
+To configure your own Auth0 provider, you need to change the following environment variables from their defaults:
+
+```bash
+# required if you don't use the default test account
+SOLARA_SESSION_SECRET_KEY="change me"
+# found in the Auth0 dashboard Applications->Applications->Client ID
+SOLARA_OAUTH_CLIENT_ID="cW7owP5Q52YHMZAnJwT8FPlH2ZKvvL3U"
+# found in the Auth0 dashboard Applications->Applications->Client secret
+SOLARA_OAUTH_CLIENT_SECRET="zxITXxoz54OjuSmdn-PluQgAwbeYyoB7ALlnLoodftvAn81usDXW0quchvoNvUYD"
+# found in the Auth0 dashboard Applications->Applications->Domain
+SOLARA_OAUTH_API_BASE_URL="dev-y02f02f2bpr8skxu785.us.auth0.com"
+```
+
+You can optionally set the following environment variables:
+
+```bash
+SOLARA_OAUTH_SCOPE = "openid profile email"
+```
+
+### Create your own Auth0 Application
+
+
+To create your own Auth0 application, follow these steps:
+
+1. Go to the [Auth0 dashboard](https://manage.auth0.com/dashboard/) and click on "Applications" on the left side navigation menu.
+
+    ![Auth0 dashboard](https://dxhl76zpt6fap.cloudfront.net/public/docs/enterprise/oauth/goto-applications.webp)
+
+2. Click on "Create Application".
+
+    ![Create Application](https://dxhl76zpt6fap.cloudfront.net/public/docs/enterprise/oauth/click-create-application.webp)
+
+3. Enter a name for your application and select "Regular Web Applications" as the application type. Click on "Create".
+
+    ![Create Application](https://dxhl76zpt6fap.cloudfront.net/public/docs/enterprise/oauth/name-type-create.webp)
+
+4. Click "Skip Integration" to skip the integration step.
+
+5. Click on the "Settings" tabs and enter the following information:
+
+    - Allowed Callback URLs: `http://localhost:8765/_solara/auth/authorize, https://yourdomain.com/_solara/auth/authorize`
+    - Allowed Logout URLs: `http://localhost:8765/_solara/auth/logout, https://yourdomain.com/_solara/auth/logout`
+
+    Note that the localhost URLs are only meant for testing. You can remove them once you are ready to deploy your application.
+    We recommend setting up a new application for each environment (e.g. development, staging, production).
+
+    ![Callback URLs](https://dxhl76zpt6fap.cloudfront.net/public/docs/enterprise/oauth/callbacks.webp)
+
+6. Configure Solara.
+
+    At the top of the "Settings" tab, you should see your "Domain", "Client ID" and "Client Secret". You will need to set the following environment variables to these values:
+
+    ```bash
+    SOLARA_OAUTH_API_BASE_URL="dev-y02f2bpr8skxu785.us.auth0.com"  # replace with your domain
+    SOLARA_OAUTH_CLIENT_ID="ELOFERLovc7e7dPwkxO6WFAljtYj9UzJ"  # replace with your client ID
+    SOLARA_OAUTH_CLIENT_SECRET="..."  # not shown here, replace with your client secret
+    ```
+
+    ![Settings](https://dxhl76zpt6fap.cloudfront.net/public/docs/enterprise/oauth/configuration-values.webp)
+
+    Set your `SOLARA_SESSION_SECRET_KEY` to a random string. See the [Generating a secret key](#generating-a-secret-key) for a convenient way to generate a secret key.
+
+    If you want to test on localhost, you might also want to set `SOLARA_SESSION_HTTPS_ONLY="false"`
+
+    Now you can run the above solara example using your own auth0 provider.
+
+
+### Configuring Fief
+
+You can also configure Solara to use our Fief test account. To do this, you need to set the following environment variables:
+
+```bash
+SOLARA_SESSION_SECRET_KEY="change me"  # required if you don't use the default test account
+SOLARA_OAUTH_CLIENT_ID="x2np62qgwp6hnEGTP4JYUE3igdZWhT-AvjpjwwDyKXU"  # found in the Auth0 dashboard Clients->General Tab->Secret
+SOLARA_OAUTH_CLIENT_SECRET="XQlByE1pVIz5h2SBN2GYDwT_ziqArHJgLD3KqMlCHjg" # found in the Auth0 dashboard Clients->General Tab->ID
+SOLARA_OAUTH_API_BASE_URL="solara-dev.fief.dev"  # found in the Fief dashboard Tenants->Base URL
+ # different from Solara's default
+SOLARA_OAUTH_LOGOUT_PATH="logout"
+```
+
+### Generating a secret key
+
+To generate a secret key, you can use the following code:
+
+```bash
+$ python -c "import secrets; print(secrets.token_urlsafe(32))"
+ZgrzSLUyft-JvnNMNJ2LgbCFVqcxPOatANAQhMD5EYU
+```
+
+*Note: do not copy this key, run this yourself in a terminal.*
+
+
+## OAuth Component
+
+Solara provides two convenient components for creating a user interface for login and logout:
+
+ 1. [Avatar](/documentation/components/enterprise/avatar): This component shows the user's avatar.
+ 2. [AvatarMenu](/documentation/components/enterprise/avatar_menu): This component shows a menu with the user's avatar and a logout button.
+
+ ## Python version support
+
+Please note that Python 3.6 is not supported for Solara OAuth.
+
+
+## Possible issues
+
+### Wrong redirection
+
+If the redirection back to solara return to the wrong address, it might be due to solara not choosing the right default for `SOLARA_BASE_URL`. For instance this variable could be set to `SOLARA_BASE_URL=https://solara.dev` for the solara.dev server. If you application runs behind a subpath, e.g. `/myapp`, you might have to set `SOLARA_ROOT_PATH=/myapp`.

solara/website/pages/documentation/advanced/content/40-development/01-contribute.md

@@ -0,0 +1,45 @@
+---
+title: Contributing to Solara
+description: You do not need to be a developer to contribute to Solara. We welcome all contributions, bug reports, documentation improvements and code contributions.
+---
+# Contributing to Solara
+
+You do not need to be a developer to contribute to Solara. We welcome all contributions, bug reports, documentation improvements and code contributions.
+
+
+## Bug reports
+
+We use [GitHub to manage issues](https://github.com/widgetti/solara/issues/new) and you should not hesitate to report any bug you find. Please include as much information as possible for us to be able to reproduce the bug. Yes, reporting a bug/issue is a contribution!
+
+It might take a while for us to get back to you. If the bug is urgent, and you are able to provide financial support for its rapid resolution, please [contact us](/contact).
+If you can fix the bug yourself, please consider submitting a pull request instead, see [the development guide](/documentation/advanced/development/setup) for more information.
+
+If you are unable to address the bug yourself and find it challenging to provide financial support, please be assured we are still committed to rectifying bugs and resolving issues. However, please understand that our ability to address these issues may be impacted by our resources at hand, as sustaining this project also entails financial obligations. Your patience and understanding in this matter is highly appreciated 🙇.
+
+## Documentation
+
+The documentation is mostly written in Markdown, and can be found at [in the main repository](https://github.com/widgetti/solara/tree/master/solara/website/pages).
+
+You can use the GitHub web interface to edit the files, or clone the repository and edit them locally. See [the development guide](/documentation/advanced/development/setup) for more information.
+
+If you locally want to render the documentation, run:
+
+```bash
+$ solara run solara.website.pages
+```
+
+## Examples or showcase
+
+If you have a complete program you want to share, and you think it would be cool to be listed at [our showcase page](/showcase), [please contact us](/contact).
+
+If you want to show a particular way of using Solara that you think is very useful
+for others, but it is not a complete program, consider adding to [the examples](/documentation/examples/). See [the development guide](/documentation/advanced/development/setup) for more information.
+
+## Share your experiences and ideas
+
+If you want to share your thoughts, share your experiences, or just want to talk
+to other people using and developing on Solara, consider using [GitHub discussions](https://github.com/widgetti/solara/discussions) for asynchronous discussions
+or consider joining discord for more synchronous discussions.
+
+
+[![Discord Shield](https://discordapp.com/api/guilds/1106593685241614489/widget.png?style=banner2)](https://discord.gg/dm4GKNDjXN)

solara/website/pages/documentation/advanced/content/40-development/10-setup.md

@@ -0,0 +1,76 @@
+---
+title: Development setup for Solara
+description: Learn how to set up your installation for developing on the Solara itself.
+---
+# Development
+
+See also [the contributing guide](/documentation/advanced/development/contribute) for more information on how to contribute to Solara.
+## Development setup
+
+Assuming you have created a virtual environment as described in [the installation guide](/documentation/getting_started/installing), you can install a development install of Solara using:
+
+    $ git clone git@github.com:widgetti/solara.git
+    $ cd solara
+    $ pip install ".[dev,documentation]"  # documentation is optional
+
+
+## Running Solara server in auto restart mode
+
+By passing the `--auto-restart/-a` flag, the solara server will automatically restart when the sourcecode of the solara server changes, which makes it friendlier for development
+
+    $ solara run myscript.py -a
+
+This will:
+
+    * Automatically restart the server if any of the source code of solara changes (excluding solara.website)
+
+## Contributing
+
+If you plan to contribute, also run the following:
+
+    $ pre-commit install
+
+This will cause a test of linters/formatters and mypy to run so the code is in good quality before you git commit.
+
+    $ playwright install
+
+This will install playwright, for when you want to run the integration tests.
+
+### Test suite
+
+If you want to run the unit tests (quick run when doing development, or when you do test driven development)
+
+    $ py.test tests/unit
+
+
+If you want to run the integration tests (uses playwright to open a browser to test the live server with a real browser)
+
+    $ py.test tests/integration
+
+Pass the `--headed` flag to see what is going on, [or check out the docs](https://playwright.dev/python/docs/intro)
+
+
+### Creating a PR
+
+Make sure you forked the repository, and set up the remote and origin correctly.
+
+```
+# rename origin to upstream
+$ git remote rename origin upstream
+# add your fork as origin
+$ git remote add origin https://github.com/yourusername/solara.git
+```
+
+Now we will create a branch, push it, and open a PR
+
+```
+# create a branch
+$ git checkout -b fix_some_thing
+# add whatever changes you want to make
+$ git add -p
+# commit your changes
+$ git commit -m "fix: some thing"
+# push your changes
+$ git push
+# click the link that is printed to open a PR
+```

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

@@ -0,0 +1,19 @@
+"""
+# Overview
+Click on one of the items on the left.
+"""
+
+import solara
+from solara.website.components import CategoryLayout, Gallery
+
+_title = "API"
+
+
+@solara.component
+def Page(route_external=None):
+    Gallery(route_external)
+
+
+@solara.component
+def Layout(children=[]):
+    CategoryLayout(children=children)

solara/website/pages/documentation/api/cross_filter/__init__.py

@@ -0,0 +1,9 @@
+import solara
+from solara.website.components import NoPage, SubCategoryLayout
+
+Page = NoPage
+
+
+@solara.component
+def Layout(children=[]):
+    SubCategoryLayout(children=children)

solara/website/pages/documentation/api/cross_filter/cross_filter_dataframe.py

@@ -0,0 +1,23 @@
+"""# CrossFilterDataFrame"""
+
+import plotly
+
+import solara
+import solara.lab
+from solara.website.utils import apidoc
+
+title = "CrossFilterDataFrame"
+df = plotly.data.gapminder()
+
+
+@solara.component
+def Page():
+    solara.provide_cross_filter()
+    with solara.VBox() as main:
+        solara.CrossFilterReport(df, classes=["py-2"])
+        solara.CrossFilterSelect(df, "country")
+        solara.CrossFilterDataFrame(df)
+    return main
+
+
+__doc__ += apidoc(solara.CrossFilterDataFrame.f)  # type: ignore

solara/website/pages/documentation/api/cross_filter/cross_filter_report.py

@@ -0,0 +1,22 @@
+"""# CrossFilterReport"""
+
+import plotly
+
+import solara
+import solara.lab
+from solara.website.utils import apidoc
+
+df = plotly.data.gapminder()
+
+
+@solara.component
+def Page():
+    solara.provide_cross_filter()
+    with solara.VBox() as main:
+        solara.CrossFilterReport(df, classes=["py-2"])
+        solara.CrossFilterSelect(df, "country")
+        solara.CrossFilterSlider(df, "gdpPercap", mode=">")
+    return main
+
+
+__doc__ += apidoc(solara.CrossFilterReport.f)  # type: ignore

solara/website/pages/documentation/api/cross_filter/cross_filter_select.py

@@ -0,0 +1,22 @@
+"""# CrossFilterSelect"""
+
+import plotly
+
+import solara
+import solara.lab
+from solara.website.utils import apidoc
+
+df = plotly.data.tips()
+
+
+@solara.component
+def Page():
+    solara.provide_cross_filter()
+    with solara.VBox() as main:
+        solara.CrossFilterReport(df, classes=["py-2"])
+        solara.CrossFilterSelect(df, "sex")
+        solara.CrossFilterSelect(df, "time")
+    return main
+
+
+__doc__ += apidoc(solara.CrossFilterSelect.f)  # type: ignore

solara/website/pages/documentation/api/cross_filter/cross_filter_slider.py

@@ -0,0 +1,22 @@
+"""# CrossFilterSlider"""
+
+import plotly
+
+import solara
+import solara.lab
+from solara.website.utils import apidoc
+
+df = plotly.data.gapminder()
+
+
+@solara.component
+def Page():
+    solara.provide_cross_filter()
+    with solara.VBox() as main:
+        solara.CrossFilterReport(df, classes=["py-2"])
+        solara.CrossFilterSlider(df, "pop", mode=">")
+        solara.CrossFilterSlider(df, "gdpPercap", mode="<")
+    return main
+
+
+__doc__ += apidoc(solara.CrossFilterSlider.f)  # type: ignore

solara/website/pages/documentation/api/hooks/__init__.py

@@ -0,0 +1,9 @@
+import solara
+from solara.website.components import NoPage, SubCategoryLayout
+
+Page = NoPage
+
+
+@solara.component
+def Layout(children=[]):
+    SubCategoryLayout(children=children)

solara/website/pages/documentation/api/hooks/use_cross_filter.py

@@ -0,0 +1,25 @@
+"""# use_cross_filter"""
+
+import plotly
+
+import solara
+import solara.lab
+from solara.website.utils import apidoc
+
+title = "use_cross_filter"
+
+
+df = plotly.data.gapminder()
+
+
+@solara.component
+def Page():
+    solara.provide_cross_filter()
+    with solara.VBox() as main:
+        solara.CrossFilterReport(df, classes=["py-2"])
+        solara.CrossFilterSelect(df, "continent")
+        solara.CrossFilterSlider(df, "gdpPercap", mode=">")
+    return main
+
+
+__doc__ += apidoc(solara.use_cross_filter)  # type: ignore

solara/website/pages/documentation/api/hooks/use_dark_effective.py

@@ -0,0 +1,12 @@
+"""# use_dark_effective"""
+
+import solara
+import solara.autorouting
+import solara.lab
+from solara.website.utils import apidoc
+
+from . import NoPage
+
+title = "use_dark_effective"
+Page = NoPage
+__doc__ += apidoc(solara.lab.use_dark_effective)  # type: ignore

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

@@ -0,0 +1,43 @@
+# use_effect
+
+```python
+def use_effect(
+    effect: EffectCallable,
+    dependencies: Any | None = None
+) -> None
+    ...
+```
+
+Execute non-declarative code within a callback, for instance to add event handlers. `effect` is executed *after* page render, letting us fetch the actual underlying widget object using `solara.get_widget` on an element. `dependencies` should be a list of variables, which when changed trigger re-execution of `effect`. If left empty, `effect` will never re-execute.
+
+`effect` can return a cleanup function, which will be called before re-execution of `effect`, or when the component containing `use_effect` is removed.
+
+Example use of `use_effect` to attach an event handler to a solara component:
+
+```python
+def use_event(el: solara.Element, callback: Callable):
+    def add_event_handler():
+        def on_enter(widget, event, data):
+            callback(widget.v_model)
+
+        widget = cast(ipyvue.VueWidget, solara.get_widget(el))
+        widget.on_event("keyup.enter", on_enter)
+
+        def cleanup():
+            widget.on_event("keyup.enter", on_enter, remove=True)
+
+        return cleanup
+
+    solara.use_effect(add_event_handler, dependencies=[])
+
+@solara.component
+def Page():
+    def function():
+        #Do something...
+
+    input = solara.InputText():
+    use_event(input, function)
+    ...
+```
+
+See also the [Reacton docs](https://reacton.solara.dev/en/latest/api/#use_effect).

solara/website/pages/documentation/api/hooks/use_effect.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+from solara.website.components import NoPage
+
+HERE = Path(__file__).parent
+__doc__ = open(HERE / "use_effect.md").read()
+
+Page = NoPage
+title = "use_effect"

solara/website/pages/documentation/api/hooks/use_exception.py

@@ -0,0 +1,33 @@
+import solara
+
+title = "use_exception"
+set_fail = None
+clear = None
+
+
+@solara.component
+def UnstableComponent(number: int):
+    if number == 3:
+        raise Exception("I do not like 3")
+    return solara.Text(f"You picked {number}")
+
+
+@solara.component
+def Page():
+    value, set_value = solara.use_state(1)
+    value_previous = solara.use_previous(value)
+    exception, clear_exception = solara.use_exception()
+    # print(exception)
+    with solara.VBox() as main:
+        if exception:
+
+            def reset():
+                set_value(value_previous)
+                clear_exception()
+
+            solara.Text("Exception: " + str(exception))
+            solara.Button(label="Go to previous state", on_click=reset)
+        else:
+            solara.IntSlider(value=value, min=0, max=10, on_value=set_value, label="Pick a number, except 3")
+            UnstableComponent(value)
+    return main

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

@@ -0,0 +1,16 @@
+# use_memo
+
+```python
+def use_memo(
+    f: Any,
+    dependencies: Any | None = None,
+    debug_name: str = None
+) -> Any:
+    ...
+```
+
+`use_memo` stores ([memoize](https://en.wikipedia.org/wiki/Memoization)) the function return on first render, and then excludes it from being re-executed, except when one of the `dependencies` changes. `dependencies` can take the value `None`, in which case dependencies are automatically obtained from nonlocal variables. If an empty list is passed as `dependencies` instead, the function is only executed once over the entire lifetime of the component.
+
+Not to be confused with [memorize](https://solara.dev/documentation/api/utilities/memoize) which can cache multiple return values and which can be used outside of component.
+
+See also the [Reacton docs](https://reacton.solara.dev/en/latest/api/#use_memo).

solara/website/pages/documentation/api/hooks/use_memo.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+from solara.website.components import NoPage
+
+HERE = Path(__file__).parent
+__doc__ = open(HERE / "use_memo.md").read()
+
+Page = NoPage
+title = "use_memo"

solara/website/pages/documentation/api/hooks/use_previous.py

@@ -0,0 +1,33 @@
+"""
+# use_previous
+
+```python
+def use_previous(value: T) -> T:
+    ...
+```
+
+Returns the value from a previous render phase, or the current value on the first render.
+
+
+"""
+
+import solara
+
+title = "use_previous"
+
+
+@solara.component
+def Page():
+    value, set_value = solara.use_state(4)
+    value_previous = solara.use_previous(value)
+    with solara.VBox() as main:
+        solara.IntSlider("value", value=value, on_value=set_value)
+        solara.Markdown(
+            f"""
+        **Current**:  `{value}`
+
+        **Previous**: `{value_previous}`
+"""
+        )
+
+    return main

solara/website/pages/documentation/api/hooks/use_reactive.py

@@ -0,0 +1,16 @@
+"""
+# use_reactive
+
+"""
+
+import solara
+from solara.website.components import NoPage
+from solara.website.utils import apidoc
+
+title = "use_reactive"
+
+
+Page = NoPage
+
+
+__doc__ += apidoc(solara.use_reactive)  # type: ignore

solara/website/pages/documentation/api/hooks/use_state.py

@@ -0,0 +1,10 @@
+"""# use_state"""
+
+import solara
+import solara.autorouting
+from solara.website.components import NoPage
+from solara.website.utils import apidoc
+
+title = "use_state"
+Page = NoPage
+__doc__ += apidoc(solara.use_state)  # type: ignore