Export as_widget() and update README to refer to new article (#90)

Author: cpsievert

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Closed #94: New `SHINYWIDGETS_CDN` and `SHINYWIDGETS_CDN_ONLY` environment variables were added to more easily specify the CDN provider. Also, the default provider has changed from <unpkg.com> to <cdn.jsdelivr.net/npm> (#95)
 * A warning is no longer issued (by default) when the path to a local widget extension is not found. This is because, if an internet connection is available, the widget assests are still loaded via CDN. To restore the previous behavior, set the `SHINYWIDGETS_EXTENSION_WARNING` environment variable to `"true"`. (#95)
 * Closed #14: Added a `bokeh_dependency()` function to simplify use of bokeh widgets. (#85)
+* Closed #89: Exported the `as_widget()` function to attempt coercion of objects into ipywidgets. Internally, `{shinywidgets}` uses it to implictly coerce objects into ipywidgets, but it can be also useful to explicitly coerce objects before passing to `register_widget()` (so that the ipywidget can then be updated in-place and/or used as a reactive value (`reactive_read()`)). (#90)
 
 ## [0.1.6] - 2023-03-24
 

README.md

@@ -12,164 +12,41 @@ pip install shinywidgets
 
 ## Overview
 
-Every Shiny app has two main parts: the user interface (UI) and server logic.
-`{shinywidgets}` provides `output_widget()` for defining where to place a widget in the UI
-and `register_widget()` (or `@render_widget`) for supplying a widget-like object to
-the `output_widget()` container. More technically, widget-like means:
-
-* Any object that subclasses `{ipywidgets}`'s `Widget` class.
-* Some other widget-like object that can be coerced into a `Widget`. Currently, we
-  support objects from `{altair}`, `{bokeh}`, and `{pydeck}`, but [please let us
-  know](https://github.com/rstudio/py-shinywidgets/issues/new) about other packages that we
-  should support.
-
-The recommended way to incorporate `{shinywidgets}` widgets into Shiny apps is to:
-
-1. Initialize and `register_widget()` _once_ for each widget.
-    * In most cases, initialization should happen when the user session starts (i.e.,
-      the `server` function first executes), but if the widget is slow to initialize and
-      doesn't need to be shown right away, you may want to delay that initialization
-      until it's needed.
-2. Use Shiny's `@reactive.Effect` to reactively modify the widget whenever relevant
-   reactive values change.
-3. Use `{shinywidgets}`'s `reactive_read()` to update other outputs whenever the widget changes.
-    * This way, relevant output(s) invalidate (i.e., recalculate) whenever the relevant
-      widget attributes change (client-side or server-side).
-
-The following app below uses `{ipyleaflet}` to demonstrate all these concepts:
+See the [using ipywidgets section](https://shiny.rstudio.com/py/docs/ipywidgets.html) of the Shiny for Python website.
 
-```py
-from shiny import *
-from shinywidgets import output_widget, register_widget, reactive_read
-import ipyleaflet as L
-
-app_ui = ui.page_fluid(
-    ui.input_slider("zoom", "Map zoom level", value=4, min=1, max=10),
-    output_widget("map"),
-    ui.output_text("map_bounds"),
-)
-
-def server(input, output, session):
+## Frequently asked questions
 
-    # Initialize and display when the session starts (1)
-    map = L.Map(center=(52, 360), zoom=4)
-    register_widget("map", map)
+### What ipywidgets are supported?
 
-    # When the slider changes, update the map's zoom attribute (2)
-    @reactive.Effect
-    def _():
-        map.zoom = input.zoom()
+In theory, shinywidgets supports any instance that inherits from `{ipywidgets}`' `Widget` class.
 
-    # When zooming directly on the map, update the slider's value (2 and 3)
-    @reactive.Effect
-    def _():
-        ui.update_slider("zoom", value=reactive_read(map, "zoom"))
+That said, `{shinywidgets}` can also "directly" render objects that don't inherit from `Widget`, but have a known way of coercing into a `Widget` instance. This list currently includes:
 
-    # Everytime the map's bounds change, update the output message (3)
-    @output
-    @render.text
-    def map_bounds():
-        b = reactive_read(map, "bounds")
-        lat = [b[0][0], b[0][1]]
-        lon = [b[1][0], b[1][1]]
-        return f"The current latitude is {lat} and longitude is {lon}"
+* Altair charts (via the [vega](https://pypi.org/project/vega/) package).
+* Bokeh widgets (via the [jupyter_bokeh](https://github.com/bokeh/jupyter_bokeh) package).
+* Plotly's `Figure` class (via `FigureWidget`).
+* Pydeck's `Deck` class (via it's `.show()` method).
 
-app = App(app_ui, server)
-```
+[See here](https://github.com/rstudio/py-shinywidgets/blob/main/shinywidgets/_as_widget.py) for more details on how these objects are coerced into `Widget` instances, and if you know of other packages that should be added to this list, please [let us know](https://github.com/rstudio/py-shinywidgets/issues/new)
 
-<div align="center">
-    <img src="https://user-images.githubusercontent.com/1365941/171508416-1ebe157c-b305-4517-9c89-14891dff8f79.gif" width="70%">
-</div>
+### Bokeh widgets aren't displaying, what gives?
 
-The style of programming above (display and mutate) is great for efficiently performing
-partial updates to a widget. This is really useful when a widget needs to display lots
-of data and also quickly handle partial updates; for example, toggling the visibility of
-a fitted line on a scatterplot with lots of points:
+Similar to how you have to run `bokeh.io.output_notebook()` to run `{bokeh}` in notebook, you also have to explicitly bring the JS/CSS dependencies to the Shiny app, which can be done this way:
 
 ```py
-from shiny import *
-from shinywidgets import output_widget, register_widget
-import plotly.graph_objs as go
-import numpy as np
-from sklearn.linear_model import LinearRegression
-
-# Generate some data and fit a linear regression
-n = 10000
-d = np.random.RandomState(0).multivariate_normal([0, 0], [(1, 0.5), (0.5, 1)], n).T
-fit = LinearRegression().fit(d[0].reshape(-1, 1), d[1])
-xgrid = np.linspace(start=min(d[0]), stop=max(d[0]), num=30)
+from shiny import ui
+from shinywidgets import bokeh_dependencies
 
 app_ui = ui.page_fluid(
-    output_widget("scatterplot"),
-    ui.input_checkbox("show_fit", "Show fitted line", value=True),
+    bokeh_dependencies(),
+    # ...
 )
-
-def server(input, output, session):
-
-    scatterplot = go.FigureWidget(
-        data=[
-            go.Scattergl(
-                x=d[0],
-                y=d[1],
-                mode="markers",
-                marker=dict(color="rgba(0, 0, 0, 0.05)", size=5),
-            ),
-            go.Scattergl(
-                x=xgrid,
-                y=fit.intercept_ + fit.coef_[0] * xgrid,
-                mode="lines",
-                line=dict(color="red", width=2),
-            ),
-        ]
-    )
-
-    register_widget("scatterplot", scatterplot)
-
-    @reactive.Effect
-    def _():
-        scatterplot.data[1].visible = input.show_fit()
-
-app = App(app_ui, server)
 ```
 
-<div align="center">
-    <img src="https://user-images.githubusercontent.com/1365941/171507230-4b32ce4a-6e80-43a4-9c71-6a1f3ffe443e.gif" width="70%">
-</div>
-
-
-That being said, in a situation where:
-
-* Performant updates aren't important
-* Other outputs don't depend on the widget's state
-* It's convenient to initialize a widget in a reactive context
-
-Then it's ok to reach for `@render_widget()` (instead of `register_widget()`) which
-creates a reactive context (similar to Shiny's `@render_plot()`, `@render_text()`, etc.)
-where each time that context gets invalidated, the output gets redrawn from scratch. In
-a simple case like the one below, that redrawing may not be noticable, but if you we're
-to redraw the entire scatterplot above everytime the fitted line was toggled, there'd
-be noticeable delay.
 
-```py
-from shiny import *
-from shinywidgets import output_widget, render_widget
-import ipyleaflet as L
-
-app_ui = ui.page_fluid(
-    ui.input_slider("zoom", "Map zoom level", value=4, min=1, max=10),
-    output_widget("map")
-)
-
-def server(input, output, session):
-    @output
-    @render_widget
-    def map():
-        return L.Map(center=(52, 360), zoom=input.zoom())
-
-app = App(app_ui, server)
-```
+### Does `{shinywidgets}` work with Shinylive?
 
-## Frequently asked questions
+To some extent, yes. As shown on the official [shinylive examples](https://shinylive.io/py/examples/), packages like plotly and ipyleaflet work (as long as you've provided the proper dependencies in a [`requirements.txt` file](https://shinylive.io/py/examples/#extra-packages)), but other packages like altair and qgrid may not work (at least currently) due to missing wheel files and/or dependencies with compiled code that can't be compiled to WebAssembly.
 
 ### How do I size the widget?
 
@@ -179,8 +56,8 @@ including `height` and `width`. So, given a `Widget` instance `w`, you should be
 do something like:
 
 ```py
-w.layout.height = "600px"
-w.layout.width = "80%"
+w.layout.height = "100%"
+w.layout.width = "100%"
 ```
 
 ### How do I hide/show a widget?
@@ -204,18 +81,6 @@ w.layout.display = "none"
 Yes! In fact this a crucial aspect to how packages like `{ipyleaflet}` work. In
 `{ipyleaflet}`'s case, each [individual marker is a widget](https://ipyleaflet.readthedocs.io/en/latest/layers/circle_marker.html) which gets attached to a `Map()` via `.add_layer()`.
 
-### Does `{shinywidgets}` work with Shinylive?
-
-Shinylive allows some Shiny apps to be statically served (i.e., run entirely in the
-browser). [py-shinylive](https://github.com/rstudio/py-shinylive) does have some special
-support for `{shinywidgets}` and it's dependencies, which should make most widgets work
-out-of-the-box.
-
-In some cases, the package(s) that you want to use may not come pre-bundled with
-`{shinywidgets}`; and in that case, you can [include a `requirements.txt`
-file](https://shinylive.io/py/examples/#extra-packages) to pre-install those other
-packages
-
 ## Troubleshooting
 
 If after [installing](#installation) `{shinywidgets}`, you have trouble rendering widgets,
@@ -243,7 +108,8 @@ app_ui = ui.page_fluid(
     # ...
 )
 ```
-```
+
+
 #### Other widgets?
 
 Know of another widget that requires initialization code? [Please let us know about

shinywidgets/_as_widget.py

@@ -0,0 +1,86 @@
+from typing import Optional
+
+from ipywidgets.widgets.widget import Widget
+
+from ._dependencies import widget_pkg
+
+__all__ = ("as_widget",)
+
+
+# Some objects aren't directly renderable as an ipywidget, but in some cases,
+# we can coerce them into one
+def as_widget(x: object) -> Widget:
+    if isinstance(x, Widget):
+        return x
+
+    pkg = widget_pkg(x)
+
+    _as_widget = AS_WIDGET_MAP.get(pkg, None)
+    if _as_widget is None:
+        raise TypeError(f"Don't know how to coerce {x} into a ipywidget.Widget object.")
+
+    res = _as_widget(x)
+
+    if not isinstance(res, Widget):
+        raise TypeError(
+            f"Failed to coerce {x} (an object from package {pkg}) into a ipywidget.Widget object."
+        )
+
+    return res
+
+
+def as_widget_altair(x: object) -> Optional[Widget]:
+    try:
+        from vega.widget import VegaWidget
+    except ImportError:
+        raise ImportError("Install the vega package to use altair with shinywidgets.")
+
+    if not hasattr(x, "to_dict"):
+        raise TypeError(
+            f"Don't know how to coerce {x} (an altair object) into an ipywidget without a .to_dict() method."
+        )
+
+    try:
+        return VegaWidget(x.to_dict())  # type: ignore
+    except Exception as e:
+        raise RuntimeError(f"Failed to coerce {x} into a VegaWidget: {e}")
+
+
+def as_widget_bokeh(x: object) -> Optional[Widget]:
+    try:
+        from jupyter_bokeh import BokehModel
+    except ImportError:
+        raise ImportError(
+            "Install the jupyter_bokeh package to use bokeh with shinywidgets."
+        )
+
+    return BokehModel(x)  # type: ignore
+
+
+def as_widget_plotly(x: object) -> Optional[Widget]:
+    # Don't need a try import here since this won't be called unless x is a plotly object
+    import plotly.graph_objects as go
+
+    if not isinstance(x, go.Figure):
+        raise TypeError(
+            f"Don't know how to coerce {x} into a plotly.graph_objects.FigureWidget object."
+        )
+
+    return go.FigureWidget(x.data, x.layout)  # type: ignore
+
+
+def as_widget_pydeck(x: object) -> Optional[Widget]:
+    if not hasattr(x, "show"):
+        raise TypeError(
+            f"Don't know how to coerce {x} (a pydeck object) into an ipywidget without a .show() method."
+        )
+
+    return x.show()  # type: ignore
+
+
+AS_WIDGET_MAP = {
+    "altair": as_widget_altair,
+    "bokeh": as_widget_bokeh,
+    "plotly": as_widget_plotly,
+    "pydeck": as_widget_pydeck,
+}