feat(kepler-jupyter): restore save_to_html() using kepler.gl UMD bundle from CDN (#3382)

Author: lixun910

.github/workflows/build-publish-pypi.yml

@@ -19,6 +19,17 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Verify CDN version matches package.json
+        run: |
+          MAJOR=$(node -p "require('./package.json').version.split('.')[0]")
+          CDN=$(grep -Po '(?<=DEFAULT_KEPLER_GL_CDN_VERSION = ")[^"]+' bindings/python/keplergl/_html_export.py)
+          echo "package.json major: $MAJOR"
+          echo "Python CDN version: $CDN"
+          if [ "$MAJOR" != "$CDN" ]; then
+            echo "::error::DEFAULT_KEPLER_GL_CDN_VERSION ($CDN) in _html_export.py does not match major version ($MAJOR) from package.json. Please update it."
+            exit 1
+          fi
+
       - name: Install uv
         uses: astral-sh/setup-uv@v4
 

bindings/python/DEVELOPMENT.md

@@ -102,6 +102,7 @@ The version in `pyproject.toml` determines what type of release you can publish:
 1. **Update the version** in both files:
    - `pyproject.toml` (line: `version = "x.x.x"`)
    - `keplergl/_version.py` (line: `__version__ = "x.x.x"`)
+   - On a kepler.gl **major** release, also update `DEFAULT_KEPLER_GL_CDN_VERSION` in `keplergl/_html_export.py` to match the new major version.
 
 2. **Go to GitHub Actions** → "Build and Publish KeplerGL Python Package" workflow
 

bindings/python/keplergl/_html_export.py

@@ -0,0 +1,235 @@
+# SPDX-License-Identifier: MIT
+# Copyright contributors to the kepler.gl project
+
+"""Generate standalone HTML export using the kepler.gl UMD bundle from CDN."""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import pandas as pd
+import geopandas as gpd
+
+DEFAULT_KEPLER_GL_CDN_VERSION = "3"
+
+
+def _dataset_to_csv(data) -> Optional[str]:
+    """Convert a dataset value to CSV string for kepler.gl processCsvData."""
+    if isinstance(data, gpd.GeoDataFrame):
+        import shapely.wkt
+
+        if data.crs and data.crs.to_epsg() != 4326:
+            data = data.to_crs(4326)
+        df = pd.DataFrame(data)
+        geom_col = data.geometry.name
+        df[geom_col] = data.geometry.apply(shapely.wkt.dumps)
+        return df.to_csv(index=False)
+    elif isinstance(data, pd.DataFrame):
+        return data.to_csv(index=False)
+    elif isinstance(data, str):
+        return data
+    else:
+        return None
+
+
+def _dataset_to_geojson(data) -> Optional[dict]:
+    """Try to convert dataset to GeoJSON dict."""
+    if isinstance(data, gpd.GeoDataFrame):
+        if data.crs and data.crs.to_epsg() != 4326:
+            data = data.to_crs(4326)
+        return json.loads(data.to_json())
+    elif isinstance(data, dict):
+        geojson_types = {
+            "FeatureCollection", "Feature", "Point", "MultiPoint",
+            "LineString", "MultiLineString", "Polygon", "MultiPolygon",
+            "GeometryCollection",
+        }
+        if data.get("type") in geojson_types:
+            return data
+    elif isinstance(data, str):
+        try:
+            parsed = json.loads(data)
+            if isinstance(parsed, dict) and parsed.get("type") in {
+                "FeatureCollection", "Feature",
+            }:
+                return parsed
+        except (json.JSONDecodeError, TypeError):
+            pass
+    return None
+
+
+def _serialize_datasets_for_html(data: dict) -> str:
+    """Serialize datasets dict into JS code that calls addDataToMap.
+
+    Generates a JS snippet that processes each dataset using kepler.gl's
+    processCsvData or processGeojson, then dispatches addDataToMap.
+    """
+    snippets = []
+    for name, dataset in data.items():
+        geojson = _dataset_to_geojson(dataset)
+        if geojson is not None:
+            snippets.append(
+                f"  datasets.push({{info: {{id: {json.dumps(name, ensure_ascii=False)}, label: {json.dumps(name, ensure_ascii=False)}}}, "
+                f"data: keplerGl.processGeojson({json.dumps(geojson, ensure_ascii=False)})}});"
+            )
+        else:
+            csv_str = _dataset_to_csv(dataset)
+            if csv_str is not None:
+                snippets.append(
+                    f"  datasets.push({{info: {{id: {json.dumps(name, ensure_ascii=False)}, label: {json.dumps(name, ensure_ascii=False)}}}, "
+                    f"data: keplerGl.processCsvData({json.dumps(csv_str, ensure_ascii=False)})}});"
+                )
+    return "\n".join(snippets)
+
+
+def export_map_html(
+    data: dict,
+    config: dict,
+    read_only: bool = False,
+    center_map: bool = False,
+    mapbox_token: str = "",
+    kepler_gl_version: str = DEFAULT_KEPLER_GL_CDN_VERSION,
+) -> str:
+    """Generate a standalone HTML string that renders a kepler.gl map.
+
+    Loads all dependencies from CDN (unpkg). No local JS build required.
+    """
+    dataset_js = _serialize_datasets_for_html(data)
+    config_json = json.dumps(config, ensure_ascii=False) if config else "{}"
+    mapbox_token_json = json.dumps(mapbox_token)
+    read_only_js = "true" if read_only else "false"
+    center_map_js = "true" if center_map else "false"
+
+    return f"""\
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8"/>
+    <title>Kepler.gl embedded map</title>
+
+    <!--Uber Font-->
+    <link rel="stylesheet" href="https://d1a3f4spazzrp4.cloudfront.net/kepler.gl/uber-fonts/4.0.0/superfine.css">
+
+    <!--Kepler css-->
+    <link href="https://unpkg.com/kepler.gl@{kepler_gl_version}/umd/keplergl.min.css" rel="stylesheet">
+
+    <!--MapBox css-->
+    <link href="https://api.tiles.mapbox.com/mapbox-gl-js/v1.1.1/mapbox-gl.css" rel="stylesheet">
+    <link href="https://unpkg.com/maplibre-gl@^3/dist/maplibre-gl.css" rel="stylesheet">
+
+    <!-- Load React/Redux -->
+    <script src="https://unpkg.com/react@18.3.1/umd/react.production.min.js" crossorigin></script>
+    <script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.production.min.js" crossorigin></script>
+    <script src="https://unpkg.com/redux@4.2.1/dist/redux.js" crossorigin></script>
+    <script src="https://unpkg.com/react-redux@8.1.2/dist/react-redux.min.js" crossorigin></script>
+    <script src="https://unpkg.com/styled-components@6.1.8/dist/styled-components.min.js" crossorigin></script>
+
+    <!-- Load Kepler.gl -->
+    <script src="https://unpkg.com/kepler.gl@{kepler_gl_version}/umd/keplergl.min.js" crossorigin></script>
+
+    <style type="text/css">
+      body {{margin: 0; padding: 0; overflow: hidden;}}
+    </style>
+
+    <script>
+      const MAPBOX_TOKEN = {mapbox_token_json};
+    </script>
+  </head>
+  <body>
+    <div id="app"></div>
+
+    <script>
+      /** STORE **/
+      const reducers = (function createReducers(redux, keplerGl) {{
+        return redux.combineReducers({{
+          keplerGl: keplerGl.keplerGlReducer.initialState({{
+            uiState: {{
+              readOnly: {read_only_js},
+              currentModal: null
+            }}
+          }})
+        }});
+      }}(Redux, KeplerGl));
+
+      const middleWares = (function createMiddlewares(keplerGl) {{
+        return keplerGl.enhanceReduxMiddleware([]);
+      }}(KeplerGl));
+
+      const enhancers = (function createEnhancers(redux, middles) {{
+        return redux.applyMiddleware(...middles);
+      }}(Redux, middleWares));
+
+      const store = (function createStore(redux, enhancers) {{
+        return redux.createStore(reducers, {{}}, redux.compose(enhancers));
+      }}(Redux, enhancers));
+      /** END STORE **/
+
+      /** COMPONENTS **/
+      var KeplerElement = (function makeKeplerElement(react, keplerGl, mapboxToken) {{
+        return function App() {{
+          var rootElm = react.useRef(null);
+          var _useState = react.useState({{
+            width: window.innerWidth,
+            height: window.innerHeight
+          }});
+          var windowDimension = _useState[0];
+          var setDimension = _useState[1];
+          react.useEffect(function sideEffect() {{
+            function handleResize() {{
+              setDimension({{width: window.innerWidth, height: window.innerHeight}});
+            }}
+            window.addEventListener('resize', handleResize);
+            return function() {{ window.removeEventListener('resize', handleResize); }};
+          }}, []);
+          return react.createElement(
+            'div',
+            {{style: {{position: 'absolute', left: 0, width: '100vw', height: '100vh'}}}},
+            react.createElement(keplerGl.KeplerGl, {{
+              mapboxApiAccessToken: mapboxToken,
+              id: "map",
+              width: windowDimension.width,
+              height: windowDimension.height
+            }})
+          );
+        }};
+      }}(React, KeplerGl, MAPBOX_TOKEN));
+
+      const app = (function createReactReduxProvider(react, reactRedux, KeplerElement) {{
+        return react.createElement(
+          reactRedux.Provider,
+          {{store}},
+          react.createElement(KeplerElement, null)
+        );
+      }}(React, ReactRedux, KeplerElement));
+      /** END COMPONENTS **/
+
+      /** Render **/
+      (function render(react, reactDOM, app) {{
+        const container = document.getElementById('app');
+        const root = reactDOM.createRoot(container);
+        root.render(app);
+      }}(React, ReactDOM, app));
+    </script>
+
+    <script>
+      (function customize(keplerGl, store) {{
+        var datasets = [];
+{dataset_js}
+
+        var config = {config_json};
+
+        window.setTimeout(function() {{
+          store.dispatch(keplerGl.addDataToMap({{
+            datasets: datasets,
+            config: config,
+            options: {{
+              centerMap: {center_map_js}
+            }}
+          }}));
+        }}, 500);
+      }}(KeplerGl, store));
+    </script>
+  </body>
+</html>
+"""

bindings/python/keplergl/_version.py

@@ -3,4 +3,4 @@
 
 """Version information."""
 
-__version__ = "0.4.0rc1"
+__version__ = "0.4.0rc2"

bindings/python/keplergl/serializers.py

@@ -17,6 +17,14 @@ def _debug(msg):
         print(f"[keplergl-serializer] {msg}")
 
 
+def _arrow_table_to_base64(table: pa.Table) -> str:
+    """Serialize an Arrow table to a base64-encoded IPC stream."""
+    sink = pa.BufferOutputStream()
+    with pa.ipc.new_stream(sink, table.schema) as writer:
+        writer.write_table(table)
+    return base64.b64encode(sink.getvalue().to_pybytes()).decode("utf-8")
+
+
 def _try_parse_geojson(data: str) -> Optional[dict]:
     """Try to parse a string as GeoJSON. Returns parsed dict if valid GeoJSON, None otherwise."""
     import json
@@ -37,10 +45,11 @@ def _try_parse_geojson(data: str) -> Optional[dict]:
 def data_to_json(data: dict, widget) -> dict:
     """Serialize Python data for JavaScript consumption."""
     _debug(f"data_to_json called with {len(data)} datasets")
+    use_arrow = getattr(widget, '_use_arrow', False) if widget else False
     result = {}
     for name, dataset in data.items():
         _debug(f"  Serializing dataset '{name}' of type {type(dataset).__name__}")
-        result[name] = serialize_dataset(dataset, name)
+        result[name] = serialize_dataset(dataset, name, use_arrow=use_arrow)
         _debug(f"  Result format: {result[name].get('format')}")
     _debug(f"data_to_json result: {list(result.keys())}")
     return result
@@ -51,32 +60,34 @@ def data_from_json(data: dict, widget) -> dict:
     return data
 
 
-def serialize_dataset(data: Any, name: str) -> dict:
+def serialize_dataset(data: Any, name: str, use_arrow: bool = False) -> dict:
     """Serialize a single dataset."""
     if isinstance(data, gpd.GeoDataFrame):
         return serialize_geodataframe(data, name)
     elif isinstance(data, pd.DataFrame):
-        return serialize_dataframe(data, name)
+        return serialize_dataframe(data, name, use_arrow=use_arrow)
     elif isinstance(data, str):
-        # Try to detect if the string is GeoJSON
         geojson_data = _try_parse_geojson(data)
         if geojson_data is not None:
             _debug(f"  Detected GeoJSON string for '{name}'")
             return {"id": name, "data": geojson_data, "format": "geojson"}
-        # Otherwise treat as CSV
         return {"id": name, "data": data, "format": "csv"}
     elif isinstance(data, dict):
         return {"id": name, "data": data, "format": "geojson"}
     else:
         raise ValueError(f"Unsupported data type: {type(data)}")
 
 
-def serialize_dataframe(df: pd.DataFrame, name: str) -> dict:
-    """Serialize DataFrame to JSON format for kepler.gl.
-    
-    We use JSON format instead of Arrow to avoid version mismatch issues
-    between the apache-arrow package used here and the one bundled with kepler.gl.
+def serialize_dataframe(df: pd.DataFrame, name: str, use_arrow: bool = False) -> dict:
+    """Serialize DataFrame for kepler.gl.
+
+    When use_arrow=True, serializes as Arrow IPC (base64-encoded) which is more
+    compact and preserves types better for large numeric datasets.
+    When use_arrow=False (default), serializes as JSON columns+rows.
     """
+    if use_arrow:
+        return _serialize_dataframe_arrow(df, name)
+
     columns = df.columns.tolist()
     rows = df.values.tolist()
     _debug(f"serialize_dataframe: {len(columns)} columns, {len(rows)} rows")
@@ -92,6 +103,17 @@ def serialize_dataframe(df: pd.DataFrame, name: str) -> dict:
     }
 
 
+def _serialize_dataframe_arrow(df: pd.DataFrame, name: str) -> dict:
+    """Serialize DataFrame to Arrow IPC format (base64-encoded)."""
+    table = pa.Table.from_pandas(df)
+    _debug(f"_serialize_dataframe_arrow: {table.num_columns} columns, {table.num_rows} rows")
+    return {
+        "id": name,
+        "data": _arrow_table_to_base64(table),
+        "format": "arrow",
+    }
+
+
 def serialize_geodataframe(gdf: gpd.GeoDataFrame, name: str) -> dict:
     """Serialize GeoDataFrame to GeoArrow format."""
     import geoarrow.pyarrow as ga
@@ -107,12 +129,8 @@ def serialize_geodataframe(gdf: gpd.GeoDataFrame, name: str) -> dict:
     col_names = non_geom_cols + [geom_col]
 
     table = pa.table(dict(zip(col_names, arrays)))
-    sink = pa.BufferOutputStream()
-    with pa.ipc.new_stream(sink, table.schema) as writer:
-        writer.write_table(table)
-    arrow_bytes = sink.getvalue().to_pybytes()
     return {
         "id": name,
-        "data": base64.b64encode(arrow_bytes).decode("utf-8"),
+        "data": _arrow_table_to_base64(table),
         "format": "geoarrow",
     }