point pydeck to deck 9.1 and update documentation

Author: chrisgervang

bindings/pydeck/docs/CHANGELOG.rst

@@ -6,6 +6,10 @@ Releases and associated GitHub PRs for pydeck are documented here.
 0.9 Releases
 ------------
 
+0.9.2 - Jan XX 2025
+^^^^^^^^^^^^^^^^^^^
+- Add support for deck.gl widgets (#9342)
+
 0.9.1 - May 10 2024
 ^^^^^^^^^^^^^^^^^^^
 - Fix pydeck iframe height in Google Colab (#8881)

bindings/pydeck/docs/index.rst

@@ -66,6 +66,11 @@ like plotting in flat plane instead of plotting on a mercator projection
 
 Configure the lighting within a visualization.
 
+`Widgets <widget.html>`__
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Configure one of the many deck.gl UI widgets for displaying and controlling deck.gl state in pydeck.
+
 .. note::
    The pydeck library assumes Internet access. You will need an Internet connection or the visualization will not render.
 
@@ -99,6 +104,7 @@ Index
    view_state
    view
    light_settings
+   widget
 
 .. toctree::
    :maxdepth: 1

bindings/pydeck/docs/layer.rst

@@ -156,7 +156,7 @@ Passing string constants
 
 Strings most often in pydeck indicate a data set variable name, like ``lng`` or ``lat`` in the previous examples.
 Some pydeck arguments require a string constant, however.
-In order to indiciate to the library that you're passing a string constant, you must wrap your strings in the ``pydeck.String`` constructor.
+In order to indicate to the library that you're passing a string constant, you must wrap your strings in the ``pydeck.String`` constructor.
 For example, below
 we plot the mean of billions of dollars of profit per employee by passing ``'MEAN'`` to ``aggregation``,
 giving us the average for that statistic within an area:

bindings/pydeck/docs/widget.rst

@@ -5,3 +5,6 @@ Widget
     :members:
     :undoc-members:
     :show-inheritance:
+
+The ``pydeck.Widget`` object follow the same conventions as ``pydeck.Layer`` for styling keyword arguments and the ``type`` positional argument. 
+Read `Understanding keyword arguments in pydeck layers <layer.html#understanding-keyword-arguments-in-pydeck-layers>`__ documentation for more information.

bindings/pydeck/examples/01 - Introduction.ipynb

@@ -124,11 +124,12 @@
     "    pitch=40.5,\n",
     "    bearing=-27.36)\n",
     "\n",
-    "# Add a zoom control\n",
-    "widget = pdk.Widget('ZoomWidget')\n",
+    "# Add a compass and zoom control\n",
+    "compass_widget = pdk.Widget('CompassWidget', placement='top-right')\n",
+    "zoom_widget = pdk.Widget('ZoomWidget', placement='top-right')\n",
     "\n",
     "# Combined all of it and render a viewport\n",
-    "r = pdk.Deck(layers=[layer], initial_view_state=view_state, widgets=[widget])\n",
+    "r = pdk.Deck(layers=[layer], initial_view_state=view_state, widgets=[compass_widget, zoom_widget])\n",
     "r.show()"
    ]
   },

bindings/pydeck/pydeck/bindings/widget.py

@@ -8,20 +8,24 @@ class Widget(JSONMixin):
     Represents a deck.gl widget, which are UI components around the WebGL2/WebGPU canvas
     to offer controls and information for a better user experience.
 
+    Please see the deck.gl
+    `Widget catalog <https://deck.gl/docs/api-reference/widgets/overview>`_
+    to determine the particular parameters of your widget.
+
     Parameters
     ---------
     type : str, default None
-        deck.gl widget to display, e.g., 'CompassWidget'
+        deck.gl widget to display, e.g., ``CompassWidget``
     id : str, default None
         Unique name for widget
-    placement : string, default 'top-left'
-        Placement of the widget on the map. Options are 'top-left', 'top-right', 'bottom-left', 'bottom-right', and 'fill'.
+    placement : str, default ``top-left``
+        Placement of the widget on the map. Options are ``top-left``, ``top-right``, ``bottom-left``, ``bottom-right``, and ``fill``.
         Note that not all widgets support custom placement.
-    view_id : string, default None
+    view_id : str, default None
         ID of the view to which the widget should be added. The widget will be added to the default view if not specified.
         Note that not all widgets support custom view_id.
     **kwargs
-        Any of the parameters passable to a deck.gl Widget
+        Any of the parameters passable to a deck.gl widget.
     """
 
     def __init__(self, type, id=None, placement=None, view_id=None, **kwargs):

bindings/pydeck/pydeck/frontend_semver.py

@@ -1 +1 @@
-DECKGL_SEMVER = "~9.0.*"
+DECKGL_SEMVER = "~9.1.*"

bindings/pydeck/pydeck/io/html.py

@@ -34,6 +34,7 @@ def convert_js_bool(py_bool):
 j2_loader = jinja2.FileSystemLoader(TEMPLATES_PATH)
 j2_env = jinja2.Environment(loader=j2_loader, trim_blocks=True)
 CDN_URL = "https://cdn.jsdelivr.net/npm/@deck.gl/jupyter-widget@{}/dist/index.js".format(DECKGL_SEMVER)
+CDN_CSS_URL = "https://cdn.jsdelivr.net/npm/@deck.gl/widgets@{}/dist/stylesheet.css".format(DECKGL_SEMVER)
 
 
 def cdn_picker(offline=False):
@@ -72,6 +73,7 @@ def render_json_to_html(
         google_maps_key=google_maps_key,
         json_input=json_input,
         deckgl_jupyter_widget_bundle=cdn_picker(offline=offline),
+        deckgl_widget_css_url=CDN_CSS_URL,
         tooltip=convert_js_bool(tooltip),
         css_text=css_text,
         custom_libraries=custom_libraries,

bindings/pydeck/pydeck/io/templates/index.j2

@@ -11,6 +11,7 @@
     <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.2.0/css/bootstrap-theme.min.css" />
     <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css" />
     {{ deckgl_jupyter_widget_bundle }}
+    <link rel="stylesheet" href={{ deckgl_widget_css_url }} />
     <style>
     {{ css_text }}
     </style>